Agentic Software Factory · 2026-07-17

Debugging with Markers

Press one key when the app feels wrong. Ship the moment — human testimony plus the ordered events that led there — straight into an agent.

TL;DR

🤖 Have your agent set this up — paste this into it:

Fetch https://mindful-mango-accy.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.

Quick start

Runs from any empty directory — needs only curl and Node 18+. It pulls the recorder, the packet renderer, and a real captured session from this site, then prints the agent-ready debug packet.

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

Prompt library

Hand an agent a debug packet

any coding agent anywhere a one-sentence hypothesis, then a reproducible scenario with unproven parts flagged

Here is a debug packet captured from a live session of my app. Before you read any code:

1. Read the human testimony, then the evidence trail in seq order.
2. State your single most likely hypothesis for the failure, in one sentence.
3. Draft a reproducible scenario — preconditions, steps, expected, observed — using ONLY the evidence in the packet.
4. Label anything the trail cannot prove as "hypothesis — needs verification".

Testimony is not diagnosis. Context is not proof.

--- PACKET ---
[paste the output of: node scripts/make-agent-packet.mjs your-session.json]

Grade your capture: can it be read cold?

any coding agent your project, with a fresh export on disk a stated hypothesis, or the one knob to turn first

Here is a marker-session export from my app (JSON, schemaVersion 1). Render it with scripts/make-agent-packet.mjs and read the packet cold — no source code, no other context.

Answer two things:
1. Can you state one specific hypothesis from the testimony and trail alone? State it.
2. If you cannot, tell me which single change to make first: mark closer to the failure, raise nearbyEventLimit, or add one missing event type to the recorder.

Write the redaction policy first

your coding agent your project, before any recording code lands an exclusion list for your app plus a redaction JSON block for every export

I'm adding just-in-time debug capture (markers plus an event trail) to this app. Before any recording code lands, draft our redaction policy: list every category of data a capture must NEVER contain (request/response bodies, tokens, storage values, raw user text, plus anything specific to this codebase), and produce a redaction JSON block to embed verbatim in every export so readers can audit what was withheld. Default user text to "preview+length only".

Set it up (agent guide)

