@tangle-network/traces 0.23.1 → 1.0.1

package/dist/supervisor-run-context-WO6VOTGV.js

@@ -0,0 +1,30 @@
+import {
+  COORDINATION_LOG_FILE,
+  RESULT_FILE,
+  SPAWN_JOURNAL_FILE,
+  ZERO_ROLL,
+  addSpend,
+  fileRunContextSupervisorRunReader,
+  inferRole,
+  isFileRunContextDir,
+  mergeRolls,
+  readCoordinationLog,
+  readFileRunContext,
+  readRunContextJournal,
+  readRunContextSnapshot
+} from "./chunk-M3W6TZHQ.js";
+export {
+  COORDINATION_LOG_FILE,
+  RESULT_FILE,
+  SPAWN_JOURNAL_FILE,
+  ZERO_ROLL,
+  addSpend,
+  fileRunContextSupervisorRunReader,
+  inferRole,
+  isFileRunContextDir,
+  mergeRolls,
+  readCoordinationLog,
+  readFileRunContext,
+  readRunContextJournal,
+  readRunContextSnapshot
+};

package/dist/upload-3R7GRSKS.js

@@ -0,0 +1,20 @@
+import {
+  PartialUploadError,
+  executeUpload,
+  planUpload,
+  planUploadFrom,
+  toTraceSpanEvents
+} from "./chunk-TOCNGML5.js";
+import "./chunk-6GOG5KIK.js";
+import "./chunk-7USMM4MA.js";
+import "./chunk-UQSAGXPH.js";
+import "./chunk-CQ6UYZG6.js";
+import "./chunk-RZL5GAWH.js";
+import "./chunk-DU534HAX.js";
+export {
+  PartialUploadError,
+  executeUpload,
+  planUpload,
+  planUploadFrom,
+  toTraceSpanEvents
+};

package/dist/verify-safe-C5ZXZOZ2.js

@@ -0,0 +1,8 @@
+import {
+  formatVerdict,
+  verifySafe
+} from "./chunk-4VKPN432.js";
+export {
+  formatVerdict,
+  verifySafe
+};

package/docs/analyze.md

