agenticreplay 0.1.0 → 0.1.2

package/docs/agenticreplay-acceptance.md

@@ -1,135 +0,0 @@
-# AgenticReplay 0.5.0 acceptance
-
-This checkout implements a clean break from OrcaReplay. New traces use schema 0.4.0 and
-`agenticreplay_version`. Old archives and traces are rejected; existing user data is not migrated
-or deleted. Package names, commands, environment variables, owned paths, and public recorder
-symbols use AgenticReplay. Upstream attribution and real external protocol identifiers remain.
-
-## Recording contract
-
-`net.request` start evidence is persisted before dispatch. Every physical attempt has a request
-identifier. Body evidence and terminal outcomes are separate from logical `model.*` navigation
-events. Replay selects complete transport pairs; a logical response alone is insufficient.
-Cross-provider forks retain the serving provider's actual request and response bodies. Those
-origin records are excluded from direct replay because the client received a translated response.
-
-Capture completeness, upstream HTTP/transport outcome, and agent exit status are independent.
-A fully recorded HTTP 500 may be complete. An interrupted 200 response is incomplete. A child
-process exiting zero with no observed API traffic does not prove capture: recording returns exit 2.
-
-Bodies are buffered in memory up to 64 MiB by default. Configure the per-body and concurrent
-buffer limits with `--max-body-bytes` and `--max-buffered-bytes`. No plaintext temporary HTTP body
-files are used. Resource exhaustion, failed persistence, unsupported bodies, and missing evidence
-remain explicit incomplete states. The limit is a body-buffer policy, not an operating-system
-resident-memory ceiling.
-
-Whole-body redaction precedes inline or atomic blob persistence. Unknown provider fields and
-text survive. Transformation records identify the rule, location, count, and reason without
-containing removed credentials. Persisted redacted body bytes have their own SHA-256 digest.
-Blob digests cover the JSON storage wrapper; body downloads remove that wrapper.
-
-Capture starts at the named HTTP proxy or process-local fetch boundary. It cannot recover
-provider-hidden reasoning or SDK transformations before that boundary. Node fetch normalization
-is distinct from wire bytes. `canonical_exact` in terminal output and `canonicalExact` in CLI JSON
-describe replay matching, not raw-body equality.
-
-## Reproduce the local checks
-
-```sh
-npm ci
-npm run check
-node scripts/conformance.mjs
-node scripts/fidelity.mjs --check
-node scripts/check-neutrality.mjs
-node scripts/installed-smoke.mjs
-```
-
-The CI workflow installs the required framework dependencies before running:
-
-```sh
-node test/integrations/run.mjs --require-all
-python test/integrations/agents/crewai_model_names.py
-python test/integrations/agents/llama_index_model_names.py
-```
-
-The independent API oracle covers Responses, Chat Completions, Anthropic Messages, and DeepSeek
-Messages over JSON and SSE, with bodies above 1 MiB and a secret split across response writes.
-Its expected redactions are explicit test expectations, not the recorder's redaction code.
-Dedicated proxy, TLS, core, and instrumentation suites cover HTTP/2, layered encodings, repeated
-headers, limits, cancellation, concurrency, connection failures, and storage failure.
-
-## Companion Kiokuko DSH
-
-The changes are supplied in [`companion-kiokuko-dsh.patch`](../companion-kiokuko-dsh.patch), against
-Kiokuko DSH commit `a4f029ff78d50124ee464963850a72b2a384fb8`. The working companion checkout for this
-implementation is `/private/tmp/agenticreplay-companion-kiokuko-dsh`.
-
-The native recorder installs process-local transport capture before provider calls, carries
-session/model-call scope through async iteration, and writes transport and logical evidence
-through the shared AgenticReplay writer. The HTTP-capture capability depends on transport
-installation. Missing evidence or correlation marks the trace incomplete. Owned DSH configuration,
-commands, source files, database tables, and public symbols are renamed. Historical database
-migrations retain their identifiers; migration 034 creates the new recording surfaces.
-
-## Verification boundary
-
-Local fixture results are not live-provider verification. CI now targets Node 24 and 26;
-remote CI has not been run for these uncommitted changes. Docker builds from this checkout's
-tarballs, and CI includes a Docker build gate; Docker is not installed in the local environment,
-so its build and runtime remain unverified locally.
-
-Fresh Python wheel installation passes 255 tests. All 22 required framework integrations pass
-without skips. Native pinned DSH 0.1.5-rc.1 recording acceptance passes 65 tests against rebuilt
-AgenticReplay packages; the companion default unit suite has 832 passes and 44 opt-in skips,
-reported separately from native acceptance. A clean npm-ci checkout on Node 24.0.0 and Python 3.12 passes 3,087 tests with 41 opt-in skips. Formatting, TypeScript,
-conformance (72 events), fidelity (3 canonical matches, no regressions), and neutrality pass.
-All 12 renamed npm tarballs declare `node >=24.0.0` and install together in a fresh consumer and pass CLI recording,
-inspection, HTML export, offline replay, and MCP tool-identity checks.
-
-Claude Code 2.1.220 and OpenCode 2.0.18 pass independent endpoint comparisons with a synthetic
-MCP tool roundtrip and the published Kiokuko 1.0.26 MCP server active. Each client's captured model
-requests contain real Kiokuko tool schemas; the Kiokuko process receives initialization and
-`tools/list`. This uses isolated client configuration and the final installed AgenticReplay tarballs.
-The independent endpoint oracle matches all 3 Claude Code and 4 OpenCode request/response pairs,
-including system text, actual tool schemas/results, and the trailing stream sentinel.
-OpenCode 2.0.18 also passes two native custom-provider loopback cases using the adapter's exact
-emitted arguments and configuration. Version detection recognizes its `opencode v2.0.18` banner;
-the launch uses a private server and the native `http.request` plugin. All seven OpenCode capture
-checks pass on Node 24.0.0, including native API-key and OAuth fixtures seeded in the v2 credential
-store, two custom origins, replay, and disabled-interception detection. Existing `OPENCODE_CONFIG`
-overrides and explicit remote-server attachment remain rejected for version 2.
-
-The follow-up source check on Node 24.0.0 passes 3,089 tests with 41 opt-in skips; the affected
-proxy, adapter, TLS and Python-bootstrap suites separately pass 997 tests. All 12 final tarballs
-install together and pass the distribution smoke checks.
-
-Following explicit authorization, the remaining native clients were run with synthetic credentials
-and isolated configuration. Codex 0.153.4 rejects reserved built-in provider overrides and ignores
-`OPENAI_BASE_URL`; the adapter now uses `openai_base_url` for its built-in provider. Installed-package
-acceptance verifies complete HTTP request/response bodies against an independent endpoint, including
-system instructions and tool schemas. This Codex version first attempts WebSockets: these unsupported
-attempts are now recorded as incomplete instead of silently returning 404. HTTP fallback is captured,
-but the overall run correctly exits 2. WebSocket frame capture remains unsupported.
-
-Hermes dce1e9b37581 (Python 3.14.7, OpenAI SDK 2.24.0) uses OS-backed Python truststore contexts that
-ignore the standard CA environment variable. The process-local bootstrap now adds the run CA while
-retaining certificate verification and platform roots. Installed-package acceptance matches all three
-HTTP request/response pairs against the independent TLS endpoint (main model call, auxiliary model
-call, and model catalog). System text, 24 tool definitions, and trailing SSE content survive capture.
-This runtime also resets a TLS session; the failure is persisted and the run correctly stays incomplete
-with exit 2. Successful HTTP body comparisons do not establish complete session coverage.
-
-Reproduction scripts are `scripts/codex-client-acceptance.mjs` and
-`scripts/hermes-client-acceptance.mjs`; both accept `AGENTICREPLAY_TEST_CLI` and
-`AGENTICREPLAY_TEST_TRACE_READER` for installed-package validation. Hermes additionally requires
-`AGENTICREPLAY_TEST_HERMES` naming its isolated executable. The Hermes fixture uses nip.io DNS for a
-loopback origin outside proxy exclusions. A synthetic-key Codex request reached OpenAI and received
-401 during diagnosis; no successful authenticated live-provider generation was tested. Remote CI
-and Docker remain unverified. No real credentials, personal configuration changes, commits, or pushes
-were used.
-
-The Node minimum is consistent across all npm manifests, the lockfile, the CLI doctor check,
-release workflows, Docker images, documentation, and the DSH companion. CI and release test jobs
-explicitly install Python 3.12 because the TypeScript suite also launches Python fixture agents.
-The 22 required framework integrations also pass on exactly Node 24.0.0. These are local CI-command
-results on macOS; GitHub's Linux jobs and Docker remain separate unexecuted gates.

