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 mrk-1-mro9e75t, 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

# 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 mrk-1-mro9e75t`, 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.