---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-debug-markers-practice"
title: "Human testimony joined to runtime evidence — prompts and exercises"
---

# Human testimony joined to runtime evidence — prompts and exercises

Complete reusable prompts, setup recipes, success checks, and caveats for human testimony joined to runtime evidence.

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

``` text
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

- Agent: any coding agent
- Working directory: anywhere
- Expected result: a one-sentence hypothesis, then a reproducible scenario with unproven parts flagged

``` text
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?

- Agent: any coding agent
- Working directory: your project, with a fresh export on disk
- Expected result: a stated hypothesis, or the one knob to turn first

``` text
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

- Agent: your coding agent
- Working directory: your project, before any recording code lands
- Expected result: an exclusion list for your app plus a redaction JSON block for every export

``` text
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)

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](https://mindful-mango-accy.here.now/agent-markers.js) on this site.)

    ``` text
    /**
     * 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.

    ``` text
    /* 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.

    ``` text
    #!/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.

``` text
curl -sO https://mindful-mango-accy.here.now/sample-session.json
node scripts/make-agent-packet.mjs sample-session.json
```

``` text
# Debug packet — marker <demo-marker>

- session: <demo-session> (started the recorded snapshot)
- 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.

## Complete reusable setup contract

## Debugging with Markers — agent setup guide

Following this file sets up: a just-in-time debug-capture loop in the user's web app — a ~150-line dependency-free recorder (semantic event trail + human markers), a mark hotkey, a redacted JSON export, and a renderer that turns exports into agent-ready debug packets.

Placeholders used below: `<project-root>` = the project you are working in; `<static-dir>` = wherever that app serves static JS from (often `public/` or the app's HTML directory). All other paths are literal.

Human companion pages on this site (for your user, not needed to execute this file): the section guide at https://mindful-mango-accy.here.now/, a Session Replay of the captured run this file's success check reproduces at https://mindful-mango-accy.here.now/replay.html, and a Q&A Dialogue at https://mindful-mango-accy.here.now/dialogue.html.

## Prerequisites

Check each before starting:

```bash
node --version   # need v18 or newer
curl --version   # used only to download the sample session in the success check
```

Expected: Node 18+ and curl present. If a tool is missing, stop and tell your user what to install.

## Steps

1. Create `<static-dir>/agent-markers.js` with exactly this content (same bytes as https://mindful-mango-accy.here.now/agent-markers.js — you may download it instead of typing it):

   ```js
   /**
    * 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. Create `<static-dir>/markers-boot.js` with exactly this content, replacing only `"my-app"` with the app's real name:

   ```js
   /* 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";
   };
   ```

3. Load both files in the app's page BEFORE the app's own scripts (and before any code that replaces `window.fetch` — app-level fetch wrappers such as mocks or auth shims must be installed before `AgentMarkers.start()` runs so their calls land in the trail):

   ```html
   <script src="agent-markers.js"></script>
   <script src="markers-boot.js"></script>
   ```

4. Create `<project-root>/scripts/make-agent-packet.mjs` with exactly this content (same bytes as https://mindful-mango-accy.here.now/make-agent-packet.mjs):

   ```js
   #!/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

Run from `<project-root>`:

```bash
curl -sO https://mindful-mango-accy.here.now/sample-session.json
node scripts/make-agent-packet.mjs sample-session.json
```

Expected observable result: a markdown debug packet beginning `# Debug packet — marker <demo-marker>`, containing the testimony line `> It said Saved but my note never reached the server — this happened right after I reconnected.`, a 9-event evidence trail whose last line is `- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]`, four redaction receipts, a task section, and a claims boundary.

Then perform the cold-read check: read that packet with NO other context (do not open the recorder source or this page) and state one specific hypothesis for the failure. A passing hypothesis names the mechanism, e.g. "the reconnect rotated or invalidated a session credential the client still holds, and the app treats the resulting 401 as success."

Finally, verify the loop live in the user's app: open it in a browser, press Ctrl/Cmd+M (or run `window.__AGENT_MARKERS__.mark("user-flag", "test marker")` in the console — `prompt()` blocks automation), then run `exportMarkers()` in the console. Confirm a `session-*.json` file downloads with `markers.length >= 1` and a `redaction` block.

Report to your user: what you set up, the packet output of the success check, your cold-read hypothesis, and anything you had to adapt.

## Notes for agents

- `prompt()` blocks scripted browsers. In automation, call `window.__AGENT_MARKERS__.mark(label, note)` instead of the Ctrl/Cmd+M hotkey.
- On macOS, Cmd+M can collide with the browser's minimize shortcut. The console call or an on-page button wired to the same `dropMarker` logic is the reliable path.
- The event ring buffer is in-memory only — a page reload wipes it. Export before navigating or reloading.
- `make-agent-packet.mjs` exits with `unsupported schemaVersion` unless the export has `schemaVersion: 1`. Exports from this recorder always do; hand-edited files may not.
- The export deliberately excludes storage values, request/response bodies, and raw user text (preview+length only). Do not "improve" it by adding them — the redaction block inside every export is the audit trail readers rely on.
- The recorder caps the trail at 200 events and pins the 12 nearest event ids to each marker (`maxEvents` / `nearbyEventLimit` options on `AgentMarkers.start`). If packets read too thin, raise `nearbyEventLimit` before adding new event types.

## Original references

- [Human testimony joined to runtime evidence](https://mindful-mango-accy.here.now/)
- [Public setup contract](https://mindful-mango-accy.here.now/agent.md)