package/docs/architecture.md

@@ -1,160 +0,0 @@
-# Architecture
-
-## The observation everything rests on
-
-Model APIs are stateless. On every turn an agent resends the entire conversation — including the
-previous turn's `tool_result` blocks. So a proxy in front of the model sees the whole loop: each
-request, each streamed response, every tool call the model emitted, and every tool result the
-harness produced.
-
-**This is why AgenticReplay does not patch your agent.** One well-placed interception point yields a
-near-complete execution graph for any agent that talks to a model over HTTP.
-
-Two honest limits come with it, and they shape everything else:
-
-1. You see a tool result **one turn late** — it arrives with the next request.
-2. You see the harness's **rendering** of the result, often truncated, not the raw bytes.
-
-The three supplementary capture layers exist to close that gap where it matters.
-
-## Capture layers
-
-```
-agent process ──(base-URL env redirect)──▶ agenticreplay proxy ──(verbatim)──▶ provider API
-agent process ──(rewritten MCP config)───▶ agenticreplay mcp-shim ─(unmodified)▶ MCP servers
-workspace ─────(snapshot per turn)───────▶ shadow git index
-                                              │
-                                              ▼
-                            .agenticreplay/runs/<id>/{manifest,events.jsonl,blobs,fs}
-```
-
-| Layer | Mechanism | Confidence | Fallback |
-|---|---|---|---|
-| Model calls | `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` injected into the child; proxy speaks the native wire protocol and tees a canonical copy while streaming through | high | none — a harness that ignores those variables is not captured |
-| Tools & results | free — reconstructed from the protocol | high | — |
-| MCP | config rewritten to launch `agenticreplay mcp-shim -- <original>`, a transparent JSON-RPC tee | high | protocol layer, one turn late |
-| Shell | `PATH` shim in front of `sh`/`bash`, capturing argv, exit code, duration, stdout/stderr split | medium | protocol layer gives the command and merged output |
-| Filesystem | shadow git index (`--git-dir=.agenticreplay/runs/<id>/fs --work-tree=.`), one snapshot per turn | high | — |
-| Network | not captured | — | — |
-
-Reusing git plumbing for the filesystem layer gives content-addressed storage, cheap diffs,
-`.gitignore` handling and worktree materialization — the exact four things fork replay needs — for
-about a hundred lines of code.
-
-The tee on the model layer is a real tee: chunks are written to the agent as they arrive and the
-copy we keep is assembled on the way past. Buffering the response first would make every turn of
-an interactive session appear to hang for its full duration, because the agent's own progressive
-rendering has nothing progressive left to render. One path is the exception — a **cross-provider
-fork**, where the agent asked one provider and a different one answered. Translating a reply means
-having all of it, so that path reads the upstream response to completion, converts it, and only
-then writes. It costs the streaming, and it applies only to a fork that deliberately changed
-provider; recording never takes it.
-
-**There is no CA mode, opt-in or otherwise.** Nothing in the tree generates a certificate,
-terminates TLS or touches a trust store. Capture is base-URL redirection and nothing else, so an
-agent that ignores `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL` and `OPENAI_API_BASE` is simply not
-captured today. Whether to build one, and under what constraints, is written down in
-[SECURITY.md](../SECURITY.md); it is a design question, not a flag that exists and is switched off.
-
-Non-model HTTP is not captured either. `net.request` and `net.response` are reserved in the format
-(spec §2.3) and the viewer renders them, but no writer emits one. The proxy is an origin server,
-not a forward proxy: it matches `/v1/messages` and the chat-completions paths, answers everything
-else with a 404, and registers no `CONNECT` handler — so pointing a child's `HTTPS_PROXY` at it
-would get its tunnel request dropped rather than recorded. Out of scope for v0, and with no partial
-capture to misread.
-
-### Auth, verified against a real agent
-
-Claude Code under a subscription login authenticates with its **own** `authorization: Bearer`
-header and ignores an injected `ANTHROPIC_API_KEY`. So the proxy forwards auth headers upstream
-verbatim while never writing them to the trace — §7 forbids *recording* auth material, which is a
-different requirement from relaying it. A proxy that dropped the header would break the agent
-outright, and only for subscription users, which is the worst kind of bug to ship.
-
-It also probes `GET /v1/code/agent-proxy/ca-cert` and a websocket upgrade at
-`/v1/code/agent-proxy/ws`. The proxy answers both with a clean 404 rather than an error — the
-upgrade included, because nothing listens for the server's `upgrade` event and node then hands the
-request to the ordinary handler, which 404s it like any other unmatched path. (`CONNECT` is the one
-node closes when nothing listens for it, which is the other half of why `HTTPS_PROXY` is not a
-capture route.)
-
-One capture gap follows from the same place: a Codex CLI signed in with a ChatGPT subscription
-talks to its own backend rather than the OpenAI API base URL, so base-URL redirection alone does
-not capture that auth mode. OpenCode's provider-OAuth logins carry the same shape of risk.
-
-## Three modes, one proxy
-
-Exact, fork and compare are not three subsystems. They are one proxy with a **cursor**: the
-position in the recorded event stream where it stops serving from disk and starts serving from the
-network.
-
-| Mode | Cursor | Behaviour |
-|---|---|---|
-| Exact | end | Every response served from the trace. Egress blocked at the socket, not merely discouraged. |
-| Fork | *n* | Serve from the trace below *n*, live at and above it. Filesystem materialized from the checkpoint tree. |
-| Compare | *n* × N | *N* forks from one checkpoint, isolated worktrees, run one after another, then a verdict table. |
-
-A fork is recorded as a new run carrying `parent_run` and `fork_point`, so forks of forks work with
-no extra machinery.
-
-Compare runs its forks **sequentially**, and that is deliberate rather than unfinished. Each fork
-spawns a real agent against a real worktree; running four of those concurrently on one machine
-measures the machine, not the models. The wall-clock column would be the first casualty, and it is
-a column people compare.
-
-## Divergence
-
-Agent harnesses are not deterministic — timestamps, UUIDs, working directories, context compaction
-firing at a different point. A recorded request frequently will **not** be byte-identical to the one
-the agent makes on replay.
-
-Matching runs as a ladder, and the rung that matched is always reported:
-
-| Rung | Strategy | Result |
-|---|---|---|
-| 1 | canonical hash of the normalized request | exact, no event |
-| 2 | same turn index and message count, structural distance under threshold | `divergence` minor |
-| 3 | identical trailing message, different prefix | `divergence` major |
-| 4 | no match | halt and report; `--loose` continues live |
-
-**Replay never silently approximates.** Where an inexact match ends up depends on the mode, because
-only one of them is writing a trace. A fork produces a new run, so each divergence below its fork
-point is written into the child's trace as a `divergence` event carrying the rung and the level. An
-exact replay produces no trace at all — it is reproducing a run, not recording one — so its
-divergences are printed as they happen, counted in the closing `replay.done` line, and an unmatched
-request halts the replay and makes the exit code non-zero even if the agent exited 0. Either way
-you are told. A debugger that quietly guesses is worse than no debugger, because you will believe
-it.
-
-The share of runs replaying clean at rung 1 would be the best single health metric for the project.
-**Nothing measures it yet.** The rung that matched is recorded per divergence inside a forked run's
-trace, but no code aggregates those across runs, and the recorder sends no telemetry there would be
-anything to aggregate from. Per-adapter and per-harness-version numbers need a harness that replays
-a corpus of traces and tallies the outcome — worth building, and not built.
-
-## Checkpoints are derived
-
-A checkpoint is any `seq` with a complete conversation prefix and a filesystem tree from the same
-turn, so the recorder never has to guess where you might want to fork. A `--from N` that lands
-between two snaps to the nearest preceding checkpoint **and says so** — silently forking from the
-wrong state is the worst bug this project could ship.
-
-## Why blobs are load-bearing
-
-Because every turn resends the whole conversation, naive capture is `O(n²)` in turns. Content
-addressing makes the resent prefix dedupe to nothing, so storage is `O(n)` in new content. This is
-not an optimisation to defer: without it the recorder is unusable on exactly the long, interesting
-runs people want to debug.
-
-## Package graph
-
-```
-schema ──────┬──▶ core ──┬──▶ proxy ──▶ cli
-plugin-api ──┤           ├──▶ fs-capture
-             ├──▶ providers ──────┘
-             └──▶ adapters
-                  viewer ──▶ cli
-```
-
-`schema` and `plugin-api` are the contracts. Everything else compiles against them, which is what
-keeps the format from becoming TypeScript-shaped.

