@tangle-network/traces 0.11.6 → 0.15.0

package/docs/trace-analysts.md

@@ -8,6 +8,8 @@ Keeping them separate prevents an exploratory model output from being reported a
 | What happened? | Built-in local checks | Findings from explicit trace facts |
 | Why might it have happened? | `--llm`, HALO, or a custom analyst | Findings or a diagnosis report with cited spans |
 | What behavior should we inspect? | Hodoscope | Samples marked `needs_review` |
+| What exactly does this session say about X? | `traces ask` | An answer per question, with checked `trace://` citations |
+| What does this session state, exactly and for free? | `traces facts` | A deterministic facts sheet, no model call |
 
 ## Start here
 
@@ -34,6 +36,8 @@ Without those fields, the result is explicitly incomplete; names, nicknames, and
 It reports missing files, duplicate IDs, contradictory parents, and cycles instead of guessing.
 Use `--max-workflow-sessions <n>` to set a different bound.
 Claude Code already folds nested subagent files into its parent trace.
+The adapter preserves Claude source UUIDs in `traces.claude.source_*` attributes and derives valid OTLP IDs for the exported graph.
+It emits tool spans from recorded tool calls, but does not invent loop iterations or causal links absent from the transcript.
 Ordinary Claude subagents use their parent tool call ID.
 Claude Workflow subagents use the run ID and transcript directory returned by the parent `Workflow` call.
 If the same Workflow run is resumed, each child attaches to the latest matching call that started before it.
@@ -54,6 +58,262 @@ Returned directories from another resumed Claude session are parsed and included
 The OpenInference file is the shared input for external engines.
 The original trace and exact cited span remain available for review.
 