These steps mirror agent.md — the machine copy your agent fetches. <static-dir> means wherever your app serves static JS from (often public/).

  1. Add the recorder to your app as <static-dir>/agent-markers.js. This is the whole thing — no dependencies, no build step. (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);
  2. Boot it with <static-dir>/markers-boot.js — starts recording, binds Ctrl/Cmd+M to “mark”, and exposes exportMarkers() for downloading the capture. Replace "my-app" with your app’s name.
    /* markers-boot.js — load AFTER agent-markers.js, BEFORE your app's own scripts.
       Ctrl/Cmd+M drops a marker; exportMarkers() in the console downloads the capture. */
    AgentMarkers.start({ app: "my-app" }); // replace "my-app" with your app's name
    
    // One keystroke at the moment of surprise: one sentence of testimony.
    window.addEventListener("keydown", (e) => {
      if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "m") {
        e.preventDefault();
        const note = prompt("Why does this moment matter? (one sentence — it travels with the capture)");
        if (note !== null) console.log("marked:", AgentMarkers.mark("user-flag", note).id);
      }
    });
    
    // Call exportMarkers() from the console, or wire it to a button.
    window.exportMarkers = () => {
      const session = AgentMarkers.exportSession();
      const blob = new Blob([JSON.stringify(session, null, 2)], { type: "application/json" });
      const a = Object.assign(document.createElement("a"), {
        href: URL.createObjectURL(blob),
        download: session.sessionId + ".json",
      });
      a.click();
      URL.revokeObjectURL(a.href);
      return session.sessionId + ".json";
    };
    Load both before your app’s own scripts: <script src="agent-markers.js"></script> then <script src="markers-boot.js"></script>.
  3. Save the packet renderer as scripts/make-agent-packet.mjs in your project — it turns any export into the markdown packet the prompts above expect.
    #!/usr/bin/env node
    /**
     * make-agent-packet.mjs — turn a marker-session export into a bounded agent debug packet.
     *
     * Usage:
     *   node scripts/make-agent-packet.mjs <session.json> [marker-id]
     *
     * Emits markdown on stdout: human testimony, the nearby evidence slice, redaction
     * receipts, and an explicit claims boundary — ready to paste into any agent.
     */
    import { readFileSync } from "node:fs";
    
    const [file, markerArg] = process.argv.slice(2);
    if (!file) {
      console.error("usage: node scripts/make-agent-packet.mjs <session.json> [marker-id]");
      process.exit(1);
    }
    
    const session = JSON.parse(readFileSync(file, "utf8"));
    if (session.schemaVersion !== 1) {
      console.error(`unsupported schemaVersion: ${session.schemaVersion}`);
      process.exit(1);
    }
    
    const marker = markerArg
      ? session.markers.find((m) => m.id === markerArg)
      : session.markers.at(-1);
    if (!marker) {
      console.error(markerArg ? `marker '${markerArg}' not found` : "no markers in session");
      process.exit(1);
    }
    
    const nearbyIds = new Set(marker.nearbyEventIds ?? []);
    const nearby = session.events.filter((e) => nearbyIds.has(e.id));
    const fmt = (e) => {
      const d = e.data ?? {};
      switch (e.type) {
        case "fetch":
          return `${d.method} ${d.url} → ${d.status ?? "NETWORK-ERROR"}${d.error ? ` (${d.error.preview ?? d.error})` : ""} [${d.ms}ms]`;
        case "console":
          return `console.${d.level}: ${d.message?.preview ?? ""}`;
        case "click":
          return `click <${d.tag}${d.id ? `#${d.id}` : ""}> "${d.text?.preview ?? ""}"`;
        case "error":
          return `error: ${d.message?.preview ?? ""}`;
        default:
          return JSON.stringify(d);
      }
    };
    
    const lines = [];
    lines.push(`# Debug packet — marker ${marker.id}`);
    lines.push("");
    lines.push(`- session: ${session.sessionId} (started ${session.startedAt})`);
    lines.push(`- marker time: t+${marker.t}ms · label: ${marker.label}`);
    lines.push(`- screenshot: ${marker.screenshot ?? "unavailable"}`);
    lines.push("");
    lines.push("## Human testimony (why this moment matters)");
    lines.push("");
    lines.push(`> ${marker.note || "(no explanation recorded)"}`);
    lines.push("");
    lines.push(`## Evidence trail (${nearby.length} events nearest the marker, seq order)`);
    lines.push("");
    for (const e of nearby) lines.push(`- [seq ${e.seq} · t+${e.t}ms] ${e.type}: ${fmt(e)}`);
    lines.push("");
    lines.push("## Redaction receipts");
    lines.push("");
    for (const [k, v] of Object.entries(session.redaction ?? {})) lines.push(`- ${k}: ${v}`);
    lines.push("");
    lines.push("## Task for the agent");
    lines.push("");
    lines.push("Draft a reproducible scenario (preconditions, steps, expected, observed) that");
    lines.push("explains the testimony using ONLY the evidence above. Flag anything the trail");
    lines.push("cannot prove as a hypothesis needing verification.");
    lines.push("");
    lines.push("## Claims boundary");
    lines.push("");
    lines.push("Testimony is not diagnosis. Context is not proof. The trail shows what was");
    lines.push("captured, not everything that happened.");
    
    console.log(lines.join("\n"));

Success check: render the real captured session from this site, then read the packet cold and state a hypothesis before looking at any code.

curl -sO https://mindful-mango-accy.here.now/sample-session.json
node scripts/make-agent-packet.mjs sample-session.json
# Debug packet — marker mrk-1-mro9e75t

- session: session-mro9dmel (started 2026-07-17T01:27:53.517Z)
- marker time: t+26900ms · label: user-flag
- screenshot: unavailable

## Human testimony (why this moment matters)

> It said Saved but my note never reached the server — this happened right after I reconnected.

## Evidence trail (9 events nearest the marker, seq order)

- [seq 1 · t+0ms] session: {"note":"recording started","app":"field-notes-demo"}
- [seq 2 · t+16914ms] click: click <button#toggle-net> "Go offline"
- [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]
…

You pass when a reader — human or agent — gets from that packet alone to something like “the reconnect rotated or invalidated a session credential the client still holds.” Then verify the loop in your own app: press Ctrl/Cmd+M, type a sentence, run exportMarkers() in the console, and confirm the downloaded JSON has your marker and a redaction block.

The signal you normally throw away

You are testing an app. Something feels off — a stale value, a success message you do not believe. Usually that judgment evaporates: hours later someone asks for a bug report, and you reconstruct the moment from memory, losing the timing, the order of actions, and most of the value. The pattern this session builds on calls human intent “the missing signal” in agent debugging and records it the moment it occurs.