package/docs/fidelity.md

@@ -1,16 +0,0 @@
-# Replay fidelity
-
-<!-- Generated by scripts/fidelity.mjs. Do not edit by hand. -->
-
-Every recording below is replayed with the network off and the numbers asserted. A turn the
-recording cannot serve — `unmatched` — has a budget of zero, because a replay that has to go
-and ask a model is not a replay. `canonical_exact` counts turns matched after canonical normalization; a floor is
-set per entry so fidelity carried by the match ladder rather than by the capture shows up as
-a regression rather than as a pass.
-
-| Harness | Canonical exact | Unmatched | Divergences | Live calls | Budget |
-|---|---|---|---|---|---|
-| a Node agent over chat completions | 3 | 0 | 0 | 0 | canonical exact ≥ 3, divergences ≤ 0 |
-
-- **a Node agent over chat completions** — the run `agenticreplay quickstart` ships and replays on every invocation
-

package/docs/good-first-issues.md

@@ -1,78 +0,0 @@
-# Good first issues
-
-Real work, scoped so the first PR is a few hours rather than a weekend. Each one names the file to
-start in and how you will know it worked.
-
-The four categories are ordered by how much they help the project: an adapter brings a whole
-agent's userbase, a provider unlocks a model nobody could fork onto, a redaction rule protects
-everyone, and an analyzer proves the trace format is useful to people who did not write it.
-
-## Adapters — support an agent we don't cover
-
-**Start:** `packages/adapters/src/generic-openai.ts` is the smallest complete example.
-**Done when:** `checkAdapterContract` passes and `packages/adapters/fixtures/harness/<id>.json`
-records the env vars you verified against.
-
-1. **Aider adapter.** Python-based; check whether it reads `OPENAI_API_BASE`.
-2. **Continue adapter.** VS Code extension — the interesting question is where its model config
-   lives and whether a base URL can be injected per-process.
-3. **Cline adapter.** Same shape as Continue; if neither can be pointed at a base URL per process,
-   there is nothing to fall back on — base-URL injection is the only capture mechanism there is,
-   and no CA mode exists. Finding that out is still a result worth writing down.
-
-**Before writing one, answer one question:** does the agent respect a base-URL environment
-variable? That single fact decides whether this is an afternoon, a week, or not possible yet. Put
-the answer in the issue even if you write no code — it is genuinely useful on its own.
-
-**And answer it by running the harness, not by reading its docs.** The goose adapter — which used
-to be item 4 on this list — is the argument for that. goose does respect a base-URL variable, so
-the question above says "an afternoon". What running it revealed is that it reads `OPENAI_HOST`
-*ahead of* `OPENAI_BASE_URL`, and that it does not read `ANTHROPIC_BASE_URL` at all. An adapter
-written from the docs would have set the usual variables, passed every check, and produced empty
-traces for anyone who already had `OPENAI_HOST` exported. Point the harness at a sink server and
-read the request line back; it takes ten minutes and it is the only part of this nobody can guess.
-
-## Providers — a model you can't currently fork onto
-
-**Start:** `packages/providers/src/openai.ts`. Most APIs are OpenAI-shaped and need only a new
-entry in `pricing.ts` plus a registry line.
-**Done when:** round-trip translation tests pass and `priceFor` resolves your model's real id.
-
-5. **Google Gemini provider.** The one major API that is not OpenAI-shaped; needs real translation.
-6. **AWS Bedrock provider.** Model id resolution is the interesting part — `pricing.ts` already
-   handles the `us.anthropic.…-v1:0` form, so start there.
-7. **Pricing table refresh.** `MODEL_PRICING` will drift. A PR that updates figures and cites the
-   source pages is welcome and easy to review.
-
-## Redaction rules — a secret shape we miss
-
-**Start:** `packages/core/src/redaction.ts`.
-**Done when:** a test proves the shape is caught *and* a test proves a realistic near-miss is not.
-
-8. **More key shapes.** Stripe (`sk_live_`), Twilio, SendGrid, npm tokens, Postgres connection
-   strings with inline credentials.
-9. **False-positive hunting.** The entropy rule already needed a mixed-alphabet guard because
-   `getUserAuthenticationTokenFromRequestHeaders` scores 4.08 bits/char. Traces are mostly source
-   code, so a PR that adds realistic code samples the redactor must *not* touch is as valuable as
-   one that adds a rule.
-
-## Analyzers — read a trace, find something useful
-
-**Start:** `detectLoops` in `packages/viewer/src/render.ts` — about forty lines, no privileged
-access, the model to copy.
-**Done when:** it runs against `examples/traces/` and finds the thing it claims to find.
-
-10. **Cost attribution by turn.** Which turn of a run actually spent the money.
-11. **Thrash detector.** A file edited three or more times across turns with the tree returning to
-    an earlier state — a loop the current detector misses because the tree is not identical.
-12. **Context growth analyzer.** Plot input tokens per turn; a run that grows superlinearly is
-    usually re-reading the same files.
-
-## Before you start
-
-Read [CONTRIBUTING.md](../CONTRIBUTING.md). The short version: write the failing test first and
-watch it fail for the reason you expect, no new runtime dependencies without discussion, and if
-you change the trace format, change `spec/agenticreplay-trace-v0.md` in the same PR.
-
-Say hello on the issue before starting something large — we would rather have the conversation
-early than have you guess.

