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.
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.
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);
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";
};
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>
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"));
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.
prompt() blocks scripted browsers. In automation, call window.__AGENT_MARKERS__.mark(label, note) instead of the Ctrl/Cmd+M hotkey.dropMarker logic is the reliable path.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.maxEvents / nearbyEventLimit options on AgentMarkers.start). If packets read too thin, raise nearbyEventLimit before adding new event types.# 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.