@tangle-network/traces 0.23.1 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # traces
 
-> Point `traces` at any agent trace — OTLP spans your own system emits, or the session logs Claude Code, Codex, OpenCode, Pi, Kimi, Factory and Gemini already write to disk. Get failure-mode and efficiency findings, plus a straight answer about what the trace cannot tell you. A CLI *and* an SDK.
+> What your coding agents did, where they wasted time, and whether a run passes: exact answers from the sessions Claude Code, Codex, OpenCode, Pi, Kimi and Factory already write to disk, or from the OTLP spans your own system emits. A CLI and an SDK.
 
 ![traces analyzing a real Claude Code session](https://raw.githubusercontent.com/tangle-network/traces/main/docs/demo.gif)
 
@@ -8,1103 +8,86 @@
 [![license](https://img.shields.io/npm/l/@tangle-network/traces.svg)](./LICENSE)
 [![node](https://img.shields.io/node/v/@tangle-network/traces.svg)](https://nodejs.org)
 
-It reads a run as spans and reports where the agent got stuck, burned tokens, or stopped checking its own work. The deterministic pass runs locally, with no API key and no cost.
-
-There are two ways in, and they are not equal:
-
-| | Use when | How |
-|---|---|---|
-| **Emit the contract** | You control the system | Emit [`@tangle-network/agent-trace-contract`](https://github.com/tangle-network/agent-sdk/tree/main/packages/agent-trace-contract) spans, then `traces analyze --otlp <file\|dir>` |
-| **Adapters** | You do *not* control the format | `traces analyze --harness claude-code` reads a proprietary session store and translates it |
-
-Emitting the contract is the supported way to integrate a new system. The adapters are the legacy edge — they exist because the coding agents write formats nobody standardised, and each one is a translation somebody has to maintain. If you can choose, choose `--otlp`.
-
-## Contents
-
-- [Install](#install)
-- [Quick start](#quick-start)
-- [Gate CI on a trace contract](#gate-ci-on-a-trace-contract)
-- [Integrate your own system](#integrate-your-own-system)
-- [What it finds](#what-it-finds)
-- [Supported harnesses](#supported-harnesses)
-- [CLI reference](#cli-reference)
-- [Live stream](#live-stream)
-- [Watch a run tree](#watch-a-run-tree)
-- [Improvement engine](#improvement-engine)
-- [Ask questions](#ask-questions)
-- [Session facts](#session-facts)
-- [Skill usage](#skill-usage)
-- [Diff two runs](#diff-two-runs)
-- [MCP server](#mcp-server)
-- [Session index](#session-index)
-- [Session bundle](#session-bundle) · [Two views](#two-views-two-consumers)
-- [Policy-mining evidence](#policy-mining-evidence)
-- [Upload to the Intelligence Platform](#upload-to-the-intelligence-platform) · [Check before sharing](#check-before-sharing)
-- [Trace analysts](#trace-analysts)
-- [Agent skills](#agent-skills)
-- [Library (SDK)](#library-sdk)
-- [Examples](#examples)
-- [Audit benchmark](#audit-benchmark)
-- [Develop](#develop)
+Every command except `ask` runs locally, with no key and no cost. Agents: run traces, never parse a session store yourself; the [`inspect-agent-traces`](skills/inspect-agent-traces/SKILL.md) skill maps each question to its command.
 
 ## Install
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/tangle-network/traces/main/install.sh | bash
-traces --version
-
-npx --yes @tangle-network/traces@latest analyze --harness claude-code --last 1  # run without installing
-npm i -g @tangle-network/traces                                           # install manually
-npm i @tangle-network/traces                                              # use it as a library
+npm i @tangle-network/traces    # as a library
 ```
 
-Requires Node ≥ 22.
+Requires Node 22 or later. `install.sh` refuses to overwrite another program's `traces` and names it. Coming from 0.x: [Migrate to 1.0](docs/migrate-1.0.md).
 
 ## Quick start
 
 ```bash
-traces validate spans.otlp.jsonl                  # what can this trace answer?
-traces analyze  --otlp spans.otlp.jsonl           # analyse it, no adapter involved
-traces analyze --harness claude-code --last 1     # or read a coding agent's own log
-traces check session.jsonl --contract contract.json # gate CI on the path the run took
-traces improve --harness claude-code --last 5 --dir .traces/improvement
-traces watch --all
-traces stream --all --mode findings
-```
-
-The first command is shown in the demo above.
-The **deterministic pass** checks stuck loops, token growth, output decay, missing self-verification, tool failures, and human corrections.
-Each supported issue is returned as a finding with evidence, an action, confidence, and a validation plan.
-It needs no API key and costs nothing.
-
-Add `--llm` for the **agentic analysts**. `traces` first uses free local signals to choose the smallest useful set: a failure review always runs, while knowledge and edit reviews run only when failures, repeated calls, or corrective feedback support them. They call OpenAI and respect `--budget <usd>`.
-
-Every run also writes a **canonical OpenInference JSONL artifact**.
-Use it with [HALO](https://github.com/context-labs/halo), [Hodoscope](https://github.com/ManifoldRG/hodoscope), or any command that reads the file.
-See [Trace analysts](#trace-analysts).
-
-`traces improve` is the reviewable action path.
-It writes one typed result, one report, flattened evidence rows, and the canonical OTLP trace.
-Each finding already contains the claim, evidence, recommended action, confidence, and validation plan.
-
-## Gate CI on a trace contract
-
-Two runs can give the same answer while one of them calls a forbidden tool.
-An output check passes both; a trace contract fails the wrong one.
-
-```json
-{
-  "name": "refund-desk",
-  "run": { "requireCompleted": true, "maxDurationMs": 300000 },
-  "tools": { "required": ["Read"], "forbidden": ["Bash"], "allowed": ["Read", "Grep"], "maxCalls": 10, "enforced": true },
-  "retries": { "reads": ["Read", "Grep"] },
-  "llm": { "maxCalls": 10 }
-}
-```
-
-```bash
-claude -p "$TASK" --tools Read,Grep --strict-mcp-config --output-format stream-json --verbose > run.jsonl
-traces check run.jsonl --contract refund-desk.json --junit contract.xml
+traces list --cwd . --last 5                     # which sessions ran here
+traces facts --current                           # what this session did: turns, PRs, first failure, cost, $0
+traces facts --since 30d --match 'pnpm test'     # did we already try X
+traces analyze 019a3c7e                          # where it wasted time, ranked
+traces check run.jsonl --contract contract.json  # fail CI when a run took a forbidden path
 ```
 
-`tools.enforced` fails when the harness offered the model a tool the contract does not allow, which a flag such as `--tools` does not prove.
-Without `--strict-mcp-config`, the run above is also offered every MCP server the account or project configures.
-`retries` fails when a tool repeats a call with the same arguments and nothing proves the repeat is safe.
-
-The trace is `claude -p --output-format stream-json` output, a Claude Code or Codex session file, OTLP spans (a file or a directory), or trace evidence; `--format` names it when the file could be read as more than one.
-Only stream-json output records the offered tools and the run's own result.
-**A saved interactive session file carries no run status at all** (the `result` record above only exists in `-p` mode), so `run.requireCompleted`/`run.allowedStatuses` always fail on one — write a contract for a session file with no `run` key, like the `refund-desk` example above running against `run.jsonl`.
-Every rule prints `pass`, `fail`, `error`, or `skipped` (a rule of an alternative path that did not decide the result).
-
-| Exit | Meaning |
-|---|---|
-| 0 | Every rule passed. |
-| 1 | A rule failed. |
-| 2 | The contract is malformed or contradicts itself, or a rule could not be evaluated. |
-| 3 | The trace could not be read. |
-| 4 | The trace reference is ambiguous. |
-
-`--junit` writes one test case per rule, and GitHub annotations print under `GITHUB_ACTIONS=true` or `--annotations`.
-`traces check --contract <file> --explain` prints what each compiled rule checks and reads no trace.
-For a trace that does not pass, the verdict, the contract, its plain-language statement, and the redacted spans the violations cite go to `--evidence` (default `.traces/check`).
-The contract keys and rule semantics are in [agent-eval's trace-contract guide](https://github.com/tangle-network/agent-eval/blob/main/docs/trace-contracts.md).
-
-## Integrate your own system
-
-No adapter, no plugin. Emit the span contract and point `--otlp` at the file.
-
-```bash
-npm i @tangle-network/agent-trace-contract    # zero runtime dependencies
-```
-
-You install it to PRODUCE spans. This package already depends on it to read
-them, so `npx @tangle-network/traces@latest` arrives with the contract-backed
-analyses working: trace conformance, `traces validate`, `--otlp` inbound
-reading, round-over-round convergence and the steering chain, and OpenInference
-/ intelligence-spans conversion.
-
-```ts
-import { llmSpan, loopSpan, steeredBy, toolSpan } from '@tangle-network/agent-trace-contract'
-
-// One round of a loop, the model call and tool call inside it, then the next
-// round — linked to the verdict that CAUSED it, not parented to it.
-const round1 = loopSpan({ traceId, spanId: 'round-1', parentSpanId: null, name: 'round 1',
-  loopId: 'fix-loop', iteration: 1, startTime, endTime })
-const call = llmSpan({ traceId, spanId: 'llm-1', parentSpanId: 'round-1', name: 'coder turn',
-  model: 'glm-5.2', inputTokens: 1200, outputTokens: 340, costUsd: 0.0042, startTime, endTime })
-const tool = toolSpan({ traceId, spanId: 'tool-1', parentSpanId: 'round-1', name: 'bash',
-  toolName: 'bash', startTime, endTime })
-const round2 = loopSpan({ traceId, spanId: 'round-2', parentSpanId: null, name: 'round 2',
-  loopId: 'fix-loop', iteration: 2, resumed: true, startTime, endTime,
-  links: [steeredBy('llm-1', traceId)] })
-```
-
-Write one span per line to a `.jsonl` file, then:
-
-```bash
-traces validate spans.otlp.jsonl        # exit 1 only when the file is not a trace
-traces analyze --otlp spans.otlp.jsonl  # a directory reads the OTLP files under it
-```
+## Commands
 
-A directory is a run directory, not a span directory: it holds the span export
-next to raw event, stream and SDK logs that are also `*.jsonl`. Only the OTLP
-files are read — every other JSONL is listed in the report with what it actually
-holds, rather than counted as several hundred broken spans. Put the exports in an
-`otlp/` subdirectory and that decides it outright.
-
-Writing commands (`convert`, `export`, `evidence`, `upload`) take `--otlp-out`; they refuse `--otlp`.
-
-`parent_span_id` is CONTAINMENT — this span happened inside that one. `links` is
-CAUSALITY — that verdict caused this retry. Encoding causality as a parent claims
-a nesting that never existed, so the two edges stay separate and both survive a
-round-trip through `traces`.
-
-### What a trace cannot tell you, said out loud
-
-`validate` reports the conformance of any OTLP file, conforming or not — it never
-throws on a foreign trace, it reports it:
-
-- **findings** by severity, each naming the *consequence* of the defect and the capabilities it blocks
-- **the capability table** — `token-accounting`, `cost-attribution`, `tool-usage`, `loop-convergence`, `tree-comparison`, `steering-chain`, `latency-analysis` — available or not, with the trace's own reason
-- **span structure** — how much of the tree actually attaches, and how many rows could not be read at all
-
-Exit code is 1 on exactly one condition: not one entry could be read as a span,
-so the file is not a trace. Severity says what a finding claims about the INPUT,
-not how loud it is — `error` is "nothing readable", `warn` is "readable but
-degraded", `info` is "nothing measurable lost" — so a `warn` exits 0 and the
-capability table, not the exit code, says what the degradation cost.
-
-#### A re-export never validates cleaner than its source
-
-`--otlp-out` writes the spans that were analysed. Anywhere this package
-normalized a field to analyse it — an `end_time` that precedes its `start_time`,
-a status code the contract does not recognise — the export writes what the
-PRODUCER wrote and keeps the normalized value in an attribute beside it, so
-`negative-duration` and `invalid-status` are still findings against the copy.
-
-A row that never became a span is the one thing that cannot be re-emitted: the
-artifact is also the file the analysts read, so a non-span line in it is garbage
-fed to the analysis and a repaired one is invented work. The export refuses the
-equivalence instead — it carries `traces.source.unreadable_rows` and the kinds
-behind it, accumulating across every hop, and `validate` on a re-export leads
-with how much of the original is missing from it. Round-tripping a defective
-trace through `traces` cannot produce a clean bill of health.
-
-`analyze` prints the same section, plus an **analyses skipped, and why** list —
-and, crucially, carries that verdict INTO the report. A section whose inputs are
-incomplete says so in its own heading and again directly above its table, so a
-number and the reason it is wrong can never end up forty lines apart. When the
-trace supports `tree-comparison`, the table names the command that compares its
-arms: `traces diff <file>#branch=<a> <file>#branch=<b>`.
-
-Two of those analyses are why the loop shape exists at all:
-
-- **round-over-round convergence** — per `agent.loop.id`, the per-round outcome
-  and score series, and whether it improved, plateaued, regressed, or peaked and
-  fell back. The verdict is read from the round's own `agent.outcome` or from the
-  shallowest EVALUATOR span under it.
-- **steering chain** — follows `links` (`agent.link.kind`) to report which verdict
-  caused which subsequent round. A link whose target is missing is kept and marked,
-  because a shorter chain than the producer recorded is the opposite of the truth.
-
-Parent and verdict lookups use both trace and span IDs.
-Steering edges retain `causeTraceId` and `effectTraceId`, including unresolved targets.
-Generic chat transcripts report unknown execution status because message text does not establish completion.
-
-Nothing is repaired on the way in. A span with an unreadable timestamp is
-reported and excluded, because a synthesized value would put invented work into a
-total.
-
-## What it finds
-
-The deterministic pass (free, no key) surfaces:
-
-| Finding | Meaning |
-|---|---|
-| **Stuck loops** | the same tool called N× with identical args and no state change |
-| **Monotonic input growth** | full history re-sent every step; context never compressed |
-| **Output-length decay** | planning/reasoning per step shrinking as context grows |
-| **No self-verification** | state-mutating actions never followed by an eval/inspect/check |
-| **Tool mix / retry / error rates** | repeated, retried, and failed tool calls |
-
-`--llm` adds agentic analysts that read the conversation and cluster higher-order failure and improvement signals. They receive the compact deterministic findings first, then share their earlier findings with later analysts. With `traces improve`, the selected analysts and reasons are saved in `result.json` and the report, so another agent can reuse the packet without rereading the raw trace.
-
-## Supported harnesses
-
-Adapters are the **legacy edge**: they exist for coding agents whose on-disk format we do not
-control, and each is a translation from a proprietary session store onto the span model. They are
-not the way to integrate a system you own — for that, [emit the contract](#integrate-your-own-system).
-
-"Verified" = tested against real sessions; "fixture" = tested against schema-accurate fixtures (no real sessions available).
-
-| Harness (aliases) | Reads from | Status |
+| Job | Command | Page |
 |---|---|---|
-| `claude-code` (`claude`, `claudish`, `openclaw`, `nanoclaw`) | `~/.claude/projects/<cwd>/*.jsonl` (+ subagent sidechains), or an explicit `claude -p --output-format stream-json --verbose` JSONL file | verified |
-| `codex` (`codex-acp`) | `~/.codex/sessions/**/rollout-*.jsonl` | verified |
-| `codex-exec` (`codex-json`) | explicit `codex exec --json` JSONL file | fixture |
-| `opencode` | `~/.local/share/opencode/opencode.db` (shared reader), plus historical `storage/` JSON sessions (legacy reader) | verified |
-| `gemini` (`gemini-cli`) | `~/.gemini/tmp/<hash>/chats/session-*.json` | verified |
-| `pi` | `~/.pi/agent/sessions/<cwd>/*.jsonl` | verified |
-| `kimi` (`kimi-code`) | `~/.kimi/sessions/<cwd hash>/<session id>/wire.jsonl` | verified |
-| `factory` (`factory-droids`, `droid`) | `~/.factory/sessions/<cwd>/*.jsonl` + `.settings.json` sidecar | verified |
-| `qwen` (`qwen-code`) | `~/.qwen/projects/<cwd>/chats/*.jsonl` | fixture |
-| `amp` | `~/.local/share/amp/threads/T-*.json` | fixture |
-| `github-copilot` (`copilot`) | `~/.copilot/session-state/<id>/events.jsonl` | fixture |
-
-Every adapter captures the conversation stored in one session file: the **user's prompt** and the **assistant's response** text, plus tool calls/results and token usage.
-Claude Code, Codex, current OpenCode, Pi, Kimi, and Factory read native records through [`@tangle-network/harness-sessions`](https://github.com/tangle-network/agent-sdk/tree/main/packages/harness-sessions); traces adds conversation and workflow spans over its model and tool calls. Historical OpenCode JSON sessions remain readable through the older adapter because their IDs do not overlap the SQLite store. Kimi's wire log has no served-model field, so its model remains unknown rather than being guessed.
-Claude Code's nested subagent files are folded into the parent trace.
-Claude Code's stream-json output also records the tools the harness offered the model and whether the run failed.
-The root span keeps them as `gen_ai.tool.definitions` and `run.status`, so a trace contract can check what the harness enforced.
-Exported native-session span IDs derive deterministically from the session and record IDs.
-The Claude transcript proves turns and tool calls, but does not prove loop iterations or causal links, so those fields remain absent.
-Codex stores each worker in a separate session file; add `--workflow` to resolve the connected coordinator and worker files.
-`github-copilot` is the one exception: its log format carries no user prompt.
-Factory stores token totals in `.settings.json`, not per turn.
-ACP-only bridges may not persist a local transcript.
-
-## CLI reference
-
-```bash
-traces list     --harness claude-code --last 20    # discover sessions
-traces analyze  --harness codex --session <id>     # pin one ID printed by `list`
-traces analyze  --harness codex --current          # this session, even when a child wrote later
-traces analyze --harness codex --current --latest-turn --workflow  # current turn plus workers
-traces analyze --harness claude-code --session <path> --latest-turn # latest task plus its subagents
-traces investigate --all --last 10 --out report.md  # explicit investigation alias
-traces improve --all --last 10 --dir .traces/improvement
-traces ask --harness codex --session <id> --question "Which commands failed?"
-traces facts --harness codex --session <id>        # the deterministic facts sheet, $0
-traces facts --all --since 2026-10-14 --until 2026-10-15  # every session with a record that day, that day's turns
-traces skills --since 30d                          # skill use across every local session, incremental, $0
-traces diff  run-a.otlp.jsonl run-b.otlp.jsonl      # where two runs of one task first diverge
-traces mcp   --otlp spans.otlp.jsonl                # read-only trace tools for an MCP client
-traces analyze  --all --since 2026-06-18 --out report.md
-traces check   spans.otlp.jsonl --contract c.json --junit c.xml  # exit 0 pass, 1 fail, 2 bad contract, 3 unreadable, 4 ambiguous
-traces validate spans.otlp.jsonl                   # conformance; exit 1 only when it is not a trace
-traces validate results/sessions --out conformance.md  # a whole directory of exports
-traces analyze  --otlp spans.otlp.jsonl            # analyse foreign OTLP, no adapter
-traces analyze  --otlp results/sessions --out report.md
-traces convert  --harness claude-code --last 1 --otlp-out spans.jsonl   # OTLP only
-traces index    --all --since 24h --out session-index.json
-traces bundle   --harness claude-code --session <id|path> --out bundle-dir   # one session's durable evidence dir
-traces bundle-view bundle-dir --view evidence-only --out writer-dir   # same session, without its own words
-traces bundle verify bundle-dir                                        # every file against its manifest SHA-256
-traces inspect  session-index.json --out inspection-report.md
-traces evidence --harness codex --last 20 --out policy-evidence.jsonl
-traces evidence --harness codex-exec --session /tmp/codex.jsonl --cwd "$PWD" --out policy-evidence.jsonl
-traces export   policy-evidence.jsonl --out spans.openinference.jsonl
-traces import-codetracebench verified.jsonl --trajectory-dir normalized --out traces --revision <40-or-64-character-hex>
-traces watch    --all                              # live observer; loops + semantic findings
-traces watch    runs/my-run                        # live run tree: status, budget, driver vs child spend
-traces watch    runs/my-run --once                 # one snapshot, then exit
-traces watch    traces.otlp.jsonl                  # any OTLP span file, any emitter
-traces analyze  --supervisor-run-dir runs/my-run   # the full tree report
-traces stream   --all --mode findings              # low-volume semantic feed
-traces stream   --all --mode agent                 # findings + deterministic report events
-traces stream   spans.openinference.jsonl --format openinference --no-spans
-traces upload   --since 1h --dry-run               # redact + dedup + preview, no network
-traces upload   --since 24h                        # upload last day to the Intelligence Platform
-traces verify-safe bundle-dir                      # SAFE / SAFE_WITH_WARNINGS / UNSAFE (exit 1) / UNKNOWN (exit 2)
-traces replay-verify --steps steps.json --image <docker-image> --at 37 --cwd /home --out ./replay-out \
-  --fix-command "<corrected step>"                 # executed proof: replay prefix, reproduce failure, show fix
-traces verify-findings --findings findings.json --out ./receipts \
-  --steps steps.json --image <replay-ready-image> --cwd /app   # execute recorded analyst findings as proofs
-traces analyze --last 1 --llm --verify-findings --replay-corpus h=labels.json::prepared/  # proof-carrying analyze
-```
-
-`replay-verify` replays a CodeTraceBench-style trajectory prefix in a real sandbox and executes step k twice — recorded (does the failure reproduce?) and corrected (does it vanish?).
-`verify-findings` runs that proof per analyst finding and annotates each with `reproduced | fix-flipped | divergent | not-replayable` plus a receipt directory; see [Verified findings](./docs/trace-analysts.md#verified-findings-executed-replay).
-See [Replay verification](./docs/replay-verify.md) for setup, semantics, and honest limits (SWE-style trajectories with a docker image only; commands run as the non-root sandbox user).
-
-| Flag | Meaning |
-|---|---|
-| `--harness <id>` | Harness or alias (default: `claude-code`) |
-| `--all` | Every known harness |
-| `--last <n>` | Most-recent N sessions |
-| `--current` | Active Codex session from `CODEX_THREAD_ID` |
-| `--latest-turn` | Limit a resumed Codex or Claude Code session to its latest task turn |
-| `--session <id\|path>` | One listed session ID or explicit session file |
-| `--workflow` | Expand selected files through stable parent and child session IDs |
-| `--max-workflow-sessions <n>` | Stop workflow expansion before parsing more than `n` files; default `100` |
-| `--cwd <dir>` | Filter by working directory |
-| `--since <t>` | `30m`/`2h`/`7d` before now, or an ISO date. Commands that select sessions read those modified at or after it; `upload`: its window (default 24h); `facts`: opens a time window — see [Session facts](#session-facts) |
-| `--until <t>` | `facts`: closes the time window (exclusive), same forms as `--since` |
-| `--out <path>` | Write the report to a file |
-| `--dir <path>` | `improve`: write the full artifact pack to this directory; `ask`: write `answers.json` + `report.md` there |
-| `--otlp <file\|dir>` | **READ** OTLP-JSONL from any system, skipping the adapters; a directory reads the OTLP files under it (only `otlp/` when the producer made one) and names the JSONL that is not OTLP. `validate`, `check`, `analyze`, `investigate`, `improve`, `ask`, `stream` |
-| `--contract <file>` | `check`: the declarative trace contract (JSON) |
-| `--junit <file>` | `check`: write JUnit XML, one test case per rule |
-| `--evidence <dir>` | `check`: where evidence for a trace that did not pass goes (default `.traces/check`) |
-| `--annotations` | `check`: print GitHub workflow annotations (on by default under `GITHUB_ACTIONS=true`) |
-| `--otlp-out <path>` | **WRITE** the OTLP artifact here (also evidence provenance / dry-run upload preview) |
-| `--format <kind>` | File `analyze`, `export`, or `stream`: `auto`, `policy-evidence`, `sandbox-events`, `openinference`, `intelligence-spans`, or `chat-trajectory` |
-| `--source-bundle <dir>` | `analyze` / `investigate` / `improve` / `ask`: read a retained full bundle and explicitly grant source-field reads |
-| `--llm` / `--budget <usd>` | Enable agentic analysts (needs `TANGLE_API_KEY` + Python with `agent-eval-rpc[dspy]`) / cap their spend |
-| `--question <text>` | `ask`: one question, repeatable. Kept short so the engine sees it whole |
-| `--questions <file>` | `ask`: JSON array of questions — strings, or `{ id?, question, instructions?, answerSchema? }` |
-| `--question-budget <usd>` | `ask`: provider ceiling for ONE question; `--budget` is the ceiling shared by all of them |
-| `--question-timeout <seconds>` | `ask`: wall-clock deadline for ONE question's investigation (default 600); raise it for questions over many large sessions |
-| `--concurrency <n>` | `ask`: questions running at once (default 4); `import-codetracebench`: trajectories imported at once |
-| `--config <path>` | `analyze` / `investigate` / `improve` / `stream`: load BYO analysts, live analysts, and external analyzers |
-| `--interval <s>` / `--window <m>` | `watch` / live `stream`: poll seconds (sessions 5, run tree 2) / active-session window minutes (default 30) |
-| `--min-loop <n>` | Identical repeated calls before flagging a loop (default 3) |
-| `--mode <kind>` | `stream`: `visualizer` (spans + findings), `findings` (low-volume), or `agent` (findings + reports) |
-| `--supervisor-run-dir <dir>` | `analyze`: report one run tree; `watch`: tail it live |
-| `--verify-findings` | `analyze`: execute the findings as sandbox replay proofs; each is marked VERIFIED (receipt path) or UNVERIFIABLE (reason). Needs `--replay-corpus` and a running sandbox (`SANDBOX_API_KEY` / `SANDBOX_API_URL`) |
-| `--replay-corpus name=<labels>::<prepared>` | Trajectory source for `--verify-findings` (repeatable) |
-| `--verify-out <dir>` | Receipt root for `--verify-findings` (default: `<--out>.verify`) |
-| `--replay` | `stream`: scan once, then exit |
-| `--once` | `stream`: scan once; `watch <target>`: print ONE snapshot and exit |
-| `--no-spans` / `--no-findings` | `stream`: suppress raw span rows / finding rows |
-| `--no-content` | `facts`: omit conversation, commands, paths and assignment text; `upload`: send metadata only |
-| `--dry-run` / `--yes` | `upload`: preview without sending / skip the confirm prompt |
-
-## Live stream
-
-`traces watch` is the human terminal view.
-It prints repeated-tool loops and semantic findings while a coding agent is still running.
-
-`traces stream` is the machine feed.
-It emits newline-delimited JSON events that a dashboard, art visualizer, local watcher, or hosted product can consume without scraping terminal prose.
-
-```bash
-traces stream --all
-traces stream --all --mode findings
-traces stream --all --mode agent --config traces.config.mjs
-traces stream spans.openinference.jsonl --format openinference --no-spans
-```
-
-Live streaming emits `session`, `span`, `analysis_batch`, `finding`, and `tick` events; `--mode agent` also emits `report` events.
-The semantic findings currently cover repeated failing commands, verification churn without code/config changes, completion claims without later verification, and high tool-error rates.
-Use `--mode findings` when you want the low-volume meaning layer; keep `visualizer` for real-time views that need motion, timing, and tool-call texture.
-Use `--mode agent` when another agent needs deterministic loop/tool-use reports alongside the findings.
-The same JSONL shape is used for live sessions and replayed trace files:
-
-![traces stream findings mode terminal capture](./docs/stream-findings.svg)
-
-Custom online analysts use the same config file as `investigate` and `improve`:
-
-```js
-export default {
-  liveAnalysts: [{
-    id: 'my-live-rule',
-    analyze(context) {
-      return context.actions.some((action) => action.kind === 'claim') ? [{
-        schemaVersion: 1,
-        kind: 'traces.live_finding',
-        id: `live.my-live-rule.${context.session.sessionId}`,
-        ruleId: 'my-live-rule',
-        fingerprint: `my-live-rule.${context.session.sessionId}`,
-        severity: 'info',
-        title: 'Completion claim seen',
-        claim: 'A claim-like assistant message appeared in the live trace.',
-        action: 'Require the next stream batch to include a verification action.',
-        check: 'A later finding or batch should show a test/build/typecheck action.',
-        evidence: [{ kind: 'metric', label: 'actions', value: String(context.actions.length) }],
-        session: context.session,
-        observedAt: context.generatedAt,
-      }] : []
-    },
-  }],
-}
-```
-
-## Watch a run tree
-
-`traces watch <target>` tails ONE run that fans work out to other agents, instead of one harness session.
-It prints the tree at any depth: per node the status, the runtime, the authored budget, and the actual spend.
-Plain stdout, no cursor control, no extra dependency — it works over SSH, in a CI log, and through a pipe.
-
-```bash
-traces watch runs/my-run                 # live: reprints only when something changed
-traces watch runs/my-run --once          # one snapshot, for a script or an agent
-traces watch traces.otlp.jsonl           # spans only, for any emitter
-```
-
-Two sources sit behind the one verb, and the output always names which number came from which:
-
-| Source | Reads | Gives you | Cannot give you |
-|---|---|---|---|
-| **General** — OTLP spans | `trace_id` / `span_id` / `parent_span_id` in any `*.otlp.jsonl`, `*.spans.jsonl`, `*.traces.jsonl` | tree shape, wall time, per-turn tokens, cost when the emitter priced it | the authored budget — no span vocabulary carries one |
-| **Specific** — the spawn journal | `spawn-journal.jsonl` written by agent-runtime's `createFileRunContext` | authored budget, settled spend, settlement status, blocking questions, steers, the typed result | per-turn detail the journal does not tap |
-
-The general source is the one that matters for a system nobody has written yet: anything that emits a parent span pointer gets a tree, whether it is a supervisor, a pi session, a Claude subagent fan-out, or a custom fanout.
-Attributes are read through `@tangle-network/agent-eval/trace-attributes` alias lists, so both live vocabularies — OpenInference's `llm.token_count.*` and GenAI semconv's `gen_ai.usage.*` — already work, and no key is invented here.
-
-Two rules the view will not bend on:
-
-- **Driver inference and child work never merge.** A node that drove and the work it delegated are separate lines, because one total cannot answer "which half spent the budget" — the decisive question in three real runs.
-- **Unknown is never rendered as zero.** A turn the harness did not price reads `cost unknown (n unpriced)`, never `$0.0000`. A recorded `$0` paid on real tokens is printed AND flagged, because "free" and "unmetered" are different facts.
-
-```
-run proof-harness-mcp-20260731i
-  2 node(s) · depth 1 · elapsed 9m59s
-  driver total    in 639,632 · out 35,077 · $0.0000 (zero across 58 priced)
-  worker total    in 47,965 · out 515 · cost unknown (1 unpriced)
-
-● · root  [pending]  supervisor  inline  budget 12it/400,000tok/$2.00/15m00s
-    driver    58 turn(s) · in 639,632 · out 35,077 · $0.0000 (zero across 58 priced) · 169% tok of budget
-    children  1 settled · in 47,965 · out 515 · cost unknown (1 unpriced)
-└─ ✗ artifact-writer-s0  [failed]  worker  pi  budget 6it/80,000tok  wall 20.8s
-       settled   3it · in 47,965 · out 515 · cost unknown (1 unpriced) · 50% it, 61% tok of budget
-
-  ! spend recorded $0 with tokens spent: usdKnown was never set false, so this reads as FREE rather
-    than unmetered. A harness-billed brain (a CLI on a subscription) looks exactly like this.
-
-RESULT no-winner · budget-exhausted
-```
-
-`traces analyze --supervisor-run-dir <dir>` writes the full report for the same run.
-It also reads `failure.json` when Runtime fails before the first spawn.
-Pass a parent directory to combine reports from its Runtime runs.
-Eval owns discovery, normalization, and analysis; Traces adds recorded coordination requests and delivery receipts.
-Old Loops directories are unsupported.
-
-Replay and resume are a separate concern: they belong to the durable spawn journal, and nothing here routes them through telemetry.
-
-## Improvement engine
-
-`traces improve` turns observed sessions into a portable improvement packet:
-
-```bash
-traces improve --all --last 20 --dir .traces/improvement
-```
-
-The directory contains:
-
-| File | Purpose |
-|---|---|
-| `result.json` | findings, actions, checks, execution facts, adoption data, and the chosen LLM analysis route |
-| `evidence.jsonl` | one row per evidence ref, suitable for downstream mining |
-| `report.md` | human-readable report rendered from the typed data |
-| `traces.otlp.jsonl` | canonical trace used by the analysts and execution accounting |
-
-Bring your own analysts with a config file:
-
-```bash
-traces improve --last 5 --config examples/improvement-config.mjs --dir .traces/improvement
-```
-
-The config can export:
-
-- `analysts`: deterministic or LLM analysts that implement the `agent-eval` `Analyst` contract
-- `liveAnalysts`: deterministic online analysts that implement the `TraceLiveAnalyst` contract for `traces stream`
-- `registry`: a prebuilt `AnalystRegistry`
-- `externalAnalyzers`: HALO or any command/model adapter that reads the OTLP artifact
-
-Traces does not pretend that an action is a measured candidate.
-Use `agent-eval` to propose and compare candidate changes, `agent-runtime` to package an approved improvement, and `agent-interface` to represent profile edits.
-
-## Ask questions
-
-`traces ask` answers free-form questions about the selected sessions.
-Each question becomes its own recursive investigation over the same trace, and the questions run at the same time under one budget.
-
-```bash
-traces ask --harness codex --session <id> \
-  --question "Which shell commands exited non-zero, and what were they?" \
-  --question "What was the last thing the human asked for?" \
-  --dir .traces/ask
-```
-
-Ask many questions from a file, and hold an answer to a shape a scorer can compare:
-
-```bash
-traces ask --all --last 3 --questions questions.json --concurrency 6 --budget 2 --dir .traces/ask
-```
-
-```json
-[
-  "Which pull requests did this session open?",
-  {
-    "id": "merged-prs",
-    "question": "Which pull requests were merged?",
-    "instructions": "Count only merges the trace records, not merges the agent said it would do.",
-    "answerSchema": { "type": "array", "items": { "type": "integer" } }
-  }
-]
-```
-
-An entry is a question string, or an object with `question` and an optional `id`, `instructions`, and `answerSchema`.
-The schema accepts a small JSON Schema subset: `type`, `properties`, `required`, `additionalProperties`, `items`, `enum`, and `const`.
-Any other keyword is rejected when the run starts, because a constraint that is silently ignored would let a wrong answer pass as checked.
-
-The command writes two artifacts to `--dir`:
-
-| File | Contents |
-|---|---|
-| `answers.json` | per question: the answer text, the parsed answer, every citation with whether it resolves, accepted findings, evidence-gate rejections by reason, model calls, tool calls, cost with provenance, and latency |
-| `report.md` | the same run as readable Markdown: a summary line, a per-question table, then each answer with its citation and rejection notes |
-
-What it checks, and what it costs:
-
-- **Facts first.** Every question receives the deterministic [session-facts sheet](#session-facts) as prepared context before its first model call, at $0. The sheet is not citable; it names the span ids behind each fact.
-- **Citations.** Every `trace://<trace_id>/span/<span_id>` URI in an answer is looked up in the trace. An answer that cites a span the trace does not hold fails.
-- **Budget.** `--budget` is one ceiling shared by every question. `--question-budget` bounds one question. The run refuses to start when the budget cannot cover a single model call, and warns when the budget admits fewer concurrent calls than `--concurrency`.
-- **Cost.** Each cost carries its provenance: `observed` from a provider receipt, `estimated` from token counts, or `uncaptured`. An uncaptured cost stays null; it never becomes zero.
-- **Exit code.** `ask` writes both artifacts first, then exits 1 when any question failed, returned no answer, broke its schema, or cited a span that does not exist. A failed question never costs the other answers, and neither does Ctrl-C: the answers already bought are recorded, the questions the run never reached are recorded as `aborted`, and both artifacts are still written.
-- **Wall time.** `totals.wallTimeMs` covers the whole run, including writing and indexing the trace file; `totals.setupTimeMs` says how much of it that setup was. `totals.peakConcurrency` is how many questions actually overlapped, which is at most `min(--concurrency, questions)`.
-
-`ask` uses the same engine and credentials as `--llm`, so it needs `TANGLE_API_KEY` and a Python interpreter with `agent-eval-rpc[dspy]`.
-Do not pass `--llm`; the command is model-backed by definition.
-
-## Session facts
-
-The SDK also accepts verified retained captures through
-`parseRetainedSession({ harness, nativeSessionId, files, signal? })`.
-Pass files as `{ path, content }` with their original relative layout.
-Runtime or the caller owns custody, digest verification and capture completeness.
-The reader uses existing adapters and selects a file only when native records
-establish the supplied session identity.
-It does not inspect the host session catalog or infer identity from filenames.
-Directory-only stores and formats without a recorded native identity remain unavailable.
-The returned source files, duplicate snapshots and unselected files explain the selection.
-Identical or append-only copies count once; divergent histories remain unavailable.
-Parsing is bounded to 1024 text files, 16 MiB per file, and 64 MiB total.
-No model calls occur.
-Call `buildSessionFactsReport(selection.spans, { includeContent: false })` to
-withhold native bodies from the resulting facts.
-The reader itself returns spans containing native content, for local trusted consumers only.
-
-
-The same facts sheet includes observed tool outcomes, captured input/output byte
-volumes, call-to-result intervals, compaction boundaries and available context
-sizes, spawn intervals, and existing skill invocation/document-read evidence.
-Each measurement carries coverage; absent telemetry remains unknown.
-`facts --no-content` withholds conversation (including each turn's `answered` text),
-command, changed-file, working-directory and assignment text while retaining
-measurement metadata. This is a local metadata view, not a
-share-safety certificate.
-
-SDK consumers use `buildSessionFactsReport(spans, { includeContent: false })`.
-Pass `window: { since, until }` (ISO bounds) for the windowed report `facts --since/--until` prints, and use
-`createSessionFactsReportBuilder(options)` (`add(spans)`, `addUnread(...)`, `build()`) to build it one session at a time.
-Cache by `measurementVersion` and `sourceDigest`; `evidenceThrough` is the latest
-recorded endpoint, not current liveness. Computing the sheet parses the supplied
-spans; returning a stored sheet needs no model call or trace scan. Semantic
-judgments remain attributed analyst results.
-
-
-`traces facts` prints the deterministic session-facts sheet: the answers a session audit needs first, computed straight from the spans.
-No model call, no engine, no budget — it costs $0 and always returns the same sheet for the same spans.
-
-```bash
-traces facts --harness codex --session <id>                 # JSON on stdout
-traces facts --harness codex --last 5 --format text         # the short readable form
-traces facts --otlp spans.otlp.jsonl --out facts.json
-traces facts --harness claude-code --since 7d               # every session with a record in the last week
-traces facts --all --since 2026-10-14 --until 2026-10-15    # one day, across every harness
-```
-
-`--since <t>` and `--until <t>` open a half-open time window `[since, until)`; each takes `30m`/`2h`/`7d` before now or an ISO date, and either may be left open.
-With a window, `facts` selects **every** session with a record that starts or ends inside it, not only the newest (`--last <n>` still caps it to the newest `n` per harness, and `--session` or `--otlp` still name the input).
-Sessions are read one at a time, and a session file last modified before `since` is not read, because it cannot hold a later record.
-Within a selected session, `humanTurns`, `excludedTurns` and `turnsByActor` keep only turns that started inside the window, so a one-day run counts only that day's turns; every other fact covers the whole session.
-The report's `selection` states the window, both rules, the sessions read whose records all fell outside it (`outsideWindow`), and every session that could not be read (`unreadSessions`, each with its reason).
-A report built without a window has `selection: null`.
-
-| Fact | What it is |
-|---|---|
-| `toolCalls` | TOOL spans **this session's agent** actually invoked. Synthesized lifecycle spans are excluded and counted in `synthesizedToolSpans`, so the total is not high by the number of subagents; calls a spawned subagent made are excluded and counted in `subagentToolSpans` |
-| `toolCallsByName` | the same calls by tool name, so a category decision is the reader's, not a guess |
-| `subagentToolSpans` | TOOL spans excluded because a subagent, not this agent, made the call. Zero on a trace that carries no subagent records |
-| `subagents` | every subagent-spawning call with the task name the adapter recorded |
-| `pullRequests` | the pull requests the commands created and merged, each named by number or head branch, with the command span and how the identity was joined. Scanned the way a shell reads the script, so a `gh pr create` inside a heredoc body is not a command that ran |
-| `cwd` | the working directory the harness recorded for the session (`traces.session.cwd` on the root span): Claude Code's first record `cwd`, Codex's `session_meta` cwd, Pi's session header, OpenCode's session directory (the older JSON store: its messages' `path.cwd`), Factory's `session_start`. Never decoded from a directory name or inferred from paths; `null` with the reason when the source names none or its adapter does not read one |
-| `humanTurns` | `user.prompt` turns a person typed into this session, in order, with the timestamp. Inherited fork or compaction history, harness-injected blocks, and a second record of the same turn are excluded — each listed in `excludedTurns` with its reason and span ids, never silently dropped. `turnsByActor` shows every turn by actor so the filter is checkable. Each turn's `answered` is the last message this session's own agent wrote before it (not a subagent's, not inherited history), clipped to 1,500 characters with a `… [+N chars]` marker, with its span in `answeredSpanId`; `null` when the agent had written no text yet in the spans read (a `--latest-turn` read starts at the latest task, so its first turn has none) |
-| `finalMessages` | the last message of the session's own agent, and of each subagent task, kept apart |
-| `changedFiles` | paths the harness recorded for the changes it applied, plus paths named by patch headers and file-editing tool arguments, with the operation |
-| `firstRecordAt` / `lastRecordAt` | the earliest span start and latest span end among this session's own records — a subagent that outlives the session does not stretch its window |
-| `unreadRecords` | records the session reader could not parse, from the session's integrity receipt |
-| `tokenTotal` | the harness's own cumulative token total, when a span carries `traces.session.total_tokens` |
-| `firstFailure` | the first failure among this session's own records, ranked by agent-eval's fixed precedence: the innermost ERROR span that ended first, else a span whose `agent.outcome` is `fail`, else `none` — spans were observed and none of them failed. When every span is UNSET (a capture that failed before any status was written), or a session has no records of its own at all (every span is `traces.span.subagent` — spawned work folded into this trace, with nothing this agent recorded itself), the status is `unknown`, not `none`: the record does not say whether the run failed. Failures that ended at the same instant are `ambiguous` and list the candidates instead of picking one. `blame` separates machine and provider failures from the agent's own, and is `unknown` rather than `agent` when no evidence names the agent |
-
-Three rules hold for every field:
-
-- **Every fact is about this session's own agent.** Some harnesses fold a spawned agent's transcript into the parent's trace, so a trace can carry both what this agent did and what a child it spawned did. The child's work is named in `subagents` and counted in `subagentToolSpans`; it is never added to the parent's totals.
-- **Every fact names its span ids.** `spanIds` lists the spans the value was computed from, so any number here can be opened and checked. The sheet itself is not a span and cannot be cited.
-- **A fact the spans cannot support is `null` with its reason.** It is never guessed, and never a silent zero. `partial` marks a measured value that is known to be incomplete — a truncated patch, or a list above the entry cap.
-
-Without a window, `facts` exits non-zero when a selected session cannot be read at all: a session that produced no record spans would otherwise print a sheet of zeros stating, in the sheet's own voice, that the session did nothing.
-With a window, a session that cannot be read — the parser failed, or no record could be read — is named in `selection.unreadSessions` with its reason and a warning on stderr, and the run still exits 0 with the sessions it could read; it is never counted as a session with no turns.
-
-The same sheet reaches the model-backed analysts as prepared context, before their first model call — see [Trace analysts](docs/trace-analysts.md#session-facts-as-prepared-context).
-
-## Skill usage
-
-`traces skills` indexes skill records in Claude Code, Codex, and Kimi Code sessions on this machine.
-It makes no model call.
-
-```bash
-traces skills                     # every stored event, with the installed catalog joined
-traces skills --since 30d         # one window
-traces skills --unused            # installed skills with no use in the window, one per line
-traces skills --format json       # rows, unused skills, refresh cost and sweep exclusions
-traces skills --no-refresh        # answer from the store without reading transcripts
-```
-
-A run reads only transcript bytes appended since the previous run.
-It parses only lines that can carry a skill record and stores the events in `~/.local/state/traces/skill-usage.json` (`--store`).
-The first run reads the whole corpus: about two minutes for 41 GB on an M-series Mac.
-Later runs take seconds, mostly to stat every session file.
-Stored events survive a harness deleting old transcripts.
-
-| Column | Harness | Counted record |
-| --- | --- | --- |
-| `model` | Claude Code | A Skill tool result that loaded a skill. A failed call does not count. |
-| `slash` | Claude Code | A `/name` command whose next record is its expanded prompt. Built-in commands such as `/clear` do not expand and do not count. |
-| `read` | Codex | A completed command that reads `<skill>/SKILL.md`. Codex records no skill event, so a read is the closest observable act. It does not show that the skill shaped the outcome. |
-| `read` | Kimi Code | A successful `ReadFile` call or shell command that reads `<skill>/SKILL.md`, including streamed arguments. Kimi records no dedicated skill event. |
-
-Each event is keyed by its record ID, so a resumed session that copies earlier records counts once.
-One Codex or Kimi command that reads three or more skills (`--sweep`) is a catalog sweep, such as an audit; its reads are excluded and reported separately.
-`installed` names the harnesses whose catalog lists the skill now: `~/.claude/skills` and enabled plugins for Claude Code, and `~/.codex/skills` and `~/.agents/skills` for Codex.
-OpenCode, Pi, Gemini, Factory, and other harnesses are not indexed.
-
-## Diff two runs
-
-`traces diff` pairs the steps of two runs of the same task and marks where they first stop agreeing.
-
-```bash
-traces diff runs/a/otlp runs/b/otlp                     # two OTLP exports
-traces diff a.sdk-events.jsonl b.sdk-events.jsonl --kind TOOL   # any file convert reads; tool calls only
-traces diff spans.otlp.jsonl#<trace id> other.jsonl --format json
-traces diff run.otlp.jsonl#branch=arm-a run.otlp.jsonl#branch=arm-b    # two arms of one run
-```
-
-A side is a file or directory that holds one run, `file#<trace id>` for one run of several, or `file#branch=<id>` for one arm: the spans whose `agent.branch.id` or `agent.branch.arm` is `<id>` and have no matched ancestor (a root), and every span below them. Sibling arms can share a branch id or label; when `<id>` names more than one such root subtree, the command refuses (exit 2) and lists each root's span id, rather than silently comparing the union of both.
-Steps pair by span id first, then by position with the same name and kind, then by name and kind anywhere.
-One inserted step therefore does not mark every later step as changed.
-Paired steps compare status, tool and model.
-The first divergence is `changed`, `replaced`, `only-in-a`, `only-in-b` or `reordered`, with its reason, followed by every changed and unpaired step.
-`--kind` keeps only steps of that span kind, so event noise in a raw stream does not decide the first divergence.
-The diff is agent-eval's `diffSteps`; this command reads the runs and prints it.
-It exits 0 when the runs agree on outcome, 1 when they diverge, 2 when a side cannot be read (including an ambiguous `#branch=` selector), and 3 when the steps line up with no divergence but there is no recorded outcome to call agreement: neither side has a step with a definitive OK/ERROR status (both are entirely UNSET, the common shape for a capture that failed before any status was written), or neither side has a TOOL step. That case's report and text output carry a `caveat` naming which reason applies; a CI or agent gate should treat exit 3 as unknown, not as a pass.
-
-## MCP server
-
-`traces mcp` serves the selected traces to an MCP client over stdio.
-
-```bash
-claude mcp add traces -- traces mcp --otlp ./spans.otlp.jsonl
-claude mcp add traces -- traces mcp --harness claude-code --last 5
-```
-
-It serves agent-eval's seven trace tools: `getDatasetOverview`, `queryTraces`, `countTraces`, `viewTrace`, `viewSpans`, `searchTrace` and `searchSpan`.
-Each tool declares `readOnlyHint` and `idempotentHint` in its MCP annotations, and its description says that returned trace text is untrusted.
-
-- The spans are redacted before the store is built — every span's name, attributes, status message and causal links' attributes, every field the store reads — and each result is redacted again at the boundary. The server then reassesses the redacted spans and refuses to start when they are still UNSAFE or UNKNOWN, the same gate `upload` applies to what it sends.
-- Each result carries an `untrusted` notice beside it.
-- A result above 512 KiB is refused with an error rather than truncated.
-- `readSpanSource` is not served. It reads original source bytes in windows the caller picks, and a secret split across two windows matches no redaction rule.
-
-## Session index
-
-`traces index` writes one general JSON catalog over the selected sessions.
-It is meant for deeper investigation and joins with other local data, not for one specific workflow.
-
-```bash
-traces index --all --since 24h --out session-index.json
-traces inspect session-index.json --out inspection-report.md
-```
-
-The index contains:
-
-- selection metadata and aggregate totals
-- one row per session with harness, session id, path, cwd, repo labels, and time bounds
-- behavior metrics: spans, LLM turns, tool calls, tool errors, tokens, models, and tools
-- signal summaries: stuck loops and tool error rate
-- nearby context files for joins: `AGENTS.md`, `CLAUDE.md`, and `.evolve` artifacts — the JSONL ledgers, `scorecard.json` / `current.json`, reflections, `handoffs/` plus the flat `handoff-*.md` convention, and `progress.md` — with markdown heading/ToC and JSONL key summaries
-
-`traces inspect` reads that index back and prints ranked improvement findings over the sessions and nearby context.
-It is intentionally read-only: it points to repeated-call loops, high tool-error sessions, missing repo attribution, long docs without Contents, invalid JSONL rows, and skill-run rows that cannot be joined back to a session.
-
-## Session bundle
-
-`traces bundle` assembles ONE session's durable evidence directory — the input for any downstream consumer that must cite the session after the live stores rotate.
-It composes commands this CLI already owns and never spends a model call.
-
-```bash
-traces bundle --harness claude-code --session <id|path> --out bundle-dir
-```
-
-The bundle directory:
-
-- `session/` — the transcript byte-for-byte, plus the sibling subagents directory when one exists
-- `derived/` — `session-index.json`, the deterministic `report.md`, `evidence.jsonl`, and the OTLP span artifact
-- `ledger/` — the repo's `.evolve` slices for the session window: `experiments.jsonl` and `skill-runs.jsonl` rows inside the padded span window, `current.json` / `scorecard.json` / `progress.md` copied whole, the latest flat `handoff-*.md`, and reflections dated inside the window
-- `repo/git-log.txt` — commits in the session window from the session's cwd
-- `manifest.json` — `view`, SHA-256 + byte count per file, provenance (session id, harness, cwd, transcript hash, session window), every absent artifact with its reason, per-slice row counts, and the bundle's known limits
-
-A missing transcript fails the assembly loudly.
-Every optional input that is absent (no subagents, no `.evolve`, no git repo) is recorded in `manifest.absent` with the probed path — a fact, not an error.
-
-### Two views, two consumers
-
-A bundle has two kinds of reader, and they need opposite things.
-
-- An **auditor** cites the session and needs every source byte. That is the FULL view — what `traces bundle` writes, `manifest.view: "full"`.
-- A **writer** must reach its own conclusion about the session, so it must not be able to read the conclusion that session already reached. That is the EVIDENCE-ONLY view, `manifest.view: "evidence-only"`.
-
-The full bundle cannot serve the writer. Its transcript holds every word the session wrote, including the shell call that authored an earlier report, so a check that looks for the report FILE passes while the report CONTENT is right there. Projecting is the fix, not grepping:
-
-```bash
-traces bundle      --harness claude-code --session <id|path> --out bundle-dir
-traces bundle-view bundle-dir --view evidence-only --out writer-dir
-```
-
-The evidence-only view carries an explicit allow-list — `derived/session-index.json`, `derived/evidence.jsonl`, and the structured `ledger/` records (`current.json`, `scorecard.json`, `skill-runs.jsonl`). Everything else is excluded **by name** in `manifest.excluded`, with its SHA-256 and one of four rules:
-
-| rule | what it covers |
-|---|---|
-| `session-source` | `session/` — the transcript and every subagent transcript |
-| `session-text-derived` | `derived/report.md` (quotes the first prompt line and evidence excerpts) and `derived/trace.otlp.jsonl` (spans carry the full prompt and response text) |
-| `authored-prose` | `ledger/progress.md`, `ledger/handoff-*.md`, `ledger/reflections/`, `ledger/experiments.jsonl` free-text, `repo/git-log.txt` |
-| `not-allow-listed` | any other path, including one a later version of `traces` adds — the view can only narrow by accident, never widen |
-
-The allow-list is the structure. A content check is the proof it is right: before anything is written, every candidate is compared against every excluded file for shared 8-word runs of prose, with identifiers (paths, URLs, hashes) and this package's own constant strings scrubbed from both sides first. A shared run in a repo ledger file drops that file with `rule: "content-signature"` and the match count; a shared run in an artifact `traces` derives is a defect in the derivation and no view is written at all. `manifest.projection.leakCheck` records the width, the sources compared, and the result — always `matches: 0`, because a match means no view exists.
-
-A projected view also carries the full bundle's `manifest.json` hash, so an auditor can prove which record it came from. Projecting a view of a view is refused.
-
-### Verify a bundle
-
-```bash
-traces bundle verify bundle-dir            # VERIFIED, or FAILED with each difference; exit 1 on failure
-traces bundle verify writer-dir --format json
-```
-
-`bundle verify` checks every file the manifest lists for its recorded size and SHA-256.
-It reports a listed file that is missing, a file on disk that the manifest does not list, a manifest path that is absolute or climbs out of the directory, and any symbolic link.
-For a projected view it also checks that the full bundle it names still has the manifest bytes the view recorded; a moved or deleted source is `unavailable`, not a failure.
-It proves the bytes are the bytes `traces` wrote. It does not prove who wrote them: anyone who can rewrite a file can rewrite the manifest.
-
-## Policy-mining evidence
-
-`traces` does **not** emit benchmark campaign cells. It emits normalized coding-agent session evidence that another system can mine.
-
-```bash
-traces evidence --all --since 24h --out policy-evidence.jsonl --otlp-out spans.otlp.jsonl
-```
-
-`--last` follows recent file activity and may select a child session in multi-agent work.
-Use `--harness codex --current --latest-turn --workflow` for the invoking Codex turn plus its connected workers.
-Omit `--latest-turn` when the full history of a resumed session is the intended unit.
-Workflow expansion follows session IDs, never timestamps or worker names.
-For a latest Codex child, it selects the last parent task that structurally spawned or targeted that child ID, then includes only workers referenced by that parent task.
-This requires the parent log to record the child ID on a spawn, send, follow-up, or lifecycle event and to associate that event with a stable turn ID.
-If either field is absent, the workflow is reported incomplete instead of widening to the parent's full history.
-Missing files, duplicate IDs, contradictory parents, and cycles are reported explicitly.
-Claude Code subagent files are already folded into their parent trace, so `--workflow` normally resolves one Claude session file.
-With `--latest-turn`, ordinary Claude subagents are selected by their parent tool call ID.
-Claude Workflow subagents are selected by the run ID and transcript directory returned by the parent `Workflow` call.
-Each Workflow child attaches to the latest matching call that started before the child.
-Task selection then keeps only children attached to calls in that task.
-Returned directories from another resumed Claude session are included in parsing and source hashes.
-For a copied Claude session, preserve `<session UUID>/subagents/workflows/<run ID>` beside the parent JSONL file.
-Recorded native `.claude/projects/<project>/<session UUID>/subagents/workflows/<run ID>` paths resolve to that copied subtree when outside the selected store.
-Copy every referenced Workflow directory, including runs stored under another resumed session UUID.
-The original transcript stays unchanged, and child attribution uses its recorded Workflow identity.
-Missing copied directories, conflicting source bindings, and symlinks that change the copied session or run identity stop parsing.
-Copied Workflow directories contain regular transcript and metadata files; symlink entries stop parsing.
-Missing or conflicting Workflow identities stop the parse instead of widening the selected history.
-Cross-harness parent/child trees are not inferred.
-For a reproducible report, run `traces list` first and pass its session ID with `--session`.
-Ephemeral `codex exec --json` output has no discovery location, so select its file with `--harness codex-exec --session <path>`.
-The adapter rejects empty, incomplete, or other JSONL formats instead of emitting zero-valued session evidence.
-
-Each JSONL row is one session:
-
-- session provenance: harness, session id, cwd, path, mtime
-- explicit-session source binding: `provenance.sourceSha256` over every adapter-declared input file, including Claude worker and metadata files
-- repo labels: `tangle.subject.key`, `git.repository`, branch, commit
-- behavior metrics: span counts, LLM turns, tool calls, errored tool calls, tokens, models, tool histogram
-- mining signals: stuck loops and tool error rate
-- provenance marker: `notCampaignCell: true`
-
-That boundary matters. `agent-lab` campaign `cells.jsonl` says "arm X beat arm Y on task Z." `traces evidence` says "this real agent session had this repo/model/tool/failure shape." A downstream policy compiler can cluster these rows, propose candidate policies, then validate those policies in a separate eval campaign.
-
-### Export existing evidence/events to OpenInference
-
-If you already have compact evidence or event captures on disk, convert them to the same OpenInference JSONL shape that `traces analyze --analyzer halo` uses:
-
-```bash
-traces export policy-evidence.jsonl --out spans.openinference.jsonl
-traces export sandbox-events.json --format sandbox-events --out spans.openinference.jsonl
-traces export trajectory.json --format chat-trajectory --out spans.openinference.jsonl
-halo spans.openinference.jsonl --prompt "Analyze this trace slice" --max-turns 1
-```
-
-`traces export` accepts:
-
-- compact `traces.policy_evidence.session` JSONL from `traces evidence`
-- JSON arrays with `start`, `raw`, `result`, `done`, and `error` events. A tool call becomes one span, keyed by its message part id, however many events report on that part. The Sandbox SDK records each call as a `message.part.updated` event and again as the harness's raw `tool_use` event. The span takes its start from the part's first event, its final state from the last, and `ERROR` if any event reported one. The root span's `traces.event.tool_part_updates_merged` counts the events folded in.
-- existing OpenInference JSONL, rewritten through the local redaction path
-- chat message arrays and objects with a `messages` array
-
-Run `traces export --help` for the full command reference.
-
-## Upload to the Intelligence Platform
-
-`upload` **redacts locally before anything leaves the machine**, dedups against already-uploaded sessions, and tags each with metadata (harness, cwd, git branch, host).
-It then checks the final events of each session, exactly as they would be sent, with the share-safety verdict.
-A session that is UNSAFE or UNKNOWN is refused: it is not sent, not written to the dry-run preview, and not marked uploaded, and the command exits 1.
-
-```bash
-traces upload --since 24h --dry-run     # see exactly what would be sent; no network
-traces upload --since 24h --no-content  # send metadata only; drop all prompt/response text
-traces upload --since 24h               # send it
-```
-
-It needs `TANGLE_INGEST_URL` (or `TANGLE_ORCHESTRATOR_URL`), `TANGLE_INGEST_API_KEY` (or `TANGLE_API_KEY`), and `TANGLE_TENANT_ID`. Without them, `--dry-run` still works fully.
-
-### Redaction scope: read this before uploading prose
-
-Redaction is agent-eval's redaction core ([docs/redaction.md](https://github.com/tangle-network/agent-eval/blob/main/docs/redaction.md)), `default` profile.
-It finds credentials by field name (`apiKey`, `x-api-key`, `client.secret`, `refreshToken`) and by value shape (provider keys, GitHub, Slack, AWS and Google tokens, JWTs, bearer headers, private keys, `KEY=secret` assignments, credentials in URLs), and replaces the whole string.
-It replaces email, card, SSN and phone values in place.
-Token counts such as `input_tokens` and `max_tokens` are kept.
-It runs over every span attribute, including the captured prompt/response text.
-
-It does **not** catch names, postal addresses or account numbers written in prose. Those need a context-aware model. Three postures, strongest first:
-
-1. **`--no-content`**: upload metadata only (tool calls, tokens, timing, loop signal); no prose leaves the machine.
-2. **`--redactor <cmd>`**: run an ML PII scrubber (e.g. [`openai/privacy-filter`](https://github.com/openai/privacy-filter)) after the redaction core.
-3. Default: the redaction core.
-
-Always `--dry-run` first to see exactly what would be sent.
-
-### Check before sharing
-
-`verify-safe` reads files and says whether they are safe to share. It never changes them.
-
-```bash
-traces verify-safe bundle-dir                              # share profile (default)
-traces verify-safe session.jsonl --profile strict --format json
-traces verify-safe out/ --known-secret-env TANGLE_API_KEY  # also look for this exact key, in any encoding
-```
-
-| Status | Meaning | Exit |
-|---|---|---|
-| `SAFE` | Nothing found | 0 |
-| `SAFE_WITH_WARNINGS` | Only warnings: raw content, identifiers, embedded media | 0 |
-| `UNSAFE` | A credential remains, or personal data under `share` or `strict` | 1 |
-| `UNKNOWN` | A file, line or byte range could not be read, so its safety is unknown | 2 |
-
-`.json` files are parsed whole and `.jsonl` or `.ndjson` files line by line. Any other file is scanned as text.
-Each finding names the file, line and JSON Pointer, never the matched value.
-
-## Trace analysts
-
-Use the local checks by default.
-Add a model-backed engine only when the question needs semantic judgment or behavior discovery.
-
-```bash
-traces analyze --last 1
-traces analyze --last 1 --llm --budget 0.50
-traces analyze --last 1 --analyzer halo --analyzer-prompt "find token waste"
-traces analyze --all --last 20 --analyzer hodoscope
-traces analyze --last 1 --analyzer prime
-traces analyze --last 1 --analyzer my-installed-command
-```
-
-To ask your own question instead of the built-in kinds, use [`traces ask`](#ask-questions).
-
-HALO returns a diagnosis report.
-Hodoscope samples distinct behaviors and marks every sample `needs_review`.
-Prime posts the full span projection to an OpenAI-compatible bridge (`TRACES_PRIME_BRIDGE_URL`, default `http://localhost:4181`) and returns validated findings with span evidence.
-An arbitrary command returns a raw report unless its SDK adapter explicitly parses a stricter output type.
-
-Read [Trace analysts](./docs/trace-analysts.md) for the output contract, a minimal custom analyst, and labeled benchmark setup.
-
-**Redactors** scrub prompt/response prose with an external PII model (catching names/addresses the regex pass can't), running *after* the built-in redaction:
-
-```bash
-# the command reads a JSON array of strings on stdin, writes the scrubbed array on stdout
-traces upload --since 24h --dry-run --redactor "my-pii-scrubber"
-```
-
-In the SDK these are the `ExternalAnalyzer` and `Redactor` interfaces (`haloAnalyzer`, `hodoscopeAnalyzer`, `primeAnalyzer`, `commandAnalyzer`, `commandRedactor`, `applyRedactor`, `runExternalAnalyzers`).
-See [`examples/external-engines.ts`](./examples/external-engines.ts).
-
-> The built-in agentic analysts (`--llm`) run on the Tangle router by default: set `TANGLE_API_KEY`.
-> `OPENAI_API_KEY` alone targets OpenAI instead, and `OPENAI_BASE_URL` overrides the endpoint for any other OpenAI-compatible gateway.
-> `--llm` also needs a Python interpreter with `agent-eval-rpc[dspy]` installed, because agent-eval's model-backed analysts run through the DSPy RLM engine out of process; set `TRACES_PYTHON` to choose the interpreter.
-> The bridge protocol is version-locked: install the exact version matching this package's `@tangle-network/agent-eval` dependency (`pip install "agent-eval-rpc[dspy]==$(npm view @tangle-network/traces dependencies.@tangle-network/agent-eval)"`) — a skewed bridge kills every agentic analyst at startup.
-> When `--llm` was requested and every agentic analyst fails, `analyze`/`investigate`/`improve` still write the deterministic report, then exit 1 with each analyst's underlying error.
-> A requested `--analyzer` behaves the same way: its error is written into the report, and `analyze` then exits 1 naming every external analyzer that failed.
-> Every deterministic command — `list`, `analyze` without `--llm`, `convert`, `index`, `inspect`, `export`, `evidence`, `stream`, `watch`, `analyze --supervisor-run-dir` — needs neither a key nor Python.
-
-## Agent skills
-
-The npm package ships two AgentProfile-ready skills:
-
-| Skill | Use |
-|---|---|
-| [`inspect-agent-traces`](./skills/inspect-agent-traces/SKILL.md) | select workflows and export deterministic findings |
-| [`build-trace-analyst`](./skills/build-trace-analyst/SKILL.md) | write and calibrate a custom analyst |
-
-Load both from GitHub:
-
-```ts
-import { defineGitHubResource } from '@tangle-network/agent-interface'
-
-const ref = process.env.TRACES_SKILLS_REF
-if (!ref) throw new Error('TRACES_SKILLS_REF must be an immutable commit')
-
-const names = ['inspect-agent-traces', 'build-trace-analyst']
-const skills = names.map((name) => defineGitHubResource(`skills/${name}/SKILL.md`, {
-  repository: 'tangle-network/traces',
-  ref,
-  name,
-}))
-const profile = { name: 'trace-reviewer', resources: { skills } }
-```
-
-## Release automation
-
-Releases use a reviewed version commit because `main` is protected:
-
-1. Update `package.json` and `pnpm-lock.yaml` to the intended version on a branch.
-2. Merge that change through a pull request.
-3. Tag the exact merge commit as `vX.Y.Z` and push the tag.
-4. The Publish workflow verifies that the tag is merged into `main` and matches `package.json`, then builds, publishes to npm, and creates a GitHub release.
-5. `pnpm check:package` proves the npm tarball contains the `traces` binary before release.
-
-To retry a failed publish without changing source or version, manually run the Publish workflow with the existing tag.
-
-## Library (SDK)
-
-The CLI is a thin consumer of these exports.
-
-| Export | Signature | Use |
-|---|---|---|
-| `readOtlpInput` | `(file\|dir) → { files, skipped, rows, spans, validation, issues }` | ingest OTLP from **any** system — no adapter; never throws on a foreign trace |
-| `validateTraceSpans` | `(spans) → { ok, findings, capabilities }` | the contract's conformance check, re-exported |
-| `conformanceOfSpans` | `(spans) → TraceValidation` | grade spans this package produced, on the artifact a consumer receives |
-| `renderValidation` / `renderConformance` | `(validation, opts) → string` | the `validate` report / the section embedded in an analysis report |
-| `skippedAnalyses` | `(validation) → SkippedAnalysis[]` | which analyses a missing capability empties, and why |
-| `unavailableCapabilities` / `incompleteInputsNote` | `(validation) → Map` / `(map, name) → string` | the gate: what the trace cannot support, and the marker each affected section carries |
-| `summarizeSpanStructure` | `(spans) → SpanStructure` | how much of the tree attaches: rootless, orphans, links |
-| `analyzeLoopConvergence` | `(spans) → LoopConvergenceReport` | per loop, the per-round outcome/score series and whether it improved, plateaued, regressed or fell back |
-| `analyzeSteeringChain` | `(spans) → SteeringChainReport` | which verdict span caused which subsequent round, following `links` |
-| `llmSpan` / `toolSpan` / `loopSpan` / `branchSpan` / `steeredBy` | contract builders, re-exported | emit conforming spans from your own system |
-| `analyzeSpans` | `(spans, { registry?, ai?, budgetUsd? }) → AnalyzeResult` | run built-in analysts, or **your own** via `registry` |
-| `runTraceInvestigation` | `(TraceInvestigationOptions) → TraceInvestigationResult` | typed findings with actions/checks, execution facts, external analyzer output, and report |
-| `runTraceImprovement` | `(TraceImprovementOptions) → TraceImprovementResult` | writes the full findings, evidence, report, and trace artifact pack |
-| `runTraceQuestions` | `(TraceQuestionsOptions) → TraceQuestionsResult` | ask many free-form questions of one span list, concurrently, under one shared cost ledger; keeps each answer and checks its citations |
-| `buildTraceFindingPacket` | `({ findings }) → TraceFindingPacket` | render any `AnalystFinding[]` without changing its schema |
-| `runTraceStoreInvestigation` | `({ traceStore }) → TraceStoreInvestigationResult` | run the same packet layer over a hosted/custom `TraceAnalysisStore` |
-| `loadTracesConfig` | `(path?) → TracesConfig \| undefined` | load BYO analysts and external analyzers |
-| `watchSessions` | `(ObserverOptions) → Promise<void>` | live observer; `onLoop` / `onReport` / `signal` / `adapters` |
-| `streamSessions` | `(TraceStreamOptions) → Promise<void>` | live JSONL-ready event stream over active sessions |
-| `traceStreamEventsFromSpans` | `(spans, opts?) → TraceStreamEvent[]` | replay an existing span list as stream events |
-| `analyzeLiveBatch` | `(spans, opts?) → TraceLiveBatch` | compute semantic online findings for one batch |
-| `classifyLiveActions` | `(spans) → TraceLiveAction[]` | classify spans once as read/edit/verify/claim/tool/other |
-| `defaultTraceLiveAnalysts` | `TraceLiveAnalyst[]` | the built-in online analysts; extend or replace them |
-| `collectSessionIndex` | `(ScanOptions) → TraceSessionIndex` | scan sessions and return a reusable JSON-ready catalog |
-| `inspectSessionIndex` | `(TraceSessionIndex) → TraceInspectionReport` | rank improvement findings from an index without rescanning sessions |
-| `buildPolicyEvidenceRecord` | `(ref, spans, opts?) → PolicyEvidenceRecord` | summarize one session for downstream policy mining |
-| `collectPolicyEvidence` | `(ScanOptions) → PolicyEvidenceRecord[]` | scan harness sessions and emit policy-evidence rows |
-| `collectSessionWorkflow` | `(adapter, seeds, opts?) → SessionWorkflow` | resolve a bounded parent/child session tree with explicit relationship issues |
-| `collectSessionSelection` | `(groups, opts?) → SessionSelection` | parse, expand, and optionally byte-bind selected session groups |
-| `exportTraceEvidenceFile` | `(path, opts?) → { format, spans, redactionCount }` | convert compact evidence/events/OpenInference files to redacted OpenInference spans |
-| `scanSessions` | `(ScanOptions) → AsyncIterable<ScannedSession>` | the shared locate→parse iterator |
-| `collectSessions` | `(CollectOptions) → SessionBatch[]` | redacted per-session batches for your own pipeline |
-| `redactSpans` | `(spans, { profile?, knownSecrets? }) → { spans, report }` | redact spans with agent-eval's redaction core |
-| `assessSpans` / `verifySafe` | `(spans, profile?)` / `(path, { profile?, knownSecrets? })` → verdict | share-safety verdict for spans or files |
-| `planUpload` / `executeUpload` | `(…, { backend? }) → …` | redact + dedup + send to any sink |
-| `selectAdapters` / `listAdapters` / `resolveAdapter` | adapter selection + the harness registry |
-| `PiAdapter` | `new PiAdapter({ sessionsRoot? })` | parse Pi's default session tree or an exact `PI_CODING_AGENT_SESSION_DIR` |
-| `HarnessTraceAdapter` | interface (`locate` + `parse`) | implement to add a harness |
-| `ExternalAnalyzer` / `Redactor` | `haloAnalyzer` / `hodoscopeAnalyzer` / `commandAnalyzer` / `commandRedactor` | drive engines/models you install |
+| Find a session | `list` | [Refs, selection and harnesses](docs/select.md) |
+| What happened, exactly, for $0 | `facts` | [Session facts](docs/facts.md) |
+| What went wrong, ranked, for $0 | `analyze` | [Analyze a session](docs/analyze.md) |
+| A question facts cannot answer, with checked citations | `ask` | [Ask a question](docs/ask.md) |
+| The one gate: contracts, conformance, share safety | `check` | [Check](docs/check.md) |
+| Where two runs split | `diff` | [Diff two runs](docs/diff.md) |
+| Live supervision of sessions or a run tree | `watch` | [Watch](docs/watch.md) |
+| Hand spans to another tool | `convert` | [Convert](docs/convert.md) |
+| Keep a session's evidence | `bundle` | [Session bundle](docs/bundle.md) |
+| Send redacted sessions to Intelligence | `upload` | [Upload](docs/upload.md) |
+| Which skills are used | `skills` | [Skill usage](docs/skills.md) |
+| Span tools for an MCP client with no shell | `mcp` | [MCP server](docs/mcp.md) |
+
+Each page embeds its command's `--help`, and `tests/docs-help.test.ts` holds them equal to the CLI.
+
+```text
+traces: what your agents did, where they wasted time, whether a run passes
+Start here for one session: traces facts <ref> (25 lines); one field: add --format json | jq '<path>'
+
+  Which sessions ran?                              traces list [--cwd .] [--last N]
+  What happened (turns, PRs, failure, cost)? $0    traces facts <ref> | --current | --since 1d
+  Did we already try X / what was said? $0         traces facts <ref> | --since 30d --match '<re>'
+  Where did it waste time or get interrupted? $0   traces analyze <ref>
+  A question facts can't answer (model, $)         traces ask <ref> --question "…" --budget 1
+  Does this run pass? (CI)                         traces check <ref> --contract c.json|conformance
+  Is this safe to share?                           traces check <path> --share-safe
+  Where did two runs diverge?                      traces diff <a> <b>
+  What is happening right now?                     traces watch [<run-dir>] [--once]
+  Keep a session's evidence                        traces bundle <ref> --out <dir> · bundle verify <dir>
+  Hand spans to another tool                       traces convert <ref> --out <file>
+  Ship sessions to Intelligence                    traces upload <ref>|--since T [--dry-run]
+  Which skills are used?                           traces skills [--unused]
+  Serve span tools over MCP                        traces mcp <ref>|--last N
+
+ref: session id, or 8+ char unique prefix or suffix; session file; OTLP file/dir; bundle dir; run dir; store root
+Select: --current  --last N  --since/--until 2h|1d|ISO  --cwd DIR  --harness ID  --latest-turn
+Output: --format text|json|jsonl|junit|github  --out PATH  --no-content
+Exit: 0 yes · 1 no (fail, diverged, unsafe) · 2 could not answer (stderr says why)
+traces <command> --help for flags, jq paths and examples · moved from 0.x: traces help moved
+```
+
+## Library
 
 ```ts
-import {
-  AnalystRegistry, analyzeSpans, makeFinding, readOtlpInput, renderValidation,
-  streamSessions, watchSessions,
-} from '@tangle-network/traces'
+import { computeSessionFacts, readOtlpInput } from '@tangle-network/traces'
 
-// Read OTLP any system emitted, and find out what it can answer before analysing:
 const input = await readOtlpInput('spans.otlp.jsonl')   // or a directory
-console.log(renderValidation(input.validation, { subject: 'spans.otlp.jsonl', spans: input.spans }))
-if (input.validation.ok) await analyzeSpans(input.spans)
-
-// Observe live sessions, feed findings anywhere (read-only, cancellable):
-const c = new AbortController()
-await watchSessions({ all: true, signal: c.signal, onLoop: (l) => alert(`${l.toolName} x${l.occurrences}`) })
-
-// Feed a visualizer or dashboard:
-await streamSessions({ all: true, signal: c.signal, includeSpans: false, onEvent: (event) => console.log(event) })
-
-// Run your own analyst instead of the built-ins:
-const registry = new AnalystRegistry()
-registry.register({
-  id: 'mine', description: '…', inputKind: 'trace-store', cost: { kind: 'deterministic' }, version: '1.0.0',
-  async analyze() {
-    return [makeFinding({ analyst_id: 'mine', area: 'custom', claim: '…', severity: 'info', evidence_refs: [], confidence: 0.9 })]
-  },
-})
-await analyzeSpans(input.spans, { registry })
+console.log(input.validation.capabilities)             // what this trace can answer
+const [facts] = computeSessionFacts(input.spans)
 ```
 
-## Examples
-
-Runnable, in [`examples/`](./examples):
-
-| File | Shows |
-|---|---|
-| [`observe-and-alert.ts`](./examples/observe-and-alert.ts) | tail live sessions and alert on stuck loops |
-| [`custom-analyst.ts`](./examples/custom-analyst.ts) | register and run your own analyst |
-| [`improvement-config.mjs`](./examples/improvement-config.mjs) | plug in BYO analysts for `traces stream` / `traces improve` |
-| [`custom-backend.ts`](./examples/custom-backend.ts) | redact + dedup + upload to your own sink |
-| [`register-harness.ts`](./examples/register-harness.ts) | add a new harness by implementing `HarnessTraceAdapter` |
-| [`external-engines.ts`](./examples/external-engines.ts) | drive HALO, Hodoscope, and an external PII scrubber |
+The SDK is 25 functions and 25 types, one engine per command: [Library (SDK)](docs/sdk.md). Runnable code is in [examples](examples/README.md).
 
-## Audit benchmark
+## Docs
 
-[`bench/audit/`](./bench/audit) asks nineteen questions about three synthetic agent
-sessions and scores an arm's answers by exact match, with no model judging anything. It
-measures whether reading a session with `traces` beats reading the raw files, on facts a
-single read cannot cover: counts over hundreds of records, timestamps of specific records,
-and facts linked across tool calls and sessions.
-
-```bash
-pnpm bench:audit fixtures --out /tmp/audit-bench   # the tree an arm may read
-pnpm bench:audit gold --out /tmp/audit-gold.json   # the answer key, kept away from the arm
-pnpm bench:audit score /tmp/arm-answers.json --fixtures /tmp/audit-bench
-```
-
-[`bench/audit/README.md`](./bench/audit/README.md) documents the questions, the scoring
-rules, the answers-file format, and which answers are re-derived from the generated bytes.
-The benchmark ships outside the published package; the model arms are run by hand.
-
-## Develop
-
-```bash
-pnpm install
-pnpm dev analyze --harness claude-code --last 1   # run from source via tsx
-pnpm test
-pnpm typecheck
-pnpm build        # dist/index.js (SDK) + dist/cli.js (bin) + .d.ts
-```
+- **Commands:** the pages in the table above.
+- **Reference:** [Library (SDK)](docs/sdk.md) · [Migrate to 1.0](docs/migrate-1.0.md) · [Parsers outside traces](docs/parsers.md)
+- **Contribute:** [Develop and release](docs/develop.md): local setup, releases and how quality is measured