package/docs/how-to/compare-models-on-the-same-failure.md

@@ -1,58 +0,0 @@
-# Would a different model have got this right?
-
-The usual way to answer this is to re-run the whole task on another model and squint at the
-result. That measures the task setup as much as the model — different starting state, different
-conversation, different luck.
-
-Forking answers it properly: **same task, same files, same conversation prefix, one variable.**
-
-## Fork one model
-
-```console
-agenticreplay checkpoints last
-agenticreplay replay last --from 17 --model glm-5.3-flash
-```
-
-Everything before checkpoint 17 is served from the recording, so it is identical by construction.
-From 17 onward the agent runs live on the new model, in a scratch worktree.
-
-## Compare several at once
-
-```console
-agenticreplay compare last --from 17 \
-  --models claude-opus-5,gpt-5.2,glm-5.3-flash,qwen3-coder \
-  --verify 'npm test'
-```
-
-```
-MODEL          VERDICT  TOKENS   COST       WALL   RUN
-claude-opus-5  pass     186k     $5.81      312s   run_5140e2
-gpt-5.2        pass     215k     $3.42      278s   run_ee55fa
-glm-5.3-flash  pass     200k     $0.61      242s   run_85d55e
-qwen3-coder    fail     178k     $0.29      191s   run_a71e08
-```
-
-**`--verify` matters more than it looks.** Without it, `pass` only means the agent exited without
-crashing — not that the task got done. With it, the verdict is the exit code of a command you
-chose, run inside that fork's worktree.
-
-Each row is a real child run with its own trace. To see what a model actually did:
-
-```console
-agenticreplay replay run_a71e08 --ui
-```
-
-## Share the result
-
-```console
-agenticreplay compare last --from 17 --models ... --verify 'npm test' --share result.svg
-```
-
-One self-contained SVG, no external references, that renders anywhere. It carries the fork point
-and the verify command alongside the numbers, so the comparison cannot be quoted without saying
-what it measured.
-
-## The caveat worth stating
-
-An unknown model prices as `—`, never `$0.00`. A confidently wrong cost is worse than an absent
-one when it lands in a table someone makes a decision from.

