@tangle-network/traces 0.10.3 → 0.11.2

package/dist/index.d.ts

@@ -1,13 +1,205 @@
-import { ToolUseMetrics, InMemoryTraceStore } from '@tangle-network/agent-eval';
+import { TraceValidation, SpanKind, Outcome } from '@tangle-network/agent-trace-contract';
+export { Capability, ConformanceFinding, ContractSpan, SpanLink, TraceValidation } from '@tangle-network/agent-trace-contract';
+import { ToolUseMetrics, InMemoryTraceStore, CounterfactualRunner, CounterfactualContext, TraceEmitter, TraceStore } from '@tangle-network/agent-eval';
 import { StuckLoopReport, FailureClusterReport } from '@tangle-network/agent-eval/pipelines';
 import { TraceAnalystDefinition, TraceAnalysisEngine, AnalystRegistry, AnalystFinding, buildDefaultAnalystRegistry, AnalystRunSummary, AnalystRunResult, Analyst } from '@tangle-network/agent-eval/analyst';
 export { Analyst, AnalystContext, AnalystFinding, AnalystRegistry, buildDefaultAnalystRegistry, makeFinding } from '@tangle-network/agent-eval/analyst';
 import { ExecutionReport } from '@tangle-network/agent-eval/contract';
 import { TraceAnalysisStore, RedactionRule, RedactionReport } from '@tangle-network/agent-eval/traces';
 export { DEFAULT_REDACTION_RULES, ErrorCluster, RedactionReport, RedactionRule, TraceAnalysisStore, redactString, redactValue } from '@tangle-network/agent-eval/traces';
+import { SpawnEvent, NodeStatus, Runtime, Budget, Spend } from '@tangle-network/agent-runtime/kernel';
+import { SupervisorRunNodeRole, SupervisorRunReader, SupervisorRunSources } from '@tangle-network/agent-eval/supervisor-run';
 import { TraceSpanEvent } from '@tangle-network/agent-eval/hosted';
 export { HostedClient, createHostedClient, hostedClientFromEnv } from '@tangle-network/agent-eval/hosted';
 
+/**
+ * The INBOUND path: read OTLP-JSONL that some other system emitted and hand it
+ * to the same analysis pipeline the adapters feed.
+ *
+ * The adapters (`src/adapters/`) exist because Claude Code, Codex, OpenCode and
+ * friends write proprietary session logs we do not control, so somebody has to
+ * translate. A system you DO control should not need one: emit
+ * `@tangle-network/agent-trace-contract` spans and point `--otlp` at the file.
+ *
+ * Two rules govern everything here:
+ *
+ * 1. **Never throw on foreign input.** A tool that crashes on somebody else's
+ *    trace cannot read "any AI system". A malformed line, a missing timestamp, a
+ *    link pointing at nothing — each becomes a counted, named issue and the run
+ *    continues on what is readable.
+ * 2. **Validate what the PRODUCER wrote.** {@link readOtlpInput} runs
+ *    `validateTraceSpans` over the raw rows, before this module normalizes
+ *    anything, so the report tells the producer what to fix rather than
+ *    describing our own repairs back to them.
+ */
+
+/** Why one row of an OTLP file did not become an analyzable span AT ALL. */
+type OtlpIngestIssueKind = 'unparseable-line' | 'not-an-object' | 'missing-span-id' | 'unreadable-timestamp' | 'conflicting-span-id';
+interface OtlpIngestIssue {
+    readonly kind: OtlpIngestIssueKind;
+    readonly file: string;
+    /** 1-indexed line within `file`. */
+    readonly line: number;
+    readonly detail: string;
+}
+/** Which unusable field cost a span one measurement, without costing it its existence. */
+type OtlpWithheldFieldKind = 'negative-duration';
+/**
+ * A row that DID become a span, with one unusable field withheld.
+ *
+ * This is a different event from an {@link OtlpIngestIssue} and the two must
+ * never be merged. A span whose `end_time` precedes its `start_time` has an
+ * unusable INTERVAL — it does not have an unusable identity, name, tool name or
+ * status. Dropping the whole span for it silently deleted a real tool call from
+ * every count in the report, which is a worse failure than the wrong duration
+ * it was avoiding: a wrong number is visible and a missing row is not.
+ *
+ * So the span survives, its interval is withheld rather than repaired (no
+ * synthesized end time enters any total), and the withholding is reported
+ * here. The contract's own `negative-duration` finding independently marks
+ * `latency-analysis` unavailable, so every table that prints a duration is
+ * already gated.
+ */
+interface OtlpFieldWithheld {
+    readonly kind: OtlpWithheldFieldKind;
+    /** The span field that could not be used. */
+    readonly field: string;
+    readonly file: string;
+    /** 1-indexed line within `file`. */
+    readonly line: number;
+    readonly detail: string;
+}
+/**
+ * A span field this package ANALYSES as something other than what the producer
+ * wrote.
+ *
+ * Every one of these is a place the reader has to substitute a value to analyse
+ * the row at all — a trace id to group by, an end time to subtract, a status to
+ * count, a kind to bucket, a link to follow. Substituting is correct; writing
+ * the substitute into the EXPORT is not, because the export is re-validated and
+ * the substitute is by construction more conforming than the source. Every
+ * `missing-trace-id`, `invalid-timestamp`, `invalid-status`, `unknown-span-kind`
+ * and `dangling-link` this package's own re-export ever laundered away was one
+ * of these fields, so they are enumerated in ONE place and the export reads that
+ * list rather than knowing them one at a time — a sixth substitution cannot be
+ * added without the export learning about it.
+ */
+type SubstitutedField = 'trace_id' | 'end_time' | 'status.code' | 'kind' | 'links';
+interface OtlpInputFile {
+    readonly path: string;
+    readonly rows: number;
+    readonly spans: number;
+    /** Rows that re-declared a span already read, byte-identically. */
+    readonly repeats: number;
+    /** Distinct trace ids this file contributed, so a caller can attribute a
+     *  trace back to the file it came from when a directory was ingested. */
+    readonly traceIds: readonly string[];
+}
+/** A `*.jsonl` in the directory that does not hold OTLP spans, and how we know. */
+interface SkippedInputFile {
+    readonly path: string;
+    /** What the first readable line was instead of a span. */
+    readonly reason: string;
+}
+/**
+ * How much of the original source could not be represented as spans, summed
+ * across every export hop that led to this file.
+ *
+ * `rows` is the count and `kinds` names the ingest issues behind it. On a file a
+ * producer wrote, this is just what THIS ingest dropped. On a file
+ * `traces` re-exported, it also carries what earlier hops dropped, read back off
+ * the spans — so a re-export can never present itself as a complete copy of a
+ * source it is missing rows from.
+ */
+interface UnreadableSourceRows {
+    readonly rows: number;
+    readonly kinds: readonly OtlpIngestIssueKind[];
+    /** Rows dropped by EARLIER hops, already absent from the file just read. */
+    readonly inherited: number;
+}
+interface OtlpInput {
+    /** Every file read, in ingest order. */
+    readonly files: readonly OtlpInputFile[];
+    /** JSONL files in the directory that hold something other than OTLP spans. */
+    readonly skipped: readonly SkippedInputFile[];
+    /** Rows exactly as the producer wrote them — the input to `validateTraceSpans`. */
+    readonly rows: readonly unknown[];
+    /** Rows normalized into this package's span model, ready for the pipeline. */
+    readonly spans: readonly OtlpSpan[];
+    /** Conformance of the RAW rows: what this trace can and cannot answer. */
+    readonly validation: TraceValidation;
+    /** Rows that could not become spans, each with its reason. */
+    readonly issues: readonly OtlpIngestIssue[];
+    /** Rows that DID become spans, with one unusable field withheld from them. */
+    readonly withheld: readonly OtlpFieldWithheld[];
+    /** Source rows absent from `spans`, this hop's and every earlier hop's. */
+    readonly unreadable: UnreadableSourceRows;
+}
+/** A file or directory resolved to the OTLP files in it, plus the JSONL that is not OTLP. */
+interface ResolvedOtlpInput {
+    readonly files: readonly string[];
+    readonly skipped: readonly SkippedInputFile[];
+}
+/**
+ * Resolve a file or directory to the OTLP files it names.
+ *
+ * A named FILE is read as OTLP whatever it contains — the caller pointed at it,
+ * and reporting its rows as unreadable is more useful than refusing it. A
+ * DIRECTORY is a guess about which files were meant, so its non-OTLP JSONL is
+ * skipped and named rather than ingested.
+ */
+declare function resolveOtlpInputFiles(path: string): Promise<ResolvedOtlpInput>;
+/**
+ * Classify a span from its EVIDENCE — name and attributes — ignoring whatever
+ * kind it declared. Callers decide whether a declaration wins; this answers the
+ * separate question "what does this span look like".
+ *
+ * The contract's `resolveSpanKind` does the classifying, so a foreign trace
+ * cannot land in one bucket here and another there. What sits on top of it are
+ * only signals the contract deliberately does not read, and only where it
+ * returned `UNKNOWN`:
+ *
+ * - `span.type`, a Tangle-internal marker. Its tool-telemetry values name
+ *   children that DESCRIBE a tool call; counting them as calls doubles every
+ *   tool total, which is why that check runs first.
+ * - the local tool spellings above, and a name that mentions a tool.
+ * - an interaction/agent name, which is the run container this model calls
+ *   AGENT.
+ *
+ * Anything still unrecognised stays `UNKNOWN`. It is not `CHAIN`: CHAIN claims
+ * the span CONTAINS other work, and inventing that relationship is how an
+ * unclassifiable span ends up misreported as a container.
+ */
+declare function inferSpanKind(name: string, attributes: Record<string, unknown>): OtlpSpanKind;
+/**
+ * Exactly one of `span` or `issue`: a usable span, or the named reason there
+ * isn't one. `withheld` accompanies a SPAN — the row was analysable, one field
+ * on it was not.
+ */
+interface OtlpRowConversion {
+    span?: OtlpSpan;
+    issue?: Omit<OtlpIngestIssue, 'file' | 'line'>;
+    withheld?: Omit<OtlpFieldWithheld, 'file' | 'line'>;
+}
+/**
+ * One raw row to one analyzable span, or one named reason it is not analyzable.
+ *
+ * `fallbackTraceId` covers a row with no trace_id: `validateTraceSpans` reports
+ * that as `missing-trace-id`, and grouping still needs SOME key, so the source
+ * file names the anonymous trace instead of each span becoming its own run.
+ */
+declare function otlpRowToSpan(row: unknown, fallbackTraceId: string): OtlpRowConversion;
+/**
+ * Read OTLP-JSONL from a file or a directory of them.
+ *
+ * A directory ingests the OTLP files under it, recursively — every `*.jsonl` /
+ * `*.ndjson` that holds spans, or only the contents of an `otlp/` subdirectory
+ * when the producer made one — so a results directory of per-shot exports
+ * analyses as one body of work while its raw event and stream logs are named
+ * and skipped rather than counted as broken spans.
+ */
+declare function readOtlpInput(path: string): Promise<OtlpInput>;
+
 /**
  * OTLP-flat-line emitter — the canonical normalized trace shape.
  *
@@ -19,7 +211,7 @@ export { HostedClient, createHostedClient, hostedClientFromEnv } from '@tangle-n
  * (which reads the attribute vocabulary), HALO, and any OpenInference tool.
  *
  * Attribute vocabulary the downstream analysts key off:
- *   - `openinference.span.kind`  → span kind (AGENT | LLM | TOOL | CHAIN)
+ *   - `openinference.span.kind`  → span kind ({@link OtlpSpanKind})
  *   - `service.name`             → harness id (claude-code, codex, …)
  *   - `agent.name`               → agent / subagent name
  *   - `llm.model_name`           → model
@@ -27,8 +219,34 @@ export { HostedClient, createHostedClient, hostedClientFromEnv } from '@tangle-n
  *   - `tool.name`                → tool histogram (monoculture / no-verify)
  *   - `step`                     → run order (falls back to start_time)
  */
