@tangle-network/traces 0.11.6 → 0.15.0

package/dist/index.d.ts

@@ -1,17 +1,29 @@
 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 { SpanSourceReader, 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 { ToolUseMetrics, InMemoryTraceStore, CostProvenance, 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';
+import { TraceAnalystDefinition, TraceAnalysisEngine, AnalystRegistry, AnalystFinding, buildDefaultAnalystRegistry, AnalystRunSummary, AnalystRunResult, Analyst, RawAnalystFinding, AnalystUsageReceipt, TraceAnalystLimits } 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';
 
+declare const SOURCE_ATTRIBUTE_PREFIX = "traces.source_record.";
+/** Location of original bytes, never a copy of their content. */
+interface SourceRecordReference {
+    sourceId: string;
+    sourceSha256?: string;
+    recordOffset: number;
+    recordBytes: number;
+    recordSha256: string;
+    fieldLocator: string;
+}
+type SourceReferences = SourceRecordReference | readonly SourceRecordReference[] | undefined;
+
 /**
  * The INBOUND path: read OTLP-JSONL that some other system emitted and hand it
  * to the same analysis pipeline the adapters feed.
@@ -263,6 +275,7 @@ interface OtlpSpan {
     links?: OtlpSpanLink[];
 }
 interface SpanInput {
+    contentSource?: SourceReferences;
     traceId: string;
     spanId: string;
     parentSpanId?: string | null;
@@ -361,13 +374,15 @@ interface JsonlCorruptionReceipt {
     rawBytes: 'local_source_only';
 }
 type JsonlReadOptions = {
+    captureSources?: boolean;
+} & ({
     mode?: 'strict';
     signal?: AbortSignal;
 } | {
     mode: 'recover';
     onCorruption: (receipt: JsonlCorruptionReceipt) => void;
     signal?: AbortSignal;
-};
+});
 declare class JsonlParseError extends SyntaxError {
     readonly sourcePath: string;
     readonly lineNumber: number;
@@ -395,6 +410,8 @@ declare function takeJsonl<T>(path: string, limit: number, options?: JsonlReadOp
 
 type CorruptionMode = 'recover' | 'strict';
 interface ParseOptions {
+    /** Attach source locations for a caller that will retain the original files. */
+    captureSources?: boolean;
     /** Recover valid JSONL records by default; strict rejects the first corruption. */
     corruptionMode?: CorruptionMode;
     /** For resumed session formats, parse all turns, the latest turn, or one exact turn. */
@@ -480,6 +497,24 @@ interface HarnessTraceAdapter {
      * Adapters must not infer this from names or timestamps.
      */
     resolveParentTask?(ref: SessionRef, childSessionId: string, options?: Pick<ParseOptions, 'corruptionMode' | 'signal'>): Promise<ParentTaskResolution>;
+    /**
+     * Resolve the child sessions a parent spawned when the harness recorded no child session ID.
+     *
+     * Some harness builds name a spawned child only by the task path the parent asked for
+     * (codex `exec` 0.148-0.152 returns `{"task_name": "/root/c1_b_grid"}` and emits no
+     * `sub_agent_activity` stream). The same path is stamped in the child's own session metadata
+     * alongside its parent's ID, so the pair (parent session ID, agent path) is an exact key.
+     * Adapters must match that pair exactly and must not infer a child from names or timestamps.
+     */
+    locateSpawnedChildren?(parentSessionId: string, agentPaths: readonly string[], options?: LocateOptions & Pick<ParseOptions, 'corruptionMode' | 'signal'>): Promise<readonly SpawnedChildResolution[]>;
+}
+/** One `agent path -> child session` answer. `ref` is absent when the pair matched no file. */
+interface SpawnedChildResolution {
+    readonly agentPath: string;
+    readonly ref?: SessionRef;
+    readonly reason?: 'not-found' | 'ambiguous';
+    /** Session IDs that matched the pair when more than one did. */
+    readonly candidates?: readonly string[];
 }
 
 /**
@@ -665,11 +700,13 @@ interface LoopConvergenceReport {
 /** 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 causeTraceId: string;
     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 effectTraceId: string;
     readonly effectSpanId: string;
     readonly effectName: string;
     readonly effectIteration: number | null;
@@ -916,7 +953,9 @@ declare class JsonSourceError extends Error {
     readonly code?: string;
     constructor(sourcePath: string, kind: JsonSourceErrorKind, cause: unknown);
 }
-declare function readJsonFile<T>(path: string): Promise<T>;
+declare function readJsonFile<T>(path: string, options?: {
+    captureSources?: boolean;
+}): Promise<T>;
 
 declare function recordSessionCorruption(ref: SessionRef, receipt: JsonlCorruptionReceipt): void;
 declare function sessionIntegrityAttributes(ref: SessionRef): Record<string, string | number>;
@@ -995,6 +1034,12 @@ interface ScannedSession {
  *  propagate unless an explicit `onError` callback handles them. */
 declare function scanSessions(opts: ScanOptions): AsyncGenerator<ScannedSession>;
 
+/** Grant only the original records associated with unchanged attributes in these selected spans. */
+declare function createBundleSourceReader(directory: string, spans: readonly OtlpSpan[], options?: {
+    signal?: AbortSignal;
+    maxRecordBytes?: number;
+}): Promise<SpanSourceReader | undefined>;
+
 type SessionRole = 'operator' | 'child' | 'unknown';
 interface SessionRelationship {
     readonly sessionId: string;
@@ -1005,6 +1050,15 @@ interface SessionRelationship {
     readonly spawnedChildSessionIds: readonly string[];
     /** Existing child sessions resumed or steered in this task. */
     readonly resumedChildSessionIds: readonly string[];
+    /**
+     * Agent paths this session spawned that carry NO child session ID.
+     *
+     * A codex `exec` build returns `{"task_name": "/root/c1_b_grid"}` from `spawn_agent` and emits
+     * no `sub_agent_activity` stream, so both id-bearing keys are absent. The child exists, ran,
+     * and spent tokens; only the ID is missing. These paths are the join key of last resort, and
+     * a path still on this list after expansion is a child that was NOT joined.
+     */
+    readonly unjoinedSpawnPaths: readonly string[];
     readonly depth?: number;
     readonly agentNickname?: string;
     readonly agentRole?: string;
@@ -1040,6 +1094,20 @@ type SessionWorkflowIssue = {
 } | {
     readonly kind: 'cycle';
     readonly sessionIds: readonly string[];
+} | {
+    /**
+     * A child the parent demonstrably spawned that no session file could be joined to.
+     *
+     * This exists so a silent miss can never read as clean. `--workflow` used to report
+     * `0 relationship issues` for a codex parent with three `spawn_agent` calls and three child
+     * rollouts in the same directory, because the harness recorded no child session ID and the
+     * expansion therefore had nothing to look for. An unjoinable child is now a stated issue.
+     */
+    readonly kind: 'unjoined-child';
+    readonly parentSessionId: string;
+    readonly agentPath: string;
+    readonly reason: 'not-found' | 'ambiguous' | 'unsupported';
+    readonly candidates?: readonly string[];
 } | {
     readonly kind: 'unresolved-parent-task';
     readonly parentSessionId: string;
@@ -1101,6 +1169,7 @@ interface CollectSessionSelectionOptions {
     readonly bindSources?: boolean;
     readonly signal?: AbortSignal;
 }
+declare function fileSha256(path: string, signal?: AbortSignal): Promise<string>;
 /** Parse selected seed groups, optionally expanding and byte-binding their session tree. */
 declare function collectSessionSelection(groups: readonly SessionSeedGroup[], options?: CollectSessionSelectionOptions): Promise<SessionSelection>;
 
@@ -1121,8 +1190,19 @@ interface RepoResolution {
  * `git@host:owner/repo.git` SCP-style forms. Returns null when unparseable.
  */
 declare function normalizeRemote(url: string): string | null;
-/** Expand a selected cwd to every checked-out worktree for the same git repo. */
+/**
+ * Expand a selected cwd to every checked-out worktree for the same git repo.
+ * Each candidate is emitted in both its selected and its resolved form: git
+ * prints symlink-resolved paths (macOS `/var` → `/private/var`), while a
+ * recorded session cwd usually keeps the unresolved spelling, and a match
+ * must not depend on which spelling either side used.
+ */
 declare function equivalentGitCwds(cwd: string | null | undefined): Promise<string[]>;
+/**
+ * `cwdMatchesSelection`, then a second attempt with the cwd's resolved
+ * (symlink-free) form. A deleted cwd cannot resolve and keeps the raw verdict.
+ */
+declare function cwdMatchesSelectionResolved(cwd: string | null | undefined, selections: readonly string[]): Promise<boolean>;
 /** Boundary-aware cwd matching; `/repo` matches `/repo/src`, not `/repo-old`. */
 declare function cwdMatchesSelection(cwd: string | null | undefined, selections: readonly string[]): boolean;
 /**
@@ -1197,6 +1277,13 @@ declare class CodexAdapter implements HarnessTraceAdapter {
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
     locateBySessionId(sessionId: string, opts?: LocateOptions): Promise<SessionRef[]>;
     resolveParentTask(ref: SessionRef, childSessionId: string, options?: Pick<ParseOptions, 'corruptionMode'>): Promise<ParentTaskResolution>;
+    /**
+     * Join a parent's `spawn_agent` calls to the child rollouts they produced, by the exact pair
+     * (parent thread ID, agent path). Only the head of each candidate file is read.
+     */
+    locateSpawnedChildren(parentSessionId: string, agentPaths: readonly string[], opts?: LocateOptions & Pick<ParseOptions, 'corruptionMode' | 'signal'>): Promise<readonly SpawnedChildResolution[]>;
+    /** The parent thread ID and agent path a child rollout stamps in its own session metadata. */
+    private readSpawnIdentity;
     parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
@@ -1235,7 +1322,8 @@ declare class OpencodeAdapter implements HarnessTraceAdapter {
     readonly harness = "opencode";
     private storage;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    sourcePaths(ref: SessionRef): Promise<readonly string[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
 /**
@@ -1270,7 +1358,7 @@ declare class GeminiFamilyAdapter implements HarnessTraceAdapter {
      *  digests and stay null.) Loaded once per locate(). */
     private loadProjectCwds;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 declare class GeminiAdapter extends GeminiFamilyAdapter {
     constructor();
@@ -1316,6 +1404,7 @@ declare class FactoryAdapter implements HarnessTraceAdapter {
     readonly aliases: readonly ["factory-droids", "droid"];
     private root;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    sourcePaths(ref: SessionRef): Promise<readonly string[]>;
     parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
@@ -1361,7 +1450,7 @@ declare class AmpAdapter implements HarnessTraceAdapter {
     readonly harness = "amp";
     private threadsRoot;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
 /**
@@ -1407,7 +1496,7 @@ declare class ForgeAdapter implements HarnessTraceAdapter {
     /** Directories scanned for `*-dump.json` exports. */
     private dumpDirs;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
 /**
@@ -1441,6 +1530,7 @@ type Actor = 'human' | 'agent' | 'subagent-spawn' | 'injected' | 'tool-result';
  *  `tangle.sessionId`/`tangle.ingest_source` wire contract. */
 declare const ACTOR_ATTR = "tangle.actor";
 interface UserPromptInput {
+    contentSource?: SourceReferences;
     traceId: string;
     spanId: string;
     parentSpanId: string | null;
@@ -1500,13 +1590,19 @@ declare function claudeActor(args: {
     isFirstUserTurn?: boolean;
 }): Actor;
 /**
- * Derive the actor for a Codex user message. Codex has no sidechain/userType,
- * so it's text-only: synthetic markers → injected, first-turn agent-spawn
- * brief → injected, otherwise human.
+ * Derive the actor for a Codex user message.
+ *
+ * `kinds` is Codex's own per-item labelling and decides whenever the record
+ * carries it. Without it the decision is text-only: a Codex context block →
+ * injected, synthetic markers → injected, first-turn agent-spawn brief →
+ * injected, otherwise human. `blocks` are the message's separate text blocks;
+ * Codex treats the whole message as context when any one block is.
  */
 declare function codexActor(args: {
     text: string;
+    blocks?: readonly string[];
     isFirstUserTurn?: boolean;
+    kinds?: readonly unknown[];
 }): Actor;
 type Reaction = 'correction' | 'frustration' | 'praise' | 'jargon' | 'structure';
 /** Label a human turn with every reaction signal it matches. Mirrors
@@ -1516,6 +1612,100 @@ declare function classifyReaction(text: string): Reaction[];
  *  corrective-to-positive ratio). `praise` is the positive denominator. */
 declare const CORRECTIVE_REACTIONS: readonly Reaction[];
 
+/**
+ * Provenance markers for spans an adapter did NOT take from an action the agent
+ * performed inside the parsed scope.
+ *
+ * Three cases, and all of them used to be invisible:
+ *
+ *   - SYNTHESIZED — the adapter built the span from harness lifecycle events,
+ *     not from a call the model issued. A Codex subagent's start/finish stream
+ *     is one span per child thread; recording it as a TOOL call named
+ *     `tool.Agent` made every tool-call count high by exactly the number of
+ *     child threads, and nothing on the span let a counter tell the difference.
+ *   - INHERITED — the record belongs to context this session carries but did
+ *     not produce: the prefix a fork copies from its parent, and the history a
+ *     `compacted` record retains. Keeping the human's words is the point;
+ *     counting them as turns of THIS scope is not.
+ *   - SUBAGENT — the record came from a child agent's OWN transcript, folded
+ *     into the parent's trace by an adapter that reads the whole session tree.
+ *     Claude Code writes one file per spawned agent under the session
+ *     directory and the adapter parses all of them into one trace, so the
+ *     parent's TOOL spans and the children's sat in the same trace with
+ *     nothing to tell them apart: one measured session showed 2,675 tool spans
+ *     where the session's own agent made 332. The subagent did that work; the
+ *     parent did not, and a fact about the parent must not claim it.
+ *
+ * All three markers are additive attributes. A count that means "what the agent
+ * did in this scope" filters them out; a reader that wants the context selects
+ * them. They are harness-neutral on purpose: the sheet that reads them must not
+ * carry a rule per harness.
+ */
+/** `true` on a span the adapter synthesized from lifecycle events. */
+declare const SYNTHESIZED_SPAN_ATTR = "traces.span.synthesized";
+/** What the synthesized span was built from, e.g. `codex.sub_agent_activity`. */
+declare const SYNTHESIZED_SOURCE_ATTR = "traces.span.synthesized_from";
+/** `true` on a span carrying context from outside the parsed scope. */
+declare const INHERITED_SPAN_ATTR = "traces.session.inherited";
+/** Where the inherited record came from: `pre-task-prefix` or `compacted`. */
+declare const INHERITED_SOURCE_ATTR = "traces.session.inherited_source";
+type InheritedSpanSource = 'pre-task-prefix' | 'compacted';
+/** Count of inherited spans in the batch, stamped on the root span. */
+declare const INHERITED_SPAN_COUNT_ATTR = "traces.session.inherited_span_count";
+/** Inherited records the adapter's per-session cap dropped, stamped on the root. */
+declare const INHERITED_SPANS_OMITTED_ATTR = "traces.session.inherited_spans_omitted";
+declare function isSynthesizedSpan(attributes: Readonly<Record<string, unknown>>): boolean;
+declare function isInheritedSpan(attributes: Readonly<Record<string, unknown>>): boolean;
+
+/**
+ * Failure follow-up classification — the retry-with-state marker.
+ *
+ * The tool-use line has long counted "failed calls followed by another
+ * same-tool call", but that count cannot separate a blind retry (the same
+ * arguments re-sent after a failure, so the failure produced no new state)
+ * from an adapted one (the arguments changed, so the failure taught the agent
+ * something). Without the split the number reads as pure waste even in a run
+ * where every retry adapted — or as healthy adaptation in a run that re-sent
+ * the same command 300 times.
+ *
+ * Arguments are compared by the full-input hash (`traces.input.sha256`) when
+ * both sides carry it, because it survives `input.value` truncation, and by
+ * the verbatim `input.value` otherwise. A pair whose arguments cannot be
+ * compared is counted as unknown, never guessed. Calls marked
+ * `traces.expected_blocking` are excluded: re-sending an identical poll after
+ * a not-ready failure is the protocol working, not thrash.
+ */
+
+type FollowUpKind = 'blind' | 'adapted' | 'args-unknown' | 'none';
+interface FailureFollowUp {
+    traceId: string;
+    toolName: string;
+    failedSpanId: string;
+    /** Null when the tool was never called again after the failure. */
+    followUpSpanId: string | null;
+    kind: FollowUpKind;
+    /** Captured follow-up outcome; null when absent or unknown. */
+    followUpSucceeded: boolean | null;
+}
+interface FailureFollowUpReport {
+    /** Failed TOOL calls classified; expected-blocking failures are excluded. */
+    failures: number;
+    /** Failures with a later call of the same tool in the same trace. */
+    followed: number;
+    /** Follow-up re-sent identical arguments. */
+    blind: number;
+    /** Follow-up changed the arguments. */
+    adapted: number;
+    /** Arguments were not captured or not comparable on one side of the pair. */
+    argsUnknown: number;
+    /** Follow-ups with explicit success, out of `followed`. */
+    followUpSucceeded: number;
+    /** Blind-retry count per tool, largest offender first when rendered. */
+    blindByTool: Record<string, number>;
+    items: FailureFollowUp[];
+}
+declare function classifyFailureFollowUps(spans: readonly OtlpSpan[]): FailureFollowUpReport;
+
 /**
  * Run agent-eval's shipped trace pipelines over normalized harness spans.
  *
@@ -1524,6 +1714,10 @@ declare const CORRECTIVE_REACTIONS: readonly Reaction[];
  *   - stuckLoopView         — same tool + same args ≥ N times in a short interval
  *   - computeToolUseMetrics — duplicate-call / retry / error rates per run
  *
+ * One local view runs beside them: `classifyFailureFollowUps` splits each
+ * failed call's same-tool follow-up into blind (identical args) vs adapted
+ * (changed args), which the aggregate retry rate cannot express.
+ *
  * `toolWasteView` is intentionally NOT used: its default heuristic needs
  * verbatim tool *results* + per-turn LLM `messages`, which traces
  * doesn't capture from harness logs (we store tool args + error status). Its
@@ -1540,6 +1734,8 @@ interface PipelineReport {
     stuckLoops: StuckLoopReport;
     failureClusters: FailureClusterReport;
     toolUse: ToolUseMetrics[];
+    /** Absent only on hand-built reports; runPipelines always computes it. */
+    failureFollowUps?: FailureFollowUpReport;
 }
 interface PipelineOptions {
     /** Minimum repeated identical calls to flag a loop (default 3). */
@@ -1726,6 +1922,11 @@ declare function toRuntimeStore(spans: readonly OtlpSpan[]): Promise<RuntimeTrac
  */
 
 interface AnalyzeOptions {
+    /** Explicitly authorize original source reads from this full session bundle. */
+    sourceBundle?: {
+        path: string;
+        maxRecordBytes?: number;
+    };
     /**
      * Recursive analysis engine enabling the agentic analyst kinds. Omit →
      * deterministic only. The engine's id, version, and model become the
@@ -1747,6 +1948,16 @@ interface AnalyzeOptions {
     agenticRegistry?: AnalystRegistry;
     /** Select a subset of agent-eval's maintained trace analyst kinds. */
     agenticKinds?: readonly TraceAnalystDefinition[];
+    /**
+     * Supply the deterministic session-facts sheet to the agentic kinds as
+     * prepared context (default true). It costs nothing and removes the guessing
+     * the bounded trace tools force on a model that needs an exact count. Set
+     * false to measure an analyst without it.
+     *
+     * It applies only to definitions this call builds a registry from; a caller
+     * who brings `agenticRegistry` owns its own prepared context.
+     */
+    sessionFactsContext?: boolean;
     /** Compact deterministic findings that agents receive before reading spans. */
     agenticPriorFindings?: readonly AnalystFinding[];
     /** Where to write the OTLP-JSONL artifact. Defaults to a temp file. */
@@ -1770,6 +1981,56 @@ interface AnalyzeResult {
 }
 declare function analyzeSpans(spans: readonly OtlpSpan[], opts?: AnalyzeOptions): Promise<AnalyzeResult>;
 
+/**
+ * Citation normalization for model-backed trace analysts.
+ *
+ * agent-eval's evidence gate accepts a finding only when every citation
+ * resolves to a stored span and every excerpt is an exact substring of that
+ * span's decoded content. Two artifacts of how `traces` exports spans make the
+ * engine's own honest citations fail that check:
+ *
+ *   - `searchTrace` returns raw OTLP-JSONL text, so an excerpt copied from a hit
+ *     carries JSON escapes (`\"`, `\n`) that the decoded attribute does not.
+ *   - Adapters rewrite readable harness IDs (`tool:<call_id>`, a session UUID)
+ *     to fixed-width hex OTLP IDs and keep the readable form only in
+ *     `traces.<harness>.source_trace_id` / `source_span_id` attributes, so a
+ *     citation of the readable ID names no stored span.
+ *
+ * A third rejection is a subject from another kind's vocabulary (for example a
+ * `tool-doc:` locus on the cluster-only failure-mode kind). The subject is an
+ * optional label, and the finding schema tells the model to omit it rather
+ * than guess, so a subject the kind cannot hold is removed.
+ *
+ * Protected invariant: normalization never lets absent evidence pass. A
+ * citation is rewritten only to a form proven present in the span it cites: a
+ * readable ID must name exactly one span, and a decoded excerpt must be a
+ * substring of that span's own attributes or status message. Anything else is
+ * left untouched, and agent-eval's gate re-checks every rewritten row
+ * unchanged. Normalization never adds a citation, so it cannot satisfy a
+ * kind's minimum citation count on its own.
+ *
+ * Temporary: the agent-eval gate issue (agent-eval#TBD) makes this module
+ * unnecessary. Delete it when traces adopts a release whose gate accepts
+ * JSON-escaped excerpts, resolves the readable source-ID aliases above, and
+ * treats an out-of-kind optional subject as omitted.
+ */
+
+/**
+ * Appended to each wrapped definition's version. agent-eval records a
+ * `postProcess` hook as `version-bound`, so the version names this behavior.
+ * Bump it whenever the normalization rules change.
+ */
+declare const CITATION_NORMALIZATION_VERSION = "traces-citations-1";
+/**
+ * Wrap trace-analyst definitions so each submitted finding is normalized
+ * against `spans` before agent-eval's evidence gate runs.
+ *
+ * Pass the same spans the analysts' trace store was written from. A
+ * definition's own `postProcess` runs after normalization and keeps the final
+ * say over the row.
+ */
+declare function normalizeAnalystCitations(definitions: readonly TraceAnalystDefinition[], spans: readonly OtlpSpan[]): TraceAnalystDefinition[];
+
 interface TraceExecutionOptions {
     readonly experimentId?: string;
     readonly candidateId?: string;
@@ -1993,6 +2254,8 @@ declare function writeSessionIndexFile(index: TraceSessionIndex, outPath?: strin
  */
 
 interface SessionBundleFile {
+    /** Opaque source identity when this file backs native span attributes. */
+    readonly sourceId?: string;
     /** Bundle-relative path, `/`-separated. */
     readonly path: string;
     readonly bytes: number;
@@ -2467,6 +2730,13 @@ declare function runExternalAnalyzers(otlpPath: string, analyzers: readonly Exte
     signal?: AbortSignal;
     spans?: readonly OtlpSpan[];
 }): Promise<ExternalAnalysisResult[]>;
+/**
+ * Operator-facing message naming every external analyzer that failed, or
+ * undefined when all succeeded. A caller that requested an engine should
+ * treat its failure as a failed run: the report still carries the error, but
+ * exit 0 would read as "the engine ran and found nothing".
+ */
+declare function externalFailureMessage(results: readonly ExternalAnalysisResult[]): string | undefined;
 /** An external PII/secret scrubber for free-form text — catches what regex
  *  can't (names, addresses). Use to harden upload beyond the built-in rules. */
 interface Redactor {
@@ -2484,6 +2754,57 @@ declare function commandRedactor(spec: {
     timeoutMs?: number;
 }): Redactor;
 
+/**
+ * Evidence-gate rejections, counted per analyst and reason.
+ *
+ * agent-eval's trace analysts drop a submitted finding when its citations do
+ * not resolve, and report each drop only as a `finding rejected: ...` log
+ * event. A report that shows "0 findings" without those events reads as "the
+ * model found nothing" when the truth may be "the gate refused everything it
+ * found". This module turns the log events into counts a report can print.
+ */
+/** Rejection counts by reason, for one analyst or question. */
+type FindingRejectionReasons = Readonly<Record<string, number>>;
+/** Rejection counts keyed by analyst ID, then by reason. */
+type FindingRejectionCounts = Readonly<Record<string, FindingRejectionReasons>>;
+/**
+ * The analyst and reason behind one `finding rejected:` log event, or
+ * undefined for any other event. The registry prefixes each analyst's log
+ * message with `[<analyst-id>] `; a direct `runTraceAnalyst` caller does not,
+ * so the analyst ID is optional here.
+ */
+declare function findingRejection(message: string, fields?: Readonly<Record<string, unknown>>): {
+    analystId?: string;
+    reason: string;
+} | undefined;
+/**
+ * What a rejection log event carries beyond its own message: the cause, the
+ * offending URI, the citation counts, the subject. Empty when the message
+ * already says everything known — the kind is in the message, so repeating it
+ * would print "finding rejected: schema failure — schema failure". Undefined
+ * for an event that is not a rejection at all.
+ */
+declare function findingRejectionDetail(message: string, fields?: Readonly<Record<string, unknown>>): string | undefined;
+interface FindingRejectionTally {
+    /** Record one log event; events that are not rejections are ignored. */
+    record(message: string, fields?: Readonly<Record<string, unknown>>): void;
+    /** A snapshot of the counts so far. */
+    counts(): FindingRejectionCounts;
+}
+/**
+ * Count rejections from a log stream. `defaultAnalystId` names the analyst
+ * for unprefixed events, as when one tally observes one question.
+ */
+declare function createFindingRejectionTally(defaultAnalystId?: string): FindingRejectionTally;
+/** Total rejections across every reason. */
+declare function totalFindingRejections(reasons: FindingRejectionReasons | undefined): number;
+/**
+ * "2 finding(s) rejected: excerpt is not present in the cited span content ×2".
+ * Empty when nothing was rejected. Reasons are ordered by count, then name, so
+ * the same counts always render the same text.
+ */
+declare function formatFindingRejections(reasons: FindingRejectionReasons | undefined): string;
+
 type TraceLiveSeverity = 'info' | 'low' | 'medium' | 'high';
 interface TraceLiveEvidence {
     readonly kind: 'metric' | 'span' | 'pattern';
@@ -2683,6 +3004,8 @@ interface TracesConfig {
     readonly externalAnalyzers?: readonly ExternalAnalyzer[];
 }
 interface TraceInvestigationOptions {
+    /** Explicit full-bundle source access for local analyst tools only. */
+    readonly sourceBundle?: AnalyzeOptions['sourceBundle'];
     readonly spans: readonly OtlpSpan[];
     readonly harness: string;
     readonly sources?: readonly ReportSource[];
@@ -2774,6 +3097,12 @@ interface TraceInvestigationResult {
      * findings as if the requested LLM analysis had happened.
      */
     readonly agenticPerAnalyst?: readonly AnalystRunSummary[];
+    /**
+     * Findings the evidence gate refused, by analyst ID and reason. Present
+     * whenever an agentic pass ran, empty when nothing was refused, so a zero
+     * finding count can be told apart from "every finding was rejected".
+     */
+    readonly findingRejections?: FindingRejectionCounts;
     readonly external: readonly ExternalAnalysisResult[];
     readonly report: string;
 }
@@ -2817,6 +3146,8 @@ declare function buildTraceFindingPacket(opts: BuildTraceFindingPacketOptions):
 declare function loadTracesConfig(path?: string): Promise<TracesConfig | undefined>;
 declare function mergeTracesConfig(opts: TraceInvestigationOptions, config?: TracesConfig): TraceInvestigationOptions;
 declare function runTraceInvestigation(opts: TraceInvestigationOptions): Promise<TraceInvestigationResult>;
+/** True when an engine error looks like bridge version skew or a missing bridge install. */
+declare function isBridgeMismatchError(message: string): boolean;
 /**
  * Operator-facing message for a fully dead agentic pass: non-empty exactly
  * when an agentic pass ran and NO analyst in it succeeded — failed and
@@ -2832,6 +3163,651 @@ declare function writeTraceImprovementArtifacts(result: Omit<TraceImprovementRes
 declare function runTraceImprovement(opts: TraceImprovementOptions): Promise<TraceImprovementResult>;
 declare function saveReport(path: string, report: string): Promise<void>;
 
+/**
+ * Answer schemas for `traces ask`.
+ *
+ * A question may fix the shape of its answer with a JSON Schema, so a scorer
+ * can compare fields exactly instead of reading prose. This package carries no
+ * JSON Schema library, so it checks a small subset and REJECTS any schema that
+ * uses a keyword outside it: a schema whose constraint is silently ignored
+ * would let a wrong answer pass as checked.
+ *
+ * Supported keywords: `type`, `properties`, `required`, `additionalProperties`
+ * (boolean), `items` (one schema), `enum`, `const`, and the annotations
+ * `title` and `description`. The four keywords that constrain one JSON type
+ * must declare that type: `required` without `"type": "object"`, or `items`
+ * without `"type": "array"`, checks nothing against an answer of another shape.
+ */
+type AnswerSchema = Readonly<Record<string, unknown>>;
+/** Throw a TypeError naming the first unsupported or malformed part of `schema`. */
+declare function assertAnswerSchema(schema: unknown, path?: string, depth?: number): asserts schema is AnswerSchema;
+/**
+ * Every way `value` breaks `schema`, as `$.path: problem` strings. Empty means
+ * the value conforms. The schema must already have passed `assertAnswerSchema`.
+ */
+declare function answerSchemaErrors(value: unknown, schema: AnswerSchema, path?: string): string[];
+/**
+ * Read one JSON value from a model's answer text. The whole text is tried
+ * first; a single fenced block is accepted because models wrap JSON in one
+ * even when told not to. Anything else is a parse failure, not a guess.
+ */
+declare function parseJsonAnswer(text: string): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+
+/**
+ * `traces ask`: free-form questions over trace sessions, answered by a
+ * recursive trace-analysis engine.
+ *
+ * Each question runs through agent-eval's `runTraceAnalyst` directly instead
+ * of the analyst registry. The registry keeps only findings, so it discards
+ * the engine's prose answer, and it runs analysts one at a time. Here the
+ * questions run concurrently under one shared cost ledger, so a single budget
+ * bounds all of them, and every `trace://` citation in an answer is checked
+ * against the store before the answer counts as answered.
+ */
+
+/** One question to ask of the selected traces. */
+interface TraceQuestion {
+    /** Stable ID for the report, the JSON result, and cost attribution. Default: `q<n>`. */
+    readonly id?: string;
+    readonly question: string;
+    /** Extra guidance for this question only, placed after the shared rules. */
+    readonly instructions?: string;
+    /**
+     * JSON Schema the answer must satisfy (see `answer-schema.ts` for the
+     * supported subset). With a schema the answer must be one JSON value.
+     */
+    readonly answerSchema?: AnswerSchema;
+}
+/** Why a question did not produce a checked answer. */
+type TraceQuestionFailureKind = 'error' | 'aborted' | 'budget-refused' | 'no-answer' | 'invalid-answer' | 'unresolved-citations';
+interface TraceQuestionCitation {
+    readonly uri: string;
+    readonly traceId: string | null;
+    readonly spanId: string | null;
+    /** True only when the store holds the cited span. */
+    readonly resolved: boolean;
+}
+interface TraceQuestionAnswer {
+    readonly id: string;
+    readonly question: string;
+    readonly status: 'answered' | 'failed';
+    readonly failure?: {
+        readonly kind: TraceQuestionFailureKind;
+        readonly message: string;
+    };
+    /** The engine's prose answer, verbatim. Null when the engine returned none. */
+    readonly answer: string | null;
+    /** The answer parsed as JSON, present when the question had an answer schema and it parsed. */
+    readonly parsedAnswer?: unknown;
+    /** Every `trace://` URI in the answer text, with whether it resolved. */
+    readonly citations: readonly TraceQuestionCitation[];
+    /** Findings the evidence gate accepted. */
+    readonly findings: readonly RawAnalystFinding[];
+    /** Findings the evidence gate refused, by reason. */
+    readonly rejectedFindings: FindingRejectionReasons;
+    readonly model: string | null;
+    /** Successful model completions the engine reported; null when the engine failed. */
+    readonly modelCalls: number | null;
+    /** Trace-tool requests the engine reported; null when the engine failed. */
+    readonly toolCalls: number | null;
+    /** Provider usage and cost for this question alone, from the shared ledger. */
+    readonly usage: AnalystUsageReceipt | null;
+    readonly startedAt: string;
+    readonly endedAt: string;
+    readonly latencyMs: number;
+    /** Engine-native steps, retained for audit. */
+    readonly trajectory?: readonly unknown[];
+}
+/** One trace the questions could read. */
+interface TraceQuestionTrace {
+    readonly traceId: string;
+    readonly sessionId: string | null;
+    readonly spanCount: number;
+    readonly startTime: string | null;
+    readonly endTime: string | null;
+    readonly rootSpan: string | null;
+}
+interface TraceQuestionsTotals {
+    readonly questions: number;
+    readonly answered: number;
+    readonly failed: number;
+    /** Null when at least one question's count is unknown. */
+    readonly modelCalls: number | null;
+    /** Null when at least one question's count is unknown. */
+    readonly toolCalls: number | null;
+    /** Paid provider calls the shared ledger recorded, including failed ones. */
+    readonly providerCalls: number;
+    /** Total spend with its provenance; `uncaptured` carries a null amount, never 0. */
+    readonly cost: CostProvenance;
+    /** Wall time of the whole run, from the first span written to the last answer. */
+    readonly wallTimeMs: number;
+    /** Part of `wallTimeMs` spent writing and indexing the trace file, before any question ran. */
+    readonly setupTimeMs: number;
+    /** Sum of the questions' own latencies; above `wallTimeMs` when questions overlapped. */
+    readonly questionTimeMs: number;
+    /** Most questions observed running at the same time. */
+    readonly peakConcurrency: number;
+}
+interface TraceQuestionsResult {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.ask';
+    readonly generatedAt: string;
+    readonly harness: string;
+    readonly engine: {
+        readonly id: string;
+        readonly version: string;
+        readonly model: string | null;
+    };
+    /** Questions the run was allowed to overlap, as requested. */
+    readonly concurrency: number;
+    /** Workers the run actually created: `min(concurrency, questions)`. */
+    readonly effectiveConcurrency: number;
+    /** Shared ceiling across every question; null when uncapped. */
+    readonly budgetUsd: number | null;
+    /** The engine's own ceiling for one question, when it declares one. */
+    readonly questionBudgetUsd: number | null;
+    readonly spanCount: number;
+    readonly otlpPath: string;
+    readonly traces: readonly TraceQuestionTrace[];
+    readonly questions: readonly TraceQuestionAnswer[];
+    readonly totals: TraceQuestionsTotals;
+    readonly warnings: readonly string[];
+    /** True when every question produced an answer whose citations all resolved. */
+    readonly ok: boolean;
+    readonly report: string;
+}
+interface TraceQuestionsOptions {
+    readonly questions: readonly TraceQuestion[];
+    readonly spans: readonly OtlpSpan[];
+    readonly engine: TraceAnalysisEngine;
+    readonly harness?: string;
+    /** Questions running at once. Default 4. */
+    readonly concurrency?: number;
+    /** Shared USD ceiling across every question. Omit for no shared ceiling. */
+    readonly budgetUsd?: number;
+    readonly limits?: Partial<TraceAnalystLimits>;
+    /** Explicit full-bundle source access for `readSpanSource`. */
+    readonly sourceBundle?: {
+        path: string;
+        maxRecordBytes?: number;
+    };
+    /** Where to write the OpenInference file the engine reads. Default: a temp file. */
+    readonly otlpOutPath?: string;
+    readonly generatedAt?: string;
+    readonly signal?: AbortSignal;
+    readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
+}
+interface TraceQuestionsArtifacts {
+    readonly directory: string;
+    readonly result: string;
+    readonly report: string;
+    readonly traces: string;
+}
+declare const DEFAULT_ASK_CONCURRENCY = 4;
+/** Longest question that keeps the whole question field inside the preview. */
+declare const MAX_TRACE_QUESTION_CHARS: number;
+/**
+ * Validate questions and assign default IDs. Throws on an empty list, a
+ * duplicate or malformed ID, a question too long for the preview, or an answer
+ * schema outside the supported subset.
+ *
+ * Explicit IDs are reserved before any default is assigned, so a file entry
+ * named `q2` plus a positional question cannot collide and kill the run before
+ * it starts. A default keeps its own position where it can: it starts at
+ * `q<index + 1>` and takes the next free number only when that one is spoken for.
+ */
+declare function normalizeTraceQuestions(questions: readonly TraceQuestion[]): Array<TraceQuestion & {
+    id: string;
+}>;
+/**
+ * Read questions from a JSON file: an array, or an object with a `questions`
+ * array. Each entry is a question string or an object with `question` and
+ * optional `id`, `instructions`, and `answerSchema`. Unknown keys are
+ * rejected so a misspelled field cannot be ignored silently.
+ */
+declare function loadTraceQuestionsFile(path: string): Promise<TraceQuestion[]>;
+/** The engine's `question` input: a short header, then the question, whole. */
+declare function renderTraceQuestionPrompt(question: string): string;
+/** The definition's instructions: rules first, so the preview keeps them. */
+declare function renderTraceQuestionInstructions(question: Pick<TraceQuestion, 'instructions' | 'answerSchema'>): string;
+/** Characters of the instructions the DSPy preview keeps from the start; the rules must fit. */
+declare const TRACE_QUESTION_PREVIEW_HEAD_CHARS = 500;
+/** Every distinct `trace://<trace>/span/<span>` URI in the text, in order. */
+declare function traceCitationsInText(text: string): Array<{
+    uri: string;
+    traceId: string | null;
+    spanId: string | null;
+}>;
+/**
+ * Smallest reservation one model call makes before it runs: its full output and
+ * reasoning allowance at the output rate, before any input tokens. Undefined
+ * when the engine does not describe its pricing and token caps.
+ */
+declare function engineCallReservationFloorUsd(engine: TraceAnalysisEngine): number | undefined;
+/**
+ * Ask every question of the spans, concurrently, under one shared cost
+ * ledger. Never throws for a failed question: each failure is recorded on its
+ * answer and `ok` turns false. An aborted run is one of those failures, not an
+ * exception: answers already bought are kept and the questions the run never
+ * reached are recorded as `aborted`, so the caller can still write both
+ * artifacts. Throws before any model call for invalid questions, options, or a
+ * budget below one call's reservation.
+ */
+declare function runTraceQuestions(opts: TraceQuestionsOptions): Promise<TraceQuestionsResult>;
+/** Readable Markdown for a result; the JSON result carries every field. */
+declare function renderTraceQuestionsReport(result: Omit<TraceQuestionsResult, 'report'>): string;
+/** Write `answers.json` and `report.md` next to the trace file the engine read. */
+declare function writeTraceQuestionsArtifacts(result: TraceQuestionsResult, outDir: string): Promise<TraceQuestionsArtifacts>;
+
+/**
+ * Which pull requests a session created, and which it merged.
+ *
+ * The spans already hold the answer and no reader was extracting it. A Codex
+ * `CommandExecution` item becomes a `command.execution` span carrying the
+ * script, its exit code and its output; a Claude Code `Bash` call becomes a
+ * TOOL span with the same three things under the same I/O keys. A `gh pr
+ * create` is therefore visible, and so is the pull-request URL `gh` printed
+ * back — which is the only place the new PR's number appears.
+ *
+ * Three rules keep the reading honest:
+ *
+ *   1. The command is found by scanning the script the way a shell would
+ *      ({@link shellCommands}), not by matching text. A `gh pr create` quoted
+ *      inside a heredoc body or a commit message never ran and is not counted.
+ *   2. 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 it does not — the
+ *      identity the command itself supplies. A call with neither stays a
+ *      recorded event with a null identifier and a stated reason.
+ *   3. Every entry names the span its command came from, plus the span whose
+ *      output supplied the number, so the reading can be checked against the
+ *      raw spans rather than trusted.
+ *
+ * A command that never reached `gh` is not an event: a failed
+ * `git push … && gh pr create` exited non-zero without running `gh`, so it
+ * counts only when the exit code is zero or the output shows `gh` itself
+ * answering.
+ */
+
+/** One pull request the agent created or merged, with the evidence that named it. */
+interface PullRequestFact {
+    /** The PR number when one is known, else the head branch. Null when neither is. */
+    readonly identifier: string | null;
+    readonly number: string | null;
+    readonly headBranch: string | null;
+    /** The `gh` command, as the scanner read it. */
+    readonly command: string;
+    /** How `identifier` was arrived at, naming the span that supplied it. */
+    readonly evidence: string;
+    /** The command span, plus any span whose output supplied the number. */
+    readonly spanIds: readonly string[];
+    /** Why `identifier` is null. Null when the pull request was identified. */
+    readonly unavailable: string | null;
+}
+interface PullRequestFacts {
+    readonly created: readonly PullRequestFact[];
+    readonly merged: readonly PullRequestFact[];
+}
+interface PullRequestReading {
+    /** Null exactly when `unavailable` explains why the spans cannot support it. */
+    readonly facts: PullRequestFacts | null;
+    readonly spanIds: readonly string[];
+    readonly unavailable: string | null;
+    readonly partial: string | null;
+    /** Spans carrying an executed command: the denominator of this reading. */
+    readonly commandSpans: number;
+}
+/**
+ * Read every pull request the spans show the agent creating or merging.
+ *
+ * `spans` must be in trace order: a number a later command states is joined to
+ * the create it belongs to by position, and that ordering is the position.
+ */
+declare function readPullRequests(spans: readonly OtlpSpan[]): PullRequestReading;
+
+/**
+ * The deterministic session-facts sheet.
+ *
+ * A handful of facts about a session decide most audit questions — how many
+ * tools ran, which subagents were spawned, which pull requests were opened and
+ * merged, what the human actually typed, what the agent said last, which files
+ * changed, when the session started and ended, and how many tokens it burned.
+ * Every one of them is already carried by the normalized
+ * spans, but no trace tool returns any of them: `viewTrace` degrades to a
+ * 20-entry name histogram above its byte ceiling, `countTraces` counts traces
+ * rather than spans, `viewSpans` needs span ids the reader does not have, and
+ * `searchTrace` stops at 500 hits. A model asked for a tool-call total therefore
+ * adds up a capped histogram and decides by eye which names count.
+ *
+ * This module computes those facts mechanically instead. No model call, no
+ * budget, no byte ceiling: it reads the spans directly, so a session far above
+ * the tool ceiling still yields exact numbers.
+ *
+ * Two rules make the sheet auditable:
+ *
+ *   1. Every field carries the span ids it was computed from, so a reader can
+ *      open those spans and check the number.
+ *   2. A field the spans cannot support is `null` with a stated `unavailable`
+ *      reason. It is never guessed, and never silently zero. A value the sheet
+ *      filtered — a `user.prompt` turn that is not a human turn of this session
+ *      — is reported beside the count with the reason, never silently dropped.
+ *
+ * Every fact below is about THE 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 hold two kinds of record: what this session's agent did,
+ * and what a child agent it spawned did. The child's work is the child's: it is
+ * excluded from this sheet's counts, named in `subagents` and counted in
+ * `subagentToolSpans`, never added to the parent's totals. A trace with no
+ * subagent records is unaffected — every one of those counts is zero.
+ *
+ * The sheet is NOT a span and cannot be cited. It is prepared context, and
+ * `trace://` citations still resolve against the raw spans — which is why every
+ * fact names its span ids rather than asking the reader to trust the sheet.
+ */
+
+/**
+ * The cumulative harness token total for a whole session, when the adapter
+ * records one. Codex's `token_count` events carry
+ * `info.total_token_usage.total_tokens`; the adapter uses that object only as a
+ * de-duplication signature today, so no span carries the value and
+ * {@link SessionFacts.tokenTotal} states that rather than summing the per-turn
+ * deltas, which is a different (and smaller) number.
+ */
+declare const SESSION_TOKEN_TOTAL_ATTR = "traces.session.total_tokens";
+/**
+ * The first marker an adapter used for a span it created to describe a
+ * lifecycle rather than an invocation the agent made. The current marker is
+ * `traces.span.synthesized` (see `adapters/provenance.ts`); this one is still
+ * recognized so a trace exported before the rename keeps counting correctly.
+ */
+declare const SPAN_SYNTHESIZED_ATTR = "traces.codex.span_synthesized";
+/** Max characters of message or prompt text kept per fact entry. */
+declare const FACT_TEXT_CAP = 2000;
+/** Entries kept per list field before the sheet reports the rest as omitted. */
+declare const FACT_LIST_CAP = 200;
+/**
+ * Entries kept for {@link SessionFacts.changedFiles}.
+ *
+ * The cap above bounds the sheet's size against lists whose entries carry up to
+ * {@link FACT_TEXT_CAP} characters of message or prompt text. A changed-file
+ * entry is a path and two short arrays, two orders of magnitude smaller, and a
+ * session that edits hundreds of files is the one whose file list a reader most
+ * needs whole — the rendered context prints only the count either way. So this
+ * list gets its own ceiling, still finite so a runaway session cannot make the
+ * sheet unbounded.
+ */
+declare const CHANGED_FILE_LIST_CAP = 5000;
+/**
+ * One measured fact. `value` is `null` exactly when `unavailable` explains why
+ * the spans cannot support it; `spanIds` names the spans the value came from,
+ * in the order they appear in the trace.
+ */
+interface SessionFact<T> {
+    readonly value: T | null;
+    readonly spanIds: readonly string[];
+    /** Why `value` is null. Null when the fact was measured. */
+    readonly unavailable: string | null;
+    /** A measured value that is known to be incomplete says so here. */
+    readonly partial?: string;
+}
+/** One subagent-spawning call, with the task name the adapter recorded for it. */
+interface SubagentSpawnFact {
+    /** The task name the spawn span carries, verbatim. Null when it carries none. */
+    readonly taskName: string | null;
+    /** Why `taskName` is null. Null when it was recorded. */
+    readonly taskNameUnavailable: string | null;
+    readonly startedAt: string;
+    /** The spawn span's status: `OK`, `ERROR`, or `UNSET` while still open. */
+    readonly status: string;
+    /** The spawn call span, plus the subagent lifecycle span when one joined it. */
+    readonly spanIds: readonly string[];
+}
+/** One `user.prompt` turn, with the actor the adapter classified it as. */
+interface SessionTurnFact {
+    readonly actor: string;
+    readonly at: string;
+    readonly text: string;
+    readonly spanId: string;
+}
+/** How many `user.prompt` turns each actor produced. */
+interface TurnActorCount {
+    readonly actor: string;
+    readonly turns: number;
+    readonly spanIds: readonly string[];
+}
+/**
+ * `user.prompt` turns {@link SessionFacts.humanTurns} did not count, grouped by
+ * the reason they were not counted. Nothing is dropped silently: every excluded
+ * span is named here, so a reader who disagrees with a reason can open the span
+ * and count it back in.
+ */
+interface ExcludedTurnFact {
+    readonly reason: string;
+    readonly turns: number;
+    readonly spanIds: readonly string[];
+}
+/** The last thing one agent said, for the main session or for one subagent. */
+interface FinalMessageFact {
+    /**
+     * The subagent's task path, or null for the session's own agent. One session
+     * interleaves its own `message.assistant` spans with the `message.agent.*`
+     * traffic of every subagent under the same root, so "the final message" is
+     * only well defined per task.
+     */
+    readonly task: string | null;
+    readonly at: string;
+    readonly text: string;
+    readonly spanId: string;
+}
+/** One path a tool call changed, and how. */
+interface ChangedFileFact {
+    readonly path: string;
+    /**
+     * `add`, `update`, `delete`, or `move`, in the order first observed. A kind a
+     * harness reports under another name is kept verbatim rather than mapped.
+     */
+    readonly operations: readonly string[];
+    readonly spanIds: readonly string[];
+}
+/** Everything the spans of one session state, computed without a model. */
+interface SessionFacts {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.session_facts';
+    readonly traceId: string;
+    readonly sessionId: string | null;
+    readonly harness: string | null;
+    /** Spans in this trace, including the synthesized ones. */
+    readonly spanCount: number;
+    /**
+     * Spans the adapter built from the session's own records. The session root
+     * and the integrity receipts are not among them, so zero means nothing in the
+     * file was read and every count below would be an unsupported zero.
+     */
+    readonly recordSpans: number;
+    /** Records the adapter could not read, from the session's integrity receipt. */
+    readonly unreadRecords: SessionFact<number>;
+    /**
+     * TOOL spans THIS session's agent invoked. Synthesized lifecycle spans and
+     * the tool calls of subagents it spawned are excluded, and each exclusion is
+     * counted below so the reader can add them back.
+     */
+    readonly toolCalls: SessionFact<number>;
+    /** Every synthesized span excluded from `toolCalls`, so the exclusion is checkable. */
+    readonly synthesizedToolSpans: SessionFact<number>;
+    /** TOOL spans excluded because a subagent, not this agent, made the call. */
+    readonly subagentToolSpans: SessionFact<number>;
+    /** Tool-call counts by tool name, over the same spans `toolCalls` counted. */
+    readonly toolCallsByName: SessionFact<Readonly<Record<string, number>>>;
+    readonly subagents: SessionFact<readonly SubagentSpawnFact[]>;
+    /** Pull requests this session created and merged, each with its evidence. */
+    readonly pullRequests: SessionFact<PullRequestFacts>;
+    /** `user.prompt` turns a person typed into THIS session, in order. */
+    readonly humanTurns: SessionFact<readonly SessionTurnFact[]>;
+    /** Every `user.prompt` turn `humanTurns` left out, with the reason. */
+    readonly excludedTurns: SessionFact<readonly ExcludedTurnFact[]>;
+    /** Every `user.prompt` turn by actor, so the human filter is checkable. */
+    readonly turnsByActor: SessionFact<readonly TurnActorCount[]>;
+    /** The last message of the session's own agent, and of each subagent task. */
+    readonly finalMessages: SessionFact<readonly FinalMessageFact[]>;
+    readonly changedFiles: SessionFact<readonly ChangedFileFact[]>;
+    /** Earliest span start among this session's own records. Not the session
+     *  file's first record when the adapter selected a task boundary inside the
+     *  file, and not a spawned subagent's first record. */
+    readonly firstRecordAt: SessionFact<string>;
+    /** Latest span end among this session's own records. */
+    readonly lastRecordAt: SessionFact<string>;
+    /** The harness's own cumulative token total, when a span carries it. */
+    readonly tokenTotal: SessionFact<number>;
+}
+interface SessionFactsReport {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.session_facts_report';
+    readonly generatedAt: string;
+    readonly harness: string | null;
+    readonly spanCount: number;
+    readonly sessions: readonly SessionFacts[];
+}
+/**
+ * Compute the facts sheet for every trace in `spans`. One trace is one session.
+ * Deterministic and free: the same spans always produce the same sheet, and no
+ * model, network call, or budget is involved.
+ */
+declare function computeSessionFacts(spans: readonly OtlpSpan[]): SessionFacts[];
+/** The facts sheet for a set of spans, as one report. */
+declare function buildSessionFactsReport(spans: readonly OtlpSpan[], options?: {
+    harness?: string | null;
+    generatedAt?: string;
+}): SessionFactsReport;
+/** The short readable form: the same facts, one screen, no span-id lists. */
+declare function renderSessionFacts(report: SessionFactsReport): string;
+/**
+ * The byte ceiling one prepared-context string stays under.
+ *
+ * `DEFAULT_TRACE_ANALYST_BUDGETS.perCallByteCeiling` is 150,000 — the size one
+ * trace-tool result may return. Prepared context is read by the same model in
+ * the same turn as those results, so the sheet claims a fifth of that ceiling
+ * and leaves the rest for the tool calls the model still has to make.
+ */
+declare const PREPARED_CONTEXT_BYTE_CEILING = 30000;
+/**
+ * Render the sheet as bounded prepared context.
+ *
+ * Prepared context is not evidence: it is a head start. The rendering therefore
+ * keeps every field's span ids so that each fact can be checked against the raw
+ * spans, and says out loud that the sheet itself is not citable.
+ *
+ * The result is guaranteed to be at most `byteCeiling` bytes. Fields are shed
+ * from the largest list downward, and the shed is reported inside the context
+ * rather than silently applied.
+ */
+declare function renderSessionFactsContext(report: SessionFactsReport, options?: {
+    byteCeiling?: number;
+}): string;
+/**
+ * The prepared-context string for one set of spans, or undefined when there is
+ * nothing to prepare. Analyst definitions install this through
+ * `TraceAnalystDefinition.prepareContext`, which runs before the model does.
+ */
+declare function sessionFactsContext(spans: readonly OtlpSpan[], options?: {
+    byteCeiling?: number;
+    generatedAt?: string;
+}): string | undefined;
+/**
+ * Version suffix stamped on a definition that receives the sheet.
+ *
+ * `createTraceAnalyst` records `prepare_context: "version-bound"` in an
+ * analyst's exact-run identity, which is a contract: a definition whose
+ * prepared context changed is a different analyst. Wrapping therefore bumps the
+ * version instead of quietly changing what the same version does.
+ */
+declare const SESSION_FACTS_VERSION_SUFFIX = "session-facts.1";
+/**
+ * Supply the sheet to every definition as prepared context, before the model
+ * runs. A definition that already prepares context keeps it; the sheet is
+ * appended after it, bounded by its own ceiling, so the pair stays inside the
+ * documented `perCallByteCeiling` of 150,000 bytes.
+ *
+ * The sheet is computed once for the whole set: it is deterministic, so every
+ * definition receives the identical text.
+ */
+declare function withSessionFactsContext(definitions: readonly TraceAnalystDefinition[], spans: readonly OtlpSpan[], options?: {
+    byteCeiling?: number;
+}): TraceAnalystDefinition[];
+
+/**
+ * Split one shell script into the simple commands it would actually run.
+ *
+ * A trace records a command as the script the agent handed to `/bin/zsh -lc`,
+ * and one script routinely runs several commands: `git push && gh pr create`,
+ * a `cat > file <<'EOF' … EOF` heredoc followed by a `gh` call, a `sh -c`
+ * wrapper around another script. Asking "did this session create a pull
+ * request?" with a regular expression over that text answers yes for a heredoc
+ * body that merely mentions `gh pr create`, and no for a command hidden behind
+ * a `$( … )` substitution.
+ *
+ * This scanner answers the question the way the shell would: it walks the
+ * script once, tracking quoting, comments, redirections and heredoc bodies, and
+ * returns the word list of every simple command it finds — recursing into
+ * command substitutions, subshells, and the `-c` argument of a nested shell.
+ *
+ * It is a reader, not an interpreter. Variables are not expanded, globs are not
+ * matched, and a word built from a variable comes back as the literal text of
+ * the script. A caller therefore learns which command *names* ran with which
+ * *literal* arguments, which is exactly what an audit of `gh pr create` needs
+ * and is never mistaken for a claim about what the shell computed.
+ */
+/** Recursion limit for `$( … )`, backticks, subshells and nested `sh -c`. */
+declare const MAX_SHELL_DEPTH = 4;
+/**
+ * Every simple command in `script`, as word lists, in the order the scanner
+ * meets them. Commands inside substitutions and nested shells are included.
+ */
+declare function shellCommands(script: string, depth?: number): string[][];
+/**
+ * The script a tool span recorded, from its `input.value`.
+ *
+ * Adapters store a command as JSON — `{"command": ["/bin/zsh", "-lc", "…"]}`
+ * for a Codex `CommandExecution` item, `{"command": "…"}` for a Claude Code
+ * `Bash` call, `{"cmd": "…"}` for a Codex `exec_command` argument list. An argv
+ * array whose head is a shell keeps only the script that shell was given; any
+ * other array is joined back into one command line. A value that is not JSON,
+ * or JSON without a command field, yields undefined: the span records something
+ * other than an executed command, and guessing from its text is how a heredoc
+ * body becomes a pull request.
+ */
+declare function commandTextFromInput(input: string): string | undefined;
+
+/** Model the CLI's recursive analysts use when neither `--model` nor TRACES_ANALYST_MODEL names one. */
+declare const DEFAULT_ANALYST_MODEL = "gpt-5.6-luna";
+interface AnalysisEngineFromEnvOptions {
+    model: string;
+    /**
+     * Provider-side spend ceiling for ONE investigation (one analyst or one
+     * question). Omitted, the engine keeps its own default. A caller that runs
+     * several investigations under one shared ledger passes the per-investigation
+     * cap here and the total to the ledger.
+     */
+    maxCostUsd?: number;
+    /** Receives one line per model call, in the CLI's analyst log format. */
+    log?: (msg: string, fields?: Record<string, unknown>) => void;
+    /** Environment to read credentials and the Python interpreter from. Default: process.env. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * The recursive analysis engine behind `--llm` and `ask`. agent-eval's
+ * model-backed analysts run through DSPy RLM, which drives
+ * `agent-eval-rpc[dspy]` out of process, so this needs a Python interpreter
+ * with that extra installed, selectable via TRACES_PYTHON. Every deterministic
+ * command is unaffected and still needs neither a key nor Python.
+ */
+declare function analysisEngineFromEnv(opts: AnalysisEngineFromEnvOptions): TraceAnalysisEngine;
+
 type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
@@ -3012,45 +3988,10 @@ 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.
+ * Runtime journal snapshots for the live view, plus report-reader enrichment.
+ * Eval owns report normalization, terminal records, and evidence accounting.
+ * This module adds coordination-log steers and questions to those sources.
+ * The live view uses Runtime's tree fold and keeps partial journal tails visible.
  */
 
 declare const SPAWN_JOURNAL_FILE = "spawn-journal.jsonl";
@@ -3121,16 +4062,15 @@ interface CoordinationLog {
  */
 declare function readCoordinationLog(text: string | null): CoordinationLog;
 interface FileRunContextReaderOptions {
-    /** Override the run identity used for rollup grouping (default: the journal root). */
+    /** Override the recorded Runtime identity used for rollup grouping. */
     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.
+ * Eval preserves missing evidence and rejects malformed Runtime records.
+ * Coordination-log evidence extends the normalized worker sources.
  */
 declare function readFileRunContext(runDir: string, opts?: FileRunContextReaderOptions): Promise<SupervisorRunSources>;
 /** The `createFileRunContext` on-disk layout, as a `SupervisorRunReader`. */
@@ -4589,4 +5529,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 AnalystReplayFinding, type AnalyzeOptions, type AnalyzeResult, type ArmExecutionResult, type AssembleSessionBundleOptions, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type CaseResources, type ChatCompletionCaller, type ChatOutcome, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, type ChatUsage, 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 CorpusSpec, type CorruptionMode, type CwdSource, DEFAULT_HARNESS, DEFAULT_SANDBOX_BASE_URL, type DockerImagePreparerOptions, EMPTY_SPAN_RUN_SNAPSHOT, EXPORT_RULE, EmptySessionError, type EnumerationResult, type EvidenceOnlyVerdict, type ExcludedCase, type ExecuteOptions, type ExportRule, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FactoryAdapter, type FailedFixAttempt, type FileRunContextReaderOptions, type FindSessionTextLeaksOptions, type FindingReplaySource, type FindingReplayability, type FindingVerification, type FindingVerificationStatus, type FixArmExecution, type FixArmExecutor, type FixGenerationOutcome, type FixLoopAttemptRecord, type FixLoopOptions, type FixLoopResult, type FixPromptInput, ForgeAdapter, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, type ImagePreparation, type ImagePreparer, type IncorrectStepsSubject, 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, POLICY_EVIDENCE_NOTE, type ParentTaskResolution, type ParseOptions, PartialUploadError, PiAdapter, type PiAdapterOptions, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, type PrefixDivergence, type PrefixReplayResult, type PrimeAnalyzerOptions, type PrimeTransport, type PrimeTransportRequest, type PrimeTransportResponse, type ProjectSessionBundleOptions, type ProjectSessionBundleResult, QwenAdapter, REACTIONS, RESULT_FILE, RULE, type Reaction, type ReactionReport, type ReactionSessionReport, type Redactor, type ReplayArmVerdict, type ReplayBatchCaseRow, type ReplayBatchCliArgs, type ReplayBatchFixResult, type ReplayBatchOptions, type ReplayBatchReport, type ReplayExclusionReason, type ReplayExecBackend, type ReplayExecResult, type ReplayExecSession, type ReplayFindingOptions, type ReplayFindingResult, type ReplayVerdict, type ReplayVerifyCliArgs, type ReplayVerifyOptions, type ReplayableCase, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedFindingReplay, type ResolvedOtlpInput, type ResolvedReplayInvocation, type ResourceResolution, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunResult, type RunWatchSnapshot, type RunWatchTarget, type RuntimeTrace, SPAWN_JOURNAL_FILE, STATUS_MARK, SUBMIT_ACTION_SIGNATURE, SandboxCounterfactualRunner, type SandboxCounterfactualRunnerOptions, type SandboxReplayBackendOptions, type ScanOptions, type ScannedSession, type SessionBatch, type SessionBundleAbsence, type SessionBundleCarriedSignatures, type SessionBundleExclusion, type SessionBundleExclusionRule, type SessionBundleFile, type SessionBundleLeakCheck, type SessionBundleLedgerSlice, type SessionBundleManifest, type SessionBundleProjection, type SessionBundleResult, type SessionBundleSliceRule, type SessionBundleView, type SessionCorruptionReceipt, type SessionEnvironment, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionTextLeak, type SessionTextLeakReport, 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 VerifiableFinding, type VerifyFindingsCliArgs, type VerifyFindingsOptions, type VerifyFindingsRun, type WatchRunTargetOptions, ZERO_ROLL, type ZaiChatCallerOptions, addSpend, alreadyUploaded, analyzeAdoption, analyzeLiveBatch, analyzeLoopConvergence, analyzeReactions, analyzeSpans, analyzeSteeringChain, applyRedactor, assembleSessionBundle, assertSandboxReachable, buildFixPrompt, buildPolicyEvidenceRecord, buildRetryFixPrompt, buildSessionIndex, buildSessionIndexFromRows, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyEvidenceOnlyPath, classifyLiveActions, classifyReaction, classifyVerdict, claudeActor, clipText, cmdReplayVerify, cmdReplayVerifyBatch, cmdVerifyFindings, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, conformanceOfSpans, connectors, countScriptCommands, countSkillRunsJsonl, cwdMatchesSelection, defaultTraceLiveAnalysts, deriveFailureSignature, derivedImageTag, describeSessionRelationship, dockerImagePreparer, enumerateReplayableCases, environmentAttributes, environmentFromSpanAttributes, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, extractFixCommand, fileRunContextSupervisorRunReader, findContextRoot, findSessionTextLeaks, findSpanSourceFiles, findingReplayStep, findingTrajectoryId, forEachTreeNode, generateFixCommand, goldIncorrectSteps, haloAnalyzer, hashSessionBundleFiles, hodoscopeAnalyzer, httpJsonTransport, importCodeTraceBench, incompleteInputsNote, indexSessionIdsByTrace, inferRole, inferSpanKind, ingestCodeTraceBenchSteps, inspectSessionIndex, int, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, isSubmitAction, knownHarnesses, listAdapters, listSessionBundleFiles, loadState, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeRemote, otlpRowToSpan, outboundHash, parseCorpusFlag, parseIncorrectStepsSubject, parseIsoToEpochMs, parseObservationOutput, parseRecordedReturncode, parseReplayBatchArgs, parseReplayVerifyArgs, parseSession, parseSince, parseVerifyFindingsArgs, planTraceAgenticRoute, planUpload, primeAnalyzer, projectSessionBundle, readCoordinationLog, readFileRunContext, readFindingsFile, readJsonFile, readJsonl, readLabelEntries, readOtlpInput, readRunContextJournal, readRunContextSnapshot, readRunWatchSnapshot, readSessionBundleManifest, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderBatchReport, renderConformance, renderInspectionReport, renderRunContextSnapshot, renderRunWatchSnapshot, renderSpanRunSnapshot, renderValidation, renderVerifiedFindingsSection, replayBatchUsage, replayVerify, replayVerifyFinding, replayVerifyUsage, resolveAdapter, resolveCaseResources, resolveFindingInvocation, resolveFindingReplayability, resolveOtlpInputFiles, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runFixLoop, runPipelines, runReplayBatch, runTotals, runTraceImprovement, runTraceInvestigation, runTraceStoreInvestigation, sandboxReplayBackend, saveReport, saveState, scanSessions, seededSample, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, sessionTextSignatures, skippedAnalyses, span, spanRunTotals, stampEnvironmentAttrs, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, summarizeSpanStructure, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, tokens, totalAgenticFailureMessage, traceAgenticKinds, traceStreamEventsFromSpans, unavailableCapabilities, uploadKey, usd, userPromptSpan, validateOtlpSpans, validationExitCode, verifyFindings, verifyFindingsUsage, watchRunTarget, watchSessions, wrap, wrapActionForExec, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionBundleManifest, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, zaiChatCaller, zeroPricedCost };
+export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalysisEngineFromEnvOptions, type AnalystReplayFinding, type AnalyzeOptions, type AnalyzeResult, type AnswerSchema, type ArmExecutionResult, type AssembleSessionBundleOptions, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CHANGED_FILE_LIST_CAP, CITATION_NORMALIZATION_VERSION, CODING_REDACTION_RULES, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type CaseResources, type ChangedFileFact, type ChatCompletionCaller, type ChatOutcome, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, type ChatUsage, 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 CorpusSpec, type CorruptionMode, type CwdSource, DEFAULT_ANALYST_MODEL, DEFAULT_ASK_CONCURRENCY, DEFAULT_HARNESS, DEFAULT_SANDBOX_BASE_URL, type DockerImagePreparerOptions, EMPTY_SPAN_RUN_SNAPSHOT, EXPORT_RULE, EmptySessionError, type EnumerationResult, type EvidenceOnlyVerdict, type ExcludedCase, type ExcludedTurnFact, type ExecuteOptions, type ExportRule, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FACT_LIST_CAP, FACT_TEXT_CAP, FactoryAdapter, type FailedFixAttempt, type FailureFollowUp, type FailureFollowUpReport, type FileRunContextReaderOptions, type FinalMessageFact, type FindSessionTextLeaksOptions, type FindingRejectionCounts, type FindingRejectionReasons, type FindingRejectionTally, type FindingReplaySource, type FindingReplayability, type FindingVerification, type FindingVerificationStatus, type FixArmExecution, type FixArmExecutor, type FixGenerationOutcome, type FixLoopAttemptRecord, type FixLoopOptions, type FixLoopResult, type FixPromptInput, type FollowUpKind, ForgeAdapter, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, INHERITED_SOURCE_ATTR, INHERITED_SPANS_OMITTED_ATTR, INHERITED_SPAN_ATTR, INHERITED_SPAN_COUNT_ATTR, type ImagePreparation, type ImagePreparer, type IncorrectStepsSubject, type IngestedTrajectory, type InheritedSpanSource, type InspectSessionIndexOptions, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type LoopConvergence, type LoopConvergenceReport, type LoopIteration, type LoopTrend, type LoopTrendBasis, MAX_SHELL_DEPTH, MAX_TRACE_QUESTION_CHARS, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpIngestIssue, type OtlpIngestIssueKind, type OtlpInput, type OtlpInputFile, type OtlpRowConversion, type OtlpSpan, type OtlpSpanKind, type OtlpSpanLink, type OtlpStatusCode, POLICY_EVIDENCE_NOTE, PREPARED_CONTEXT_BYTE_CEILING, type ParentTaskResolution, type ParseOptions, PartialUploadError, PiAdapter, type PiAdapterOptions, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, type PrefixDivergence, type PrefixReplayResult, type PrimeAnalyzerOptions, type PrimeTransport, type PrimeTransportRequest, type PrimeTransportResponse, type ProjectSessionBundleOptions, type ProjectSessionBundleResult, type PullRequestFact, type PullRequestFacts, type PullRequestReading, QwenAdapter, REACTIONS, RESULT_FILE, RULE, type Reaction, type ReactionReport, type ReactionSessionReport, type Redactor, type ReplayArmVerdict, type ReplayBatchCaseRow, type ReplayBatchCliArgs, type ReplayBatchFixResult, type ReplayBatchOptions, type ReplayBatchReport, type ReplayExclusionReason, type ReplayExecBackend, type ReplayExecResult, type ReplayExecSession, type ReplayFindingOptions, type ReplayFindingResult, type ReplayVerdict, type ReplayVerifyCliArgs, type ReplayVerifyOptions, type ReplayableCase, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedFindingReplay, type ResolvedOtlpInput, type ResolvedReplayInvocation, type ResourceResolution, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunResult, type RunWatchSnapshot, type RunWatchTarget, type RuntimeTrace, SESSION_FACTS_VERSION_SUFFIX, SESSION_TOKEN_TOTAL_ATTR, SOURCE_ATTRIBUTE_PREFIX, SPAN_SYNTHESIZED_ATTR, SPAWN_JOURNAL_FILE, STATUS_MARK, SUBMIT_ACTION_SIGNATURE, SYNTHESIZED_SOURCE_ATTR, SYNTHESIZED_SPAN_ATTR, SandboxCounterfactualRunner, type SandboxCounterfactualRunnerOptions, type SandboxReplayBackendOptions, type ScanOptions, type ScannedSession, type SessionBatch, type SessionBundleAbsence, type SessionBundleCarriedSignatures, type SessionBundleExclusion, type SessionBundleExclusionRule, type SessionBundleFile, type SessionBundleLeakCheck, type SessionBundleLedgerSlice, type SessionBundleManifest, type SessionBundleProjection, type SessionBundleResult, type SessionBundleSliceRule, type SessionBundleView, type SessionCorruptionReceipt, type SessionEnvironment, type SessionFact, type SessionFacts, type SessionFactsReport, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionTextLeak, type SessionTextLeakReport, type SessionTurnFact, type SessionWorkflow, SessionWorkflowError, type SessionWorkflowErrorCode, type SessionWorkflowIssue, type SessionWorkflowSession, type SessionWorkflowSummary, type SkippedAnalysis, type SkippedInputFile, type SourceRecordReference, type SpanInput, type SpanNodeStatus, type SpanRedaction, type SpanRunNode, type SpanRunSnapshot, type SpanStructure, type SpawnedChildResolution, type SpendRoll, type SteeringChainReport, type SteeringEdge, type SubagentSpawnFact, TRACES_REDACTION_RULES, TRACE_QUESTION_PREVIEW_HEAD_CHARS, 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 TraceQuestion, type TraceQuestionAnswer, type TraceQuestionCitation, type TraceQuestionFailureKind, type TraceQuestionTrace, type TraceQuestionsArtifacts, type TraceQuestionsOptions, type TraceQuestionsResult, type TraceQuestionsTotals, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type TurnActorCount, type UnavailableCapabilities, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, type VerifiableFinding, type VerifyFindingsCliArgs, type VerifyFindingsOptions, type VerifyFindingsRun, type WatchRunTargetOptions, ZERO_ROLL, type ZaiChatCallerOptions, addSpend, alreadyUploaded, analysisEngineFromEnv, analyzeAdoption, analyzeLiveBatch, analyzeLoopConvergence, analyzeReactions, analyzeSpans, analyzeSteeringChain, answerSchemaErrors, applyRedactor, assembleSessionBundle, assertAnswerSchema, assertSandboxReachable, buildFixPrompt, buildPolicyEvidenceRecord, buildRetryFixPrompt, buildSessionFactsReport, buildSessionIndex, buildSessionIndexFromRows, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyEvidenceOnlyPath, classifyFailureFollowUps, classifyLiveActions, classifyReaction, classifyVerdict, claudeActor, clipText, cmdReplayVerify, cmdReplayVerifyBatch, cmdVerifyFindings, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, commandTextFromInput, computeSessionFacts, conformanceOfSpans, connectors, countScriptCommands, countSkillRunsJsonl, createBundleSourceReader, createFindingRejectionTally, cwdMatchesSelection, cwdMatchesSelectionResolved, defaultTraceLiveAnalysts, deriveFailureSignature, derivedImageTag, describeSessionRelationship, dockerImagePreparer, engineCallReservationFloorUsd, enumerateReplayableCases, environmentAttributes, environmentFromSpanAttributes, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, externalFailureMessage, extractFixCommand, fileRunContextSupervisorRunReader, fileSha256, findContextRoot, findSessionTextLeaks, findSpanSourceFiles, findingRejection, findingRejectionDetail, findingReplayStep, findingTrajectoryId, forEachTreeNode, formatFindingRejections, generateFixCommand, goldIncorrectSteps, haloAnalyzer, hashSessionBundleFiles, hodoscopeAnalyzer, httpJsonTransport, importCodeTraceBench, incompleteInputsNote, indexSessionIdsByTrace, inferRole, inferSpanKind, ingestCodeTraceBenchSteps, inspectSessionIndex, int, isBridgeMismatchError, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, isInheritedSpan, isSubmitAction, isSynthesizedSpan, knownHarnesses, listAdapters, listSessionBundleFiles, loadState, loadTraceQuestionsFile, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeAnalystCitations, normalizeRemote, normalizeTraceQuestions, otlpRowToSpan, outboundHash, parseCorpusFlag, parseIncorrectStepsSubject, parseIsoToEpochMs, parseJsonAnswer, parseObservationOutput, parseRecordedReturncode, parseReplayBatchArgs, parseReplayVerifyArgs, parseSession, parseSince, parseVerifyFindingsArgs, planTraceAgenticRoute, planUpload, primeAnalyzer, projectSessionBundle, readCoordinationLog, readFileRunContext, readFindingsFile, readJsonFile, readJsonl, readLabelEntries, readOtlpInput, readPullRequests, readRunContextJournal, readRunContextSnapshot, readRunWatchSnapshot, readSessionBundleManifest, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderBatchReport, renderConformance, renderInspectionReport, renderRunContextSnapshot, renderRunWatchSnapshot, renderSessionFacts, renderSessionFactsContext, renderSpanRunSnapshot, renderTraceQuestionInstructions, renderTraceQuestionPrompt, renderTraceQuestionsReport, renderValidation, renderVerifiedFindingsSection, replayBatchUsage, replayVerify, replayVerifyFinding, replayVerifyUsage, resolveAdapter, resolveCaseResources, resolveFindingInvocation, resolveFindingReplayability, resolveOtlpInputFiles, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runFixLoop, runPipelines, runReplayBatch, runTotals, runTraceImprovement, runTraceInvestigation, runTraceQuestions, runTraceStoreInvestigation, sandboxReplayBackend, saveReport, saveState, scanSessions, seededSample, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionFactsContext, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, sessionTextSignatures, shellCommands, skippedAnalyses, span, spanRunTotals, stampEnvironmentAttrs, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, summarizeSpanStructure, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, tokens, totalAgenticFailureMessage, totalFindingRejections, traceAgenticKinds, traceCitationsInText, traceStreamEventsFromSpans, unavailableCapabilities, uploadKey, usd, userPromptSpan, validateOtlpSpans, validationExitCode, verifyFindings, verifyFindingsUsage, watchRunTarget, watchSessions, withSessionFactsContext, wrap, wrapActionForExec, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionBundleManifest, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, writeTraceQuestionsArtifacts, zaiChatCaller, zeroPricedCost };