+## Ask free-form questions
+
+The built-in kinds ask fixed questions.
+`traces ask` asks your own.
+
+```bash
+traces ask --harness codex --session <id> \
+  --question "Which shell commands exited non-zero?" \
+  --question "Which pull requests did the session open, and were they merged?" \
+  --dir .traces/ask
+```
+
+Each question runs through agent-eval's `runTraceAnalyst` directly, not through the analyst registry.
+That matters for three reasons.
+
+- The registry keeps only findings, so it discards the engine's prose answer. `ask` keeps the answer text verbatim.
+- The registry runs analysts one at a time. `ask` runs questions concurrently, so wall time falls toward the slowest question instead of the sum.
+- One shared `CostLedger` bounds the whole run, so `--budget` means the same thing whatever the number of questions.
+
+### Questions
+
+A question stays short on purpose.
+The engine shows the model a preview of each long input: it keeps the first 500 and last 500 characters and drops the middle.
+A question inside the limit therefore reaches the model whole, and the answer rules sit in the first 500 characters of the instructions, which the preview always keeps.
+`ask` rejects an over-long question before it starts a model call and names the limit.
+Put the detail in the entry's `instructions` field instead, which the model reads after the rules.
+
+Read many questions from a file:
+
+```json
+{
+  "questions": [
+    "What was the last thing the human asked for?",
+    {
+      "id": "failed-commands",
+      "question": "Which shell commands exited non-zero?",
+      "instructions": "Report the command line and the exit code. Ignore commands the agent only proposed.",
+      "answerSchema": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": { "command": { "type": "string" }, "exit_code": { "type": "integer" } },
+          "required": ["command", "exit_code"]
+        }
+      }
+    }
+  ]
+}
+```
+
+An `answerSchema` makes the answer one JSON value a scorer can compare field by field.
+The supported keywords are `type`, `properties`, `required`, `additionalProperties`, `items`, `enum`, `const`, `title`, and `description`.
+A keyword that constrains one JSON type must declare it: `required`, `properties`, and `additionalProperties` need `"type": "object"`, and `items` needs `"type": "array"`, or the constraint would be skipped for an answer of another shape.
+Any other keyword is rejected when the run starts.
+This package carries no JSON Schema library, and a constraint that is quietly ignored would let a wrong answer pass as checked.
+
+### What the run guarantees
+
+- Every question receives the deterministic [session-facts sheet](#session-facts) as prepared context, before its first model call. It costs nothing and answers the counting questions the bounded trace tools cannot.
+- Every `trace://<trace_id>/span/<span_id>` URI in an answer is resolved against the store. An unresolvable citation fails that question.
+  A citation the model wrapped in Markdown emphasis (`**...**`, `_..._`, `~~...~~`) or ended a sentence with resolves like a bare one: the delimiters are prose, not part of the span ID.
+- Findings the answer submits still pass the same evidence gate as the built-in kinds. Refused findings are counted by reason in both artifacts.
+- A failed question never stops the others. Its failure is recorded on its own answer, and the remaining answers are written.
+- Ctrl-C keeps what the run already bought. The signal reaches the engine, not the checks that follow it: an answer that came back is kept with its citations resolved, and each question the run never reached is recorded as `aborted`.
+- The artifacts are written before the exit code is decided. `ask` exits 1 when any question failed, returned no answer, broke its schema, or cited a missing span.
+- `totals.wallTimeMs` covers the whole run, including writing and indexing the trace file; `totals.setupTimeMs` names that part. `result.effectiveConcurrency` is the number of workers the run created, `min(--concurrency, questions)`, and `totals.peakConcurrency` is how many actually overlapped.
+
+### Budget under concurrency
+
+`--budget` is the ceiling shared by every question; `--question-budget` is the provider ceiling for one question.
+The ledger reserves each model call's maximum charge before the call runs, and releases the unused part when the call settles.
+Two consequences follow.
+
+- A budget below one call's reservation refuses the run before any model call, rather than failing every question.
+- A budget that admits fewer concurrent reservations than `--concurrency` still runs, and the report carries a warning naming how many concurrent calls it covers.
+
+A question the ledger refuses is reported as `budget-refused`, and the answers already produced are kept.
+That kind is decided from the accounting, not only from the error text.
+The refusal happens inside the model proxy, behind the DSPy bridge, whose HTTP error handling can replace the Node error with its own message.
+So a failed question is reported as `budget-refused` whenever the shared ledger's settled spend left less than one model call's reservation at the time it failed and nothing else in the failure names its cause.
+A failure whose own text names its cause keeps that cause: a bridge version mismatch stays `error`, so the reinstall hint still prints, and an empty answer from the bridge stays `no-answer`.
+The message itself is kept verbatim on the answer.
+
+### SDK
+
+```ts
+import { analysisEngineFromEnv, runTraceQuestions, writeTraceQuestionsArtifacts } from '@tangle-network/traces'
+
+const result = await runTraceQuestions({
+  questions: [
+    { id: 'failed-commands', question: 'Which shell commands exited non-zero?' },
+    { id: 'last-ask', question: 'What was the last thing the human asked for?' },
+  ],
+  spans,
+  engine: analysisEngineFromEnv({ model: 'gpt-5.6-luna', maxCostUsd: 1 }),
+  concurrency: 4,
+  budgetUsd: 2,
+})
+await writeTraceQuestionsArtifacts(result, '.traces/ask')
+if (!result.ok) process.exitCode = 1
+```
+
+`result.questions[i].answer` is the engine's prose, unedited.
+`result.totals` carries the wall time, the summed question time, the peak concurrency, and the cost with its provenance.
+
+## Session facts
+
+`traces facts` computes a fixed set of session facts straight from the spans.
+It runs no model, opens no engine, and spends nothing.
+The same spans always produce the same sheet.
+
+```bash
+traces facts --harness codex --session <id>            # JSON on stdout
+traces facts --harness codex --last 5 --format text    # the short readable form
+traces facts --otlp spans.otlp.jsonl --out facts.json
+```
+
+### Why it exists
+
+The trace tools are bounded, and above their bounds they answer a different question than the one asked.
+`viewTrace` returns a `≤20`-entry span-name histogram once a trace exceeds `perCallByteCeiling` (150,000 bytes).
+`countTraces` counts traces, not spans.
+`viewSpans` needs span ids the reader does not have yet.
+`searchTrace` stops at 500 hits.
+
+A model asked "how many tool calls ran?" therefore adds up a capped histogram and decides by eye which names belong.
+Measured over twelve private audit sessions, the model-backed analyst arm scored a deterministic mean of **0.389**.
+Extracting the same answers mechanically from the OTLP spans those runs already wrote scored **0.858** — the facts were present and exact the whole time.
+The sheet is that extraction, made part of the tool.
+
+### What it states
+
+| Field | Value |
+| --- | --- |
+| `toolCalls` | TOOL spans **this session's agent** invoked. Synthesized lifecycle spans are excluded and counted in `synthesizedToolSpans`; calls made by a spawned subagent are excluded and counted in `subagentToolSpans` |
+| `toolCallsByName` | the same calls by tool name |
+| `subagentToolSpans` | TOOL spans excluded because a subagent, not this agent, made the call |
+| `subagents` | every subagent-spawning call, with the task name the call recorded |
+| `pullRequests` | pull requests the commands created and merged, each named by number or head branch, with the command span and the join evidence |
+| `humanTurns` | `user.prompt` turns a person typed into this session, in order, with timestamps |
+| `excludedTurns` | every `user.prompt` turn `humanTurns` left out, grouped by the reason, with the span ids |
+| `turnsByActor` | every `user.prompt` turn by actor, so the human filter is checkable |
+| `finalMessages` | the last message of the session's own agent, and of each subagent task, separately |
+| `changedFiles` | paths the harness recorded for its own file changes, plus paths from `*** Add/Update/Delete/Move to File:` patch headers and from file-editing tool arguments |
+| `firstRecordAt`, `lastRecordAt` | the earliest span start and latest span end among this session's own records |
+| `unreadRecords` | records the session reader could not parse |
+| `tokenTotal` | the harness's cumulative total, when a span carries `traces.session.total_tokens` |
+
+Three rules hold for every field.
+
+- **Every fact is about this session's own agent.** Some harnesses fold a spawned agent's transcript into the parent's trace — Claude Code writes one file per subagent under the session directory and the adapter reads them all — so a trace can carry both what this agent did and what a child it spawned did. The child's work is named in `subagents` and counted in `subagentToolSpans`, never added to the parent's totals. On a trace with no subagent records every one of those counts is zero.
+- **Every fact names the span ids it came from.** A reader can open those spans and check the number. The sheet is not a span and cannot be cited.
+- **A fact the spans cannot support is `null` with a stated reason.** It is never guessed and never a silent zero. `partial` marks a measured value known to be incomplete.
+
+`facts` exits non-zero when a selected session produced no record spans, rather than printing a sheet of zeros for a session it could not read.
+
+#### Pull requests
+
+The command spans carry the script, the exit code and the output.
+`pullRequests` scans each script the way a shell would, so a `gh pr create` inside a heredoc body or a commit message is not counted as a command that ran.
+A pull request is named by its number when the command or an output that joins to it shows one, and by its head branch when neither does.
+A create whose stdout was redirected away takes the number a later output states for the same branch on the same line, and names the span that stated it.
+A failed `git push && gh pr create` counts only when the output shows `gh` itself answering; otherwise the shell never reached it.
+A trace whose spans carry no executed command returns `null` with that reason, because "no pull requests" and "the spans cannot say" are different answers.
+
+#### Human turns
+
+A user message is one the human typed into this session.
+Three filters run in order, and each excluded span is listed in `excludedTurns` with its reason, never silently dropped:
+
+- history the session carries but did not receive — the prefix a fork copies from its parent, and the turns a compaction replays;
+- turns whose actor is not a person — an instruction file, an environment-context block, a system reminder, a subagent notification, a turn-aborted marker, or a skill or slash-command expansion;
+- a second record of the turn before it, meaning the same text at the same instant with no model call, tool call or assistant message between them.
+
+For Codex the actor comes from the harness's own per-item labelling (`internal_chat_message_metadata_passthrough.content_item_kinds`) whenever the record carries it: a message is the person's exactly when every item in it is a `user.` kind.
+
+### Session facts as prepared context
+
+The same sheet is supplied to the model-backed analysts before their first model call, through `TraceAnalystDefinition.prepareContext`.
+It reaches the built-in kinds run by `analyze --llm`, `investigate`, and `improve`, and it reaches every `traces ask` question inside `PREPARED CONTEXT:`.
+
+- The sheet is bounded at `PREPARED_CONTEXT_BYTE_CEILING` (30,000 bytes), a fifth of the `perCallByteCeiling` of 150,000 the trace tools work to, so the rest of the budget stays available for the tool calls the model still makes.
+- When the sheet does not fit, fields are shed from the largest downward and the shed is listed in `omitted_fields`. The tool-call counts are the last facts to go.
+- Receiving the sheet changes an analyst's behavior, so its version carries `+session-facts.1`. `createTraceAnalyst` records `prepare_context` in the exact-run identity, and a changed prepared context must not hide behind an unchanged version.
+- The sheet is not evidence. Citations still resolve against the raw spans, which is why every fact names its span ids rather than asking the model to trust the sheet.
+
+Pass `sessionFactsContext: false` to `analyzeSpans` to run an analyst without it.
+
+```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)))
+```
+
+## Evidence-gate rejections
+
+A model-backed analyst can submit a finding the evidence gate then refuses.
+Without the reason, a report showing "0 findings" reads as "the model found nothing" when the truth may be "the gate refused everything it found".
+
+`analyze`, `investigate`, `improve`, and `ask` now carry those refusals:
+
+- the CLI log adds whatever the event carries beyond its own text to each `finding rejected` line: the cause (`reason` for the gate's rejections and the bridge-row rejection, `issues` for a schema failure), the offending URI, the citation counts, and the subject;
+- the analyst table's Detail cell names the reasons and their counts;
+- `result.findingRejections` (investigation and improvement) and `answers.json` (`ask`) hold the counts per analyst and reason.
+
+The common reasons are an excerpt the cited span does not contain, a span the trace does not hold, and too few distinct citations for the kind.
+
+## External analyzer failures exit non-zero
+
+`--analyzer halo|hodoscope|prime|<command>` promises that engine's output.
+An analyzer that fails now writes its error into the report as before, and then the command exits 1 naming every analyzer that failed.
+Scripts that treated exit 0 as "the analyzer ran" were reading a report that said otherwise.
+
+The check runs on `analyze`, `investigate`, and `improve`, and it covers every analyzer the run requested, not only the ones named on the command line.
+`investigate` and `improve` load the default traces config file, so an analyzer declared in `externalAnalyzers` there is a requested analyzer too, and a flaky one now turns those two commands red.
+`analyze` does not load a default config, so only its own `--analyzer` flags reach the check.
+
+## Codex tool outcomes
+
+Both function and custom tool outputs use the same status parser.
+Explicit exit codes, error flags, and runner headers determine tool status.
+Explicit failure takes precedence when structured fields conflict.
+Text such as `error:`, `ENOENT`, or `command failed` inside stdout does not determine status.
+An unmatched call, running process, or output without trustworthy status remains `UNSET`.
+A recorded `wait_agent` timeout is a completed poll, not proof that the agent finished.
+Tool output remains in `output.value`, with the existing size limit and truncation receipt.
+
+Error and retry counts use explicit failures.
+Successful follow-up counts require explicit success; unknown follow-up outcomes remain `null` in the detailed report.
+The runtime span projection leaves its optional status absent for `UNSET` spans.
+Use the execution report for terminal run outcomes.
+The older runtime store's required run status cannot represent unknown and is not completion evidence.
+
+## Model-assisted citations
+
+agent-eval's evidence gate accepts a model finding only when each cited span exists and each excerpt appears in that span.
+Before the gate runs, `traces` normalizes the citations of the built-in `--llm` analysts against the analyzed spans.
+
+- An excerpt copied from a `searchTrace` hit carries JSON escapes such as `\"` and `\n`.
+  It is replaced by its decoded form only when the cited span contains that decoded text.
+- A citation of a readable harness ID, such as `tool:<call_id>` or the Codex session ID, is replaced by the hex OTLP span ID.
+  The readable ID must name exactly one span through its `traces.<harness>.source_*` attributes.
+- A subject from another analyst's vocabulary is removed, because the subject is optional.
+  The claim and its citations still go through the gate.
+
+The gate itself is unchanged and checks every rewritten finding.
+A fabricated excerpt, an unknown ID, or an ambiguous ID remains rejected.
+Normalization never adds a citation, so a failure-mode finding still needs two distinct spans.
+A subject outside the subject grammar is rejected before normalization runs.
+Wrapped analysts report a version ending in `+traces-citations-1`.
+
+A custom analyst built with `createTraceAnalyst` gets the same behavior through `normalizeAnalystCitations(definitions, spans)`.
+Pass the spans that the analyst's trace store was written from.
+
 ## External engines
 
 External engines are optional tools that you install separately.
@@ -287,3 +547,50 @@ The required review path is:
 ```text
 production trace -> finding -> reviewed feedback -> eval case -> candidate change -> comparison
 ```
+
+## Read retained source fields
+
+Normalized conversation text and tool values remain capped.
+Create a full bundle before the harness rotates its original files.
+Explicitly authorize that bundle when analysis needs omitted text:
+
+```bash
+traces bundle --session <session-id> --out ./session-bundle
+traces analyze --source-bundle ./session-bundle --llm
+```
+
+`investigate` and `improve` accept the same flag.
+The SDK accepts `sourceBundle: { path, maxRecordBytes? }` in analysis and investigation options.
+This authorization exposes `traces.readSpanSource` to local analysts through the existing trace store.
+External analyzers receive normalized OTLP without this capability.
+Ordinary OTLP input does not authorize source reads.
+
+The tool selects a trace, span, attribute, and optional `source_index`.
+It returns a UTF-8 byte window of that field's decoded value.
+Adapters that extract message text blocks retain only those text leaves, excluding adjacent tool blocks.
+Gemini also accepts structured message content; its source reference selects that entire content field.
+Multiple records or text fragments use separate source indices.
+Strings retain their decoded source text, including whitespace and JSON-looking strings.
+Structured values use the existing sorted-key tool-value JSON encoder.
+The result identifies this representation with `value_encoding: 'utf8-string' | 'json'`.
+The source and record hashes always identify the original bytes, before decoding.
+
+Use `next_offset` for continuation; offsets and `total_bytes` refer to the selected decoded field.
+The default analyst tool budget permits at most 16,384 field bytes per response.
+Configure Eval trace-store budgets to change that tool limit.
+An offset inside a UTF-8 character returns unavailable.
+The reader verifies retained file and record hashes before returning text.
+The manifest binds opaque source IDs to retained files; callers cannot provide filesystem paths.
+
+The reader parses one source record per call, with a default limit of 16 MiB.
+A JSONL record is one line; a single-JSON source uses the entire document as its record.
+Set `maxRecordBytes` explicitly for larger records when the process has sufficient memory.
+This parsing limit differs from the response window limit.
+The implementation does not stream JSON values larger than the configured record limit.
+
+Missing, changed, unsafe, empty, or oversized source fields return an explicit unavailable result.
+Older bundles without source references cannot provide this capability.
+Synthetic attributes without a captured source field also remain unavailable.
+Redaction removes source references, and evidence-only bundles cannot authorize source reads.
+Analysis output must remain outside the retained bundle.
+Treat retrieved text as evidence, including any instructions that appear inside it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.11.6",
+  "version": "0.15.0",
   "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, …) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite — observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
   "type": "module",
   "license": "MIT",
@@ -22,6 +22,7 @@
     "llm",
     "coding-agent"
   ],
+  "packageManager": "pnpm@10.33.4",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -46,29 +47,32 @@
   "engines": {
     "node": ">=22.13.0"
   },
-  "dependencies": {
-    "@tangle-network/agent-eval": "0.145.22",
-    "@tangle-network/agent-interface": "1.0.0",
-    "@tangle-network/agent-runtime": "0.137.0",
-    "@tangle-network/agent-trace-contract": "^1.0.2",
-    "@tangle-network/sandbox": "0.27.1"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "postcss": "^8.5.25",
-    "tsup": "^8.0.0",
-    "tsx": "^4.23.1",
-    "typescript": "^5.7.0",
-    "vite": "^8.1.5",
-    "vitest": "^4.1.10"
-  },
   "scripts": {
     "dev": "tsx src/cli.ts",
+    "bench:audit": "tsx bench/audit/cli.ts",
     "build": "tsup src/index.ts src/cli.ts --format esm --target node22 --clean --dts",
     "check:package": "node scripts/check-package-bin.mjs",
     "check:source": "node scripts/check-source-text.mjs",
+    "prepare": "node scripts/check-source-text.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm check:source && pnpm build && pnpm check:package"
+  },
+  "dependencies": {
+    "@tangle-network/agent-eval": "0.182.0",
+    "@tangle-network/agent-interface": "2.6.1",
+    "@tangle-network/agent-runtime": "0.231.1",
+    "@tangle-network/agent-trace-contract": "1.0.2",
+    "@tangle-network/sandbox": "0.40.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "postcss": "^8.5.26",
+    "tsup": "^8.0.0",
+    "tsx": "^4.23.13",
+    "typescript": "^5.7.0",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
   }
-}
+}