This is not a paper idea. A production desktop app we studied ships the same move: a hotkey mints a marker id, captures a screenshot, writes a dev_marker log event, and opens a note where the tester types one explanation — all joined by the same id, with a log CLI whose --marker flag slices the session for agents. The design rule that makes it work: capture happens during the surprise, one keystroke and one sentence. Anything heavier and nobody uses it at the moment that matters.

A capture has two parts that answer different questions. A marker says why this moment deserves attention; a trail says how the tester arrived there. Testimony alone tells an agent what to look for but not when; a trail alone is complete but unweighted. Paired, the testimony points into the trail, and the trail grounds the testimony in ordered facts. Treat the marker as a search warrant, not a verdict.

One captured failure, read cold

The workshop demo plants a bug worth marking: a notes app goes offline, reconnects, and saves. The server rotated its session token during the reconnect; the client kept its stale copy; the save handler treats any status below 500 as success. The user sees “Saved ✓”. The server said 401. We drove that path in a real browser, pressed mark, and typed: “It said Saved but my note never reached the server — this happened right after I reconnected.” Seven consecutive lines of the captured trail, exactly as the packet renderer printed them:

- [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 and name a hypothesis before anyone tells you: a network failure, a “session restored” log, then a 401 on the very next save under a visible “Saved ✓”. If you reached “the reconnect invalidated something the client still holds,” a nine-line slice just did what a full log dump rarely does — and an agent reads it the same way you just did.

What the capture leaves out

The moment you say “capture the entire state of the app,” you have a privacy decision, because the payload will leave your machine — pasted into an agent, attached to a ticket, shared in chat. Decide the exclusions before the first capture, write them into the payload itself, and accept the narrower evidence. The demo’s export embeds exactly this policy, so every reader can audit what was withheld:

{
  "storageValues": "excluded",
  "requestBodies": "excluded",
  "responseBodies": "excluded",
  "userText": "preview+length only"
}

An external architecture review of the production system pushed the same rule harder: order events by a sequence counter, join records by session and marker ids, and store user input as preview, hash, and length — never raw. A capture safe enough to paste anywhere gets pasted; a risky one gets hoarded and helps no one.

The handoff needs a fence too. A weak handoff pastes a log dump and asks “what’s wrong?”, inviting confident guessing over unweighted noise. A strong handoff gives less data and more structure — what the human saw, what the system recorded, what was withheld, and what kind of answer is allowed. That is why the packet ends with a claims boundary, and why the first prompt above demands a hypothesis before code: the agent’s draft arrives labeled as a draft, and a person verifies it against the running app.

Appendix

Limits & caveats
  • Testimony is not diagnosis; context is not proof. The trail shows what was captured, not everything that happened — session metadata does not prove a defect, and testimony does not prove cause.
  • The captured failure here is a bug we planted ourselves. The loop is demonstrated end to end, but its yield on organic bugs is untested on this page.
  • Redaction trades fidelity for safety. A capture without request bodies cannot settle every question; sometimes the correct next step is a targeted, consented follow-up capture.
  • prompt() blocks automation. Scripted browsers should call window.__AGENT_MARKERS__.mark(label, note) from the console instead of the hotkey.
  • On macOS, Cmd+M can collide with the browser’s minimize shortcut; a page button or the console call is the reliable path.
  • The ring buffer is in-memory only — a reload wipes it. Export before navigating away. Screenshots are "unavailable" in the plain-browser recorder; the production system captures them via native APIs.
  • If your app installs its own fetch wrapper (mocks, auth shims), install it before AgentMarkers.start() so wrapped calls land in the trail.
Provenance

Sources: S1 — “Mark the Moment: A Human-Anchored Pattern for Agent Debugging,” the public article this workshop section names (boreal-tablet-hbeh.here.now); quoted briefly and paraphrased. S2 — the demo recorder agent-markers.js, published raw on this site and printed complete above. S3 — the demo app (“Field Notes”) with a deliberately planted stale-token bug. S4 — one session captured from a real scripted run of that demo on 2026-07-17 (one marker, ten events), published raw as sample-session.json; every trail line quoted on this page reproduces it verbatim. S5 — the packet renderer make-agent-packet.mjs, published raw and printed complete above. S6 — project research notes describing a production desktop app’s marker implementation (private codebase, verified by reading its source) and an external architecture review of it; claims from the review are attributed, not independently verified.

Transformations: this page condenses the project’s earlier Scholarly Folio; the argument order is editorial. The reconnect-bug hypothesis is reasoning the reader is invited to perform, grounded in S4. No citations, measurements, or artifacts were invented; private paths and identifiers were withheld. One canonical script (app.js) adds copy buttons; the page reads fully without it.