@tangle-network/traces 0.16.3 → 0.17.0

package/dist/cli.js

@@ -31,6 +31,7 @@ import {
   indexSessionIdsByTrace,
   inspectSessionIndex,
   isBridgeMismatchError,
+  iterSerializedSpans,
   knownHarnesses,
   loadTraceQuestionsFile,
   loadTracesConfig,
@@ -61,7 +62,6 @@ import {
   selectAdapters,
   serializePolicyEvidence,
   serializeSessionIndex,
-  serializeSpans,
   serializeTraceStreamEvent,
   sessionReportSource,
   streamSessions,
@@ -83,7 +83,7 @@ import {
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceQuestionsArtifacts
-} from "./chunk-G5KKIQZ6.js";
+} from "./chunk-4QY4U4XW.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
@@ -1194,7 +1194,7 @@ async function cmdFacts(args) {
   const collected = await collectSpans(args);
   if (collected.spans.length === 0) throw new Error("no spans found for the given selection");
   warnIncompleteWorkflow(collected.workflow);
-  const report = buildSessionFactsReport(collected.spans, { harness: collected.harness });
+  const report = buildSessionFactsReport(collected.spans, { harness: collected.harness, includeContent: !args.noContent });
   const unread = report.sessions.filter((facts) => facts.recordSpans === 0);
   if (unread.length > 0) {
     throw new Error(
@@ -1234,7 +1234,7 @@ async function cmdExport(args) {
     return;
   }
   const result = await exportTraceEvidenceFile(args.input, { format, attributes });
-  process.stdout.write(serializeSpans(result.spans));
+  for (const line of iterSerializedSpans(result.spans)) process.stdout.write(line);
 }
 async function cmdImportCodeTraceBench(args) {
   if (!args.input) {
@@ -2110,7 +2110,8 @@ Options:
   --window <m>     watch/stream: only sessions active in the last N minutes (default 30)
   --min-loop <n>   Min identical repeated calls to flag a loop (default 3)
   --dry-run        upload: redact + dedup + preview, write OTLP, but do NOT send
-  --no-content     upload: strip prompt/response text; send metadata only
+  --no-content     facts: omit conversation, commands, paths and assignments;
+                   upload: strip prompt/response text; send metadata only
   --redactor <cmd> upload: external PII scrubber (JSON array stdin\u2192stdout) after the redaction core
   --yes, -y        upload: skip the confirmation prompt
   --version, -v    Print the installed traces version

package/dist/index.d.ts

@@ -355,9 +355,18 @@ declare const EXPORT_RULE: Readonly<Record<SubstitutedField, ExportRule>>;
 declare function toOpenInferenceSpan(s: OtlpSpan): Record<string, unknown>;
 /** Serialize spans to OpenInference JSONL (one complete span per line). This is a
  *  standard OpenInference representation: it feeds our analysts, HALO, and other
- *  OpenInference tools directly — no per-tool conversion. */
+ *  OpenInference tools directly — no per-tool conversion.
+ *
+ *  The returned string is the WHOLE export; for span counts whose export can
+ *  approach V8's maximum string length, iterate {@link iterSerializedSpans}
+ *  instead so the export never has to exist as one allocation. */
 declare function serializeSpans(spans: readonly OtlpSpan[]): string;
-/** Write spans to an OTLP-JSONL file (a temp file when no path is given). */
+/** Yield the export one span line at a time (each line ends in `\n`), so a
+ *  writer stays bounded no matter how many spans it is handed. */
+declare function iterSerializedSpans(spans: readonly OtlpSpan[]): Generator<string>;
+/** Write spans to an OTLP-JSONL file (a temp file when no path is given), one
+ *  bounded chunk at a time — never the whole export as one string, so a
+ *  session larger than V8's string limit still exports. */
 declare function writeOtlpFile(spans: readonly OtlpSpan[], outPath?: string): Promise<string>;
 
 interface JsonlCorruptionReceipt {
@@ -1870,6 +1879,9 @@ interface AdoptionOptions {
      *  passes the cwds of the analyzed sessions. */
     cwds?: readonly string[];
 }
+/** Pure span evidence. Repository history is added only by analyzeAdoption. */
+declare function computeAdoption(spans: readonly OtlpSpan[]): AdoptionReport;
+/** Add only explicitly requested repository history to the same span measurements. */
 declare function analyzeAdoption(spans: readonly OtlpSpan[], opts?: AdoptionOptions): Promise<AdoptionReport>;
 
 type TraceAgenticRouteReasonCode = 'requested-baseline' | 'execution-failures' | 'repeated-tool-loops' | 'corrective-human-feedback';
@@ -3507,6 +3519,66 @@ declare function renderTraceQuestionsReport(result: Omit<TraceQuestionsResult, '
 /** Write `answers.json` and `report.md` next to the trace file the engine read. */
 declare function writeTraceQuestionsArtifacts(result: TraceQuestionsResult, outDir: string): Promise<TraceQuestionsArtifacts>;
 
+/** Coverage counts refer to observed records, never an assertion that capture was complete. */
+interface CoveredMeasurement {
+    readonly total: number | null;
+    readonly measured: number;
+    readonly eligible: number;
+    readonly unavailable: string | null;
+}
+interface ToolMeasurement {
+    readonly name: string;
+    readonly calls: number;
+    readonly outcomes: {
+        readonly ok: number;
+        readonly error: number;
+        readonly unset: number;
+    };
+    readonly inputBytes: CoveredMeasurement;
+    readonly outputBytes: CoveredMeasurement;
+    /** Recorded call-to-result interval. Not CPU time or model latency; overlaps may occur. */
+    readonly callToResultMs: CoveredMeasurement;
+    readonly spanIds: readonly string[];
+}
+interface CompactionMeasurement {
+    readonly spanId: string;
+    readonly at: string;
+    readonly sincePreviousMs: number | null;
+    readonly latencyMs: number | null;
+    readonly tokensBefore: number | null;
+    readonly tokensAfter: number | null;
+}
+interface ContentFootprint {
+    readonly spanId: string;
+    readonly field: string;
+    readonly bytes: number;
+    readonly lines: number;
+    readonly entries: number | null;
+    /** Source representation, not the reconstructed full model request. */
+    readonly scope: 'captured-attribute';
+}
+interface SessionMeasurements {
+    readonly execution: ExecutionReport | null;
+    readonly adoption: AdoptionReport;
+    readonly relationship: SessionRelationship;
+    readonly tools: readonly ToolMeasurement[];
+    readonly observedSpawns: number;
+    readonly spawnIntervalsMs: readonly {
+        readonly spanId: string;
+        readonly intervalMs: number | null;
+    }[];
+    readonly compactions: SessionFact<readonly CompactionMeasurement[]>;
+    readonly contextFootprints: readonly ContentFootprint[];
+    readonly coverage: {
+        readonly profile: string;
+        readonly materializedResources: string;
+        readonly contextTokens: string;
+        readonly toolTokens: string;
+        readonly compaction: string;
+        readonly semanticAssessments: string;
+    };
+}
+
 /**
  * Which pull requests a session created, and which it merged.
  *
@@ -3621,6 +3693,12 @@ declare function readPullRequests(spans: readonly OtlpSpan[]): PullRequestReadin
  * {@link SessionFacts.tokenTotal} states that rather than summing the per-turn
  * deltas, which is a different (and smaller) number.
  */
+/** Cache invalidation key for deterministic measurements and prepared analyst context. */
+declare const SESSION_FACTS_MEASUREMENT_VERSION = "3";
+interface SessionFactsOptions {
+    /** Defaults to true for compatibility. False withholds conversation, commands, paths and assignment text. */
+    readonly includeContent?: boolean;
+}
 declare const SESSION_TOKEN_TOTAL_ATTR = "traces.session.total_tokens";
 /**
  * The first marker an adapter used for a span it created to describe a
@@ -3772,11 +3850,18 @@ interface SessionFacts {
      * Failures that ended at the same instant are `ambiguous`, never guessed.
      */
     readonly firstFailure: FirstFailure;
+    readonly measurements: SessionMeasurements;
 }
 interface SessionFactsReport {
     readonly schemaVersion: 1;
     readonly kind: 'traces.session_facts_report';
     readonly generatedAt: string;
+    readonly measurementVersion: typeof SESSION_FACTS_MEASUREMENT_VERSION;
+    /** SHA-256 of the canonical selected spans, including content, attributes, links and timing. */
+    readonly sourceDigest: string;
+    /** Latest recorded endpoint, not the last time the filesystem was checked. */
+    readonly evidenceThrough: string | null;
+    readonly contentIncluded: boolean;
     readonly harness: string | null;
     readonly spanCount: number;
     readonly sessions: readonly SessionFacts[];
@@ -3786,9 +3871,9 @@ interface SessionFactsReport {
  * 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[];
+declare function computeSessionFacts(spans: readonly OtlpSpan[], options?: SessionFactsOptions): SessionFacts[];
 /** The facts sheet for a set of spans, as one report. */
-declare function buildSessionFactsReport(spans: readonly OtlpSpan[], options?: {
+declare function buildSessionFactsReport(spans: readonly OtlpSpan[], options?: SessionFactsOptions & {
     harness?: string | null;
     generatedAt?: string;
 }): SessionFactsReport;
@@ -3834,7 +3919,7 @@ declare function sessionFactsContext(spans: readonly OtlpSpan[], options?: {
  * 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.2";
+declare const SESSION_FACTS_VERSION_SUFFIX: string;
 /**
  * Supply the sheet to every definition as prepared context, before the model
  * runs. A definition that already prepares context keeps it; the sheet is
@@ -3976,26 +4061,33 @@ declare function hodoscopeAnalyzer(options?: HodoscopeAnalyzerOptions): External
  * one-shot RLM over the OTLP-JSONL artifact through an OpenAI-compatible
  * bridge (cli-bridge's prime backend, or any `/v1/chat/completions` endpoint).
  *
- * Protocol, in one pass with no tools:
- *   1. The FULL span projection is inlined into the prompt as JSON — prime has
- *      no REPL and no trace tools, so unlike the dspy-rlm analysts (which
- *      drill via viewSpans/searchTrace) every fact must travel in the prompt.
- *   2. The reply contract is one fenced ```json block of SHORT strings
- *      (long strings get corrupted in transport), citing span ids verbatim.
- *   3. A structurally malformed reply gets ONE bounded stateless repair turn
- *      carrying the malformed reply plus the contract — never the trajectory —
- *      mirroring the typed-adapter repair the dspy arm gets, so both arms face
- *      the same structured-output affordance.
- *   4. Cited span ids are resolved against the artifact; rows citing unknown
- *      or ambiguous ids are rejected with a recorded reason, never guessed.
- *      Zero findings from a well-formed reply is an honest null, not an error.
- *
- * Oversized traces: when the rendered projection exceeds the inline budget it
- * is re-rendered with a per-attribute character cap (the prompt-side analog of
- * the trace store's per-attribute byte cap); if still oversized the run fails
- * loud — inline delivery is the only delivery, so silently dropping spans
- * would understate the trajectory. The delivery decision is recorded in the
- * result output.
+ * Delivery, small traces first:
+ *   1. INLINE — the full span projection is inlined into the prompt as JSON.
+ *      Cheap and bridge-portable, but bounded: past `maxInlineChars` the
+ *      projection is re-rendered with a per-attribute character cap (the
+ *      prompt-side analog of the trace store's per-attribute byte cap).
+ *   2. FILE — when even the capped render overflows the budget, the artifact
+ *      is copied into a per-run directory and that directory is passed as
+ *      `cwd` on the chat-completions request (cli-bridge starts prime there).
+ *      Prime is a recursive language model with a REPL, so the prompt tells
+ *      it to load `trajectory.otlp.jsonl` itself and fan out with `rlm()` —
+ *      the trajectory travels as a file, not as prompt bytes. A bridged
+ *      prime must be able to READ that directory (host-mode bridges do; a
+ *      jailed or remote bridge needs the dir registered/uploaded on the
+ *      bridge side — cli-bridge's jail already covers its own dirs).
+ *
+ * Reply contract, both modes: one fenced ```json block of SHORT strings
+ * (long strings get corrupted in transport), citing span ids verbatim.
+ *   - A structurally malformed reply gets ONE bounded stateless repair turn
+ *     carrying the malformed reply plus the contract — never the trajectory —
+ *     mirroring the typed-adapter repair the dspy arm gets, so both arms face
+ *     the same structured-output affordance.
+ *   - Cited span ids are resolved against the artifact in BOTH delivery
+ *     modes; rows citing unknown or ambiguous ids are rejected with a recorded
+ *     reason, never guessed. Zero findings from a well-formed reply is an
+ *     honest null, not an error.
+ *
+ * The delivery decision is recorded in the result output.
  *
  * Usage (bridge-reported token counts and call count) is recorded in the
  * result output; cost stays uncaptured because the bridge reports no priced
@@ -4010,6 +4102,9 @@ interface PrimeTransportRequest {
             role: 'user';
             content: string;
         }>;
+        /** File delivery: the per-run directory the artifact was copied into;
+         *  cli-bridge starts prime here, so `trajectory.otlp.jsonl` resolves. */
+        cwd?: string;
     };
     /** Aborts on the analyzer's deadline AND the caller's signal. */
     signal: AbortSignal;
@@ -4035,6 +4130,11 @@ interface PrimeAnalyzerOptions {
     maxInlineChars?: number;
     /** Character cap applied to each attribute on the oversized re-render. */
     perAttributeCharCap?: number;
+    /** How the trajectory reaches prime. `auto` (default) inlines when it fits
+     *  the budget and falls back to file delivery when it does not; `file`
+     *  always ships the artifact as `cwd` + `trajectory.otlp.jsonl`; `inline`
+     *  keeps the legacy refusal when the capped render still overflows. */
+    delivery?: 'auto' | 'file' | 'inline';
     /** Disable the bounded repair turn (one extra call on a malformed reply). */
     repair?: boolean;
     transport?: PrimeTransport;
@@ -4834,4 +4934,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 AnalysisEngineFromEnvOptions, type AnalyzeOptions, type AnalyzeResult, type AnswerSchema, type AssembleSessionBundleOptions, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CHANGED_FILE_LIST_CAP, CITATION_NORMALIZATION_VERSION, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type ChangedFileFact, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, type CodeTraceBenchFileRef, type CodeTraceBenchImportOptions, type CodeTraceBenchImportReceipt, type CodeTraceBenchImportResult, type CodeTraceBenchImportedTrace, type CodeTraceBenchStep, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, type ConformanceRenderOptions, type CoordinationLog, type CoordinationQuestion, type CoordinationSteer, CopilotAdapter, type CorruptionMode, DEFAULT_ANALYST_MODEL, DEFAULT_ASK_CONCURRENCY, DEFAULT_HARNESS, DEFAULT_SANDBOX_BASE_URL, EMPTY_SPAN_RUN_SNAPSHOT, EXPORT_RULE, EmptySessionError, type EvidenceOnlyVerdict, 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 FailureFollowUp, type FailureFollowUpReport, type FileRunContextReaderOptions, type FinalMessageFact, type FindSessionTextLeaksOptions, type FindingRejectionCounts, type FindingRejectionReasons, type FindingRejectionTally, 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 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 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 RedactSpansOptions, type Redactor, type RefusedSession, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedOtlpInput, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunDiffOptions, type RunDiffReport, type RunDiffSide, 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, SYNTHESIZED_SOURCE_ATTR, SYNTHESIZED_SPAN_ATTR, type SandboxReplayBackendOptions, type ScanOptions, type ScannedSession, type SessionBatch, type SessionBundleAbsence, type SessionBundleCarriedSignatures, type SessionBundleExclusion, type SessionBundleExclusionRule, type SessionBundleFile, type SessionBundleIssue, type SessionBundleIssueKind, type SessionBundleLeakCheck, type SessionBundleLedgerSlice, type SessionBundleManifest, type SessionBundleProjection, type SessionBundleResult, type SessionBundleSliceRule, type SessionBundleVerification, 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, 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 VerifySafeOptions, type VerifySafeResult, type WatchRunTargetOptions, ZERO_ROLL, type ZaiChatCallerOptions, addSpend, alreadyUploaded, analysisEngineFromEnv, analyzeAdoption, analyzeLiveBatch, analyzeLoopConvergence, analyzeReactions, analyzeSpans, analyzeSteeringChain, answerSchemaErrors, applyRedactor, assembleSessionBundle, assertAnswerSchema, assertSandboxReachable, assessSpans, buildPolicyEvidenceRecord, buildSessionFactsReport, buildSessionIndex, buildSessionIndexFromRows, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyEvidenceOnlyPath, classifyFailureFollowUps, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, commandTextFromInput, computeSessionFacts, conformanceOfSpans, connectors, countSkillRunsJsonl, createBundleSourceReader, createFindingRejectionTally, cwdMatchesSelection, cwdMatchesSelectionResolved, defaultTraceLiveAnalysts, describeSessionRelationship, diffRuns, engineCallReservationFloorUsd, environmentAttributes, environmentFromSpanAttributes, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, externalFailureMessage, fileRunContextSupervisorRunReader, fileSha256, findContextRoot, findSessionTextLeaks, findSpanSourceFiles, findingRejection, findingRejectionDetail, forEachTreeNode, formatFindingRejections, formatVerdict, haloAnalyzer, hashSessionBundleFiles, hodoscopeAnalyzer, httpJsonTransport, importCodeTraceBench, incompleteInputsNote, indexSessionIdsByTrace, inferRole, inferSpanKind, inspectSessionIndex, int, isBridgeMismatchError, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, isInheritedSpan, isSynthesizedSpan, knownHarnesses, listAdapters, listSessionBundleFiles, loadState, loadTraceQuestionsFile, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeAnalystCitations, normalizeRemote, normalizeTraceQuestions, otlpRowToSpan, outboundHash, parseIsoToEpochMs, parseJsonAnswer, parseSession, parseSince, planTraceAgenticRoute, planUpload, primeAnalyzer, projectSessionBundle, readCoordinationLog, readFileRunContext, readJsonFile, readJsonl, readOtlpInput, readPullRequests, readRunContextJournal, readRunContextSnapshot, readRunSide, readRunWatchSnapshot, readSessionBundleManifest, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderConformance, renderInspectionReport, renderRunContextSnapshot, renderRunDiff, renderRunWatchSnapshot, renderSessionFacts, renderSessionFactsContext, renderSpanRunSnapshot, renderTraceQuestionInstructions, renderTraceQuestionPrompt, renderTraceQuestionsReport, renderValidation, resolveAdapter, resolveOtlpInputFiles, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTotals, runTraceImprovement, runTraceInvestigation, runTraceQuestions, runTraceStoreInvestigation, sandboxReplayBackend, saveReport, saveState, scanSessions, 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, verdictExitCode, verifyFindingsInSandbox, verifySafe, verifySessionBundle, watchRunTarget, watchSessions, withSessionFactsContext, wrap, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionBundleManifest, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, writeTraceQuestionsArtifacts, zaiChatCaller, zeroPricedCost };
+export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalysisEngineFromEnvOptions, type AnalyzeOptions, type AnalyzeResult, type AnswerSchema, type AssembleSessionBundleOptions, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CHANGED_FILE_LIST_CAP, CITATION_NORMALIZATION_VERSION, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type ChangedFileFact, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, type CodeTraceBenchFileRef, type CodeTraceBenchImportOptions, type CodeTraceBenchImportReceipt, type CodeTraceBenchImportResult, type CodeTraceBenchImportedTrace, type CodeTraceBenchStep, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, type CompactionMeasurement, type ConformanceRenderOptions, type ContentFootprint, type CoordinationLog, type CoordinationQuestion, type CoordinationSteer, CopilotAdapter, type CorruptionMode, type CoveredMeasurement, DEFAULT_ANALYST_MODEL, DEFAULT_ASK_CONCURRENCY, DEFAULT_HARNESS, DEFAULT_SANDBOX_BASE_URL, EMPTY_SPAN_RUN_SNAPSHOT, EXPORT_RULE, EmptySessionError, type EvidenceOnlyVerdict, 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 FailureFollowUp, type FailureFollowUpReport, type FileRunContextReaderOptions, type FinalMessageFact, type FindSessionTextLeaksOptions, type FindingRejectionCounts, type FindingRejectionReasons, type FindingRejectionTally, 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 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 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 RedactSpansOptions, type Redactor, type RefusedSession, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedOtlpInput, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunDiffOptions, type RunDiffReport, type RunDiffSide, type RunResult, type RunWatchSnapshot, type RunWatchTarget, type RuntimeTrace, SESSION_FACTS_MEASUREMENT_VERSION, SESSION_FACTS_VERSION_SUFFIX, SESSION_TOKEN_TOTAL_ATTR, SOURCE_ATTRIBUTE_PREFIX, SPAN_SYNTHESIZED_ATTR, SPAWN_JOURNAL_FILE, STATUS_MARK, SYNTHESIZED_SOURCE_ATTR, SYNTHESIZED_SPAN_ATTR, type SandboxReplayBackendOptions, type ScanOptions, type ScannedSession, type SessionBatch, type SessionBundleAbsence, type SessionBundleCarriedSignatures, type SessionBundleExclusion, type SessionBundleExclusionRule, type SessionBundleFile, type SessionBundleIssue, type SessionBundleIssueKind, type SessionBundleLeakCheck, type SessionBundleLedgerSlice, type SessionBundleManifest, type SessionBundleProjection, type SessionBundleResult, type SessionBundleSliceRule, type SessionBundleVerification, type SessionBundleView, type SessionCorruptionReceipt, type SessionEnvironment, type SessionFact, type SessionFacts, type SessionFactsOptions, type SessionFactsReport, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionMeasurements, 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, TRACE_QUESTION_PREVIEW_HEAD_CHARS, type ToolMeasurement, 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 VerifySafeOptions, type VerifySafeResult, type WatchRunTargetOptions, ZERO_ROLL, type ZaiChatCallerOptions, addSpend, alreadyUploaded, analysisEngineFromEnv, analyzeAdoption, analyzeLiveBatch, analyzeLoopConvergence, analyzeReactions, analyzeSpans, analyzeSteeringChain, answerSchemaErrors, applyRedactor, assembleSessionBundle, assertAnswerSchema, assertSandboxReachable, assessSpans, buildPolicyEvidenceRecord, buildSessionFactsReport, buildSessionIndex, buildSessionIndexFromRows, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyEvidenceOnlyPath, classifyFailureFollowUps, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, commandTextFromInput, computeAdoption, computeSessionFacts, conformanceOfSpans, connectors, countSkillRunsJsonl, createBundleSourceReader, createFindingRejectionTally, cwdMatchesSelection, cwdMatchesSelectionResolved, defaultTraceLiveAnalysts, describeSessionRelationship, diffRuns, engineCallReservationFloorUsd, environmentAttributes, environmentFromSpanAttributes, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, externalFailureMessage, fileRunContextSupervisorRunReader, fileSha256, findContextRoot, findSessionTextLeaks, findSpanSourceFiles, findingRejection, findingRejectionDetail, forEachTreeNode, formatFindingRejections, formatVerdict, haloAnalyzer, hashSessionBundleFiles, hodoscopeAnalyzer, httpJsonTransport, importCodeTraceBench, incompleteInputsNote, indexSessionIdsByTrace, inferRole, inferSpanKind, inspectSessionIndex, int, isBridgeMismatchError, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, isInheritedSpan, isSynthesizedSpan, iterSerializedSpans, knownHarnesses, listAdapters, listSessionBundleFiles, loadState, loadTraceQuestionsFile, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeAnalystCitations, normalizeRemote, normalizeTraceQuestions, otlpRowToSpan, outboundHash, parseIsoToEpochMs, parseJsonAnswer, parseSession, parseSince, planTraceAgenticRoute, planUpload, primeAnalyzer, projectSessionBundle, readCoordinationLog, readFileRunContext, readJsonFile, readJsonl, readOtlpInput, readPullRequests, readRunContextJournal, readRunContextSnapshot, readRunSide, readRunWatchSnapshot, readSessionBundleManifest, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderConformance, renderInspectionReport, renderRunContextSnapshot, renderRunDiff, renderRunWatchSnapshot, renderSessionFacts, renderSessionFactsContext, renderSpanRunSnapshot, renderTraceQuestionInstructions, renderTraceQuestionPrompt, renderTraceQuestionsReport, renderValidation, resolveAdapter, resolveOtlpInputFiles, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTotals, runTraceImprovement, runTraceInvestigation, runTraceQuestions, runTraceStoreInvestigation, sandboxReplayBackend, saveReport, saveState, scanSessions, 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, verdictExitCode, verifyFindingsInSandbox, verifySafe, verifySessionBundle, watchRunTarget, watchSessions, withSessionFactsContext, wrap, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionBundleManifest, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, writeTraceQuestionsArtifacts, zaiChatCaller, zeroPricedCost };

package/dist/index.js

@@ -44,6 +44,7 @@ import {
   REACTIONS,
   RESULT_FILE,
   RULE,
+  SESSION_FACTS_MEASUREMENT_VERSION,
   SESSION_FACTS_VERSION_SUFFIX,
   SESSION_TOKEN_TOTAL_ATTR,
   SOURCE_ATTRIBUTE_PREFIX,
@@ -91,6 +92,7 @@ import {
   commandAnalyzer,
   commandRedactor,
   commandTextFromInput,
+  computeAdoption,
   computeSessionFacts,
   conformanceOfSpans,
   connectors,
@@ -138,6 +140,7 @@ import {
   isFileRunContextDir,
   isInheritedSpan,
   isSynthesizedSpan,
+  iterSerializedSpans,
   knownHarnesses,
   listAdapters,
   listSessionBundleFiles,
@@ -267,7 +270,7 @@ import {
   writeTraceQuestionsArtifacts,
   zaiChatCaller,
   zeroPricedCost
-} from "./chunk-G5KKIQZ6.js";
+} from "./chunk-4QY4U4XW.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {
@@ -345,6 +348,7 @@ export {
   REACTIONS,
   RESULT_FILE,
   RULE,
+  SESSION_FACTS_MEASUREMENT_VERSION,
   SESSION_FACTS_VERSION_SUFFIX,
   SESSION_TOKEN_TOTAL_ATTR,
   SOURCE_ATTRIBUTE_PREFIX,
@@ -395,6 +399,7 @@ export {
   commandAnalyzer,
   commandRedactor,
   commandTextFromInput,
+  computeAdoption,
   computeSessionFacts,
   conformanceOfSpans,
   connectors,
@@ -444,6 +449,7 @@ export {
   isFileRunContextDir,
   isInheritedSpan,
   isSynthesizedSpan,
+  iterSerializedSpans,
   knownHarnesses,
   listAdapters,
   listSessionBundleFiles,

package/docs/trace-analysts.md

@@ -353,8 +353,12 @@ Hodoscope always returns `discovery`, and each candidate has `status: 'needs_rev
 ### Prime engine
 
 `--analyzer prime` runs a one-shot analyst over the emitted OTLP artifact through an OpenAI-compatible bridge, such as cli-bridge's prime backend.
-Unlike the `--llm` analysts, which drill into the trace with paged tools, prime has no REPL and no trace tools: the full span projection is inlined into a single prompt as JSON.
-Oversized projections are re-rendered with a per-attribute character cap; if the projection still exceeds the inline budget the engine fails loud instead of silently dropping spans.
+Unlike the `--llm` analysts, which drill into the trace with paged tools, prime is a recursive language model with its own REPL, so the trajectory reaches it one of two ways:
+
+- **Inline (small traces):** the full span projection is inlined into a single prompt as JSON. Oversized projections are re-rendered with a per-attribute character cap.
+- **File (large traces):** when even the capped projection exceeds the inline budget, the artifact is copied into a per-run directory, that directory is sent as `cwd` on the chat-completions request (cli-bridge starts prime there), and the prompt tells prime to load `trajectory.otlp.jsonl` itself and fan out with `rlm()` — so the trajectory travels as a readable file, not prompt bytes, and no trace is refused for size. The bridge must be able to read that directory: host-mode bridges do by construction; a jailed or remote bridge needs the directory registered or uploaded on the bridge side.
+
+Span-id grounding is identical in both modes: every cited id is validated against the artifact, and the delivery decision is recorded in the result output.
 
 Prerequisites:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.16.3",
-  "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, …) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite — observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
+  "version": "0.17.0",
+  "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, \u2026) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite \u2014 observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -61,11 +61,11 @@
     "prepublishOnly": "pnpm check:source && pnpm build && pnpm check:package"
   },
   "dependencies": {
-    "@tangle-network/agent-eval": "0.197.0",
-    "@tangle-network/agent-interface": "2.12.0",
-    "@tangle-network/agent-runtime": "0.277.0",
-    "@tangle-network/agent-trace-contract": "1.3.0",
-    "@tangle-network/sandbox": "0.45.0"
+    "@tangle-network/agent-eval": "0.205.1",
+    "@tangle-network/agent-interface": "2.17.0",
+    "@tangle-network/agent-runtime": "0.293.0",
+    "@tangle-network/agent-trace-contract": "2.0.0",
+    "@tangle-network/sandbox": "0.60.10"
   },
   "devDependencies": {
     "@types/node": "^22.20.4",

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

@@ -9,37 +9,30 @@ Use the deterministic CLI first; keep inspection local and read-only.
 
 ## Choose the way in
 
-If the trace is already OTLP (any `@tangle-network/agent-trace-contract` emitter or other
-conforming exporter), read it directly. No adapter is involved.
+Read conforming OTLP directly, including `@tangle-network/agent-trace-contract` exports.
 
 ```bash
-traces validate spans.otlp.jsonl          # what can this trace answer? exit 1 on error findings
+traces validate spans.otlp.jsonl          # exit 1 on error findings
 traces analyze --otlp spans.otlp.jsonl --out .traces/current.md
 traces analyze --otlp results/sessions --out .traces/all.md   # a directory of exports
 ```
 
-Use `--harness` only for coding agents whose on-disk format we do not control.
-Those adapters are the legacy edge, not the way to integrate a system you own.
+Use `--harness` for native coding-agent formats; integrate systems you own through OTLP.
 
-In a run directory only the OTLP files are read; other `*.jsonl` logs are listed with
-what they hold. An `otlp/` subdirectory, when present, is read on its own.
+Directories read only OTLP files, preferring an `otlp/` subdirectory; other JSONL logs are listed separately.
 
-A section headed `inputs incomplete`, or carrying an `Inputs incomplete` line above its
-table, is computed from a field the trace does not carry everywhere. Report those numbers
-as uncaptured, never as zero spend. The `trace conformance` section names each such
-capability once; the markers repeat it at the number.
+Report `Inputs incomplete` values as uncaptured, never zero spend.
+The `trace conformance` section lists missing capabilities.
 
-For a loop trace, read `round-over-round convergence` (did round N+1 improve on N) and
-`steering chain` (which verdict caused which retry) before drawing any conclusion about
-whether the agent was making progress.
+For loops, inspect `round-over-round convergence` and `steering chain` before judging progress.
 
 ## Select the workflow
 
 ```bash
 traces --version
 traces list --harness codex --cwd "$PWD"
-traces analyze --harness codex --current --latest-turn --workflow \
-  --out .traces/current.md
+traces facts --harness codex --current --latest-turn --workflow \
+  --format text --out .traces/current-facts.txt
 ```
 
 - Use `--current` for the active Codex session.
@@ -50,6 +43,19 @@ traces analyze --harness codex --current --latest-turn --workflow \
 - For Claude Code, use `--harness claude-code --session <path> --latest-turn`; nested subagents are included.
 
 Never join agents by display name or timestamp when Traces reports missing or conflicting IDs.
+Read facts before full transcripts or analysis.
+Check parent and worker counts against the task being investigated.
+Run `analyze` only for questions the facts sheet cannot answer:
+
+```bash
+traces analyze --harness codex --current --latest-turn --workflow \
+  --out .traces/current.md
+```
+
+For moved evidence, keep byte-identical transcripts and record their source paths and hashes.
+Preserve Claude's `<session UUID>/subagents/workflows/<run ID>` subtree beside the copied parent JSONL file.
+Restore missing child files from the source; rewriting recorded paths loses the original evidence.
+Check current branches, edits, commits, and PRs before reporting unfinished work; transcripts describe past actions.
 
 ## Export
 
@@ -70,41 +76,37 @@ traces improve --harness codex --current --latest-turn --workflow \
 `improve` writes findings, evidence, a report, and spans.
 It edits no agent, repository, memory store, or knowledge base.
 
-Write one session's durable evidence directory for a later reader:
+Preserve a session for later inspection:
 
 ```bash
 traces bundle --harness claude-code --session <id-or-path> --out .traces/bundle
 ```
 
-`bundle` copies the transcript, the derived report and spans, the `.evolve` ledger rows inside the session window, and a `manifest.json` with a SHA-256 per file.
-It spends no model call.
-A missing transcript stops the assembly; an absent optional input is recorded in `manifest.absent` with the probed path.
+`bundle` copies transcripts, report, spans, and session-window `.evolve` rows with per-file SHA-256 hashes.
+It uses no model calls.
+Missing transcripts stop assembly; optional missing inputs appear in `manifest.absent`.
 
 ## Pick the view for the reader
 
-That bundle is the FULL view (`manifest.view: "full"`) and holds the whole session transcript.
-Never give it to a writer that must not see an earlier conclusion: the transcript holds the text of every file the session wrote, so a check for the earlier report FILE passes while its CONTENT is still readable.
-
-Project the writer's copy instead:
+The full bundle includes transcripts containing prior reports, even when report files are removed.
+For a writer who must not see earlier conclusions, project an evidence-only copy:
 
 ```bash
 traces bundle-view .traces/bundle --view evidence-only --out .traces/writer
 ```
 
-It carries `derived/session-index.json`, `derived/evidence.jsonl`, and the structured `ledger/` records.
-It excludes the transcripts, report, spans, and every prose ledger file by name, with the rules and hashes in `manifest.excluded`.
-It also drops any carried file that repeats an 8-word run of prose from an excluded one.
-`manifest.view` names which copy you hold.
+This retains the session index, evidence JSONL, and structured ledger records.
+It excludes transcripts, reports, spans, prose ledgers, and files repeating an eight-word passage from excluded prose.
+Check `manifest.view` and the rules and hashes in `manifest.excluded`.
 
 ## Ask your own question
 
-`traces ask --last 1 --question "<text>" --budget 2 --dir .traces/ask` keeps the engine's
-prose answer, resolves every `trace://` citation in it, and spends model calls to do it.
+`traces ask --last 1 --question "<text>" --budget 2 --dir .traces/ask` spends model calls and resolves answer citations.
 
 ## Report
 
 - State the source (`--otlp <path>` or the harness), selected task boundary, session and span counts, and integrity warnings.
-- State which capabilities the trace could not support, and name the analyses that reported nothing because of it.
+- Name missing capabilities and analyses affected by them.
 - Cite each finding with its exact `trace://` reference.
 - Mark missing outcome, cost, token, skill, or relationship data unknown.
 - Do not infer task success from a completion message.

package/docs/replay-batch-20260802.md

@@ -1,76 +0,0 @@
-# Replay-verify batch — first measured replayability and fix-flip rates (2026-08-02)
-
-Provenance: labels shas in `~/bench-cache/ctb-20260801/replay-batch/label-shas.txt`; docker 29.6.1; node v24.16.0; orchestrator :4095 + SDK adapter :4097; seed 17; fix model glm-5.2 via z.ai direct (16k cap, one doubled retry on length-empty); command recorded in `run2-20260802.log` header.
-Corpora: dev-32, holdout-1, holdout-2, split3 (all spent mini-SWE splits; submit-only golds excluded per the split3 positional-degeneracy finding).
-
-## Headline (n=22 replayable of 133 label entries)
-
-| Rate | Value |
-| --- | --- |
-| Replayability (prefix ≤10% divergence AND arm A reproduces recorded returncode at the gold step) | 16/22 = 72.7% |
-| Strict signature match (returncode + output substring) | 13/22 = 59.1% |
-| Fix-flip (one-shot glm-5.2 corrected command makes the failure vanish) | 9/11 = 81.8% |
-| Fix-flip, nonzero-returncode subset | 7/9 = 77.8% |
-
-Exclusions (101 of 133, all named): 65 no-swe-raw-trajectory, 21 no-docker-image, 21 gold-only-submit-step, 4 no-gold-incorrect-step.
-LLM: 16 calls, 5 residual failures (long-reasoning cases exceeding the doubled cap), 41,878 prompt + 51,312 completion tokens (~$0.14).
-
-
-Generated 2026-08-02T00:55:37.309Z.
-
-## Headline
-
-- **Replayability rate: 72.7%** (16/22 replayable cases where the prefix replayed with ≤10% returncode divergence AND arm A reproduced the recorded returncode at the gold step k).
-- Signature-strict rate: 59.1% (13/22; additionally requires the recorded error substring in arm A output).
-- **Fix-flip rate: 81.8%** (9/11 arm-B-executed cases where the generated fix made the failure vanish).
-- Fix-flip rate on recorded-rc≠0 cases: 77.8% (7/9; real recorded failures — a gold step recorded with rc 0 flips vacuously).
-
-## Enumeration
-
-133 label entries across 4 corpora → 22 replayable (SWE-style docker image + ≥1 gold incorrect step), 22 executed.
-
-| exclusion reason | count |
-| --- | --- |
-| no-swe-raw-trajectory | 65 |
-| no-docker-image | 21 |
-| gold-only-submit-step | 21 |
-| no-gold-incorrect-step | 4 |
-
-Submit-command golds are never counterfactual targets (a gold on the submit step marks a bad submit decision, not a failed command):
-
-| corpus | cases excluded (all golds = submit) | golds skipped within replayable cases |
-| --- | --- | --- |
-| dev-32 | 1 | 0 |
-| holdout-1 | 2 | 0 |
-| split3 | 18 | 0 |
-
-## Per-case results
-
-| corpus | trajectory | k | rc@k | prefix | div | div% | armA exit | rc match | sig match | replayed | fix | armB exit | vanished | wall s |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-holdout-1 | miniswe-OpenAI__GPT-5-clap-rs__clap-3179-107b… | 33 | 0 | 32 | 4 | 12.5 | 0 | yes | yes | no | — | — | — | 10.6
-holdout-1 | miniswe-OpenAI__GPT-5-clap-rs__clap-3421-8c92… | 23 | 2 | 22 | 1 | 4.5 | 2 | yes | no | **yes** | llm-failed | — | — | 7.2
-holdout-1 | miniswe-OpenAI__GPT-5-clap-rs__clap-3975-5f1a… | 33 | 101 | 32 | 1 | 3.1 | 127 | no | no | no | — | — | — | 13.0
-holdout-1 | miniswe-OpenAI__GPT-5-clap-rs__clap-4248-85bd… | 23 | 2 | 22 | 0 | 0 | 2 | yes | no | **yes** | generated | 0 | **yes** | 35.3
-holdout-2 | miniswe-OpenAI__GPT-5-instance_ansible__ansib… | 7 | 127 | 6 | 0 | 0 | 127 | yes | yes | **yes** | generated | 0 | **yes** | 20.0
-holdout-2 | miniswe-OpenAI__GPT-5-instance_ansible__ansib… | 13 | 0 | 12 | 0 | 0 | 0 | yes | yes | **yes** | llm-failed | — | — | 13.5
-holdout-2 | miniswe-OpenAI__GPT-5-instance_element-hq__el… | 17 | 2 | 16 | 0 | 0 | 2 | yes | no | **yes** | llm-failed | — | — | 25.9
-holdout-2 | miniswe-OpenAI__GPT-5-instance_internetarchiv… | 10 | 0 | 9 | 0 | 0 | 0 | yes | yes | **yes** | generated | 0 | **yes** | 4.8
-holdout-2 | miniswe-OpenAI__GPT-5-instance_qutebrowser__q… | 15 | 127 | 14 | 0 | 0 | 127 | yes | yes | **yes** | generated | 0 | **yes** | 4.1
-holdout-2 | miniswe-OpenAI__GPT-5-instance_qutebrowser__q… | 18 | 127 | 17 | 0 | 0 | 127 | yes | yes | **yes** | generated | 0 | **yes** | 4.1
-holdout-2 | miniswe-OpenAI__GPT-5-ponylang__ponyc-1057-56… | 35 | 127 | 34 | 0 | 0 | 127 | yes | yes | **yes** | generated | 0 | **yes** | 4.4
-holdout-2 | miniswe-OpenAI__GPT-5-ponylang__ponyc-2532-98… | 12 | 1 | 11 | 0 | 0 | 1 | yes | yes | **yes** | generated | 0 | **yes** | 4.4
-holdout-2 | miniswe-OpenAI__GPT-5-sveltejs__svelte-10608-… | 23 | 127 | 22 | 0 | 0 | 127 | yes | yes | **yes** | generated | 0 | **yes** | 4.7
-split3 | miniswe-OpenAI__GPT-5-fasterxml__jackson-data… | 18 | 127 | 17 | 0 | 0 | 127 | yes | yes | **yes** | generated | 127 | no | 5.7
-split3 | miniswe-OpenAI__GPT-5-instance_ansible__ansib… | 21 | 0 | 20 | 1 | 5 | 2 | no | no | no | — | — | — | 4.8
-split3 | miniswe-OpenAI__GPT-5-instance_element-hq__el… | 21 | 0 | 20 | 0 | 0 | 2 | no | no | no | — | — | — | 6.3
-split3 | miniswe-OpenAI__GPT-5-nushell__nushell-13357-… | 28 | 127 | 27 | 0 | 0 | 127 | yes | yes | **yes** | generated | 127 | no | 5.9
-split3 | miniswe-OpenAI__GPT-5-ponylang__ponyc-2205-2a… | 27 | 127 | 26 | 0 | 0 | 0 | no | no | no | — | — | — | 5.4
-split3 | miniswe-OpenAI__GPT-5-ponylang__ponyc-3973-60… | 20 | 0 | 19 | 0 | 0 | 127 | no | no | no | — | — | — | 5.8
-split3 | miniswe-OpenAI__GPT-5-simdjson__simdjson-2016… | 24 | 0 | 23 | 0 | 0 | 0 | yes | yes | **yes** | llm-failed | — | — | 5.2
-split3 | miniswe-OpenAI__GPT-5-sveltejs__svelte-11913-… | 19 | 0 | 18 | 0 | 0 | 0 | yes | yes | **yes** | generated | 0 | **yes** | 41.2
-split3 | miniswe-OpenAI__GPT-5-sveltejs__svelte-9962-5… | 21 | 127 | 20 | 0 | 0 | 127 | yes | yes | **yes** | llm-failed | — | — | 4.3
-
-## LLM fix generation
-
-Model glm-5.2: 16 calls (5 failed), 41878 prompt + 51312 completion tokens.