@tangle-network/traces 0.23.1 → 1.0.0

package/docs/migrate-1.0.md

@@ -0,0 +1,33 @@
+# Migrate to 1.0
+
+[traces](../README.md#docs) › Migrate to 1.0
+
+1.0 has 12 commands and 24 options. Every removed command and flag exits 2 and prints its replacement, with your argv rewritten where the rewrite is mechanical; `traces help moved` prints the whole table. 0.23.1 stays on npm: pin `@tangle-network/traces@0.23.1` to go back.
+
+- **Commands.** `investigate` and `improve` are `analyze` (`--out DIR`). `validate` is `check --contract conformance`, and `verify-safe` is `check --share-safe`. `stream` is `watch --format jsonl`, with the same `traces.stream.*` v1 envelope minus batch events. `export` is `convert`. `index` is `list --format json`. `evidence` is `facts --format json`. `bundle-view` is `facts --no-content`. `inspect` is `analyze`. The CodeTraceBench and replay commands are removed; use `npx --yes @tangle-network/traces@0.23.1 <command>`.
+- **Refs replace flags.** `--session`, `--otlp`, `--supervisor-run-dir` and `--source-bundle` become a positional ref. Ids, unique 8+ character prefixes or suffixes, files, directories and store roots are all refs ([refs and selection](select.md)).
+- **Selection.**
+  - `--harness` defaults to every harness, and `--all` is gone.
+  - A reading command needs a ref, `--current`, `--last` or `--since`.
+  - `--last` is by mtime and never selects your own session.
+  - `--current` works in Claude Code too; in a Codex session started from Claude Code, the Codex session wins.
+  - Children are always included; the named session is `sessions[0]`.
+  - `upload` needs a ref or `--since`.
+- **Output.** Text is the default, including for `facts`, so pass `--format json` to parse. `--dir`, `--otlp-out` and `--evidence` are `--out`. `--junit F` is `--format junit > F`. Nothing is written outside `--out` and `$XDG_STATE_HOME/traces`.
+- **Errors and exit codes:** 0 yes, 1 no, 2 could not answer. check's 3 and 4, diff's 2 and 3, and verify-safe's UNKNOWN 2 all become 2. With `--format json|jsonl`, the error is one JSON object on stderr with `code`; stdout stays empty.
+- **check needs a gate.** `check <ref>` alone exits 2. Use `--contract <file>`, `--contract conformance` or `--share-safe`. `--known-secret-env` is unchanged.
+- **Model use.** Only `ask` calls a model; `analyze --llm` is gone. `ask` requires `--budget`, caps each question at min(budget, $2), and defaults to 1800 s and concurrency 4. A partial run writes `answers.json` and exits 2 with `code: partial`. Without `TRACES_PYTHON`, the bridge runs through `uvx`.
+- **SDK.** 25 values and 25 types ([sdk](sdk.md)). Import agent-eval and agent-trace-contract names from their owners. `watchSessions` is now `streamSessions`. `runPipelines` is gone; `analyze --format json` carries its measures. `buildTraceFindingPacket` is unchanged.
+- **Harnesses.** gemini, qwen, amp and copilot are removed; pin 0.23.1 if you read them. `codex-exec` stays.
+- **mcp.** Unchanged except that its selection is refs and selection flags.
+- **facts JSON.** `measurementVersion` is 5. Fields are added: `reply`, `interrupted`, `signals`, `author`, `cost`, `matches` and the waste measures. `tokens.input` is the whole prompt, cache included, on every harness. n = 1 distributions are removed. Every existing value path is unchanged.
+- **Install.** `install.sh` refuses to overwrite a `traces` that is not this package's (Homebrew ships an unrelated one) and names it.
+
+| 0.x argv (after `traces`) | 1.0 |
+|---|---|
+| `investigate --session X` | `traces analyze X` |
+| `facts --harness codex --session P` | `traces facts P --harness codex --format json` |
+| `convert --format sandbox-events --otlp-out f x.json` | `traces convert x.json --out f` |
+| `stream --all --mode findings` | `traces watch --format jsonl` |
+| `validate f` · `verify-safe p` | `traces check f --contract conformance` · `traces check p --share-safe` |
+| `improve X --dir d --llm` | `traces analyze X --out d`, then `traces ask X --question … --budget 1` |

package/docs/parsers.md

@@ -0,0 +1,66 @@
+# Parsers outside traces
+
+[traces](../README.md#docs) › Parsers outside traces
+
+The hill: agents and operators answer every question about an agent session with `traces` and never write a transcript parser. This census lists every hand-written session parser outside traces, the command that replaces it, and the step that deletes it. A consumer PR deletes a fork only when its row in [`bench/parity/forks.json`](../bench/parity/forks.json) passes its tolerance.
+
+## How it ran (2026-10-17)
+
+On each default branch after `git fetch`: `git grep -lE 'tool_use|response_item|event_msg' origin/<default> -- . ':!*test*' ':!*fixture*' ':!docs/*' ':!*.md' ':!*.json' ':!*.jsonl'`, then every hit read and classified. Branches: dotfiles `main` b9049ca, tangle-tools `main` 1cf9239, agent-dev-container `develop` ec55d0b319, discovery-lab `master` 8fbaa456c, agent-eval `main` 16307dc8, agent-runtime `main` 89b09c8b, agent-sdk `main` 08bf6e8, trustgate `main` f7f91bd (no hits).
+`have claude project session parser` searched 198 repositories at their default branch and found nothing the grep missed. Two parsers (11, 12) read Kimi, Pi and OTLP files and match no pattern; they are listed by name.
+80 hits: 33 parsers and 47 that are not. With the 2 found by name: **35 parsers today, 26 after the 1.0 consumer PRs (steps 22 to 30), 22 after 1.1.**
+
+## Parsers
+
+| # | Repo: path | What it reads | Retired by | Release (step) |
+|---|---|---|---|---|
+| 1 | dotfiles: `claude/skills/reflect/scripts/self-audit` | rework and rule breaches in Claude Code and Codex files | counts: `facts` waste (U4); rules: `check --contract` (U16) | 1.0 (23); 1.1 |
+| 2 | dotfiles: `claude/tools/halo-extract.mjs` | HALO profile measures | `facts` (U4) | 1.0 (23) |
+| 3 | dotfiles: `claude/tools/wf-status` | Claude Code workflow runs | `watch` on workflow runs (U17) | 1.1 |
+| 4 | dotfiles: `claude/tools/skill_ledger/core.py` | PRs, human turns, tokens per skill run | `facts <session_id>` (U2, U3, U4) | 1.0 (23) |
+| 5 | dotfiles: `claude/skills/voice-ledger/scripts/multi_extract.py` | every harness's turns | `facts --format jsonl` (U2, U3) | 1.0 (23) |
+| 6 | dotfiles: `claude/analysis/wait-loss/scan_waits.py` | gaps between records | `facts` stalls (U4) | 1.x |
+| 7 | dotfiles: `claude/analysis/wait-loss/loss.py` | wait loss per session | `facts` stalls (U4) | 1.x |
+| 8 | tangle-tools: `trace-insights/mine/analyst/extract.mjs` | turns for the meta-analyst | `facts --format jsonl` (U3) | 1.0 (25) |
+| 9 | tangle-tools: `trace-insights/trace_insights/claude_adapter.py` | Claude Code to spans | `convert` | 1.0 (25) |
+| 10 | tangle-tools: `trace-insights/trace_insights/codex_adapter.py` | Codex to spans | `convert` | 1.0 (25) |
+| 11 | tangle-tools: `trace-adapters/adapt.py` | Kimi and Pi wire logs to spans | `convert` | 1.0 (25) |
+| 12 | tangle-tools: `trace-adapters/flatten.py` | collector OTLP files to rows | OTLP refs (U10) | 1.0 (25) |
+| 13 | tangle-tools: `fleet/recurrence.py` | Codex homes: tokens, topics | `facts --format json` (U2, U3) | 1.0 (25) |
+| 14 | tangle-tools: `dispatch-eval/extract.py` | dispatch rows | `facts` | 1.x |
+| 15 | tangle-tools: `lineage/lineage_collect.py` | the lineage graph | `facts` | 1.x |
+| 16 | tangle-tools: `trace-insights/mine/outputs/distill/harvest.py` | distilled turns | `facts --format jsonl` | 1.x |
+| 17 | agent-runtime: `src/runtime/codex-rollout-store.ts` | Codex rollouts as spend receipts | one parser (U18) | 1.1 |
+| 18 | tangle-tools: `fleet/deliver.py` | acknowledgements in agent records | `facts --match` | 1.x |
+| 19 | tangle-tools: `fleet/messages.py` | delivery evidence in session records | `facts --match` | 1.x |
+| 20 | tangle-tools: `lineage/lineage_outcomes.py` | Bash calls and results per session | `facts` | 1.x |
+| 21 | tangle-tools: `lineage/lineage_timeline.py` | Claude Code and Codex timelines | `facts --format jsonl` | 1.x |
+| 22 | tangle-tools: `lineage/lineage_workflows.py` | workflow lifecycle journals | `watch` on workflow runs (U17) | 1.1 |
+| 23 | tangle-tools: `fleet/weather.py` | Codex rollouts per day | `facts --since` | 1.x |
+| 24 | tangle-tools: `trace-archive/catalog.py` | tool and turn counts for the archive catalog | `list --format json`, `facts` over a store root | 1.x |
+| 25 | discovery-lab: `runner/readout-transcripts.mjs` | each agent's steps from retained sessions | `facts --format jsonl` | 1.x |
+| 26 | discovery-lab: `runner/skill-usage.mjs` | skill use in retained sessions | `facts` `measurements.skills` | 1.x |
+| 27 | discovery-lab: `runner/scorecard.mjs` | tool calls and tokens from run streams and archives | `convert`, `facts` | 1.x |
+| 28 | discovery-lab: `tools/trace-assess/science.mjs` | its assessor's required Bash calls | `check --contract` | 1.x |
+| 29 | discovery-lab: `tools/trace-assess/pdf-source.mjs` | its assessor's required Read call | `check --contract` | 1.x |
+| 30 | discovery-lab: `reports/fleet-observability/coverage.mjs` | Task spawns in run records | `facts` subagents | 1.x |
+| 31 | discovery-lab: `experiments/wait-cost-smoke/measure.mjs` | a director's per-turn usage | `facts` tokens and stalls | 1.x |
+| 32 | agent-dev-container: `products/sandbox/evals/src/local-agent-sessions.ts` | local Claude Code and Codex sessions for evals | `convert`, `facts` | 1.x |
+| 33 | agent-eval: `src/contract/intake/code-agent-session.ts` | Claude Code and Codex records for contracts | harness-sessions, as U18 does for traces | 1.x |
+| 34 | agent-eval: `src/contract/intake/code-agent-observation.ts` | the same, as observations | harness-sessions | 1.x |
+| 35 | agent-eval: `src/supervisor-run/claude-code-reader.ts` | Claude Code supervision trees (U17 extends it) | harness-sessions | 1.x |
+
+The 1.0 consumer PRs retire 2, 4, 5 and 8 to 13 (9 parsers) and the counting half of 1: 35 − 9 = 26. 1.1 retires 1 (rules), 3, 17 and 22: 22 remain, each a 1.x consumer PR for its owner after its parity row passes.
+Against the spec's expectation (23 today, 8 after 1.0, 5 after 1.1): this census read seven repositories instead of two, and found 13 parsers no step yet retires (23 to 35), and 5 of the 6 candidates are parsers (18 to 22).
+
+## Read and not a parser
+
+- dotfiles `claude/hooks/secret_scan.py`: a PostToolUse hook's payload, not a store. tangle-tools `fleet/research_observer.py`: the output of its own `claude -p` runs.
+- discovery-lab `tools/profile-ablation-report.mjs` (a comment), `reports/fleet-understanding-20261003/index.html` (a report page), `research/raw/sources/disco-research-*.txt` (source text), `prereg/factory-portfolio-20260929/sources/phony/…/{metrics,scorecard}.ts` (a frozen copy of another product), `reports/research-frontier-continuation-20260909/…/capture_usage.py` (a script inside frozen report evidence).
+- agent-dev-container: the 18 files under `packages/sdk-provider-*`, `packages/sdk-telemetry/src/sse-parser.ts`, four under `products/sandbox/sdk/src`, `products/sandbox/cli/src/commands/agent-connect.ts`, `products/platform/api/src/lib/openai-compatible-backend.ts`, `products/intelligence/api/src/routes/proxy.ts` and `products/sandbox/evals/src/auto-optimization.ts` drive a harness's live stream or a model API's `tool_use` blocks.
+- agent-eval `examples/_shared/openai-compatible-owner.ts` and `src/campaign/external-optimizer-anthropic.ts`; agent-runtime `scripts/lib/full-capacity-acceptance.mjs`, `src/runtime/profile-chat-client.ts`, `src/runtime/sandbox-events.ts` and `src/runtime/supervise/trace-source.ts`; agent-sdk `packages/agent-core` (3 files): live streams and model API blocks. agent-sdk `packages/harness-sessions/src/formats/*`: the shared reader itself.
+
+## Definition differences
+
+- **Tokens of a session with no usage record.** `fleet/recurrence.py` reports 0; `traces facts` reports `tokens.input: null` with its reason, because unknown is null, never 0. On the parity row of 2026-10-08..14 this is the whole disagreement (14 of 16 files equal; 2 Claude Code sessions with no usage record). It is a definition, not a defect: recurrence should read `null` as unknown when it moves to `facts` (step 25).
+- **Commands in a Codex code-mode script.** `self-audit` counts each `cmd` inside an `exec` script; `facts` waste counts each tool call's script. Search rows (`--match`) split scripts into single commands.

package/docs/release-1.0.0.md

@@ -0,0 +1,147 @@
+# traces 1.0.0
+
+traces answers every question about an agent session with one command: 12 commands and 24 options, down from 27 commands, each with its own `--help`, one page, and a test that spawns it.
+`facts` states what happened for $0, `analyze` ranks what went wrong for $0, `check` is the one gate, `watch` the one live view, and `ask` the only command that spends.
+Selection finds every session on every harness (every Codex home, ids by 8-character prefix or suffix, `--current` in Claude Code too), `facts` owns every number with tokens and cost checked against the raw records, `--match` searches 30 days of sessions through an incremental index, nothing is written outside `--out` and `$XDG_STATE_HOME/traces`, and `install.sh` refuses to overwrite another program's `traces`.
+The `inspect-agent-traces` skill maps each question an agent asks to the command that answers it.
+
+## Migration
+
+- **Commands.** `investigate` and `improve` are `analyze` (`--out DIR`). `validate` is `check --contract conformance`, and `verify-safe` is `check --share-safe`. `stream` is `watch --format jsonl`, with the same `traces.stream.*` v1 envelope minus batch events. `export` is `convert`. `index` is `list --format json`. `evidence` is `facts --format json`. `bundle-view` is `facts --no-content`. `inspect` is `analyze`. The CodeTraceBench and replay commands are removed; use `npx --yes @tangle-network/traces@0.23.1 <command>`.
+- **Refs replace flags.** `--session`, `--otlp`, `--supervisor-run-dir` and `--source-bundle` become a positional ref. Ids, unique 8+ character prefixes or suffixes, files, directories and store roots are all refs ([refs and selection](select.md)).
+- **Selection.**
+  - `--harness` defaults to every harness, and `--all` is gone.
+  - A reading command needs a ref, `--current`, `--last` or `--since`.
+  - `--last` is by mtime and never selects your own session.
+  - `--current` works in Claude Code too; in a Codex session started from Claude Code, the Codex session wins.
+  - Children are always included; the named session is `sessions[0]`.
+  - `upload` needs a ref or `--since`.
+- **Output.** Text is the default, including for `facts`, so pass `--format json` to parse. `--dir`, `--otlp-out` and `--evidence` are `--out`. `--junit F` is `--format junit > F`. Nothing is written outside `--out` and `$XDG_STATE_HOME/traces`.
+- **Errors and exit codes:** 0 yes, 1 no, 2 could not answer. check's 3 and 4, diff's 2 and 3, and verify-safe's UNKNOWN 2 all become 2. With `--format json|jsonl`, the error is one JSON object on stderr with `code`; stdout stays empty.
+- **check needs a gate.** `check <ref>` alone exits 2. Use `--contract <file>`, `--contract conformance` or `--share-safe`. `--known-secret-env` is unchanged.
+- **Model use.** Only `ask` calls a model; `analyze --llm` is gone. `ask` requires `--budget`, caps each question at min(budget, $2), and defaults to 1800 s and concurrency 4. A partial run writes `answers.json` and exits 2 with `code: partial`. Without `TRACES_PYTHON`, the bridge runs through `uvx`.
+- **SDK.** 25 values and 25 types ([sdk](sdk.md)). Import agent-eval and agent-trace-contract names from their owners. `watchSessions` is now `streamSessions`. `runPipelines` is gone; `analyze --format json` carries its measures. `buildTraceFindingPacket` is unchanged.
+- **Harnesses.** gemini, qwen, amp and copilot are removed; pin 0.23.1 if you read them. `codex-exec` stays.
+- **mcp.** Unchanged except that its selection is refs and selection flags.
+- **facts JSON.** `measurementVersion` is 5. Fields are added: `reply`, `interrupted`, `signals`, `author`, `cost`, `matches` and the waste measures. `tokens.input` is the whole prompt, cache included, on every harness. n = 1 distributions are removed. Every existing value path is unchanged.
+- **Install.** `install.sh` refuses to overwrite a `traces` that is not this package's (Homebrew ships an unrelated one) and names it.
+
+The full table: [docs/migrate-1.0.md](migrate-1.0.md), or `traces help moved`.
+
+## A week of one host
+
+`analyze`, `ask` and `mcp` read a `--since` sweep one session at a time and keep only what their reports need, so a week of a busy host is never held as spans.
+On drew-gtr-pro, `traces analyze --since 7d --format json` over every harness (4,079 sessions, 1.54 million spans) exits 0 at the default heap with a peak RSS of 6.5 GB in 18 minutes, under `nice -n 10` at load 40 to 65. Before, it ran out of V8 heap at the default ~4.5 GB; with a 24 GB heap it held 7.5 GB and more, and skipped agent-eval's behavioral analyst (`4063 traces exceed maxTraces=1000`). Every analyst now reads every selected trace.
+For small selections the output is unchanged: analyze JSON before and after differs only in the new fields.
+
+`facts.measurements` gains three measures, and `analyze` pools them in `measures.operating`:
+
+- `modelCalls`: the context each model call read (input + cache read + cache write), and the model's latency after a tool result by 100k-token context band. Claude Code on the GTR week: mean 366k, p50 298k tokens; reply p50 3.4 s at 0-100k and 5.3 s at 900k+.
+- `guardRefusals`: tool calls a hook refused, by guard. GTR week: 1.7 per 1,000 tool calls, process-guard most.
+- `limitStop`: the usage or weekly limit notice a session stopped on. GTR week: 81 of 129 terminal failures. Mac week: 11 of 12.
+
+A Codex task that completes with an error (`You’ve hit your usage limit`) now ends its run in error, where it read as a success.
+
+## Benchmark: traces against an agent reading the raw files (U11)
+
+`bench/audit` asks 19 questions about three synthetic sessions, scored by exact match. Each model arm is one `claude -p` agent per question, model `sonnet` (served as `claude-sonnet-5-5`), $0.25 per question, tools `Bash`, `Read`, `Grep`, `Glob`; cost is the harness's own `total_cost_usd` at list price. The rule: the traces arm answers at least as many questions correctly as the raw-files arm, at lower cost.
+
+**Step 20 (2026-10-17, Claude Code 2.1.301, traces on PATH, no skill):**
+
+| Run | raw-files correct / partial / wrong | cost | traces correct / partial / wrong | cost |
+|---|---|---|---|---|
+| 1 | 17 / 1 / 1 | $0.6712 | 16 / 2 / 1 | $0.6069 |
+| 2 | 17 / 1 / 1 | $0.6951 | 17 / 1 / 1 | $0.6693 |
+| 3 | 16 / 2 / 1 | $0.7051 | 16 / 3 / 0 | $0.6974 |
+| **Total** | **50 / 57** | **$2.0714** | **49 / 57** | **$1.9736** |
+
+**Step 21 rerun (2026-10-17, the same questions, model and budget; the traces arm loads the skill as installed):**
+
+| Run | raw-files correct / partial / wrong | cost | traces correct / partial / wrong | cost | traces arm: skill loaded / ran traces / only `--help` / no traces |
+|---|---|---|---|---|---|
+| 1 | 17 / 1 / 1 | $0.6515 | 16 / 2 / 1 | $0.7436 | 4 / 4 / 5 / 10 |
+| 2 | 17 / 1 / 1 | $0.6574 | 17 / 1 / 1 | $0.9749 | 5 / 6 / 4 / 9 |
+| 3 | 17 / 1 / 1 | $0.6789 | 17 / 2 / 0 | $0.9876 | 4 / 5 / 4 / 10 |
+| **Total** | **51 / 57** | **$1.9878** | **50 / 57** | **$2.7061** | 13 / 15 / 13 / 29 of 57 |
+
+The rule is **not met**: the traces arm answered one question fewer, at 36% more cost. The question it loses is `op.role` in all three runs: it counts runs a `labctl run` inside a code-mode script loop started, which no facts field records. Where the agent loaded the skill and ran `traces facts`, the answer cost more than a targeted `grep` on these small files: the operator session's JSON sheet is about 60 KB. A first traces run with Claude Code's 19 bundled skills also listed in the Skill tool scored 15 / 3 / 1 at $1.1506; the arm now turns them off (`bench/audit/README.md`).
+
+**The facts arm** (`traces facts <ref> --format json` mapped by fixed rules, $0, in `pnpm test`): 12 of 19 on the canonical wordings and 12 of 19 held out since #215, which answers `op.runs` and `op.role` (10 of 19 at step 21, 5 before step 20's fixes).
+
+**The large-session arm** (reported apart; it does not decide the rule): one synthetic Codex session of 50,124 spans (27 MB), four questions, one run per arm.
+
+| Arm | correct / partial / wrong | cost | note |
+|---|---|---|---|
+| facts | 4 / 0 / 0 | $0 | 8 s on a laptop |
+| raw-files | 3 / 1 / 0 | $0.1225 | counted `write_stdin` poll exits as command exits (5,252 against 4,297) |
+| traces | 3 / 1 / 0 | $0.1522 | never loaded the skill; ran `traces --help` once; the same miss |
+
+**U11 round (2026-10-17, after #215: code-mode processes by program, the `commands` sheet line, the facts-first skill).** The same questions, model and budget; at most 2 `claude -p` at a time on this Mac, each started at load1 ≤ 20 and free memory ≥ 30%.
+
+| Run | raw-files correct / partial / wrong | cost | traces correct / partial / wrong | cost | traces arm: skill loaded / ran traces / only `--help` / no traces |
+|---|---|---|---|---|---|
+| 1, step 21's arm settings, before #215's two leak fixes | 17 / 1 / 1 | $0.6847 | 19 / 0 / 0 | $0.9958 | 14 / 15 / 1 / 3 |
+| 1, account skills off | 17 / 1 / 1 | $0.6317 | 17 / 1 / 1 | $0.7530 | 15 / 15 / 0 / 4 |
+| 2, account skills off | 14 / 4 / 1 | $0.6228 | 18 / 1 / 0 | $0.6707 | 15 / 15 / 0 / 4 |
+| 3, account skills off | 17 / 2 / 0 | $0.6615 | 19 / 0 / 0 | $0.6826 | 16 / 16 / 0 / 3 |
+| **Total, account skills off** | **48 / 57** | **$1.9160** | **54 / 57** | **$2.1063** | 46 / 46 / 0 / 11 of 57 |
+
+The rule is **not met**: the traces arm answers six more questions correctly, but at 9.9% more cost. Under step 21's settings, Claude Code loaded the login account's claude.ai skills into the traces arm's Skill tool after the first request (24 `commands_changed` events in 19 questions), so each question's second turn rewrote the prompt cache: `op.tokens`, the same two calls in both arms, cost $0.0171 in raw-files and $0.0310 in traces. The arm now sets `syncClaudeAiSkills: false`: 0 such events in 57 questions, and the traces arm's median second-turn cache write fell from 4,037 to about 1,378 tokens (raw-files about 585; the rest is the skill's own text). What still costs more: `claude.bash` (+$0.097 over three runs; facts counts only the main session's Bash calls), `op.runs` (+$0.090; `--match` rows carry no exit status, so agents read the raw records), and `claude.tasks` (+$0.053; no facts field holds `subagent_type`).
+
+Large session, account skills off, three paired runs: traces 12 / 12 at $0.3579 (4 / 4 each run), raw-files 9 / 12 at $0.5494 (3 / 4 each run, counting `write_stdin` poll exits as command exits, 5,252 against 4,297); facts 4 / 4 at $0.
+
+**U11 rerun after #217 (2026-10-18, traces `e8c0d35`, on GTR).** The same questions, model (`claude -p` 2.1.302, `sonnet`), budget and arm settings; at most 2 `claude -p` at a time, each started at load1 ≤ 40 and 16 GiB available. The work trees sat under `/tmp`: under the login's home, both arms' agents loaded that home's skills, `AGENTS.md` and auto-memory.
+
+| Run | raw-files correct / partial / wrong | cost | traces correct / partial / wrong | cost | traces arm: skill loaded / ran traces / only `--help` / no traces |
+|---|---|---|---|---|---|
+| 1 | 15 / 1 / 3 | $0.5731 | 19 / 0 / 0 | $0.6029 | 12 / 12 / 0 / 7 |
+| 2 | 17 / 1 / 1 | $0.6931 | 19 / 0 / 0 | $0.6996 | 11 / 11 / 0 / 8 |
+| 3 | 16 / 2 / 1 | $0.7169 | 17 / 1 / 1 | $0.6828 | 11 / 11 / 1 / 7 |
+| **Total** | **48 / 57** | **$1.9830** | **55 / 57** | **$1.9853** | 34 / 34 / 1 / 22 of 57 |
+
+The rule is **not met**, by $0.0023 (0.1%). #217's facts closed the three gaps it named: over the three runs, `claude.bash` went from +$0.097 to −$0.004, `op.runs` from +$0.090 to −$0.052, and `claude.tasks` from +$0.053 to $0.000. What still costs more is answers that cite or quote a record. The agent reads the fact, then searches the session file for its line: `op.exit-codes` +$0.091 (no exit codes by command), `op.local-copy` +$0.066, `claude.first-bash-error` +$0.035, `op.large-output` +$0.033 (`--match` showed no output) and `op.last-human-turn` +$0.027. Large session, three pairs: traces 10 / 12 at $0.3784, raw-files 9 / 12 at $0.4097; both missed `large.commands` in most runs.
+
+## Fork parity (step 20, this Mac, 2026-10-08 to 2026-10-14)
+
+Each parser traces retires, scored against the command that replaces it; a consumer PR deletes a fork only at or above its tolerance (90%).
+
+| Fork (deleted in step) | Agreement | Disagreements and their cause |
+|---|---|---|
+| voice-ledger `multi_extract.py`, Codex (23) | 75.8%, below | Codex goal-context injections the old parser counts (traces follows Codex's own context list), and question-tool answers and screenshot turns traces dropped; **fixed in 1.0.0**: on the session that held 23 of the 45, facts now reads 19 turns instead of 14 |
+| trace-mine `extract.mjs` (25) | 93.2%, pass | Claude Code `Warmup` prompts (old only), typed slash commands (traces only) |
+| reflect `self-audit`, counting half (23) | 93.8%, pass | one code-mode session: per-`cmd` against per-script counting |
+| HALO `halo-extract.mjs` (23) | 43.8%, below | HALO counts a script-launched session's prompt as a person's turn |
+| skill_ledger `_pr_events` (23) | 93.8%, pass | `gh-drew pr create` inside Codex code-mode scripts; **fixed in 1.0.0**: that session now reads all 6 creates (#127, #130, #131, #134, #135, #136) |
+| recurrence `scan()` tokens (25) | 87.5%, below | 2 sessions with no usage record: recurrence 0, facts null with its reason; a definition, not a defect ([parsers](parsers.md)) |
+| trace_insights adapters (25) | 100%, pass | none |
+| trace-adapters `flatten.py` (25) | 100%, pass | none |
+
+## Correction signals (U21, step 10)
+
+On voice-ledger's 150 blind calibration turns (148 joined, 44 corrections), against trace-mine Opus labels:
+
+| Arm | Recall [95% CI] | Precision [95% CI] | F1 |
+|---|---|---|---|
+| interrupt | 0.091 [0.04, 0.21] | 0.400 [0.17, 0.69] | 0.148 |
+| rejected-tool | 0.068 [0.02, 0.18] | 0.750 [0.30, 0.95] | 0.125 |
+| after-claim | 0.091 [0.04, 0.21] | 0.190 [0.08, 0.40] | 0.123 |
+| union | 0.205 [0.11, 0.34] | 0.290 [0.16, 0.47] | 0.240 |
+| lexical (0.23.1 baseline) | 0.341 [0.22, 0.49] | 0.577 [0.39, 0.74] | 0.429 |
+| lexical-any | 0.591 [0.44, 0.72] | 0.553 [0.41, 0.69] | 0.571 |
+
+The union does not beat the lexical baseline, so analyze section 7 is "Interrupts and rejections", and nothing calls these signals corrections.
+
+## Finding precision (U7, step 13)
+
+HIGH and MED findings on 10 real sessions (5 Claude Code, 5 Codex), each labelled by reading the evidence:
+
+| Finding kind | Severity labelled | Findings | True | Precision | Shipped |
+|---|---|---|---|---|---|
+| `terminal-failure` | HIGH | 3 | 3 | 1.00 | HIGH |
+| `completion-claim-without-verification` | MED | 9 | 0 | 0.00 | LOW in step 13, removed in step 14 |
+| `no-self-verification` | MED | 1 | 0 | 0.00 | LOW |
+| the other six kinds | | 0 | | not measured | unchanged |
+
+## Parsers outside traces
+
+[docs/parsers.md](parsers.md) re-ran the census on seven default branches: 35 hand-written session parsers today, 26 after the 1.0 consumer PRs (steps 22 to 30), 22 after 1.1. The spec expected 23, 8 and 5: the census found 13 more parsers (discovery-lab 7, tangle-tools 2, agent-dev-container 1, agent-eval 3) that no step retires yet.

package/docs/sdk.md

@@ -0,0 +1,77 @@
+# Library (SDK)
+
+[traces](../README.md#docs) › Library (SDK)
+
+The SDK is 25 functions and 25 types. Each function is the engine of a `traces` command, or the analyst extension point (`analyzeSpans` with your own `registry`).
+[`src/index.ts`](../src/index.ts) lists them, and `tests/sdk-surface.test.ts` fails when the built package exports any other name.
+Import other packages' names from their owners: `AnalystRegistry`, `makeFinding`, `checkTraceContracts` and the redaction core from `@tangle-network/agent-eval`, and the span builders from `@tangle-network/agent-trace-contract`.
+
+| Export | Signature | Command it serves |
+|---|---|---|
+| `scanSessions` | `(ScanOptions) → AsyncGenerator<ScannedSession>` | every command: locate, then parse, each harness session |
+| `parseSession` | `(adapter, SessionRef, opts?) → Promise<OtlpSpan[]>` | one session's spans |
+| `knownHarnesses` | `() → string[]` | the ids `--harness` takes |
+| `readOtlpInput` | `(file or dir) → Promise<OtlpInput>` | read OTLP from any producer; never throws on a foreign trace |
+| `writeOtlpFile` | `(spans, path) → Promise<string>` | `traces convert <ref> --out <file>` |
+| `computeSessionFacts` | `(spans, opts?) → SessionFacts[]` | `traces facts`: one sheet per session |
+| `buildSessionFactsReport` | `(spans, opts?) → SessionFactsReport` | `traces facts <ref> --format json` |
+| `renderSessionFacts` | `(SessionFactsReport) → string` | `traces facts` text |
+| `analyzeSpans` | `(spans, AnalyzeOptions?) → Promise<AnalyzeResult>` | agent-eval's deterministic analyst, or yours through `{ registry }`; no model call |
+| `runTraceInvestigation` | `(TraceInvestigationOptions) → Promise<TraceInvestigationResult>` | `traces analyze <ref> --format json`: facts, finding packet, measures, conformance, `cannotAnswer` |
+| `buildTraceFindingPacket` | `(BuildTraceFindingPacketOptions) → TraceFindingPacket` | `findings.json` under `traces analyze <ref> --out <dir>`; renders any `AnalystFinding[]` unchanged |
+| `runTraceQuestions` | `(options) → Promise<TraceQuestionsResult>` | `traces ask`: concurrent questions under one cost ledger, citations checked |
+| `analysisEngineFromEnv` | `({ model, maxCostUsd?, timeoutMs?, onPermanentFailure?, env? }) → engine` | the model engine `traces ask` runs |
+| `conformanceOfSpans` | `(spans) → TraceValidation` | `traces check <ref> --contract conformance` |
+| `diffRuns` | `(a, b) → Promise<RunDiffReport>` | `traces diff`: two trace files or `file#<trace id>` refs |
+| `renderRunDiff` | `(RunDiffReport) → string` | `traces diff` text |
+| `streamSessions` | `(options) → Promise<void>` | `traces watch --format jsonl`: session, finding and tick events (`TraceStreamEvent`) |
+| `redactSpans` | `(spans, { profile?, knownSecrets? }) → { spans, report }` | redaction before `upload` |
+| `assessSpans` | `(spans, profile?) → ShareSafetyVerdict` | the share verdict for spans |
+| `verifySafe` | `(path, { knownSecrets? }) → Promise<VerifySafeResult>` | `traces check <path> --share-safe` |
+| `planUpload` | `(opts?) → Promise<UploadPlan>` | `traces upload <ref> --dry-run` |
+| `executeUpload` | `(UploadPlan, { backend? }) → Promise<result>` | `traces upload`, to Intelligence or your own `UploadBackend` |
+| `assembleSessionBundle` | `({ adapter, ref, outDir }) → Promise<result>` | `traces bundle` |
+| `verifySessionBundle` | `(dir) → Promise<verification>` | `traces bundle verify <dir>` |
+| `tracesVersion` | `() → string` | `traces --version` |
+
+**Types:** `OtlpSpan`, `SessionRef`, `ScanOptions`, `ScannedSession`, `HarnessTraceAdapter`, `OtlpInput`, `SessionFact`, `SessionFacts`, `SessionFactsReport`, `SessionTurnFact`, `AnalyzeOptions`, `AnalyzeResult`, `TraceInvestigationOptions`, `TraceInvestigationResult`, `TraceFindingPacket`, `BuildTraceFindingPacketOptions`, `TraceQuestion`, `TraceQuestionsResult`, `RunDiffReport`, `TraceStreamEvent`, `TraceLiveFinding`, `UploadPlan`, `UploadBackend`, `VerifySafeResult`, `SessionBundleManifest`.
+An options type that is not listed is still in `dist/index.d.ts`; name it as `Parameters<typeof runTraceQuestions>[0]`.
+
+```ts
+import { analyzeSpans, readOtlpInput, streamSessions } from '@tangle-network/traces'
+
+const input = await readOtlpInput('spans.otlp.jsonl')   // any producer; never throws on a foreign trace
+console.log(input.validation.capabilities)
+
+const stop = new AbortController()
+await streamSessions({ signal: stop.signal, onEvent: (event) => { if (event.event === 'finding') console.log(event.finding.claim) } })
+```
+
+## Write your own analyst
+
+An analyst receives a paged trace store and returns typed findings; start with deterministic logic when the trace holds the facts.
+
+```ts
+import { buildDefaultAnalystRegistry, defineTraceAnalyst, makeFinding } from '@tangle-network/agent-eval/analyst'
+import { analyzeSpans } from '@tangle-network/traces'
+
+const failedTools = defineTraceAnalyst({
+  id: 'failed-tools',
+  description: 'Reports repeated tool failure signatures.',
+  async analyze(store) {
+    const overview = await store.getOverview({ has_errors: true })
+    return overview.error_clusters.map((cluster) => makeFinding({
+      analyst_id: 'failed-tools', area: 'tool-use', subject: cluster.signature,
+      claim: `${cluster.span_count} spans share this failure`, severity: cluster.span_count >= 3 ? 'high' : 'medium',
+      evidence_refs: [{ kind: 'span', uri: `trace://${cluster.exemplar_trace_ids[0]}/span/${cluster.exemplar_span_ids[0]}` }],
+      confidence: 1, id_basis: cluster.signature,
+    }))
+  },
+})
+const registry = buildDefaultAnalystRegistry()
+registry.register(failedTools)
+const { result } = await analyzeSpans(spans, { registry })
+```
+
+The runnable version is [`examples/custom-analyst.ts`](../examples/custom-analyst.ts) (`pnpm tsx examples/custom-analyst.ts --fixture` prints its one finding).
+Do not rewrite policy from an analyst's prose alone: attach a measured outcome or reviewed feedback, promote the failure into an eval case, change one thing, and compare on fresh cases.

package/docs/select.md

@@ -0,0 +1,70 @@
+# Refs, selection and harnesses
+
+[traces](../README.md#docs) › Refs, selection and harnesses
+
+Every reading command takes refs, or a selection, and the same flags choose sessions everywhere.
+`traces list` finds a session: one row per session, newest first, across every harness, never the caller's own.
+
+```bash
+traces list --cwd . --last 5
+traces facts 019a3c7e                 # a ref list printed
+```
+
+## Refs
+
+A ref is sniffed, so no flag names its type:
+
+- an existing path, read by its content: a harness session file (its store root decides the harness, else its first record), a Sandbox live stream (`"backend":"codex"` envelopes, read as `codex-exec`), a sandbox-events recording, contract OTLP-JSONL, standard OTLP/JSON (`resourceSpans`, one document or one envelope per line), `claude -p` stream-json, OpenInference JSONL, a directory of OTLP files, a bundle directory, a Runtime run directory, or a **store root**: a directory that holds harness stores the way a home does, such as a trace archive's `/mnt/traces/<host>/home`;
+- otherwise a session id, or a unique prefix or suffix of 8 or more characters, looked up across every harness. An ambiguous ref exits 2 with `code: ambiguous` and lists the candidates.
+
+`file#<traceId>` and `file#branch=<id>` name one run of several. `--harness` with a file ref forces that reader.
+
+## Selection
+
+A reading command needs a ref, `--current`, `--last N` or `--since T`; `--cwd`, `--harness`, `--until` and `--latest-turn` only narrow. `list` defaults to `--last 20`, `watch` to `--since 30m`, `skills` to `--since 30d`.
+
+- `--current` is the caller's own session: `CODEX_THREAD_ID` (Codex) wins, else `CLAUDE_CODE_SESSION_ID`. On Pi, OpenCode or Kimi, `traces list --cwd . --last 1` names it.
+- `--last N` is the N session files with the newest mtime, never the caller's own session.
+- `--since T` / `--until T` select every session with a record in the window (`30m`, `2h`, `7d`, or an ISO time).
+- `--cwd DIR` matches the cwd the session recorded, on a path boundary; a live worktree of the same repo; or, for Codex, the recorded repo of a removed worktree.
+- `--latest-turn` keeps a resumed Codex or Claude Code session to its latest task and the workers spawned from it.
+
+A named session brings its spawned children, up to 100: it is `sessions[0]`, each child follows with `parentSessionId`, and no number of the named session includes a child's.
+In a window, `--last` or a machine-wide selection, a session that cannot be read is skipped and named in `selection.unreadSessions`; a named ref that cannot be read exits 2 with `code: unreadable`.
+
+## Harnesses
+
+| Harness | Reads from |
+|---|---|
+| `claude-code` | `~/.claude/projects/<cwd>/*.jsonl` and subagent sidechains, or a `claude -p --output-format stream-json` file |
+| `codex` | every Codex home: `~/.codex` and `~/.codex-*` siblings, `$CODEX_HOME`, and `~/.config/agent-accounts/codex/<account>`, each with `sessions/` and `archived_sessions/` |
+| `codex-exec` | a `codex exec --json` file or a Sandbox live stream (a file ref) |
+| `opencode` | `~/.local/share/opencode/opencode.db`, read in place, and older `storage/` JSON sessions |
+| `pi`, `kimi`, `factory` | their session stores under the home |
+
+Native stores are read through [`@tangle-network/harness-sessions`](https://github.com/tangle-network/agent-sdk/tree/main/packages/harness-sessions); `--latest-turn` uses traces' own Claude Code and Codex readers until one parser lands (1.1), and `tests/dual-path.test.ts` holds the two equal.
+Claude Code subagent files fold into their parent trace; Codex workers are sessions of their own, joined by the session id or task path a child records.
+Unknown is null with its reason, never 0: Kimi's wire log has no served model, so its model stays unknown.
+
+## `traces list --help`
+
+```text
+Usage: traces list [<store-root>] [--last N | --since T] [--cwd DIR] [--harness ID] [--format text|json]
+Find a session: one row per session, newest first, across every harness, never the caller's own.
+
+  --last N            the N newest sessions (default 20)
+  --since T           every session with a record since T: 30m, 2h, 7d or an ISO time
+  --cwd DIR           sessions recorded in DIR or under it, or in a worktree of its repo
+  --harness ID        only this harness's sessions
+  --format text|json  text (default), or json with id, path, bytes and parent id
+
+jq paths (--format json):
+  .sessions[].ref                       the short ref any command takes
+  .sessions[] | {id, cwd, firstPrompt}  which session is which
+  .selection.unreadSessions             sessions that could not be read, and why
+
+Examples:
+  traces list --cwd . --last 5
+  traces list --since 1d --harness codex
+  traces list --format json | jq -r '.sessions[0].id'
+```

package/docs/skills.md

@@ -0,0 +1,46 @@
+# Skill usage
+
+[traces](../README.md#docs) › Skill usage
+
+`traces skills` says which skills are used, and which installed skills never are, across Claude Code, Codex and Kimi Code sessions on this machine. It calls no model.
+
+```bash
+traces skills                     # the last 30 days, with the installed catalog joined
+traces skills --unused            # installed skills with no use in the window
+traces skills --format json       # rows, unused skills, refresh cost and sweep exclusions
+```
+
+A run reads only transcript bytes appended since the previous run, and stores events in `$XDG_STATE_HOME/traces/skill-usage.json`. The first run reads the whole corpus (about two minutes for 41 GB); later runs take seconds. 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 |
+| `read` | Codex, Kimi Code | a completed command that reads `<skill>/SKILL.md`, the closest observable act |
+
+Each event is keyed by its record id, so a resumed session counts once. One command that reads three or more skills is a catalog sweep; its reads are excluded and reported apart.
+`traces facts` counts one session's skill use with the same classifier (`measurements.skills`).
+`installed` names the harnesses whose catalog lists the skill: `~/.claude/skills` and enabled plugins, `~/.codex/skills` and `~/.agents/skills`.
+
+This package ships one skill, [`inspect-agent-traces`](../skills/inspect-agent-traces/SKILL.md): a table from each question an agent asks about a session to the command that answers it. Install it where your harness reads skills (`~/.claude/skills/inspect-agent-traces/`).
+
+## `traces skills --help`
+
+```text
+Usage: traces skills [--since T] [--unused] [--format text|json]
+Which skills are used, and which installed skills never are; no model call.
+Reads Claude Code, Codex and Kimi Code sessions; each run reads only bytes appended since the last.
+
+  --since T           count use since T: 30m, 2h, 7d or an ISO time (default 30d)
+  --unused            only installed skills with no use in the window
+  --format text|json  text (default), or json with the refresh cost and sweep exclusions
+
+jq paths (--format json):
+  .rows[] | {skill, sessions}  use per skill
+  .unused[].skill              installed skills never used in the window
+
+Examples:
+  traces skills --since 30d
+  traces skills --unused
+  traces skills --format json | jq '.rows[] | {skill, sessions}'
+```

package/docs/upload.md

@@ -0,0 +1,47 @@
+# Upload
+
+[traces](../README.md#docs) › Upload
+
+`traces upload` sends redacted sessions to the Tangle Intelligence Platform. It needs a ref or `--since`; with neither it exits 2 and prints `--since 24h`.
+
+```bash
+traces upload --since 24h --dry-run              # see what would be sent; no network
+traces upload --since 24h --no-content           # metadata only
+traces upload spans.otlp.jsonl --dry-run --out preview.otlp.jsonl
+```
+
+`upload` redacts locally before anything leaves the machine, dedups against sessions already sent, and tags each with its harness, cwd, branch and host.
+It then checks each session's final events, exactly as they would be sent, with the share-safety verdict: an UNSAFE or UNKNOWN session is not sent, not previewed and not marked uploaded, and the command exits 1.
+It needs `TANGLE_INGEST_URL`, `TANGLE_INGEST_API_KEY` (or `TANGLE_API_KEY`) and `TANGLE_TENANT_ID`; `--dry-run` works without them.
+
+## What redaction catches
+
+Redaction is agent-eval's redaction core, `default` profile: credentials by field name and by value shape (provider keys, GitHub, Slack, AWS and Google tokens, JWTs, bearer headers, private keys, `KEY=secret`, credentials in URLs), and email, card, SSN and phone values. It does not catch names, postal addresses or account numbers in prose. Three postures, strongest first:
+
+1. `--no-content`: metadata only, the same rule as `traces convert <ref> --no-content`.
+2. Your own scrubber on a file: `traces convert <ref> --out spans.jsonl`, scrub `spans.jsonl`, then `traces upload spans.jsonl`; upload still redacts and gates it.
+3. The redaction core alone.
+
+Run `--dry-run` first. `traces check <path> --share-safe` gives the same verdict for any file ([check](check.md)).
+
+## `traces upload --help`
+
+```text
+Usage: traces upload <ref…> | --current | --since T [--dry-run] [--no-content] [--yes]
+Send redacted sessions to Tangle Intelligence; one still UNSAFE or UNKNOWN once redacted is refused (exit 1).
+Env: TANGLE_INGEST_URL, TANGLE_INGEST_API_KEY (or TANGLE_API_KEY), TANGLE_TENANT_ID.
+
+  --current           the caller's own session: CODEX_THREAD_ID, else CLAUDE_CODE_SESSION_ID
+  --since T           every session with a record since T: 30m, 2h, 7d or an ISO time
+  --cwd DIR           sessions recorded in DIR or under it, or in a worktree of its repo
+  --harness ID        read only this harness; with a file ref, force its reader
+  --dry-run           redact and preview; send nothing
+  --no-content        strip prompt and response text; send metadata only
+  --yes               skip the confirmation prompt
+  --out PATH          with --dry-run: write the redacted OTLP preview to PATH
+
+Examples:
+  traces upload --since 24h --dry-run
+  traces upload 019a3c7e --yes
+  traces upload spans.otlp.jsonl --dry-run --out preview.otlp.jsonl
+```

package/docs/watch-jsonl.v1.example.jsonl

@@ -0,0 +1,5 @@
+{"schemaVersion":1,"kind":"traces.stream.session","event":"session","generatedAt":"2026-10-16T10:40:00.000Z","session":{"harness":"claude-code","sessionId":"a11a1a11-aaaa-4aaa-8aaa-aaaaaaaaaaaa","cwd":"/w/analyzed-repo","path":"/tmp/traces-watch-fixture/home/.claude/projects/-w-analyzed-repo/a11a1a11-aaaa-4aaa-8aaa-aaaaaaaaaaaa.jsonl"},"spanCount":28,"startedAt":"2026-10-14T10:00:00.000Z","endedAt":"2026-10-16T10:29:20.000Z"}
+{"schemaVersion":1,"kind":"traces.stream.finding","event":"finding","generatedAt":"2026-10-16T10:40:00.000Z","finding":{"schemaVersion":1,"kind":"traces.live_finding","id":"live.same-failing-command.2e9548f302d43a89","fingerprint":"2e9548f302d43a89","ruleId":"same-failing-command","severity":"high","title":"The same command failed again and again","claim":"`pnpm test` failed 3× in a row (5 min).","action":"Stop rerunning it; read the first failure, change state, or choose a different diagnostic path before another run.","check":"The next action should read the failing output, edit code or config, or run a narrower command before this one runs again.","evidence":[{"kind":"pattern","label":"command","value":"pnpm test","spanIds":["1299987ef6149612","87c74570a098898a","7d199fa0631ea55b"]},{"kind":"metric","label":"failed_runs_in_a_row","value":"3"},{"kind":"metric","label":"minutes","value":"5"}],"session":{"harness":"claude-code","sessionId":"a11a1a11-aaaa-4aaa-8aaa-aaaaaaaaaaaa","cwd":"/w/analyzed-repo","path":"/tmp/traces-watch-fixture/home/.claude/projects/-w-analyzed-repo/a11a1a11-aaaa-4aaa-8aaa-aaaaaaaaaaaa.jsonl"},"observedAt":"2026-10-16T10:40:00.000Z"}}
+{"schemaVersion":1,"kind":"traces.stream.finding","event":"finding","generatedAt":"2026-10-16T10:40:00.000Z","finding":{"schemaVersion":1,"kind":"traces.live_finding","id":"live.verification-without-change.90335ccea7b19082","fingerprint":"90335ccea7b19082","ruleId":"verification-without-change","severity":"medium","title":"A check is rerun without a change","claim":"`pnpm test` ran 3× with no edit between.","action":"Do not run the check again until the agent edits state or says what new signal the rerun will reveal.","check":"The next action should be an edit, a targeted read, or a different, narrower check.","evidence":[{"kind":"pattern","label":"check","value":"pnpm test","spanIds":["1299987ef6149612","87c74570a098898a","7d199fa0631ea55b"]},{"kind":"metric","label":"runs_without_an_edit","value":"3"}],"session":{"harness":"claude-code","sessionId":"a11a1a11-aaaa-4aaa-8aaa-aaaaaaaaaaaa","cwd":"/w/analyzed-repo","path":"/tmp/traces-watch-fixture/home/.claude/projects/-w-analyzed-repo/a11a1a11-aaaa-4aaa-8aaa-aaaaaaaaaaaa.jsonl"},"observedAt":"2026-10-16T10:40:00.000Z"}}
+{"schemaVersion":1,"kind":"traces.stream.finding","event":"finding","generatedAt":"2026-10-16T10:40:00.000Z","finding":{"schemaVersion":1,"kind":"traces.live_finding","id":"live.high-tool-error-rate.f58f47ed22ff6ead","fingerprint":"f58f47ed22ff6ead","ruleId":"high-tool-error-rate","severity":"medium","title":"Tool calls are mostly failing","claim":"3/6 tool call(s) ended with ERROR.","action":"Switch from broad execution to diagnosis: classify the dominant error, then run one targeted command to validate the fix path.","check":"The next calls should reduce the error ratio or show a new targeted diagnostic result.","evidence":[{"kind":"metric","label":"errored_tool_calls","value":"3/6","spanIds":["1299987ef6149612","87c74570a098898a","7d199fa0631ea55b"]}],"session":{"harness":"claude-code","sessionId":"a11a1a11-aaaa-4aaa-8aaa-aaaaaaaaaaaa","cwd":"/w/analyzed-repo","path":"/tmp/traces-watch-fixture/home/.claude/projects/-w-analyzed-repo/a11a1a11-aaaa-4aaa-8aaa-aaaaaaaaaaaa.jsonl"},"observedAt":"2026-10-16T10:40:00.000Z"}}
+{"schemaVersion":1,"kind":"traces.stream.tick","event":"tick","generatedAt":"2026-10-16T10:40:00.000Z","sessions":1,"newSpans":28,"findings":3,"unreadSessions":[{"sessionId":"0199f9d0-9999-7999-8999-999999999999","source":"/tmp/traces-watch-fixture/home/.codex/sessions/2026/10/16/rollout-2026-10-16T10-30-00-0199f9d0-9999-7999-8999-999999999999.jsonl","reason":"codex adapter output contains duplicate span identity (3b14c728e785beeaa7fb4d0f5fa96b4f, 7d00cfb5b23dd5f4)"}]}

package/docs/watch.md

@@ -0,0 +1,66 @@
+# Watch live sessions and run trees
+
+[traces](../README.md#docs) › Watch
+
+`traces watch` runs the analyze rules on every session active in the last 30 minutes, on every harness, while the agents still run: a command that failed 3 or more times in a row, a check rerun 3 or more times with no edit between, and half or more of a session's tool calls failing.
+Sessions are read every 5 s and the window slides, so a feed left running never goes blind. A session that cannot be read is skipped and named.
+
+```bash
+traces watch --once                  # one pass over every active session
+traces watch --since 2h --cwd .      # this repo's sessions of the last two hours, live
+traces watch --format jsonl          # the machine feed
+```
+
+Text prints one line per new finding:
+
+```
+10:06:00 HIGH a11a1a11 claude-code same-failing-command: `pnpm test` failed 3× in a row (5 min). (spans t1, t2, …)
+```
+
+## The `traces.stream` envelope
+
+`--format jsonl` prints the same events the text renders, at `schemaVersion` 1. It is a stable API: [`watch-jsonl.v1.example.jsonl`](./watch-jsonl.v1.example.jsonl) is the CLI's output on a fixture, and `tests/watch-jsonl-contract.test.ts` holds it and the fields consumers read.
+
+| `kind` | When | Fields |
+|---|---|---|
+| `traces.stream.session` | the first pass that reads a session | `session` (`harness`, `sessionId`, `cwd`, `path`), `spanCount`, `startedAt`, `endedAt` |
+| `traces.stream.finding` | the first pass that finds it | `finding`: `ruleId`, `fingerprint`, `severity`, `claim`, `action`, `check`, `evidence`, `session`, `observedAt` |
+| `traces.stream.tick` | the end of every pass | `sessions`, `newSpans`, `findings`, `unreadSessions` |
+
+Every event also carries `schemaVersion`, `event` and `generatedAt`. Custom live rules go through the SDK: `streamSessions({ extraAnalysts })`.
+
+## A run tree
+
+`traces watch <run-dir>` tails one run that fans work out to other agents: per node its status, runtime, authored budget and actual spend, at any depth. It is plain stdout, so it works over SSH, in a CI log and through a pipe. A run tree is read every 2 s until its result lands, and a run that ended with an error exits 1.
+
+```bash
+traces watch runs/my-run --once
+traces watch traces.otlp.jsonl       # spans only, from any emitter with parent span ids
+```
+
+Two sources sit behind it, and the output names which number came from which: OTLP spans (tree shape, wall time, tokens, cost when priced) and agent-runtime's `spawn-journal.jsonl` (authored budget, settled spend, blocking questions, steers, the result).
+A node's own driving and the work it delegated are separate lines, and an unpriced turn reads `cost unknown`, never `$0.0000`. `traces analyze <run-dir>` writes the full report.
+
+## `traces watch --help`
+
+```text
+Usage: traces watch [<id…> | <store-root>] [--since T] [--once]  |  watch <run-dir|span file> [--once]
+Live supervision: what the analyze rules find in every session active in the last 30 minutes, or one run tree.
+Sessions are read every 5 s; a run tree every 2 s, until its result lands (exit 1 when the run ended with an error).
+A run dir or span file prints its tree as text, and its findings with --format jsonl.
+
+  --since T           sessions active in the last T (default 30m; it slides with time), or since an ISO time
+  --cwd DIR           sessions recorded in DIR or under it, or in a worktree of its repo
+  --harness ID        only this harness's sessions; with a file ref, force its reader
+  --once              one pass, then exit
+  --format text|jsonl text (default): a line per new finding, or the run tree; jsonl: the traces.stream events
+
+jq paths (--format jsonl):
+  select(.event == "finding") | .finding | {severity, ruleId, claim}  each new finding
+  select(.event == "tick") | .unreadSessions                          sessions a pass could not read, and why
+
+Examples:
+  traces watch --once
+  traces watch runs/my-run --once
+  traces watch --since 2h --format jsonl
+```

package/examples/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+[traces](../README.md#docs) › Examples
+
+Runnable examples for the SDK. Run one with `pnpm tsx examples/<file>`.
+
+| File | Shows |
+|---|---|
+| [`custom-analyst.ts`](./custom-analyst.ts) | register and run your own analyst |