-type OtlpSpanKind = 'AGENT' | 'LLM' | 'TOOL' | 'CHAIN' | 'SPAN';
+
+/**
+ * The span-kind vocabulary, which is exactly
+ * `@tangle-network/agent-trace-contract`'s — AGENT, CHAIN, LLM, TOOL,
+ * EVALUATOR, RETRIEVER, UNKNOWN.
+ *
+ * It is an alias, not a copy, because the two vocabularies MUST NOT drift: a
+ * narrower local union silently re-typed every kind it did not list, so a
+ * producer's EVALUATOR verdict span came back out as CHAIN and the re-exported
+ * file no longer said what the original did.
+ */
+type OtlpSpanKind = SpanKind;
 type OtlpStatusCode = 'OK' | 'ERROR' | 'UNSET';
+/**
+ * A causal edge that is NOT containment. `parent_span_id` says "this span
+ * happened INSIDE that one"; a link says "that one CAUSED this one" — round N's
+ * verdict steering round N+1, a retry pointing at the attempt it replaces.
+ * Encoding those as a parent would claim a nesting that never existed, so OTLP
+ * gives them their own edge and this model keeps it.
+ *
+ * Matches `SpanLink` in `@tangle-network/agent-trace-contract`.
+ */
+interface OtlpSpanLink {
+    trace_id: string;
+    span_id: string;
+    /** e.g. `{ 'agent.link.kind': 'steered_by' }`. */
+    attributes?: Record<string, unknown>;
+}
 interface OtlpSpan {
     trace_id: string;
     span_id: string;
@@ -41,6 +259,8 @@ interface OtlpSpan {
         message?: string;
     };
     attributes: Record<string, unknown>;
+    /** Causal edges to other spans. Absent when the producer recorded none. */
+    links?: OtlpSpanLink[];
 }
 interface SpanInput {
     traceId: string;
@@ -68,6 +288,8 @@ interface SpanInput {
     step?: number;
     /** Verbatim content the agentic analysts read via regex search. */
     content?: string | null;
+    /** Causal edges (steered-by / graded-by / retry-of), not containment. */
+    links?: readonly OtlpSpanLink[];
     /** Extra attributes merged last (escape hatch for harness-specific signal). */
     extra?: Record<string, unknown>;
 }
@@ -77,11 +299,43 @@ interface SpanInput {
  * so the behavioral analyst's "no LLM data" case stays honest.
  */
 declare function span(input: SpanInput): OtlpSpan;
-/** Project an in-memory span to a COMPLETE OpenInference span: the standard shape
- *  OTel/OpenInference consumers (and HALO) expect — top-level `kind`, `resource`,
- *  `scope`, and a string `parent_span_id` ("" at the root) — while keeping the
- *  attribute vocabulary (incl. `openinference.span.kind`) our own analysts read.
- *  One artifact feeds our pipeline, HALO, and any OpenInference tool. */
+/** The three things an export can write for a substituted field, and nothing else. */
+type ExportRule = 'faithful' | 'declared-or-analysed' | 'analysed';
+/**
+ * What the export writes for a field this package substituted. One rule per
+ * field, in one table, because the difference between them is not a style choice
+ * — each `analysed` entry is a consumer that HARD-REQUIRES the field, named.
+ *
+ * The table is EXPORTED because it is a guarantee, not documentation:
+ * `tests/otlp-export-rule.test.ts` reads it and derives, per field, the checks
+ * the declared word promises — the exact value written in each of the two
+ * producer states, that a `faithful` field erases no finding its source earned,
+ * and that the artifact stays readable by the consumer whose hard requirement is
+ * the only reason `analysed` exists. A field could be declared `faithful` here
+ * while nothing implemented it (`status.code` was, and the finding vanished from
+ * every re-export); a table that reads as a guarantee and is not one is worse
+ * than no table.
+ *
+ * - `faithful` — the producer's value, or NO field at all when they wrote none.
+ *   This is the default and the only rule that reproduces the source's finding
+ *   exactly.
+ * - `declared-or-analysed` — the producer's word when they wrote one, else this
+ *   package's. A kind is what every consumer buckets by, and a span with none is
+ *   re-derived differently by each of them (the tool-execution demotion that
+ *   stops a tool call being counted twice is one such re-derivation), so the
+ *   export always declares one. Writing the producer's word when there is one is
+ *   what keeps `unknown-span-kind` alive across the trip.
+ * - `analysed` — this package's value regardless. `trace_id` is the one field
+ *   here, and it is not a choice: `analyze --otlp-out` hands the artifact
+ *   straight to `agent-eval`'s `OtlpFileTraceStore`, whose `projectOtlpFlatLine`
+ *   drops any row with a falsy `trace_id` and then throws `TraceFileMalformed`
+ *   on the drop. A faithful (absent) trace id makes the artifact unreadable by
+ *   the tool that reads it, so `missing-trace-id` CANNOT survive the trip. The
+ *   substitution is disclosed instead — the span carries the pairing, and
+ *   `renderConformance` states it above the findings so a reader of the artifact
+ *   is told the id was minted here rather than left to assume the source had one.
+ */
+declare const EXPORT_RULE: Readonly<Record<SubstitutedField, ExportRule>>;
 declare function toOpenInferenceSpan(s: OtlpSpan): Record<string, unknown>;
 /** Serialize spans to OpenInference JSONL (one complete span per line). This is a
  *  standard OpenInference representation: it feeds our analysts, HALO, and other
@@ -207,6 +461,226 @@ interface HarnessTraceAdapter {
     resolveParentTask?(ref: SessionRef, childSessionId: string, options?: Pick<ParseOptions, 'corruptionMode' | 'signal'>): Promise<ParentTaskResolution>;
 }
 
+/**
+ * What a trace can and cannot answer, said out loud.
+ *
+ * `@tangle-network/agent-trace-contract` decides conformance: it reports
+ * findings (what is wrong, and the consequence) and capabilities (what a
+ * consumer can compute, and why not when it cannot). That package is
+ * deliberately generic. This module adds the one thing it cannot know — which
+ * section of THIS report each missing capability empties — so a thin report
+ * explains its own thinness instead of reading as "the agent did nothing".
+ */
+
+/**
+ * Capabilities the trace cannot support, mapped to the trace's own reason.
+ *
+ * This is what makes the conformance section GATE rather than narrate: the
+ * renderer takes it and marks every section whose inputs are incomplete, at the
+ * table, so a number and the reason it is wrong cannot end up forty lines
+ * apart.
+ */
+type UnavailableCapabilities = ReadonlyMap<string, string>;
+/** The trace's unavailable capabilities, each mapped to the validator's own reason. */
+declare function unavailableCapabilities(validation: TraceValidation): UnavailableCapabilities;
+/**
+ * The inline marker a section carries when its inputs are incomplete. Empty
+ * when the capability is available — the caller concatenates unconditionally,
+ * so a section can never be marked in one place and silently not in another.
+ */
+declare function incompleteInputsNote(unavailable: UnavailableCapabilities | undefined, capability: string): string;
+interface SpanStructure {
+    readonly spans: number;
+    readonly traces: number;
+    /** Spans carrying no `parent_span_id` at all. */
+    readonly rootless: number;
+    /**
+     * Rootless spans BEYOND the one root each trace is supposed to have. This,
+     * not `rootless`, is the number of spans that attribute to nothing: a
+     * textbook-correct trace has exactly one root, so `rootless === traces` with
+     * one root each is a conforming shape and must read as one.
+     */
+    readonly extraRoots: number;
+    /** Traces where every span names a parent, so the trace has no top at all. */
+    readonly tracesWithoutRoot: number;
+    /** Spans naming a parent that is absent from the export. */
+    readonly orphans: number;
+    readonly links: number;
+}
+/**
+ * How much of the span tree actually attaches.
+ *
+ * The contract's `flat-hierarchy` finding is per-trace and all-or-nothing: one
+ * parented span anywhere in a trace suppresses it for every other span. A trace
+ * where the overwhelming majority of spans have no parent is not flat by that
+ * definition and is entirely flat in practice, so this reports the DEGREE the
+ * binary finding cannot express. It measures, it does not re-implement — the
+ * finding still comes from the validator.
+ *
+ * Roots are counted PER TRACE, because "has no parent" is the definition of a
+ * root, not of a defect. Counting every rootless span as unattributed made a
+ * correct one-root trace narrate itself as broken.
+ */
+declare function summarizeSpanStructure(spans: readonly OtlpSpan[]): SpanStructure;
+interface SkippedAnalysis {
+    readonly capability: string;
+    /** The analysis in this report that the missing capability empties. */
+    readonly analysis: string;
+    /** The trace's own reason, from the contract validator. */
+    readonly reason: string;
+}
+/**
+ * Conformance of spans this package produced (adapters, importers), measured on
+ * the same OpenInference projection that gets written to disk — so the report
+ * grades the artifact a consumer would actually receive, not an in-memory shape
+ * nobody sees. For spans read from a foreign OTLP file, validate the RAW rows
+ * instead (`readOtlpInput` does): that tells the producer what to fix rather
+ * than describing our own normalization back to them.
+ */
+declare function conformanceOfSpans(spans: readonly OtlpSpan[]): TraceValidation;
+/** Unavailable capabilities, paired with the analysis each one empties. */
+declare function skippedAnalyses(validation: TraceValidation): SkippedAnalysis[];
+interface ConformanceRenderOptions {
+    /** What was validated, e.g. a file path or "spans emitted by the claude-code adapter". */
+    readonly subject: string;
+    /** Files read, when the source was an OTLP file or directory. */
+    readonly files?: readonly OtlpInputFile[];
+    /** JSONL files in the directory that hold something other than OTLP spans. */
+    readonly skipped?: readonly SkippedInputFile[];
+    /** Rows that never became spans, when the source was an OTLP file or directory. */
+    readonly issues?: readonly OtlpIngestIssue[];
+    /** Rows that DID become spans, with one field withheld from them. */
+    readonly withheld?: readonly OtlpFieldWithheld[];
+    /** Source rows absent from this file — this ingest's, and any earlier export's. */
+    readonly unreadable?: UnreadableSourceRows;
+    /** The spans that were analysed, for the hierarchy summary. */
+    readonly spans?: readonly OtlpSpan[];
+    /** Markdown heading level for the section title (default 2). */
+    readonly headingLevel?: number;
+}
+/**
+ * The conformance section of an analysis report: findings, the capability
+ * table, and — the part that makes a thin report honest — the named analyses
+ * that produced nothing and why.
+ */
+declare function renderConformance(validation: TraceValidation, opts: ConformanceRenderOptions): string;
+/**
+ * The `traces validate` report. Same body, plus a verdict line a reader (or a
+ * CI job reading the exit code) can act on.
+ *
+ * The three verdicts are the three answers `@tangle-network/agent-trace-contract`
+ * can give, in its own terms — `ok` says whether the input is a trace AT ALL, and
+ * `capabilities` says what a trace can answer. Nothing here re-derives either.
+ */
+declare function renderValidation(validation: TraceValidation, opts: ConformanceRenderOptions): string;
+/**
+ * Exit code for `traces validate`, which is read by CI.
+ *
+ * Non-zero on exactly one condition: the input is not a trace. That is what
+ * `TraceValidation.ok` means and the contract's severities are defined to match
+ * it — `error` is "nothing readable", `warn` is "readable but degraded", `info`
+ * is "nothing lost" — so a severity scan here would only be a second, driftable
+ * copy of the same rule.
+ *
+ * A degraded trace exits 0 deliberately. Failing on degradation is failing on
+ * thinness, and every real-world trace is thin somewhere: a gate that red-lights
+ * `flat-hierarchy` or `no-usage` is one a producer learns to ignore. What a
+ * missing field costs is stated per capability, in the table, where it can be
+ * acted on.
+ */
+declare function validationExitCode(validation: TraceValidation): number;
+
+/**
+ * The two questions a LOOP trace exists to answer, and that a flat event list
+ * cannot: **did round N+1 improve on round N**, and **which verdict caused
+ * which retry**.
+ *
+ * Both are read from the contract's own vocabulary and nothing else:
+ *
+ * - `agent.loop.id` / `agent.loop.iteration` group and order the rounds.
+ * - `agent.outcome` / `agent.outcome.score` carry the verdict. A round rarely
+ *   grades itself — the grade lives on an EVALUATOR span underneath it — so the
+ *   verdict is taken from the shallowest descendant that has one, which is the
+ *   round's own verdict rather than one of its per-layer sub-verdicts.
+ * - `links` carry causality. `parent_span_id` says round N+1 happened INSIDE
+ *   round N, which is false; the link says round N's verdict CAUSED it, which
+ *   is the edge a steering chain is made of.
+ *
+ * Nothing here throws on malformed input, and nothing is inferred where the
+ * trace is silent: a loop with no scores reports `unscored`, not a flat trend.
+ */
+
+/** Whether the rounds got better, stayed put, or got worse — and on what basis. */
+type LoopTrend = 'improved' | 'plateaued' | 'regressed' | 'mixed' | 'unscored';
+/** What the trend was computed from, so a reader can tell a score series from
+ *  a pass/fail series from nothing at all. */
+type LoopTrendBasis = 'score' | 'outcome' | 'none';
+interface LoopIteration {
+    readonly iteration: number;
+    readonly spanId: string;
+    readonly name: string;
+    /** Terminal verdict for the round, from the round or its shallowest graded descendant. */
+    readonly outcome: Outcome | null;
+    readonly score: number | null;
+    /** Span the verdict was read from; equals `spanId` when the round graded itself. */
+    readonly verdictSpanId: string | null;
+    readonly startTime: string;
+    readonly durationMs: number | null;
+}
+interface LoopConvergence {
+    readonly loopId: string;
+    readonly traceId: string;
+    readonly iterations: readonly LoopIteration[];
+    readonly trend: LoopTrend;
+    readonly basis: LoopTrendBasis;
+    /** The trend in the trace's own numbers, e.g. "score 0.4 → 0.9 over 4 rounds". */
+    readonly detail: string;
+}
+interface LoopConvergenceReport {
+    readonly loops: readonly LoopConvergence[];
+    /** Spans carrying `agent.loop.iteration` — 0 means the trace records no rounds. */
+    readonly iterationSpans: number;
+}
+/** One causal edge: a graded span, and the work it caused. */
+interface SteeringEdge {
+    /** The span that CAUSED the work — a verdict, an earlier attempt. */
+    readonly causeSpanId: string;
+    readonly causeName: string | null;
+    readonly causeOutcome: Outcome | null;
+    readonly causeScore: number | null;
+    /** The span the link was recorded on: the work that was caused. */
+    readonly effectSpanId: string;
+    readonly effectName: string;
+    readonly effectIteration: number | null;
+    /** `agent.link.kind`, or `unspecified` when the producer recorded none. */
+    readonly linkKind: string;
+    /** False when the cause is absent from this export, so the chain breaks here. */
+    readonly resolved: boolean;
+}
+interface SteeringChainReport {
+    readonly edges: readonly SteeringEdge[];
+    readonly links: number;
+    readonly dangling: number;
+    readonly byKind: Readonly<Record<string, number>>;
+}
+/**
+ * Round-over-round convergence, per loop.
+ *
+ * Rounds are ordered by `agent.loop.iteration`, not by time: a resumed or
+ * re-run round is written later than the round it replaces, and time order
+ * would report the replacement as a new round.
+ */
+declare function analyzeLoopConvergence(spans: readonly OtlpSpan[]): LoopConvergenceReport;
+/**
+ * The steering chain: which graded span caused which subsequent unit of work.
+ *
+ * A link is recorded on the EFFECT and points at the CAUSE, so the edge is read
+ * backwards from the span that carries it. A link whose target is absent from
+ * the export is kept and marked unresolved — dropping it would report a shorter
+ * chain than the producer recorded, which is the opposite of the truth.
+ */
+declare function analyzeSteeringChain(spans: readonly OtlpSpan[]): SteeringChainReport;
+
 interface CodeTraceBenchFileRef {
     readonly path: string;
     readonly line_start: number;
@@ -1847,6 +2321,24 @@ interface TraceInvestigationOptions {
     readonly analyzerPrompt?: string;
     readonly otlpOutPath?: string;
     readonly generatedAt?: string;
+    /**
+     * Conformance of the SOURCE the spans were read from. Supply it when the
+     * source was a foreign OTLP file, so the report grades what the producer
+     * wrote; omitted, it is computed from the spans themselves.
+     */
+    readonly conformance?: TraceValidation;
+    /** What was validated, named in the conformance section (default: the harness). */
+    readonly conformanceSubject?: string;
+    /** OTLP files read, when the spans came from `--otlp`. */
+    readonly conformanceFiles?: readonly OtlpInputFile[];
+    /** JSONL files that were not OTLP, when the spans came from `--otlp` on a directory. */
+    readonly conformanceSkipped?: readonly SkippedInputFile[];
+    /** Rows that never became spans, when the spans came from `--otlp`. */
+    readonly conformanceIssues?: readonly OtlpIngestIssue[];
+    /** Rows analysed with one field withheld, when the spans came from `--otlp`. */
+    readonly conformanceWithheld?: readonly OtlpFieldWithheld[];
+    /** Source rows absent from the file read, including any earlier export's. */
+    readonly conformanceUnreadable?: UnreadableSourceRows;
     readonly signal?: AbortSignal;
     readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
 }
@@ -1879,12 +2371,22 @@ interface TraceInvestigationResult {
     readonly workflow?: SessionWorkflowSummary;
     readonly spanCount: number;
     readonly otlpPath: string;
+    /**
+     * What these spans can and cannot answer. Every report carries it: a thin
+     * report that does not explain its own thinness reads as "the agent did
+     * nothing" when the truth is "the trace never recorded it".
+     */
+    readonly conformance: TraceValidation;
     readonly execution: ExecutionReport;
     readonly analystResult: AnalystRunResult;
     readonly findings: readonly AnalystFinding[];
     readonly pipelines: PipelineReport;
     readonly reactions: ReactionReport;
     readonly adoption: AdoptionReport;
+    /** Did round N+1 improve on round N, per loop. */
+    readonly loopConvergence: LoopConvergenceReport;
+    /** Which verdict caused which subsequent round. */
+    readonly steeringChain: SteeringChainReport;
     /** Deterministic routing record for the agentic trace-analysis pass. */
     readonly agenticRoute?: TraceAgenticRoute;
     /**
@@ -2052,6 +2554,512 @@ interface ObserverOptions {
 }
 declare function watchSessions(opts: ObserverOptions): Promise<void>;
 
+/**
+ * A SECOND implementation of agent-eval's `SupervisorRunReader` port, over the
+ * run directory that agent-runtime's `createFileRunContext(dir)` writes:
+ *
+ *   <runDir>/spawn-journal.jsonl     required — the append-only SpawnEvent log
+ *   <runDir>/coordination-log.jsonl  optional — steer / delivery / question / settled
+ *   <runDir>/blobs/                  optional — content-addressed settled results
+ *   <runDir>/result.json             optional — the terminal outcome document
+ *
+ * `loopsSupervisorRunReader` is the other implementation, over a completely
+ * different layout. Neither knows about the other, and NOTHING here analyzes:
+ * `analyzeSupervisorRun` / `parseSupervisorTree` / `rollupSupervisorRuns` in
+ * `@tangle-network/agent-eval/supervisor-run` compute every metric, and
+ * `materializeTreeView` in `@tangle-network/agent-runtime/kernel` folds the
+ * event log into the tree. This file is translation only.
+ *
+ * ## Two translations, both faithful
+ *
+ * 1. **The envelope.** agent-runtime's `FileSpawnJournal` writes each event
+ *    wrapped as `{kind:'event', root, event:{…}}` after one `{kind:'begin'}`
+ *    record. agent-eval's parser reads `kind` at the TOP level, so an
+ *    un-translated file parses as zero spawns AND zero malformed rows — a run
+ *    that reads as "the supervisor did nothing" rather than "I cannot read
+ *    this". The reader unwraps the envelope and re-emits flat JSONL.
+ *
+ * 2. **`role`.** `SupervisorRunSources.journal` documents
+ *    `role: 'supervisor' | 'worker'` on spawned rows for recursive readers.
+ *    agent-runtime's `SpawnEvent` has no such field, so it is INFERRED
+ *    structurally and exactly: a node that appears as another spawn's `parent`
+ *    is a supervisor; the root is a supervisor because it has no parent;
+ *    everything else is a worker. No new upstream field is needed for this,
+ *    and no depth limit applies — `<root>:s0:s0` classifies its parent
+ *    `<root>:s0` as a supervisor by the same rule that classifies the root.
+ *
+ * Steer traffic is translated the same way: this layout records steers in
+ * `coordination-log.jsonl` rather than per-worker inbox files, and each
+ * recorded field maps 1:1 onto the per-worker artifacts the analyzer reads.
+ * Nothing is synthesized from an absent fact — an artifact this layout does
+ * not keep is declared in `SourceLimits`, which is what turns the dependent
+ * metric into `unavailable` instead of 0.
+ */
+
+declare const SPAWN_JOURNAL_FILE = "spawn-journal.jsonl";
+declare const COORDINATION_LOG_FILE = "coordination-log.jsonl";
+declare const RESULT_FILE = "result.json";
+declare const BLOBS_DIR = "blobs";
+interface RunContextJournal {
+    /** The `root` of the `begin` record, or of the first event envelope. */
+    readonly root: string | null;
+    /** ISO instant the tree was begun, when a `begin` record was written. */
+    readonly begunAt: string | null;
+    /** Events in file order, unwrapped from their envelopes. */
+    readonly events: readonly SpawnEvent[];
+    /** Node ids that appear as some spawn's `parent` — the exact supervisor set. */
+    readonly supervisorIds: ReadonlySet<string>;
+    readonly invalidRows: number;
+    readonly partialTail: boolean;
+    readonly present: boolean;
+}
+/**
+ * Unwrap `FileSpawnJournal`'s `{kind:'begin'|'event', root, event}` records.
+ * A record whose `kind` is neither is counted as invalid rather than dropped:
+ * an unrecognized record shape is a finding, not silence.
+ */
+declare function readRunContextJournal(text: string | null): RunContextJournal;
+/**
+ * A node's role, decided by the tree's own shape. `supervisorIds` is the set of
+ * ids some spawn named as its parent, so the rule is exact at any depth and
+ * needs no field agent-runtime does not emit.
+ */
+declare function inferRole(id: string, parent: string | null | undefined, supervisorIds: ReadonlySet<string>): SupervisorRunNodeRole;
+/** One steer the driver sent down to a named node. */
+interface CoordinationSteer {
+    readonly messageId: string | null;
+    readonly toWorker: string | null;
+    readonly instruction: string;
+    readonly deliveryMode: string | null;
+    readonly at: number | null;
+}
+/** A question a node raised up. `blocking` is the run-stopping urgency. */
+interface CoordinationQuestion {
+    readonly id: string | null;
+    readonly from: string | null;
+    readonly question: string;
+    readonly reason: string | null;
+    readonly urgency: string | null;
+    readonly status: string | null;
+    readonly blocking: boolean;
+    readonly at: number | null;
+}
+interface CoordinationLog {
+    readonly present: boolean;
+    readonly steers: readonly CoordinationSteer[];
+    /** `messageId → delivered`, from `delivery` receipts. */
+    readonly deliveries: readonly {
+        messageId: string | null;
+        delivered: boolean | null;
+    }[];
+    readonly questions: readonly CoordinationQuestion[];
+    readonly invalidRows: number;
+    readonly partialTail: boolean;
+}
+/**
+ * Two record envelopes are in the wild for this file: the versioned
+ * `{version, runId, source, record:{seq, at, event}}` and the flat
+ * `{runId, at, event}`. Both carry the same `event`, so the unwrap is a single
+ * lookup and neither shape is privileged.
+ */
+declare function readCoordinationLog(text: string | null): CoordinationLog;
+interface FileRunContextReaderOptions {
+    /** Override the run identity used for rollup grouping (default: the journal root). */
+    readonly instanceId?: string | null;
+    /** Which arm of a comparison this run is (default: the run directory's basename). */
+    readonly arm?: string | null;
+}
+/**
+ * Read a `createFileRunContext` run directory into `SupervisorRunSources`.
+ * Never throws on a missing artifact: an absent file becomes a `null` field or
+ * a declared `SourceLimits` reason, which is what makes the dependent metric
+ * `unavailable` rather than 0.
+ */
+declare function readFileRunContext(runDir: string, opts?: FileRunContextReaderOptions): Promise<SupervisorRunSources>;
+/** The `createFileRunContext` on-disk layout, as a `SupervisorRunReader`. */
+declare function fileRunContextSupervisorRunReader(runDir: string, opts?: FileRunContextReaderOptions): SupervisorRunReader;
+/** Does this directory hold a `createFileRunContext` run? */
+declare function isFileRunContextDir(runDir: string): Promise<boolean>;
+/**
+ * A sum over spend records that keeps "unknown" out of the number.
+ *
+ * `usd` is the total of the records that priced themselves; `usdUnknown` is how
+ * many declined to. A renderer that has 0 known records and >=1 unknown one must
+ * print "unknown", never `$0.0000`: an unmetered turn and a free turn are
+ * different facts, and agent-runtime's `Spend.usdKnown` is the only signal that
+ * separates them (absent means known, per its contract).
+ */
+interface SpendRoll {
+    readonly records: number;
+    readonly iterations: number;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly usd: number;
+    readonly usdKnownRecords: number;
+    readonly usdUnknownRecords: number;
+}
+declare const ZERO_ROLL: SpendRoll;
+declare function addSpend(roll: SpendRoll, spend: Spend): SpendRoll;
+declare function mergeRolls(a: SpendRoll, b: SpendRoll): SpendRoll;
+interface RunContextNode {
+    readonly id: string;
+    readonly parent: string | null;
+    readonly label: string;
+    readonly depth: number;
+    readonly role: SupervisorRunNodeRole;
+    readonly status: NodeStatus;
+    readonly runtime: Runtime | null;
+    /** The budget this node was AUTHORED with, exactly as the spawn recorded it. */
+    readonly budget: Budget;
+    /** This node's own driver inference — its `metered` events. */
+    readonly driver: SpendRoll;
+    /** What this node's direct children consumed — their `settled` spend. */
+    readonly children: SpendRoll;
+    /** What this node's own settlement charged its parent (its whole subtree). */
+    readonly settled: SpendRoll;
+    readonly spawnedAt: number | null;
+    readonly settledAt: number | null;
+    /** Wall from spawn to settlement; null while the node is still live. */
+    readonly wallMs: number | null;
+    readonly outRef: string | null;
+    /** Why a cancelled node was cancelled. */
+    readonly cancelReason: string | null;
+}
+interface RunContextResult {
+    readonly kind: string | null;
+    readonly reason: string | null;
+    readonly errorName: string | null;
+    readonly errorMessage: string | null;
+}
+interface RunContextSnapshot {
+    readonly runDir: string;
+    readonly runId: string | null;
+    readonly present: boolean;
+    /** Depth-first, parents before children. */
+    readonly nodes: readonly RunContextNode[];
+    readonly maxDepth: number;
+    readonly begunAt: number | null;
+    /** Latest instant any event carried. */
+    readonly lastEventAt: number | null;
+    readonly questions: readonly CoordinationQuestion[];
+    readonly steers: readonly CoordinationSteer[];
+    readonly result: RunContextResult | null;
+    /** True once `result.json` exists — the run has reached a terminal state. */
+    readonly terminal: boolean;
+    /** Rows that were present and unreadable, per artifact. */
+    readonly invalidJournalRows: number;
+    readonly invalidCoordinationRows: number;
+    /** True when an artifact's last line was still being written. */
+    readonly partialTail: boolean;
+    /** Why the tree could not be folded, when it could not. */
+    readonly treeError: string | null;
+}
+/**
+ * Read the run directory into the shape a live view renders. The tree comes
+ * from agent-runtime's own `materializeTreeView` — the owner's fold of its own
+ * event log, so a new event kind stays correctly classified here without this
+ * file changing.
+ *
+ * The one thing the fold deliberately does NOT answer is the split this view
+ * exists for: `materializeTreeView` accumulates a node's `metered` driver
+ * inference ONTO its settled child-work base, which is the right total and the
+ * wrong breakdown. Driver and child spend are therefore rolled separately
+ * straight off the events, which is a partition of the same rows, not a second
+ * tree.
+ */
+declare function readRunContextSnapshot(runDir: string): Promise<RunContextSnapshot>;
+
+/**
+ * The GENERAL run-tree source: reconstruct a run's shape from OTLP spans alone.
+ *
+ * `supervisor-run-context.ts` is the specific source — agent-runtime's durable
+ * spawn journal, which carries the exact authored budget, settled spend, and
+ * settlement status that telemetry does not. This file is the one that works
+ * for emitters nobody has written yet: anything that emits spans carrying
+ * `trace_id` / `span_id` / `parent_span_id` gets a tree, because the parent
+ * pointer IS the tree. A supervisor, a pi session, a Claude subagent fan-out,
+ * and a custom fanout all reach the same view through the same three fields.
+ *
+ * ## Nothing here is a second exporter or a second attribute vocabulary
+ *
+ * Spans are read with this repo's existing `exportTraceEvidenceFile`, which
+ * already detects OpenInference / intelligence-span / sandbox-event files,
+ * normalizes them onto `OtlpSpan`, redacts, and validates. Every attribute is
+ * read through `@tangle-network/agent-eval/trace-attributes` alias lists
+ * (`LLM_INPUT_TOKEN_ATTR_KEYS`, `LLM_COST_ATTR_KEYS`, `SPAN_KIND_ATTR_KEYS`, …),
+ * which already cover both live vocabularies — OpenInference's
+ * `llm.token_count.*` and GenAI semconv's `gen_ai.usage.*`. No key is invented
+ * here, so a span this repo can already read is a span this view can already
+ * place.
+ *
+ * ## What a span tree can and cannot say
+ *
+ * It can say the shape, the wall time, the tokens, and — when the emitter
+ * priced them — the dollars. It CANNOT say the authored budget: neither
+ * vocabulary carries a spawn's ceiling, so budget is reported as absent, never
+ * as 0. That gap is exactly why the journal source exists and why, when both
+ * are present, the journal's numbers win.
+ */
+
+type SpanNodeStatus = 'running' | 'done' | 'failed';
+interface SpanRunNode {
+    readonly traceId: string;
+    readonly spanId: string;
+    /** The enclosing NODE's span id — not necessarily the raw parent span. */
+    readonly parentNodeId: string | null;
+    readonly label: string;
+    readonly depth: number;
+    /**
+     * `driver` when this node has nested agent nodes below it, `leaf` otherwise.
+     * Spans carry no spawn relationship, so delegation is read from the tree
+     * itself — the only fact the telemetry actually states.
+     */
+    readonly role: 'driver' | 'leaf';
+    readonly status: SpanNodeStatus;
+    /** `service.name` — which harness or runtime emitted this subtree. */
+    readonly runtime: string | null;
+    /** This node's OWN inference: the LLM spans it emitted directly. */
+    readonly driver: SpendRoll;
+    /** What its nested agent nodes consumed, whole subtrees included. */
+    readonly children: SpendRoll;
+    /** Tool spans attributed to this node directly. */
+    readonly toolCalls: number;
+    readonly startMs: number;
+    readonly endMs: number;
+    readonly wallMs: number;
+    /** Span status messages on this node or its non-node descendants. */
+    readonly errors: readonly string[];
+}
+interface SpanRunSnapshot {
+    readonly source: string;
+    readonly present: boolean;
+    /** Depth-first, parents before children, one subtree per trace. */
+    readonly nodes: readonly SpanRunNode[];
+    readonly maxDepth: number;
+    readonly traceIds: readonly string[];
+    readonly spanCount: number;
+    readonly startMs: number | null;
+    readonly endMs: number | null;
+    /** LLM spans that recorded no token count at all — a gap, not a zero. */
+    readonly llmSpansWithoutTokens: number;
+    /** LLM spans that recorded no cost at all — a gap, not $0. */
+    readonly llmSpansWithoutCost: number;
+    /** Spans whose `parent_span_id` names a span not in the file. */
+    readonly orphanSpans: number;
+    /** Why the file could not be read, when it could not. */
+    readonly readError: string | null;
+}
+declare const EMPTY_SPAN_RUN_SNAPSHOT: Omit<SpanRunSnapshot, 'source'>;
+/**
+ * Fold a flat span batch into the node tree. Pure, so the same spans always
+ * render the same text — which is what lets the live tail print only on change.
+ */
+declare function buildSpanRunTree(spans: readonly OtlpSpan[], source: string): SpanRunSnapshot;
+/**
+ * Read one span file into a snapshot. Never throws: a tail that catches the
+ * writer mid-line, or an empty file the emitter has not filled yet, is a state
+ * to display, not a crash.
+ */
+declare function readSpanRunSnapshot(path: string): Promise<SpanRunSnapshot>;
+/**
+ * The two run-level halves of a span tree, each counted exactly once: the
+ * inference emitted by nodes that DELEGATED, and the inference emitted by the
+ * leaves they delegated to. Every LLM span lands in exactly one half, so the
+ * two add up to the run and neither hides inside the other.
+ */
+declare function spanRunTotals(snapshot: SpanRunSnapshot): {
+    driver: SpendRoll;
+    leaves: SpendRoll;
+};
+/** The rendered view for one span snapshot. Pure. */
+declare function renderSpanRunSnapshot(snapshot: SpanRunSnapshot): string;
+/**
+ * Span files at or immediately under `dir`. One level only, matching how the
+ * journal source resolves a run directory: a run is the unit a caller names.
+ */
+declare function findSpanSourceFiles(dir: string): Promise<string[]>;
+
+/**
+ * `traces watch <runDir>` — a live terminal view of a supervised run written by
+ * agent-runtime's `createFileRunContext`.
+ *
+ * Plain stdout, no dependency, no cursor control: it works over SSH, in a CI
+ * log, and through a pipe, and it prints a new block only when something
+ * changed, so a long idle stretch does not scroll away the last real event.
+ *
+ * The whole view model comes from `readRunContextSnapshot`; this file only
+ * formats. Two formatting rules carry the weight:
+ *
+ *  - **Driver inference and child work never merge.** A supervisor's own
+ *    thinking and the work it spawned are separate lines on the same node,
+ *    because a single total cannot answer "which half spent the budget" — the
+ *    decisive question in three real runs, where a root burned its pool on its
+ *    own turns while its one child cost almost nothing.
+ *  - **Unknown is never rendered as zero.** `Spend.usdKnown === false` means
+ *    the harness did not price that inference; it does not mean the inference
+ *    was free. Those records are counted and named, never summed into `$0.00`.
+ */
+
+/**
+ * The whole view for one snapshot. Pure: the same snapshot always renders the
+ * same text, which is what lets the tail print only on change.
+ */
+declare function renderRunContextSnapshot(snapshot: RunContextSnapshot): string;
+/**
+ * The two run-level halves, each counted exactly once.
+ *
+ * Driver total sums every node's OWN `metered` inference, at any depth. Worker
+ * total sums the settled spend of LEAF nodes only, because a nested
+ * supervisor's settlement re-homes its whole subtree up to its parent — adding
+ * it would count every grandchild twice, and the sub-total would silently
+ * exceed the pool the run actually spent.
+ */
+declare function runTotals(snapshot: RunContextSnapshot): {
+    driver: SpendRoll;
+    workers: SpendRoll;
+};
+/**
+ * Resolve what the user pointed at: the run directory itself, or a parent
+ * holding exactly one. A parent holding several is ambiguous and says so with
+ * the candidates, rather than picking one.
+ */
+declare function resolveRunContextDir(dir: string): Promise<string>;
+
+/**
+ * Formatting primitives shared by every `traces watch <target>` view.
+ *
+ * Two rules live here rather than in each renderer, because they are the whole
+ * reason this view exists and a second copy would eventually disagree with the
+ * first:
+ *
+ *  - **Unknown is never rendered as zero.** A roll with no priced record prints
+ *    "cost unknown", not `$0.0000`. An unmetered turn and a free turn are
+ *    different facts.
+ *  - **A recorded $0 that burned tokens is printed AND flagged.** The recorded
+ *    value stands; the ambiguity is named next to it.
+ *
+ * Plain ASCII-plus-box-drawing, no cursor control and no colour: the output has
+ * to survive SSH, a CI log, and a pipe into a file.
+ */
+
+declare const RULE: string;
+declare function int(n: number): string;
+declare function ms(value: number | null): string;
+/**
+ * A dollar figure that keeps unknown out of the number. With no priced record
+ * at all the answer is "cost unknown" — printing `$0.0000` there is the exact
+ * fabrication this view exists to prevent.
+ */
+declare function usd(roll: SpendRoll): string;
+/**
+ * A roll that claims a price of exactly $0 while recording real tokens.
+ *
+ * agent-runtime's contract is that `Spend.usdKnown` absent means the dollar
+ * figure IS known, so the honest number is $0 and this view prints it. But a
+ * harness-billed brain (a CLI on a subscription) also records $0 without ever
+ * setting `usdKnown:false`, and "free" and "unmetered" are the two facts this
+ * view exists to keep apart. So the value stands and the ambiguity is named —
+ * never the reverse.
+ */
+declare function zeroPricedCost(roll: SpendRoll): boolean;
+declare function tokens(roll: SpendRoll): string;
+declare const STATUS_MARK: Record<string, string>;
+/**
+ * Tree connectors for a depth-first node list. `lastAtDepth` records, per
+ * ancestor level, whether that ancestor was its parent's last child, which is
+ * what decides between a continuing `│` and a blank column — the difference
+ * between a readable tree and an ambiguous indent at depth 3+.
+ */
+declare function connectors(depth: number, lastAtDepth: readonly boolean[]): {
+    head: string;
+    detail: string;
+};
+/**
+ * Walk a depth-first node list, handing each node the `lastAtDepth` state its
+ * connectors need. A node is its parent's last child when no later node shares
+ * that parent, which the caller's list order already encodes.
+ */
+declare function forEachTreeNode<T extends {
+    readonly depth: number;
+}>(nodes: readonly T[], parentKey: (node: T) => string | null, selfKey: (node: T) => string, visit: (node: T, lastAtDepth: readonly boolean[]) => void): void;
+/** Wrap to a terminal width so a long question is readable, never truncated. */
+declare function wrap(text: string, indent: number): string[];
+
+/**
+ * `traces watch <target>` — the live terminal view, over whichever sources the
+ * target actually has.
+ *
+ * Two sources, one verb:
+ *
+ *  - **General** — `run-span-tree.ts`, over OTLP spans. `trace_id` /
+ *    `span_id` / `parent_span_id` reconstruct the tree for ANY emitter, so a
+ *    system nobody has written yet is watchable the day it emits its first
+ *    span. It cannot report an authored budget, because no span vocabulary
+ *    carries one.
+ *  - **Specific** — `supervisor-run-context.ts`, over agent-runtime's durable
+ *    spawn journal. It carries the exact budget, spend, and settlement the
+ *    telemetry does not.
+ *
+ * When a run has both, the output shows both and LABELS which number came from
+ * which: the journal section first, because its numbers are the authoritative
+ * ones, then the span section for the shape and the per-turn detail. They are
+ * never merged into one column, because a merged column cannot be audited —
+ * and the numbers legitimately differ (a driver's spans price each turn; the
+ * journal's `settled` re-homes a whole subtree onto its parent).
+ *
+ * Plain stdout, no dependency, no cursor control: it works over SSH, in a CI
+ * log, and through a pipe. A block prints only when the rendered view changed,
+ * so a long idle stretch never scrolls the last real event away.
+ */
+
+/** What a resolved target will be read from. At least one is always present. */
+interface RunWatchTarget {
+    /** The directory holding `spawn-journal.jsonl`, when there is one. */
+    readonly runDir: string | null;
+    /** OTLP span files to fold, in read order. */
+    readonly spanFiles: readonly string[];
+    /** What the caller named, verbatim — the thing to print in an error. */
+    readonly requested: string;
+}
+/**
+ * Resolve what the user pointed at.
+ *
+ * A file the caller named is read as spans, whatever it is called. A directory
+ * is the run directory when it holds a spawn journal, or the parent of exactly
+ * one — the same rule `resolveRunContextDir` already applies — and either way
+ * its span files come along. A directory with neither is an error naming both
+ * things it looked for, because "nothing here" and "wrong kind of thing here"
+ * are different mistakes.
+ */
+declare function resolveRunWatchTarget(target: string): Promise<RunWatchTarget>;
+interface RunWatchSnapshot {
+    readonly target: RunWatchTarget;
+    /** Present only when the target has a spawn journal. */
+    readonly journal: RunContextSnapshot | null;
+    readonly spans: readonly SpanRunSnapshot[];
+    /** True once every present source says the run is over. */
+    readonly terminal: boolean;
+}
+declare function readRunWatchSnapshot(target: RunWatchTarget): Promise<RunWatchSnapshot>;
+declare function renderRunWatchSnapshot(snapshot: RunWatchSnapshot): string;
+interface WatchRunTargetOptions {
+    /** Print one snapshot and return — what a script or an agent wants. */
+    readonly once?: boolean;
+    /** Poll period in ms (default 2000). */
+    readonly intervalMs?: number;
+    /** Where to write (default stdout). */
+    readonly write?: (text: string) => void;
+    readonly signal?: AbortSignal;
+    /** Keep tailing after the run reaches a terminal state (default: stop). */
+    readonly follow?: boolean;
+}
+/**
+ * Tail a target until every source says the run is over. Prints a block only
+ * when the rendered view changed, so the last thing on screen is always the
+ * last thing that happened.
+ */
+declare function watchRunTarget(target: RunWatchTarget, opts?: WatchRunTargetOptions): Promise<RunWatchSnapshot>;
+
 /**
  * Privacy redaction for trace spans before upload.
  *
@@ -2110,6 +3118,206 @@ interface SessionBatch {
 /** Select + parse (+ redact) sessions into per-session span batches. */
 declare function collectSessions(opts?: CollectOptions): Promise<SessionBatch[]>;
 
+/**
+ * Execution-replay verification for CodeTraceBench-style shell trajectories.
+ *
+ * Turns a cited analyst finding ("step k is the error-critical step") into an
+ * executed proof: replay steps 1..k-1 inside a real sandbox on the
+ * trajectory's own docker image, then
+ *   arm A — run the recorded step k and check the recorded failure signature
+ *           reproduces (returncode + a stable output substring), and
+ *   arm B — run a corrected step k and check the failure vanishes.
+ *
+ * Built on the agent-eval counterfactual scaffold: the trajectory is ingested
+ * into a TraceStore, each arm is a `runCounterfactual` meta-run, and the
+ * sandbox-backed `CounterfactualRunner` here supplies the `executeFrom`
+ * callback that scaffold deliberately leaves to consumers.
+ *
+ * Honest limits:
+ * - Only SWE-style trajectories carry `docker_config.base_image`; tasks whose
+ *   environment needs external compose peers cannot be replayed this way.
+ * - Copy-on-write forks (`box.branch()`) are firecracker-only; on the docker
+ *   driver each arm replays the prefix in its own fresh sandbox instead.
+ * - Prefix divergence (recorded vs replayed returncode) is recorded per step
+ *   and surfaced in the verdict, never hidden: a high divergence count is a
+ *   finding about replayability, not an error of the harness.
+ */
+
+/** Recorded returncode from a mini-SWE observation, or null when absent
+ *  (terminal submit steps carry no returncode tag). */
+declare function parseRecordedReturncode(observation: string | null): number | null;
+/** Text between the observation's <output> tags, or the raw observation when
+ *  the tags are absent. */
+declare function parseObservationOutput(observation: string | null): string;
+/**
+ * Stable failure-signature candidate: the first line of the recorded output
+ * that contains the word "error". Null when no such line exists — the verdict
+ * then falls back to returncode-only matching and says so.
+ * Pass an explicit signature to override (compiler quote glyphs vary with
+ * locale, so a hand-picked ASCII substring is often more robust).
+ */
+declare function deriveFailureSignature(observation: string | null): string | null;
+interface IngestedTrajectory {
+    runId: string;
+    stepCount: number;
+}
+/**
+ * Emit one tool span per trajectory step, in order, with a monotonic
+ * injected clock so `buildTrajectory` ordering is deterministic even when
+ * two spans would share a Date.now() millisecond.
+ */
+declare function ingestCodeTraceBenchSteps(store: TraceStore, steps: readonly CodeTraceBenchStep[], caseId: string): Promise<IngestedTrajectory>;
+interface ReplayExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+interface ReplayExecSession {
+    exec(command: string, timeoutMs: number): Promise<ReplayExecResult>;
+    close(): Promise<void>;
+}
+interface ReplayExecBackend {
+    open(): Promise<ReplayExecSession>;
+}
+interface SandboxReplayBackendOptions {
+    image: string;
+    apiKey: string;
+    baseUrl: string;
+    maxLifetimeSeconds?: number;
+    /**
+     * The local SDK-adapter test harness does not translate `agent: false`
+     * into the platform-control-runtime marker the way the production
+     * sandbox API does, so images without node need the marker passed as
+     * container env. Harmless against the production API path. Default true.
+     */
+    platformRuntimeEnvMarker?: boolean;
+}
+/** One fresh sandbox per open(); close() deletes it. */
+declare function sandboxReplayBackend(options: SandboxReplayBackendOptions): ReplayExecBackend;
+/**
+ * mini-SWE runs every action as a fresh /bin/sh subshell from a fixed
+ * workdir. Reproduce that exactly — and stay quote-proof for arbitrary
+ * recorded actions — by piping the base64 of the action into `sh` after
+ * cd-ing to the workdir. Exit code is sh's, i.e. the action's.
+ */
+declare function wrapActionForExec(action: string, cwd: string): string;
+interface PrefixDivergence {
+    step: number;
+    expectedReturncode: number | null;
+    actualExit: number;
+}
+interface PrefixReplayResult {
+    prefixExecuted: number;
+    prefixDivergences: PrefixDivergence[];
+    wallMs: number;
+}
+interface ArmExecutionResult {
+    command: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    wallMs: number;
+}
+interface SandboxCounterfactualRunnerOptions {
+    cwd: string;
+    stepTimeoutMs: number;
+    /** Execute at most this many prefix steps (from the start). Fast-iteration
+     *  knob; a truncated prefix weakens state fidelity and the verdict says so. */
+    prefixLimit?: number;
+    onProgress?: (message: string) => void;
+}
+/**
+ * Replays `ctx.prefix` in a fresh sandbox session, then executes the mutated
+ * step. Divergences are recorded and never abort the replay. Results land on
+ * `lastPrefix` / `lastArm` for the caller; spans for every exec land in the
+ * counterfactual meta-run.
+ */
+declare class SandboxCounterfactualRunner implements CounterfactualRunner {
+    private readonly backend;
+    private readonly options;
+    lastPrefix: PrefixReplayResult | null;
+    lastArm: ArmExecutionResult | null;
+    constructor(backend: ReplayExecBackend, options: SandboxCounterfactualRunnerOptions);
+    executeFrom(ctx: CounterfactualContext, emitter: TraceEmitter): Promise<void>;
+}
+interface ReplayVerifyOptions {
+    stepsPath: string;
+    image: string;
+    /** 1-based step_id of the error-critical step (matches CodeTraceBench). */
+    at: number;
+    /** Corrected command for arm B. Omit to run arm A only. */
+    fixCommand?: string;
+    cwd: string;
+    out: string;
+    caseId?: string;
+    /** Override the auto-derived failure signature substring. */
+    signature?: string;
+    stepTimeoutMs?: number;
+    prefixLimit?: number;
+    /** Label of the orchestrator driver backing the sandbox (reported, not probed). */
+    driverLabel?: string;
+    /** Injectable for tests; defaults to sandboxReplayBackend(). */
+    backend?: ReplayExecBackend;
+    apiKey?: string;
+    baseUrl?: string;
+    maxLifetimeSeconds?: number;
+    onProgress?: (message: string) => void;
+}
+interface ReplayArmVerdict {
+    command: string;
+    exitCode: number;
+    wallMs: number;
+    prefix: PrefixReplayResult;
+}
+interface ReplayVerdict {
+    case: string;
+    image: string;
+    driver: string;
+    k: number;
+    cwd: string;
+    recordedReturncode: number | null;
+    signature: string | null;
+    signatureBasis: 'returncode+output-substring' | 'returncode-only';
+    prefixExecuted: number;
+    prefixDivergences: PrefixDivergence[];
+    armA: ReplayArmVerdict & {
+        failureSignatureMatch: boolean;
+    };
+    armB: (ReplayArmVerdict & {
+        failureVanished: boolean;
+    }) | null;
+    timings: {
+        armAMs: number;
+        armBMs: number | null;
+        totalMs: number;
+    };
+    runIds: {
+        original: string;
+        armA: string;
+        armB: string | null;
+    };
+}
+declare function replayVerify(options: ReplayVerifyOptions): Promise<ReplayVerdict>;
+interface ReplayVerifyCliArgs {
+    stepsPath: string;
+    image: string;
+    at: number;
+    fixCommand?: string;
+    cwd: string;
+    out: string;
+    caseId?: string;
+    signature?: string;
+    stepTimeoutMs?: number;
+    prefixLimit?: number;
+    driverLabel?: string;
+    baseUrl: string;
+    apiKeyEnv: string;
+    maxLifetimeSeconds?: number;
+}
+declare function parseReplayVerifyArgs(argv: readonly string[]): ReplayVerifyCliArgs | 'help';
+declare function replayVerifyUsage(): string;
+declare function cmdReplayVerify(argv: readonly string[]): Promise<void>;
+
 /**
  * Local upload-dedup state.
  *
@@ -2212,4 +3420,4 @@ interface ExecuteOptions {
 /** Send the final, new outbound items (or write their dry-run OTLP). */
 declare function executeUpload(plan: UploadPlan, opts?: ExecuteOptions): Promise<UploadResult>;
 
-export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, CORRECTIVE_REACTIONS, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, type CodeTraceBenchFileRef, type CodeTraceBenchImportOptions, type CodeTraceBenchImportReceipt, type CodeTraceBenchImportResult, type CodeTraceBenchImportedTrace, type CodeTraceBenchStep, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, CopilotAdapter, type CorruptionMode, DEFAULT_HARNESS, EmptySessionError, type ExecuteOptions, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, type InspectSessionIndexOptions, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, type ParentTaskResolution, type ParseOptions, PartialUploadError, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, QwenAdapter, REACTIONS, type Reaction, type ReactionReport, type ReactionSessionReport, type Redactor, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionCorruptionReceipt, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionWorkflow, SessionWorkflowError, type SessionWorkflowErrorCode, type SessionWorkflowIssue, type SessionWorkflowSession, type SessionWorkflowSummary, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceAgenticRoute, type TraceAgenticRouteReason, type TraceAgenticRouteReasonCode, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeLiveBatch, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, cwdMatchesSelection, defaultTraceLiveAnalysts, describeSessionRelationship, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, hodoscopeAnalyzer, importCodeTraceBench, indexSessionIdsByTrace, inspectSessionIndex, isChatTrajectory, isChatTrajectoryMessage, knownHarnesses, listAdapters, loadState, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeTracesConfig, normalizeRemote, outboundHash, parseIsoToEpochMs, parseSession, parseSince, planTraceAgenticRoute, planUpload, readJsonFile, readJsonl, readSessionIndexFile, recordSessionCorruption, redactSpans, renderInspectionReport, resolveAdapter, resolveRepoAttrs, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTraceImprovement, runTraceInvestigation, runTraceStoreInvestigation, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, span, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, totalAgenticFailureMessage, traceAgenticKinds, traceStreamEventsFromSpans, uploadKey, userPromptSpan, validateOtlpSpans, watchSessions, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts };
+export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type ArmExecutionResult, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, type CodeTraceBenchFileRef, type CodeTraceBenchImportOptions, type CodeTraceBenchImportReceipt, type CodeTraceBenchImportResult, type CodeTraceBenchImportedTrace, type CodeTraceBenchStep, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, type ConformanceRenderOptions, type CoordinationLog, type CoordinationQuestion, type CoordinationSteer, CopilotAdapter, type CorruptionMode, DEFAULT_HARNESS, EMPTY_SPAN_RUN_SNAPSHOT, EXPORT_RULE, EmptySessionError, type ExecuteOptions, type ExportRule, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FactoryAdapter, type FileRunContextReaderOptions, ForgeAdapter, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, type IngestedTrajectory, type InspectSessionIndexOptions, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type LoopConvergence, type LoopConvergenceReport, type LoopIteration, type LoopTrend, type LoopTrendBasis, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpIngestIssue, type OtlpIngestIssueKind, type OtlpInput, type OtlpInputFile, type OtlpRowConversion, type OtlpSpan, type OtlpSpanKind, type OtlpSpanLink, type OtlpStatusCode, type ParentTaskResolution, type ParseOptions, PartialUploadError, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, type PrefixDivergence, type PrefixReplayResult, QwenAdapter, REACTIONS, RESULT_FILE, RULE, type Reaction, type ReactionReport, type ReactionSessionReport, type Redactor, type ReplayArmVerdict, type ReplayExecBackend, type ReplayExecResult, type ReplayExecSession, type ReplayVerdict, type ReplayVerifyCliArgs, type ReplayVerifyOptions, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedOtlpInput, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunResult, type RunWatchSnapshot, type RunWatchTarget, type RuntimeTrace, SPAWN_JOURNAL_FILE, STATUS_MARK, SandboxCounterfactualRunner, type SandboxCounterfactualRunnerOptions, type SandboxReplayBackendOptions, type ScanOptions, type ScannedSession, type SessionBatch, type SessionCorruptionReceipt, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionWorkflow, SessionWorkflowError, type SessionWorkflowErrorCode, type SessionWorkflowIssue, type SessionWorkflowSession, type SessionWorkflowSummary, type SkippedAnalysis, type SkippedInputFile, type SpanInput, type SpanNodeStatus, type SpanRedaction, type SpanRunNode, type SpanRunSnapshot, type SpanStructure, type SpendRoll, type SteeringChainReport, type SteeringEdge, TRACES_REDACTION_RULES, type TraceAgenticRoute, type TraceAgenticRouteReason, type TraceAgenticRouteReasonCode, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type UnavailableCapabilities, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, type WatchRunTargetOptions, ZERO_ROLL, addSpend, alreadyUploaded, analyzeAdoption, analyzeLiveBatch, analyzeLoopConvergence, analyzeReactions, analyzeSpans, analyzeSteeringChain, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyLiveActions, classifyReaction, claudeActor, cmdReplayVerify, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, conformanceOfSpans, connectors, countSkillRunsJsonl, cwdMatchesSelection, defaultTraceLiveAnalysts, deriveFailureSignature, describeSessionRelationship, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, fileRunContextSupervisorRunReader, findSpanSourceFiles, forEachTreeNode, haloAnalyzer, hodoscopeAnalyzer, importCodeTraceBench, incompleteInputsNote, indexSessionIdsByTrace, inferRole, inferSpanKind, ingestCodeTraceBenchSteps, inspectSessionIndex, int, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, knownHarnesses, listAdapters, loadState, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeRemote, otlpRowToSpan, outboundHash, parseIsoToEpochMs, parseObservationOutput, parseRecordedReturncode, parseReplayVerifyArgs, parseSession, parseSince, planTraceAgenticRoute, planUpload, readCoordinationLog, readFileRunContext, readJsonFile, readJsonl, readOtlpInput, readRunContextJournal, readRunContextSnapshot, readRunWatchSnapshot, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderConformance, renderInspectionReport, renderRunContextSnapshot, renderRunWatchSnapshot, renderSpanRunSnapshot, renderValidation, replayVerify, replayVerifyUsage, resolveAdapter, resolveOtlpInputFiles, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTotals, runTraceImprovement, runTraceInvestigation, runTraceStoreInvestigation, sandboxReplayBackend, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, skippedAnalyses, span, spanRunTotals, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, summarizeSpanStructure, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, tokens, totalAgenticFailureMessage, traceAgenticKinds, traceStreamEventsFromSpans, unavailableCapabilities, uploadKey, usd, userPromptSpan, validateOtlpSpans, validationExitCode, watchRunTarget, watchSessions, wrap, wrapActionForExec, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, zeroPricedCost };