package/docs/how-to/debug-a-failing-agent-run.md

@@ -1,127 +0,0 @@
-# My agent broke something. How do I find out why?
-
-You ran a coding agent, it changed files, tests fail, and the terminal has scrolled. Re-running
-gives you a different failure. This is the situation AgenticReplay exists for.
-
-## 1. Record the run
-
-```console
-agenticreplay record claude
-```
-
-Your agent runs normally. Nothing about it is patched — it is started with a couple of environment
-variables pointing its model traffic at a local proxy, and that is the whole trick.
-
-When it finishes (or you `^C` it), you get a run id.
-
-## 2. Look at what happened, in order
-
-```console
-agenticreplay show last
-```
-
-```
-run_9f2c14a03b71  claude-code@0.1.0  21 events  exit 0
-
-SEQ  KIND   WHAT                                           DETAIL
-0    RUN    run started                                    claude-code
-1    SNAP   tree 6b1f0c9d2e4a8c53d1b0f7a2c96e4d38b5170ae9  0 changed
-2    MODEL  claude-opus-5                                  1 messages
-3    MODEL  claude-opus-5                                  stop: tool_use · 8,412 in · 214 out
-4    TOOL   edit_file                                      {"path":"src/auth.ts","content":"const ok = true;\n"}
-5    SNAP   tree dc61276f6baa4b3986276ae9ace6df230399788e  1 changed
-6    FILE   src/auth.ts                                    modified +14 −3
-7    TOOL   edit_file                                      ok
-8    MODEL  claude-opus-5                                  3 messages
-9    MODEL  claude-opus-5                                  stop: tool_use · 8,655 in · 190 out
-10   TOOL   run_tests                                      {"suite":"auth"}
-11   SNAP   tree dc61276f6baa4b3986276ae9ace6df230399788e  0 changed
-12   TOOL   run_tests                                      ok
-13   MODEL  claude-opus-5                                  5 messages
-14   MODEL  claude-opus-5                                  stop: end_turn · 8,901 in · 62 out
-15   SNAP   tree dc61276f6baa4b3986276ae9ace6df230399788e  0 changed
-16   SHELL  ["sh","-c","npm test -- auth"]                 /home/you/project
-17   SHELL  shell result                                   exit 1 · 8.4s
-18   SHELL  ["sh","-c","npm test -- auth"]                 /home/you/project
-19   SHELL  shell result                                   exit 1 · 8.2s
-20   RUN    run ended                                      exit 0
-
-warn loop.detected turns=1,2,3 tree=dc61276f
-
-info usage input=22968 output=466 cost=$0.1099
-```
-
-Three things about reading that are worth knowing up front, because each of them has misled
-somebody.
-
-**The failure is in the `SHELL` rows.** There is no `ERROR` row, here or in any recording: the
-format reserves an `error` event type but nothing in the recorder emits one. A command that failed
-appears as a `shell.result` with a non-zero exit code — which is precisely the fact the model never
-gets, since the harness hands it a rendering of the output one turn later.
-
-**`ok` on a `TOOL` row means the result came back, not that it worked.** The tool layer is
-reconstructed from the protocol and does record whether the harness flagged the result as an error,
-but the timeline does not surface that flag today. Read the shell rows for verdicts, not the tool
-rows.
-
-**The `SHELL` rows sit at the end even though they ran in the middle.** The `PATH` shim writes its
-frames to a file, and the recorder drains that file once the agent has exited — so shell events are
-appended last and carry the highest `seq`. Their `ts` and `mono_us` are the real moments they
-happened, so anything sorting by time puts them back where they belong, but `agenticreplay show` and the
-viewer both list a trace in `seq` order, which is append order. Line 17 happened between turns 2
-and 3, not after the run.
-
-## Did it go in circles?
-
-That is the `warn loop.detected` line under the table. It is not an event in the trace: loop
-detection is an analyzer that runs when the trace is *read*, so it will appear against a run
-recorded before the detector existed, and it costs the recorder nothing.
-
-```
-warn loop.detected turns=1,2,3 tree=dc61276f
-```
-
-Three or more consecutive snapshot-bearing turns ending on the same workspace tree — the agent kept
-working and the files stopped moving. Above, the edit on turn 1 landed and then nothing changed
-while the tests were re-run twice.
-
-`detectLoops` in `packages/viewer/src/render.ts` is about forty lines and reads nothing but the
-public format, which is the point: it is the model to copy for an analyzer of your own.
-
-The only `note` events a recording contains are the two `agenticreplay record` writes itself —
-`fs_snapshot_skipped`, when a workspace snapshot failed and that turn has no checkpoint, and
-`unresolved_tool_calls`, when the run ended with a tool call whose result never came back.
-
-## 3. Open the timeline
-
-```console
-agenticreplay replay last --ui
-```
-
-Click a step to see exactly what went in and what came out — the request, the tool result, the
-diff. Press <kbd>space</kbd> to play the run back at the speed it actually happened, which is the
-fastest way to feel where it stalled.
-
-## 4. Reproduce it exactly
-
-```console
-agenticreplay replay last
-```
-
-Every model response is served from the trace and the network is blocked. If it reproduces, you
-have a deterministic loop to work in. If it *doesn't*, AgenticReplay tells you where it diverged
-rather than pretending — that divergence is usually itself the answer.
-
-## What if replay reports divergences?
-
-An agent harness is not deterministic: generated ids, timestamps, context compaction firing at a
-different point. A `minor` divergence is normal. A `major` one means the conversation prefix
-differed — usually compaction — and is worth reading.
-
-If replay halts with `does not match the recording`, the agent asked something the recording never
-saw. `agenticreplay replay last --loose` continues live from that point.
-
-## Next
-
-- [Why did my agent delete that file?](why-did-my-agent-delete-my-file.md)
-- [Would a different model have got this right?](compare-models-on-the-same-failure.md)