Agentic Software Factory · 2026-07-17 · Debugging with Markers
Session Replay: one marked moment, read cold
An annotated replay of the session that produced this site's sample capture: reproduce the bug, mark the moment, export, render the packet, state a hypothesis before reading any code.
The session, beat by beat
Replayed from a prior scripted session against the workshop's Field Notes demo app — the same run that produced sample-session.json, published raw on this site. Prompts are condensed; every output below is quoted verbatim from the captured artifacts.
Serve the Field Notes demo and reproduce the reconnect-and-save failure: type a note, go offline, save, reconnect, save again.
Drove the app in a scripted browser. The offline save failed honestly ("Save failed (offline?)"). After Reconnect, the second save showed "Saved ✓" — but the mock server returned 401. The plant: reconnecting rotates the server's session token, the client keeps its stale copy, and the save handler treats anything below 500 as success:
// BUG: only 5xx counts as failure, so the stale-token 401 shows "Saved ✓".
if (res.status < 500) {
statusEl.textContent = "Saved ✓";
} else {
statusEl.textContent = "Save failed (server error)";
}
Would your users file a useful bug report for this? They saw a success message. That gap is the whole reason markers exist.
YouMark that moment. Testimony: "It said Saved but my note never reached the server — this happened right after I reconnected."
The ⚑ button uses prompt(), which blocks scripted browsers — so the mark went in through the console instead:
window.__AGENT_MARKERS__.mark(
"user-flag",
"It said Saved but my note never reached the server — this happened right after I reconnected."
)
Marker mrk-1-mro9e75t recorded, pinned to the nine nearest events by id.
For a human it's one keystroke (Ctrl/Cmd+M) and one sentence at the moment of surprise. No form, no repro steps demanded — anything heavier and nobody uses it when it matters.
YouExport the session and show me exactly what leaves the machine.
exportSession() produced a schemaVersion-1 JSON — 1 marker, 10 events, and a redaction block that documents what was withheld:
"redaction": {
"storageValues": "excluded",
"requestBodies": "excluded",
"responseBodies": "excluded",
"userText": "preview+length only"
}
No request or response bodies, no tokens, no storage values; user text travels as preview + length only. The full export is published raw as sample-session.json.
The redaction policy rides inside the payload, so every reader can audit what was withheld. A capture safe enough to paste anywhere gets pasted; a risky one gets hoarded and helps no one.
YouRender the agent packet from that export.
node scripts/make-agent-packet.mjs samples/sample-session.json
The packet leads with the testimony, then the seq-ordered evidence slice. Seven consecutive lines, exactly as rendered:
- [seq 3 · t+17397ms] click: click <button#save> "Save note"
- [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms]
- [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable
- [seq 6 · t+18436ms] click: click <button#toggle-net> "Reconnect"
- [seq 7 · t+18436ms] console: console.log: reconnected: session restored
- [seq 8 · t+18909ms] click: click <button#save> "Save note"
- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]
Read it top to bottom: NETWORK-ERROR → "reconnected" → 401 on the very next save, under a visible "Saved ✓". A nine-line slice doing what a full log dump rarely does.
YouNow read the packet cold — no source code, no other context. One hypothesis, one sentence, before you look at anything else.
The reconnect rotated or invalidated a session credential the client still holds, and the app treats the resulting 401 as success.
Flagged as "hypothesis — needs verification", per the packet's claims boundary: testimony is not diagnosis, context is not proof.
That is the pass condition for any capture you build: a cold reader — human or agent — gets from the packet alone to the mechanism. The hypothesis arrives labeled as a draft; a person verifies it against the running app.
YouGood. Give me the version I can drop into any app.
The whole recorder — dependency-free, no build step. Everything above was captured by these lines (same bytes as agent-markers.js on this site):
/**
* agent-markers.js — a tiny, dependency-free "press a button, capture the moment" recorder.
*
* Pattern: a MARKER is timestamped human testimony ("this moment matters, here's why").
* A TRAIL is the ordered semantic events (console, fetch, error, click) that led there.
* Export = bounded, redacted payload you can hand to an agent as a debug packet.
*
* Deliberately NOT captured: storage values, request/response bodies, raw input text.
* Testimony is not diagnosis. Context is not proof.
*/
(function (global) {
"use strict";
const state = {
running: false,
sessionId: null,
startedAtIso: null,
startedAtMs: 0,
seq: 0,
events: [],
markers: [],
maxEvents: 200,
nearbyEventLimit: 12,
restoreFns: [],
};
function now() {
return Math.round(performance.now() - state.startedAtMs);
}
function preview(text, max = 80) {
const s = String(text ?? "");
return {
preview: s.length > max ? s.slice(0, max) + "…" : s,
length: s.length,
truncated: s.length > max,
};
}
function record(type, data) {
if (!state.running) return null;
const event = { id: "evt-" + (++state.seq), seq: state.seq, t: now(), type, data };
state.events.push(event);
if (state.events.length > state.maxEvents) state.events.shift();
return event;
}
function patchConsole() {
["log", "warn", "error"].forEach((level) => {
const original = console[level];
console[level] = function (...args) {
record("console", { level, message: preview(args.map(String).join(" ")) });
return original.apply(console, args);
};
state.restoreFns.push(() => (console[level] = original));
});
}
function patchFetch() {
const original = global.fetch;
global.fetch = async function (input, init) {
const url = typeof input === "string" ? input : input.url;
const method = (init && init.method) || "GET";
const started = now();
try {
const res = await original.apply(global, arguments);
record("fetch", { method, url, status: res.status, ok: res.ok, ms: now() - started });
return res;
} catch (error) {
record("fetch", { method, url, status: null, ok: false, ms: now() - started, error: preview(error && error.message) });
throw error;
}
};
state.restoreFns.push(() => (global.fetch = original));
}
function patchErrors() {
const onError = (event) =>
record("error", { message: preview(event.message || String(event.reason || "unknown")) });
global.addEventListener("error", onError);
global.addEventListener("unhandledrejection", onError);
state.restoreFns.push(() => {
global.removeEventListener("error", onError);
global.removeEventListener("unhandledrejection", onError);
});
}
function patchClicks() {
const onClick = (event) => {
const el = event.target.closest("button, a, [data-action]") || event.target;
record("click", {
tag: el.tagName.toLowerCase(),
id: el.id || null,
action: el.dataset ? el.dataset.action || null : null,
text: preview(el.textContent && el.textContent.trim(), 40),
});
};
document.addEventListener("click", onClick, true);
state.restoreFns.push(() => document.removeEventListener("click", onClick, true));
}
const AgentMarkers = {
start(options = {}) {
if (state.running) return this;
state.sessionId = options.sessionId || "session-" + Date.now().toString(36);
state.startedAtIso = new Date().toISOString();
state.startedAtMs = performance.now();
state.maxEvents = options.maxEvents || 200;
state.nearbyEventLimit = options.nearbyEventLimit || 12;
state.seq = 0;
state.events = [];
state.markers = [];
state.running = true;
patchConsole();
patchFetch();
patchErrors();
patchClicks();
if (options.exposeGlobal !== false) global.__AGENT_MARKERS__ = AgentMarkers;
record("session", { note: "recording started", app: options.app || "unknown" });
return this;
},
/** Human presses the button: timestamped testimony + pointers into the trail. */
mark(label, note) {
if (!state.running) throw new Error("AgentMarkers not started");
const nearby = state.events.slice(-state.nearbyEventLimit).map((e) => e.id);
const marker = {
id: "mrk-" + (state.markers.length + 1) + "-" + Date.now().toString(36),
seq: ++state.seq,
t: now(),
label: label || "unlabeled",
note: note || "",
nearbyEventIds: nearby,
screenshot: "unavailable", // browser demo: no screenshot API without permissions
};
state.markers.push(marker);
record("marker", { markerId: marker.id, label: marker.label });
return marker;
},
record(type, data) {
return record("manual", { type, ...data });
},
/** Bounded, redacted payload — everything an agent gets, nothing more. */
exportSession() {
return {
schemaVersion: 1,
sessionId: state.sessionId,
startedAt: state.startedAtIso,
exportedAt: new Date().toISOString(),
userAgent: navigator.userAgent,
markers: state.markers,
events: state.events,
redaction: {
storageValues: "excluded",
requestBodies: "excluded",
responseBodies: "excluded",
userText: "preview+length only",
},
};
},
stop() {
state.restoreFns.forEach((restore) => restore());
state.restoreFns = [];
state.running = false;
return this;
},
};
if (typeof module !== "undefined" && module.exports) module.exports = AgentMarkers;
global.AgentMarkers = AgentMarkers;
})(typeof window !== "undefined" ? window : globalThis);
The boot file and the packet renderer are printed complete in the section guide, or replay this whole loop from an empty directory:
mkdir -p markers-quickstart && cd markers-quickstart
curl -sO https://mindful-mango-accy.here.now/agent-markers.js
curl -sO https://mindful-mango-accy.here.now/make-agent-packet.mjs
curl -sO https://mindful-mango-accy.here.now/sample-session.json
node make-agent-packet.mjs sample-session.json
Total session: five prompts. The loop the transcript demonstrates — mark → export → packet → hypothesis — is the same one your attendees' agents replay from agent.md.