package/skills/build-trace-analyst/SKILL.md

@@ -17,6 +17,9 @@ Check live analysts separately only for `traces stream`.
 Extend an existing analyst when it already emits the target with usable evidence.
 Do not inspect bundled `dist` or `node_modules`.
 
+Answer a one-off question with `traces ask --question "<text>"` instead.
+Build an analyst when the question repeats and its answer must be scored, not read.
+
 ## Implement
 
 - Use `Analyst`, `AnalystRegistry`, `TraceAnalysisStore`, and `makeFinding` from `@tangle-network/traces`.

package/skills/inspect-agent-traces/SKILL.md

@@ -5,13 +5,12 @@ description: Inspect real agent workflows with the published Traces CLI and expo
 
 # Inspect agent traces
 
-Use the deterministic CLI first.
-Keep inspection local and read-only.
+Use the deterministic CLI first; keep inspection local and read-only.
 
 ## Choose the way in
 
-If the trace is already OTLP (a system that emits `@tangle-network/agent-trace-contract`
-spans, or any conforming exporter), read it directly. No adapter is involved.
+If the trace is already OTLP (any `@tangle-network/agent-trace-contract` emitter or other
+conforming exporter), read it directly. No adapter is involved.
 
 ```bash
 traces validate spans.otlp.jsonl          # what can this trace answer? exit 1 on error findings
@@ -22,14 +21,13 @@ traces analyze --otlp results/sessions --out .traces/all.md   # a directory of e
 Use `--harness` only for coding agents whose on-disk format we do not control.
 Those adapters are the legacy edge, not the way to integrate a system you own.
 
-A run directory holds the span export beside raw event, stream and SDK logs that are
-also `*.jsonl`. Only the OTLP files are read; the rest are listed with what they hold.
-An `otlp/` subdirectory, when present, is read on its own.
+In a run directory only the OTLP files are read; other `*.jsonl` logs are listed with
+what they hold. An `otlp/` subdirectory, when present, is read on its own.
 
-Any section headed `inputs incomplete`, or carrying an `Inputs incomplete` line above
-its table, is computed from a field the trace does not carry everywhere. Report those
-numbers as uncaptured, never as zero spend. The `trace conformance` section at the top
-names every such capability once; the markers repeat it where the number actually is.
+A section headed `inputs incomplete`, or carrying an `Inputs incomplete` line above its
+table, is computed from a field the trace does not carry everywhere. Report those numbers
+as uncaptured, never as zero spend. The `trace conformance` section names each such
+capability once; the markers repeat it at the number.
 
 For a loop trace, read `round-over-round convergence` (did round N+1 improve on N) and
 `steering chain` (which verdict caused which retry) before drawing any conclusion about
@@ -48,7 +46,7 @@ traces analyze --harness codex --current --latest-turn --workflow \
 - Use `--session <id-or-path>` to pin a listed session.
 - Use `--latest-turn` for the current task in a resumed Codex or Claude Code session.
 - Use `--workflow` to include workers linked by stable parent and child IDs.
-- Use `--max-workflow-sessions <n>` only when the default 100-file bound is insufficient.
+- Use `--max-workflow-sessions <n>` only when the default 100-file bound is too small.
 - For Claude Code, use `--harness claude-code --session <path> --latest-turn`; nested subagents are included.
 
 Never join agents by display name or timestamp when Traces reports missing or conflicting IDs.
@@ -70,7 +68,7 @@ traces improve --harness codex --current --latest-turn --workflow \
 ```
 
 `improve` writes findings, evidence, a report, and spans.
