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.

You

Serve the Field Notes demo and reproduce the reconnect-and-save failure: type a note, go offline, save, reconnect, save again.

Agent

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.

You

Mark that moment. Testimony: "It said Saved but my note never reached the server — this happened right after I reconnected."

Agent

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.

You

Export the session and show me exactly what leaves the machine.

Agent

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.

You

Render the agent packet from that export.

Agent
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.

You

Now read the packet cold — no source code, no other context. One hypothesis, one sentence, before you look at anything else.

Agent

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.

You

Good. Give me the version I can drop into any app.

Agent

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.