@@ -0,0 +1,76 @@
+# Analyze a session
+
+[traces](../README.md#docs) › Analyze a session
+
+`traces analyze` says what went wrong in the selected sessions, ranked, for $0. It calls no model: `traces ask` is the one command that spends.
+
+```bash
+traces analyze --current
+traces analyze 019a3c7e --out analysis      # report.md and findings.json
+traces analyze --since 1d --cwd .           # a table of the sessions with the most waste
+```
+
+## The text
+
+At most 40 lines, in this order. A section with nothing to say is left out, and a fact the trace cannot support is never printed as 0.
+
+1. Header: short id, harness, repo, window, active time and cost (list price, Router rates).
+2. What was asked: the first human turn, and how many followed.
+3. The first failure and its blame.
+4. Failing commands (3 or more identical failures in a row) and rework (reruns, reverts).
+5. Tool-error clusters: the session's own failed calls, by tool and first line of error.
+6. Stalls of 10 minutes or more that no turn ended.
+7. Interrupts and rejections, each quoted. Measured against labelled turns, none of these is called a correction.
+8. Pull requests opened and merged.
+9. Findings, HIGH first, with span ids.
+10. How many questions the trace cannot answer, and where the list is.
+
+The header and sections 3, 4, 6, 7 and 8 are the [facts](facts.md) sheet's numbers; analyze renders them and never counts them again. Several sessions put sections 2 to 8 in a table of the 15 with the most waste.
+
+## Findings
+
+| Finding | From | Severity |
+|---|---|---|
+| `same-failing-command` | a failing streak in the facts sheet | HIGH |
+| `verification-without-change` | one check run 3 or more times with no edit between | MED (HIGH from 5) |
+| `high-tool-error-rate` | half or more of the session's own tool calls failed | MED (HIGH from 75%) |
+| `terminal-failure` | the session's root span ended in an error | HIGH |
+| `monotonic-input-growth`, `output-length-decay` | agent-eval's behavioral analyst | HIGH, MED |
+| `single-tool-dependency` | a run of 10 or more calls of one non-shell tool | MED |
+| `no-self-verification` | 10 or more calls, none a check | LOW (0 of 1 held on real sessions) |
+
+The first three are the rules `traces watch` runs live, so a finding means the same in both.
+
+## For programs
+
+`--format json` prints `facts`, `packet` (the finding packet ADC's Intelligence API reads), `measures`, `conformance` and `cannotAnswer` (every question the trace cannot answer, with the reason). `measures.operating` pools the sheets' `modelCalls`, `guardRefusals` (per 1,000 tool calls) and `limitStop` (with how many terminal failures were limit stops). A `--since` sweep reads one session at a time, so a week of a busy host fits in a few gigabytes.
+`--out DIR` writes exactly `report.md` (every finding and every cannot-answer reason) and `findings.json` (the packet).
+A Runtime run directory as the ref reports its supervision tree. Your own analysts run through the SDK: `analyzeSpans(spans, { registry })` ([sdk](sdk.md)).
+
+## `traces analyze --help`
+
+```text
+Usage: traces analyze <ref…> | --current | --last N | --since T [flags]
+What went wrong, ranked, for $0: failing commands, stalls, interrupts, findings, and what the trace cannot answer.
+At most 40 lines; several sessions get a table of the 15 with the most waste. A Runtime run dir reports its tree.
+
+  --current           the caller's own session: CODEX_THREAD_ID, else CLAUDE_CODE_SESSION_ID
+  --last N            the N newest sessions by file mtime, never the caller's own
+  --since T           every session with a record since T: 30m, 2h, 7d or an ISO time
+  --until T           close the --since window (exclusive); same forms
+  --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
+  --latest-turn       only the latest task turn of a resumed Codex or Claude Code session
+  --format text|json  text (default, at most 40 lines) or json: facts, packet, measures, conformance, cannotAnswer
+  --out DIR           write report.md and findings.json under DIR; stdout gets one summary line
+
+jq paths (--format json):
+  .packet.findings[] | {severity, subject, claim}  the findings, HIGH first
+  .cannotAnswer[] | {analysis, reason}             what the trace cannot answer, and why
+  .facts.sessions[0].measurements.waste            failing streaks, stalls, reverts
+
+Examples:
+  traces analyze --current
+  traces analyze 019a3c7e --out analysis
+  traces analyze --since 1d --cwd .
+```

package/docs/ask.md

@@ -0,0 +1,88 @@
+# Ask a question
+
+[traces](../README.md#docs) › Ask a question
+
+`traces ask` answers a question `traces facts` cannot, with checked `trace://` citations. It is the one command that calls a model.
+
+```bash
+traces ask 019a3c7e --question "Which command failed first, and why?" --budget 1
+traces ask --last 3 --questions questions.json --budget 2 --out answers
+```
+
+`--budget` is required: the most the run may spend, shared by every question. Each question spends at most the smaller of `--budget` and $2, within 1,800 s, and 4 run at once.
+A question is at most 705 characters, so the engine sees it whole; put detail in an entry's `instructions`.
+
+## Questions from a file
+
+The file is a JSON array of question strings or entries `{ id?, question, instructions?, answerSchema? }`.
+An `answerSchema` makes the answer one JSON value a scorer can compare; it accepts `type`, `properties`, `required`, `additionalProperties`, `items`, `enum`, `const`, `title` and `description`, and any other keyword is rejected before the run starts.
+
+```json
+[
+  "Which pull requests did this session open?",
+  { "id": "merged", "question": "Which pull requests were merged?", "answerSchema": { "type": "array", "items": { "type": "integer" } } }
+]
+```
+
+## What the run guarantees
+
+- Every question receives the [facts](facts.md) sheet before its first model call.
+- Every `trace://<trace>/span/<span>` citation is resolved; an unresolvable one fails that question. Findings pass the same evidence gate as the built-in kinds, and refusals are counted by reason.
+- A failed question never stops the others. Ctrl-C keeps the answers already bought.
+- `answers.json` and `report.md` (under `--out`) are written before the exit code is decided. Some questions unanswered: exit 2 with `code: partial`.
+- Each cost carries its provenance (`observed`, `estimated` or `uncaptured`); an uncaptured cost stays null.
+- The ledger reserves each call's maximum before it runs, so a budget below one call is refused before any spend.
+
+## Setup and refusals
+
+`ask` needs `TANGLE_API_KEY` (or `OPENAI_API_KEY` with `OPENAI_BASE_URL`) and the DSPy bridge: with `uv` installed it runs `uvx --from agent-eval-rpc[dspy]==<version>`, or `TRACES_PYTHON` names a Python that has it. A missing key or bridge exits 2 with `code: setup` before anything is read or spent.
+
+| Refusal from the endpoint | What `ask` does |
+|---|---|
+| 408, 425, 429, 5xx, no connection | retries the call: 2 s doubling to 60 s, 10 attempts, inside the question's deadline |
+| 401, 402, 403 | stops every question; exit 2, `code: auth` |
+| model not allowed, not found or unpriced | stops every question; exit 2, `code: model` |
+| anything else | fails that question alone |
+
+## SDK
+
+```ts
+import { analysisEngineFromEnv, runTraceQuestions } from '@tangle-network/traces'
+
+const result = await runTraceQuestions({
+  questions: [{ id: 'first-failure', question: 'Which command failed first?' }],
+  spans,
+  engine: analysisEngineFromEnv({ model: 'gpt-5.6-luna', maxCostUsd: 1 }),
+  budgetUsd: 2,
+})
+```
+
+## `traces ask --help`
+
+```text
+Usage: traces ask <ref…> | --current | --last N | --since T --question TEXT [flags]
+A question facts cannot answer, with checked trace:// citations: the only command that calls a model.
+Each question spends at most min(--budget, $2) within 1800 s; 4 run at once. Some unanswered: exit 2.
+Needs TANGLE_API_KEY (or OPENAI_API_KEY) and uv, or TRACES_PYTHON naming a Python with agent-eval-rpc[dspy].
+
+  --current           the caller's own session: CODEX_THREAD_ID, else CLAUDE_CODE_SESSION_ID
+  --last N            the N newest sessions by file mtime, never the caller's own
+  --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
+  --latest-turn       only the latest task turn of a resumed Codex or Claude Code session
+  --question TEXT     a question (repeatable, at most 705 characters)
+  --questions FILE    a JSON array of questions: strings or {id?, question, answerSchema?}
+  --budget USD        required: the most the run may spend, shared by every question
+  --model ID          the analyst model (default gpt-5.6-luna)
+  --format text|json  text (default): the report; json: each answer, its citations, failure and cost
+  --out DIR           write answers.json and report.md under DIR; stdout gets one summary line
+
+jq paths (--format json):
+  .questions[] | {id, status, answer, failure}  each answer, or why it has none
+
+Examples:
+  traces ask --current --question "Which command failed first?" --budget 1
+  traces ask 019a3c7e --questions questions.json --budget 5 --out answers
+  traces ask --last 3 --question "Did it verify the fix?" --budget 2 --format json | jq '.questions[0].answer'
+```

package/docs/bundle.md

@@ -0,0 +1,40 @@
+# Session bundle
+
+[traces](../README.md#docs) › Session bundle
+
+`traces bundle` keeps one session's evidence beyond log rotation, for any reader that must cite the session after the live stores rotate. It never calls a model.
+
+```bash
+traces bundle 019a3c7e --out bundle-dir
+traces bundle verify bundle-dir            # VERIFIED, or FAILED with each difference (exit 1)
+```
+
+The bundle directory holds:
+
+- `session/`: the transcript byte for byte, plus every other source file its spans cite (the subagents directory when one exists);
+- `spans.otlp.jsonl`: the session's spans, as every command reads them;
+- `facts.json`: the same as `traces facts <ref> --format json`;
+- `git-log.txt`: commits in the session window, from the cwd the session recorded;
+- `manifest.json`: SHA-256 and size per file, provenance (session id, harness, cwd, transcript hash, window), and every absent artifact with its reason.
+
+A missing transcript fails the assembly. An optional input that is absent (no subagents, no git repo) is recorded in `manifest.absent` with the path it probed.
+A bundle directory is a ref: `traces facts bundle-dir` reads the session it keeps, and `traces facts bundle-dir --no-content` gives its evidence without its words.
+
+`bundle verify` checks every listed file's size and SHA-256, and reports a missing file, an unlisted file, a path that climbs out of the directory, and any symbolic link. It proves the bytes are the ones `traces` wrote, not who wrote them.
+
+## `traces bundle --help`
+
+```text
+Usage: traces bundle <ref> | --current --out DIR      (then: traces bundle verify DIR)
+Keep one session's evidence beyond log rotation: session/, spans, facts, git log, sha256 manifest.
+A bundle directory is a ref: traces facts DIR reads it.
+
+  --current           the caller's own session: CODEX_THREAD_ID, else CLAUDE_CODE_SESSION_ID
+  --harness ID        force the reader of a file ref
+  --out DIR           a new or empty directory for the bundle
+
+Examples:
+  traces bundle 019a3c7e --out evidence/019a3c7e
+  traces bundle --current --out evidence/now
+  traces bundle verify evidence/019a3c7e
+```

package/docs/check.md

@@ -0,0 +1,77 @@
+# Check: the one gate
+
+[traces](../README.md#docs) › Check
+
+`traces check` is the one gate, and it needs one: `--contract FILE`, the built-in `--contract conformance`, or `--share-safe`. With none it exits 2 and names them, so a CI step whose contract variable expanded to nothing never passes.
+
+## Trace contracts
+
+Two runs can give the same answer while one 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"] }
+}
+```
+
+```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 --format junit > contract.xml
+traces check --contract refund-desk.json         # what each rule checks; reads no trace
+```
+
+`tools.enforced` fails when the harness offered a tool the contract does not allow. A saved interactive session records no run status, so give a contract for a session file no `run` key.
+Every rule prints `pass`, `fail`, `error` or `skipped`. The keys and semantics are in [agent-eval's trace-contract guide](https://github.com/tangle-network/agent-eval/blob/main/docs/trace-contracts.md).
+
+## Conformance: integrate your own system
+
+Emit the span contract and pass the file as the ref; no adapter or plugin.
+
+```ts
+import { llmSpan, loopSpan, steeredBy, toolSpan } from '@tangle-network/agent-trace-contract'
+```
+
+`parent_span_id` is containment and `links` is causality (`steeredBy`), so a retry is linked to the verdict that caused it, not nested under it.
+`traces check spans.otlp.jsonl --contract conformance` says what a trace can answer: each capability (`token-accounting`, `cost-attribution`, `tool-usage`, `loop-convergence`, `tree-comparison`, `steering-chain`, `latency-analysis`) available or not, with the reason. It fails only when not one entry reads as a span. It reads contract OTLP-JSONL, standard OTLP/JSON and every other ref.
+Nothing is repaired on the way in, and a re-export never validates cleaner than its source: `traces convert` keeps what the producer wrote and carries `traces.source.unreadable_rows`.
+
+## Share safety
+
+`traces check <path> --share-safe` reads each path as bytes, never as a trace, so a handoff, an issue draft and a span export are all just files. SAFE and SAFE_WITH_WARNINGS pass, UNSAFE fails, UNKNOWN cannot decide. `--known-secret-env NAME` also fails on that variable's value, in any encoding. Findings name the file and JSON Pointer, never the value.
+
+## Exit codes and output
+
+Gates combine: 1 if any fails, else 2 if any could not decide, else 0. Exit 2 means no gate, a bad contract, a rule that could not run, an UNKNOWN share verdict, or an unreadable or ambiguous ref.
+The verdict goes to stdout in `--format`: `text`, `json` (`.gates[]`), `junit` or `github` (`::error` lines). Evidence for each gate that did not pass goes under `--out DIR`; without it, `check` writes nothing.
+
+## `traces check --help`
+
+```text
+Usage: traces check <ref…> | --current | --last N | --since T  --contract FILE|conformance | --share-safe  [flags]
+The one gate: does this run pass a trace contract or conform, and is this file safe to share?
+A gate is required. --share-safe reads each path as bytes, never as a trace. --contract F with no ref explains F.
+Exit 0 pass, 1 any gate fails, 2 a gate could not decide: a bad contract, a rule or verdict that could not run, an unreadable ref.
+
+  --contract FILE|conformance gate on a trace contract file, or on conformance (repeatable)
+  --share-safe        gate on whether each path is safe to share, read as bytes: SAFE passes, UNSAFE fails, UNKNOWN cannot decide
+  --known-secret-env NAME with --share-safe: an environment variable whose value must appear nowhere (repeatable)
+  --current           the caller's own session: CODEX_THREAD_ID, else CLAUDE_CODE_SESSION_ID
+  --last N            the N newest sessions by file mtime, never the caller's own
+  --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        force the reader of a file ref (claude-code, codex, …)
+  --format text|json|junit|github text (default), json, junit or github: the verdict, on stdout
+  --out DIR           write evidence for each gate that did not pass under DIR
+
+jq paths (--format json):
+  .gates[] | {gate, status}                     each gate and what it decided
+  .gates[].report.traces[]?.verdict.violations  each rule a run broke, with span ids
+
+Examples:
+  traces check run.otlp.jsonl --contract contract.json --format junit > contract.xml
+  traces check spans.otlp.jsonl --contract conformance
+  traces check handoff.md --share-safe --known-secret-env TANGLE_API_KEY
+```

package/docs/convert.md

@@ -0,0 +1,44 @@
+# Convert to OTLP
+
+[traces](../README.md#docs) › Convert
+
+`traces convert` hands a session's spans to another tool as contract OTLP-JSONL, the OpenInference span shape every traces command reads.
+
+```bash
+traces convert --current --out spans.otlp.jsonl
+traces convert sandbox-events.json --out spans.otlp.jsonl
+traces convert raw.otlp.jsonl --no-content --out metadata.otlp.jsonl --format json
+```
+
+Any ref converts, and these inputs are sniffed: sandbox-events recordings (a tool call is one span, keyed by its message part id, however many events report on it), OpenInference JSONL, and Sandbox live streams (`"backend":"codex"`, read as `codex-exec`; `--harness codex-exec` forces it).
+Without `--out` the spans go to stdout. With `--out` stdout gets one summary line, and with `--format json` it is `{out, spans, droppedAttributes}`.
+
+`--no-content` applies the one metadata-only rule (`src/metadata-only.ts`) that `facts` and `upload` share: prompts, replies, tool input and output, error text, working directories, branch names and briefs are dropped, and `droppedAttributes` lists the keys.
+`convert` does not redact: redaction belongs where data leaves the machine (`traces upload`, and `traces check <path> --share-safe` before sharing).
+A re-export keeps what the producer wrote and carries the rows it could not read, so it never looks cleaner than its source.
+
+## `traces convert --help`
+
+```text
+Usage: traces convert <ref…> | --current | --last N | --since T [--out FILE] [--no-content]
+Hand spans to another tool: contract OTLP-JSONL, to --out or stdout.
+Sandbox events, Codex live streams and OpenInference files are sniffed; --harness forces a reader.
+
+  --current           the caller's own session: CODEX_THREAD_ID, else CLAUDE_CODE_SESSION_ID
+  --last N            the N newest sessions by file mtime, never the caller's own
+  --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
+  --latest-turn       only the latest task turn of a resumed Codex or Claude Code session
+  --no-content        metadata only: drop prompts, replies, tool input and output, error text, paths and briefs
+  --out PATH          write the spans to PATH; stdout gets one summary line
+  --format text|json  the --out summary line: text (default) or json {out, spans, droppedAttributes}
+
+jq paths (--format json):
+  .droppedAttributes  with --out and --no-content: the attribute keys the metadata-only rule removed
+
+Examples:
+  traces convert --current --out spans.otlp.jsonl
+  traces convert raw.otlp.jsonl --no-content --out metadata.otlp.jsonl --format json
+  traces convert live-stream.jsonl --harness codex-exec > spans.otlp.jsonl
+```

package/docs/develop.md

@@ -0,0 +1,32 @@
+# Develop and release
+
+[traces](../README.md#docs) › Develop and release
+
+## Develop
+
+```bash
+pnpm install
+pnpm build        # dist/index.js (SDK), dist/cli.js (bin) and .d.ts; tests spawn dist/cli.js
+pnpm test
+pnpm typecheck
+pnpm dev facts --current   # run from source through tsx
+```
+
+Tests assert through public boundaries: they spawn `dist/cli.js` with argv (`tests/run-cli.ts`) and assert stdout, stderr and exit code, or import SDK exports. Only process boundaries are faked: a fixture HOME and `XDG_STATE_HOME`, the clock, a stub `npm`, and the Python bridge as a stub child process.
+
+## Release
+
+`main` is protected, and nothing publishes until a `v*` tag:
+
+1. Change `package.json` (and `pnpm-lock.yaml`) to the version, and its notes to `docs/release-<version>.md`, through a pull request.
+2. Tag the merge commit `vX.Y.Z` and push the tag.
+3. The Publish workflow checks the tag is on `main` and matches `package.json`, builds, publishes to npm with provenance, and creates the GitHub release from `docs/release-<version>.md`.
+
+`pnpm check:package` proves the tarball ships the `traces` binary and the skill. To retry a failed publish, run the Publish workflow with the existing tag.
+
+## How quality is measured
+
+[`bench/audit/`](../bench/audit) asks 19 questions about three synthetic sessions and scores answers by exact match, with no model judging anything.
+Three arms answer it: `facts` (`traces facts <ref> --format json` mapped by fixed rules, $0; `pnpm test` holds its score to `bench/audit/facts-score.json`, which may only rise), `raw-files` (one `claude -p` agent per question over the raw files) and `traces` (the same agent with `traces` on PATH and the skill installed in its own HOME).
+`pnpm bench:audit large` runs any arm over one synthetic session of about 50,000 spans.
+The release rule: the traces arm answers at least as many questions as the raw-files arm, at lower cost. [`bench/audit/README.md`](../bench/audit/README.md) has the commands and the rule, and [`bench/parity/`](../bench/parity) scores each parser traces retires against the command that replaces it ([parsers](parsers.md)).

package/docs/diff.md

@@ -0,0 +1,38 @@
+# Diff two runs
+
+[traces](../README.md#docs) › Diff two runs
+
+`traces diff` names the first tool call where two runs of the same task split, and prints both calls.
+
+```bash
+traces diff 0199a1b2 0199c3d4                                         # two sessions
+traces diff run.otlp.jsonl#branch=arm-a run.otlp.jsonl#branch=arm-b    # two arms of one run
+```
+
+A run's steps are its tool calls in containment order; model calls are not steps, since two runs never word a reply alike.
+Each call compares by tool, status and argument: the command a shell call ran, the file a file tool touched, or the call's input.
+First each run's own places become placeholders (its cwd and worktree, temp dirs, and hex ids), so two runs of one play in two worktrees agree wherever they did the same thing.
+The first divergence is `changed`, `replaced`, `only-in-a`, `only-in-b` or `reordered`; `--format json` holds every step, and `.diff.firstDivergence.index` is 0-based.
+Exit 0 agree, 1 diverge, 2 could not compare (a side unreadable, or no call records an outcome); a gate treats 2 as unknown, never as a pass.
+
+## `traces diff --help`
+
+```text
+Usage: traces diff <a> <b> [--format text|json]
+Where two runs of one task split: the first tool call that differs, with both calls.
+A side is a session id or 8+ char prefix or suffix, a session file, OTLP, file#<trace id> or file#branch=<id>.
+Calls compare by tool, status and argument (the command, the file, or the input), after each run's
+cwd, worktree, temp dirs and hex ids become <cwd>, <worktree>, <tmp> and <hex>. Model calls are not compared.
+Exit 0 agree, 1 diverge, 2 could not compare: a side cannot be read, or neither records an outcome.
+
+  --format text|json  text (default) or json
+
+jq paths (--format json):
+  .diff.firstDivergence                   where and how the runs first split (index is 0-based)
+  .a.steps[.diff.firstDivergence.a].text  A's call at that step, normalized
+
+Examples:
+  traces diff 0199a1b2 0199c3d4
+  traces diff passing.otlp.jsonl failing.otlp.jsonl
+  traces diff run.otlp.jsonl#branch=a run.otlp.jsonl#branch=b --format json
+```

package/docs/facts.md

@@ -0,0 +1,114 @@
+# Session facts
+
+[traces](../README.md#docs) › Session facts
+
+`traces facts` states what happened in a session, exactly, for $0: who acted, the turns, tools, commands, pull requests, first failure, tokens, cost and the time lost.
+It calls no model, and the same spans always give the same sheet.
+
+```bash
+traces facts --current                                      # the text sheet: at most 25 lines a session
+traces facts 019a3c7e --format json                         # the whole sheet, with span ids
+traces facts --since 2026-10-14 --until 2026-10-15          # one day, across every harness
+traces facts --since 1d --format jsonl                      # one row per typed turn
+traces facts --since 30d --match '^gh pr merge'             # each matching turn, agent message or command
+```
+
+## The text sheet
+
+Text is the default; pass `--format json` to parse. Each session takes at most 25 lines, times in UTC:
+
+```
+99d75d4b claude-code · agent-dev-container (feat/gap-closure) · 10-15 09:12→12:40 UTC · active 3.1 h
+who dotfiles sha256:5843…ca56 · claude-opus-5-5 (from session-identity)
+human turns 14 (excluded: injected 6, fleet 2, relay 1) · interrupts 2
+tools 412 (Bash 220 (31 failed), Edit 88, Read 61, …) · subagents 6 (lint, test, docs, …)
+commands 236: pnpm test 41 (19 failed), git status 30, rg 22, gh pr 9 (1 failed), git push 6, …
+tokens in 2.1M · out 310k · cache read 88M · $38.20 list price (Router rates)
+waste 52 min: `pnpm test` failed 14× in a row (31 min) · 2 stalls ≥ 10 min (21 min) · reverts 1
+PRs opened #11021 #11022 · merged #11006 · changed 23 files
+first failure 09:40 Bash: exit 1 (blame agent, span 6be1…)
+final "Merged #11006; …"
+```
+
+A fact the spans cannot support reads `unknown` with the reason. A selection of several sessions starts with one line naming the count, the window and the sessions it could not read.
+
+## What it states
+
+Three rules hold for every field. Every fact is about this session's own agent: a subagent's work is named in `subagents` and counted in `subagentTools` (by tool name, with failures), never added to the parent's totals. Every fact names its `spanIds`. A fact the spans cannot support is `null` with its reason, never a guess and never a silent zero; `partial` marks a value known to be incomplete.
+
+| Fact | What it is |
+|---|---|
+| `toolCalls`, `toolCallsByName` | tool calls this session's agent made, by name. A Codex command that checks work is `exec_command.verify` |
+| `subagents` | every subagent-spawning call, with its task name and `agentType` (Claude Code's `subagent_type`); a refused Codex spawn is `ERROR`. On the sheet, `subagent tools` counts their calls |
+| `commands` | the programs the session's commands ran (`labctl run`, `git push`, `pnpm test`), most runs first: `runs`; `failed`, runs that were their call's only command (a `cd` aside) and ended in error; and `inScripts`, runs inside a Codex code-mode script, which records no exit code of its own; `nonZeroExits`, each run `failed` counts with the `code` its output printed (`null` when it printed none), `inScript`, `at` and `spanId`. `--match` gives each run's span. A code-mode `tools.exec_command` call inside `for (const x of [...])` counts once per element, `${x}` or `{cmd: x}` taking each value; inside any other loop, once as written. On the sheet, a tool's `(31 failed)` counts its calls that ended in error |
+| `pullRequests` | pull requests created and merged, by number or head branch, with when the command ran and the span that named it |
+| `humanTurns` | turns a person typed, each with `author`, `answered`, `reply`, `interrupted` and `signals` (`interrupt`, `rejected-tool`, `after-claim`) |
+| `excludedTurns`, `turnsByActor` | every left-out turn, by reason and author, so the filter is checkable |
+| `tokens`, `cost` | from one owner on every harness; `input` is the whole prompt, cache included; `cost` is agent-runtime's `priceTokens`, labelled `list price (Router rates)` |
+| `measurements.waste` | failing streaks (3 or more identical failures), stalls of 10 minutes or more that no turn ended, `git revert` and `reset --hard`, repeated commands |
+| `measurements.activeMinutes`, `.skills`, `.modelCalls`, `.guardRefusals`, `.limitStop` | minutes worked (gaps capped at 10); skills used, by the classifier `traces skills` uses; the context each of the session's own model calls read (input + cache read + cache write): `contextTokens.mean`, and `.p50` from 2 calls, and `latencyByContext`, tool result to next reply in 100k-token bands (`0-100k` … `900k+`), `p50Ms`/`p90Ms` from 2 replies, leaving out waits of 10 minutes or more; the `toolCalls` a hook refused (`hook error: <guard>`), `byGuard`; and the usage or weekly limit notice the session stopped on, its run's error (Codex: "You’ve hit your usage limit") or else its last reply (Claude Code: "You've hit your weekly limit"), else `null` |
+| `repo`, `cwd`, `changedFiles`, `finalMessages`, `recordFile`, `record` | the repository and recorded cwd, files the session changed, and the last message of the agent and each subagent. With `--format json`, `recordFile` is the session file, and `record` sits on each `humanTurns` entry, `firstFailure` (the failing call's result, else the call), `commands` row (its latest run's result) and each of its `nonZeroExits`, and `changedFiles` entry (the call that first changed it), the record it came from: `{line}` in `recordFile`, `{file, line}` in a subagent's file, `null` when no record names it. Cite `recordFile:line` instead of searching the files. Absent under `--no-content` |
+| `firstFailure` | the first failure among the session's own records, with its blame; `unknown` when no status was recorded, `ambiguous` when two ended at once |
+| `agent` | the profile, model, harness and directive that acted, from the root span, else the session-identity record |
+
+## Turns
+
+A turn is one a person typed into this session. History a fork or a compaction replays, harness-injected blocks (instructions, environment context, notifications, skill expansions) and a second record of the same turn are left out, each listed in `excludedTurns`. A turn the reader called human is checked once more by org convention: a fleet or session message, or a first turn over 1,500 characters, is `fleet`; a long markdown-heavy paste is `relay`; a harness command (`/model`) is left out.
+For Codex, the harness's own labels (`content_item_kinds`) decide: a message is the person's when every item is a `user.` kind. An answer to Codex's question tool (`<send_user_message_question_reply>`) is a turn, and so is a turn with an attached image, whose text is the report Codex wrote of it, without the `<image>` wrapper.
+
+`--format jsonl` prints one row per typed turn: `host`, `harness`, `session`, `cwd`, `at`, `author`, `text`, `answered`, `reply`, `interrupted`, `signals`, `spanId`, `recordFile` and `record` (native `{file, line}`, or `null` when unavailable). Window JSONL reads only the session's own records and uses the same turn classifier and reply fold as the full sheet; it does not compute costs, commands or other unused measurements.
+`--match RE` prints one row per matching human turn, agent message or shell command (`sessionId`, `kind`, `at`, `spanId`, `source`, text clipped to 300 characters). A command row of a named session also has `record` and `lastLine`, the last non-blank line of the command's whole output, which the row's text never shows. A command row's `failed` follows the `commands` rule; it is `null`, `?` in text, when its call's status is not its own. Commands match one simple command at a time, so `^traces ` matches `cd x && traces facts …` and never `tangle traces list`. Over a window it reads the turn index under `$XDG_STATE_HOME/traces/turn-index`, which reads only bytes appended since the last search.
+
+## Pull requests
+
+`pullRequests` scans each command the way a shell would, so a `gh pr create` inside a heredoc body never counts.
+A pull request is named by its number when the command or an output that joins to it shows one, else by its head branch.
+A create whose call returned while it still ran takes the number a later poll of that process printed.
+In a Codex code-mode script, each tool result the script printed is decoded (`exit_code` or `session_id`, and the command's output), and a later script's `write_stdin` poll of the session counts as that poll.
+A create counts only where an output shows `gh` answered: a script that completed says nothing about its commands.
+
+## `--no-content`, windows and exit status
+
+`--no-content` withholds conversation, commands, paths and assignments and keeps the measurements; it is a local view, not a share-safety verdict (`traces check <path> --share-safe` is).
+With `--since`/`--until`, the turn facts keep only turns inside `[since, until)`; every other fact covers the whole session. `selection` names the window, the sessions outside it and every unreadable session.
+A named session that cannot be read exits 2; in a window it is skipped, named, and the run exits 0.
+
+## SDK
+
+```ts
+import { buildSessionFactsReport, computeSessionFacts, renderSessionFacts } from '@tangle-network/traces'
+
+const [facts] = computeSessionFacts(spans)
+console.log(facts.toolCalls.value, facts.toolCalls.spanIds)
+console.log(renderSessionFacts(buildSessionFactsReport(spans)))
+```
+
+## `traces facts --help`
+
+```text
+Usage: traces facts <ref…> | --current | --last N | --since T [flags]
+What happened, exactly, for $0: who acted, turns, tools, commands, PRs, first failure, tokens, cost, time lost.
+
+  --current           the caller's own session: CODEX_THREAD_ID, else CLAUDE_CODE_SESSION_ID
+  --last N            the N newest sessions by file mtime, never the caller's own
+  --since T           every session with a record since T: 30m, 2h, 7d or an ISO time
+  --until T           close the --since window (exclusive); same forms
+  --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
+  --latest-turn       only the latest task turn of a resumed Codex or Claude Code session
+  --match RE          one row per human turn, agent message or shell command matching RE (a command: ok, failed or ?)
+  --no-content        omit conversation, commands, paths and assignments
+  --format text|json|jsonl text (default, 25 lines a session), json (the sheet), or jsonl: one row per typed turn
+  --out PATH          write the sheet to PATH; stdout gets one summary line
+
+jq paths (--format json):
+  .sessions[0].humanTurns.value[] | {at, text, spanId}                        each typed turn, its time and span
+  .sessions[0].commands.value[]                                               programs run: runs, failed, inScripts
+  .sessions[0].measurements.tools[] | {name, calls, failed: .outcomes.error}  tool calls by name, and failures
+  .sessions[0] | {firstFailure, tokens, cost, agent: .agent.value}            first failure, tokens, cost, who acted
+
+Examples:
+  traces facts --current
+  traces facts 019a3c7e --format json | jq '.sessions[0].measurements.waste'
+  traces facts --since 30d --match '^gh pr merge'
+```

package/docs/mcp.md

@@ -0,0 +1,36 @@
+# MCP server
+
+[traces](../README.md#docs) › MCP server
+
+`traces mcp` serves agent-eval's read-only span tools over stdio, for an MCP client with no shell. An agent with a shell runs the CLI instead.
+
+```bash
+claude mcp add traces -- traces mcp spans.otlp.jsonl
+claude mcp add traces -- traces mcp --last 5
+```
+
+It serves `getDatasetOverview`, `queryTraces`, `countTraces`, `viewTrace`, `viewSpans`, `searchTrace` and `searchSpan` over the spans selected at start. Each declares `readOnlyHint` and `idempotentHint`.
+
+- Spans are redacted before the store is built, and each result again at the boundary. The server refuses to start when the redacted spans are still UNSAFE or UNKNOWN.
+- Each result carries an untrusted-text notice, and a result above 512 KiB is refused rather than cut.
+- `readSpanSource` is not served: a secret split across two windows matches no redaction rule.
+
+## `traces mcp --help`
+
+```text
+Usage: traces mcp <ref…> | --current | --last N | --since T
+Serve agent-eval's read-only span tools over stdio, for an MCP client with no shell.
+Spans and results are redacted, and it refuses to start if redacted spans are UNSAFE or UNKNOWN.
+Each result carries an untrusted-text notice and is capped at 512 KiB.
+
+  --current           the caller's own session: CODEX_THREAD_ID, else CLAUDE_CODE_SESSION_ID
+  --last N            the N newest sessions by file mtime, never the caller's own
+  --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
+
+Examples:
+  traces mcp spans.otlp.jsonl
+  traces mcp --last 5
+  claude mcp add traces -- traces mcp spans.otlp.jsonl
+```