@tangle-network/traces 0.11.4 → 0.11.6

package/README.md

@@ -31,6 +31,7 @@ Emitting the contract is the supported way to integrate a new system. The adapte
 - [Watch a run tree](#watch-a-run-tree)
 - [Improvement engine](#improvement-engine)
 - [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)
 - [Trace analysts](#trace-analysts)
@@ -243,6 +244,8 @@ traces analyze  --otlp spans.otlp.jsonl            # analyse foreign OTLP, no ad
 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 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
@@ -260,9 +263,13 @@ traces upload   --since 1h --dry-run               # redact + dedup + preview, n
 traces upload   --since 24h                        # upload last day to the Intelligence Platform
 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 |
@@ -288,6 +295,9 @@ See [Replay verification](./docs/replay-verify.md) for setup, semantics, and hon
 | `--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 |
@@ -443,11 +453,58 @@ The index contains:
 - 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` JSONL / reflection artifacts, with markdown heading/ToC and JSONL key summaries
+- 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.
+
 ## Policy-mining evidence
 
 `traces` does **not** emit benchmark campaign cells. It emits normalized coding-agent session evidence that another system can mine.
@@ -541,11 +598,13 @@ 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
 ```
 
 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.
@@ -557,7 +616,7 @@ Read [Trace analysts](./docs/trace-analysts.md) for the output contract, a minim
 traces upload --since 24h --dry-run --redactor "my-pii-scrubber"
 ```
 
-In the SDK these are the `ExternalAnalyzer` and `Redactor` interfaces (`haloAnalyzer`, `hodoscopeAnalyzer`, `commandAnalyzer`, `commandRedactor`, `applyRedactor`, `runExternalAnalyzers`).
+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`.