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.

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.

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
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
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
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 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 <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:

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):

    /**
     * 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:

    /* 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):

    <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):

    #!/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>:

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.

Source references