{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-debug-marker",
  "slug": "debug-marker",
  "title": "Mark the debug moment before handoff",
  "summary": "Logs show what happened. A marker says which moment mattered.",
  "category": "Verification",
  "tags": [
    "debugging",
    "agent-markers",
    "evidence"
  ],
  "sources": [
    {
      "label": "Codex workflows companion",
      "url": "https://lapis-fossil-vsbc.here.now/#debug-marker"
    },
    {
      "label": "Published workshop recording",
      "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
    }
  ],
  "sourceUnits": [
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md",
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff",
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/The Problem",
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Bounded Debug Packets",
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Smallest Setup",
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/The Data Model",
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Privacy Defaults",
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Test Runner And Agent Handoff",
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Clean Up",
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Copyable Artifact: Bounded Debug Packet",
    "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Claim Boundaries",
    "src/lib/content/sections.ts",
    "src/lib/content/sections.ts#debug-marker",
    "src/lib/content/sections.ts#recordingSpans"
  ],
  "collection": "codex",
  "categoryId": "verification",
  "wordCount": 1080,
  "url": "/topics/codex-debug-marker/",
  "markdownUrl": "/markdown/codex-debug-marker.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-debug-marker.json",
  "headings": [
    {
      "id": "the-problem",
      "text": "The Problem",
      "level": 2
    },
    {
      "id": "bounded-debug-packets",
      "text": "Bounded Debug Packets",
      "level": 2
    },
    {
      "id": "smallest-setup",
      "text": "Smallest Setup",
      "level": 2
    },
    {
      "id": "the-data-model",
      "text": "The Data Model",
      "level": 2
    },
    {
      "id": "privacy-defaults",
      "text": "Privacy Defaults",
      "level": 2
    },
    {
      "id": "test-runner-and-agent-handoff",
      "text": "Test Runner And Agent Handoff",
      "level": 2
    },
    {
      "id": "clean-up",
      "text": "Clean Up",
      "level": 2
    },
    {
      "id": "copyable-artifact-bounded-debug-packet",
      "text": "Copyable Artifact: Bounded Debug Packet",
      "level": 2
    },
    {
      "id": "claim-boundaries",
      "text": "Claim Boundaries",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Mark the debug moment before handoff\n\nLogs show what happened. **A marker says which moment mattered.**\n\nUse **[Agent Markers](https://github.com/johnlindquist/agent-markers)** when a bug appears during real app use and the next agent needs more than a sentence and a screenshot. The move is to mark the decisive moment while it is happening, capture nearby runtime evidence, add the human explanation, review the packet, and export only what is safe to share.\n\n```text\nmark -> capture -> explain -> review/export\n```\n\n## The Problem\n\nYou found the bug while using the app. The checkout button stayed disabled, the billing retry fired twice, the auth session rotated at the wrong time, or the date rendered in the wrong format.\n\n> We're interacting with an app, we're clicking on buttons, and we're typing in fields, and then something happens, and we want to be able to capture that specific moment. We don't want to have to quit our app, start up debugging mode.\n>\n> — John Lindquist\n\nThe old ritual is expensive:\n\n- add temporary logs\n- reproduce the bug\n- forget which log line mattered\n- remove the logs\n- hope the next agent understands the state you saw\n\nA debug marker **preserves the moment** without turning the whole session into a permanent logging project.\n\n## Bounded Debug Packets\n\nA **bounded debug packet** is a small export centered on one marked moment.\n\nIt can include:\n\n- the marker label and note\n- nearby console, fetch, error, unhandled rejection, and manual events\n- route, viewport, and environment metadata\n- optional DOM or screenshot evidence\n- the privacy review boundary\n- the first verification command for the next agent\n\nIt is not a replay system, production telemetry, a browser extension, a server product, or an AI product. It is a reviewed packet for debugging work.\n\n## Smallest Setup\n\n```ts\nimport { createAgentMarkers } from \"<verified-agent-markers-client>\";\n\nconst markers = createAgentMarkers({\n  appName: \"checkout-demo\",\n  exposeGlobal: true\n});\n\nawait markers.mark(\"Checkout button stayed disabled\", {\n  note: \"Expected it to enable after selecting shipping.\",\n  tags: [\"checkout\", \"regression\"]\n});\n\nconst session = markers.export();\n```\n\n`createAgentMarkers` sets up a browser-side collector. It can mark moments, record manual events, export a `DebugSession`, optionally expose a dev/test global, and clean itself up with `stop()`.\n\n## The Data Model\n\n| Concept | Practical Meaning |\n|---|---|\n| `DebugSession` | One bounded debugging run: app name, session id, environment, markers, and events. |\n| `DebugMoment` | The human marker: label, note, tags, severity, environment, optional data, optional DOM/screenshot evidence, and `nearbyEventIds`. |\n| `CapturedEvent` | Runtime evidence near the marker: console, fetch, error, unhandled rejection, or manual event. |\n| `nearbyEventIds` | The bridge between the marked moment and the runtime events captured near it. |\n| export JSON | The reviewed packet that can be attached to a test run, issue, or agent prompt. |\n\nThe useful part is **the link between the human explanation and the runtime trail**. Without `nearbyEventIds`, the agent gets a label and starts guessing. With it, the agent gets a bounded slice of the session.\n\n## Privacy Defaults\n\nField rule: **metadata first, values only after review**.\n\nAgent Markers is designed around a local review boundary:\n\n- data stays in memory until explicit export\n- storage capture records key names and counts by default, not values\n- fetch capture records metadata and does not read request or response bodies\n- treat raw exported sessions as private until reviewed and redacted\n\n**Do not share raw exported sessions.** Review and redact private routes, screenshots, stack traces, request URLs, user-entered text, tokens, cookies, account data, local paths, and application-specific identifiers.\n\n## Test Runner And Agent Handoff\n\nIn dev and test, `exposeGlobal: true` gives a test runner a browser handle:\n\n```text\nwindow.__AGENT_MARKERS__\n```\n\nA browser test can reproduce the bug, call `mark(...)`, export JSON to a private test artifact, and attach or share only a reviewed and redacted packet. The next agent gets **a bounded packet instead of a vague report**.\n\n> You can take that kind of entire session, you can copy and paste the logs into your agent. And tell it, please review for the markers and help me get this fixed.\n>\n> — John Lindquist\n\nTreat the redaction helper below as project-specific review code, not an Agent Markers API.\n\n```ts\nconst session = await page.evaluate(async () => {\n  await window.__AGENT_MARKERS__.mark(\"checkout disabled unexpectedly\", {\n    note: \"Expected submit to enable after terms and shipping were selected.\"\n  });\n\n  return window.__AGENT_MARKERS__.export();\n});\n\nconst redactedSession = redactAgentMarkerSession(session);\n\nawait testInfo.attach(\"agent-markers.redacted.json\", {\n  body: JSON.stringify(redactedSession, null, 2),\n  contentType: \"application/json\"\n});\n```\n\nImport from the reviewed Agent Markers client in the current project. Verify the package or workspace path before turning this into executable setup.\n\nThe handoff prompt should tell the agent:\n\n- what the human expected\n- what happened instead\n- which event ids are nearby\n- what is intentionally redacted\n- where to start verification\n- what not to infer from missing data\n\n## Clean Up\n\nCall `stop()` when the collector is done.\n\nThe collector installs capture hooks for useful evidence. `stop()` disposes those hooks. After `stop()`, treat the collector as finished instead of continuing to mark new moments.\n\n## Copyable Artifact: Bounded Debug Packet\n\n```text\nMarker:\n- label:\n- note:\n- expected:\n- actual:\n- next action:\n\nSession:\n- schemaVersion:\n- sessionId:\n- appName:\n- markerId:\n- nearbyEventIds:\n\nIncluded evidence:\n- console:\n- fetch:\n- error:\n- unhandledrejection:\n- manual:\n- DOM or screenshot availability:\n\nPrivacy review:\n- storage values exported? no\n- request bodies exported? no\n- response bodies exported? no\n- private routes removed?\n- user-entered text removed?\n- stack paths reviewed?\n- screenshot reviewed?\n\nHandoff:\n- first verification command:\n- files or areas to inspect:\n- what the agent must not infer:\n- stop condition:\n```\n\nExample prompt:\n\n```text\nUse this bounded debug packet to investigate the checkout disabled-state bug.\n\nStart from the marker note and nearbyEventIds.\nDo not assume redacted fields are absent in the app.\nInspect the checkout form state, shipping selection flow, and submit-button disabled logic.\nReturn the likely cause, smallest patch plan, and first verification command before editing.\n```\n\n## Claim Boundaries\n\nAgent Markers gives the next agent a better packet. It does not guarantee the agent will find the defect automatically.\n\nUse it for local development, browser tests, and reviewed debugging artifacts. Verify any production use, data retention policy, screenshot capture, source-map behavior, and privacy implications before adopting it in a real product.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#debug-marker)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
}