-It does not edit an agent, repository, memory store, or knowledge base.
+It edits no agent, repository, memory store, or knowledge base.
 
 Write one session's durable evidence directory for a later reader:
 
@@ -80,12 +78,11 @@ traces bundle --harness claude-code --session <id-or-path> --out .traces/bundle
 
 `bundle` copies the transcript, the derived report and spans, the `.evolve` ledger rows inside the session window, and a `manifest.json` with a SHA-256 per file.
 It spends no model call.
-A missing transcript stops the assembly.
-An absent optional input is recorded in `manifest.absent` with the probed path.
+A missing transcript stops the assembly; an absent optional input is recorded in `manifest.absent` with the probed path.
 
 ## Pick the view for the reader
 
-That bundle is the FULL view (`manifest.view: "full"`), and it holds the whole session transcript.
+That bundle is the FULL view (`manifest.view: "full"`) and holds the whole session transcript.
 Never give it to a writer that must not see an earlier conclusion: the transcript holds the text of every file the session wrote, so a check for the earlier report FILE passes while its CONTENT is still readable.
 
 Project the writer's copy instead:
@@ -94,17 +91,22 @@ Project the writer's copy instead:
 traces bundle-view .traces/bundle --view evidence-only --out .traces/writer
 ```
 
-That view carries `derived/session-index.json`, `derived/evidence.jsonl`, and the structured `ledger/` records.
-It excludes the transcripts, the report, the spans, and every prose ledger file by name, with rules and hashes in `manifest.excluded`.
-Before writing, it compares each carried file against each excluded file for shared 8-word runs of prose, and drops any file that repeats one.
+It carries `derived/session-index.json`, `derived/evidence.jsonl`, and the structured `ledger/` records.
+It excludes the transcripts, report, spans, and every prose ledger file by name, with the rules and hashes in `manifest.excluded`.
+It also drops any carried file that repeats an 8-word run of prose from an excluded one.
 `manifest.view` names which copy you hold.
 
+## Ask your own question
+
+`traces ask --last 1 --question "<text>" --budget 2 --dir .traces/ask` keeps the engine's
+prose answer, resolves every `trace://` citation in it, and spends model calls to do it.
+
 ## Report
 
 - State the source (`--otlp <path>` or the harness), selected task boundary, session and span counts, and integrity warnings.
 - State which capabilities the trace could not support, and name the analyses that reported nothing because of it.
 - Cite each finding with its exact `trace://` reference.
-- Mark missing outcome, cost, token, skill, or relationship data as unknown.
+- Mark missing outcome, cost, token, skill, or relationship data unknown.
 - Do not infer task success from a completion message.
 - Do not infer skill use from reading a `SKILL.md`.
 - Do not upload traces unless explicitly requested.