@tangle-network/traces 0.8.26 → 0.9.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ToolUseMetrics, InMemoryTraceStore } from '@tangle-network/agent-eval';
-import { StuckLoopReport } from '@tangle-network/agent-eval/pipelines';
+import { StuckLoopReport, FailureClusterReport } from '@tangle-network/agent-eval/pipelines';
 import { AxAIService } from '@ax-llm/ax';
+import { ExecutionReport } from '@tangle-network/agent-eval/contract';
 import { AnalystRegistry, buildDefaultAnalystRegistry, AnalystFinding, AnalystRunResult, Analyst } from '@tangle-network/agent-eval/analyst';
 export { Analyst, AnalystContext, AnalystFinding, AnalystRegistry, buildDefaultAnalystRegistry, makeFinding } from '@tangle-network/agent-eval/analyst';
 import { TraceAnalysisStore, RedactionRule, RedactionReport } from '@tangle-network/agent-eval/traces';
@@ -23,7 +24,7 @@ export { HostedClient, createHostedClient, hostedClientFromEnv } from '@tangle-n
  *   - `service.name`             → harness id (claude-code, codex, …)
  *   - `agent.name`               → agent / subagent name
  *   - `llm.model_name`           → model
- *   - `llm.input_tokens` / `llm.output_tokens` → behavioral token trajectories
+ *   - shared `llm.token_count.*` keys → input, output, reasoning, and cache usage
  *   - `tool.name`                → tool histogram (monoculture / no-verify)
  *   - `step`                     → run order (falls back to start_time)
  */
@@ -59,6 +60,11 @@ interface SpanInput {
     tool?: string | null;
     inputTokens?: number | null;
     outputTokens?: number | null;
+    /** Reasoning subset of output tokens. */
+    reasoningTokens?: number | null;
+    cachedInputTokens?: number | null;
+    cacheWriteInputTokens?: number | null;
+    costUsd?: number | null;
     /** Run-order pivot; the behavioral analyst orders trajectories by this. */
     step?: number;
     /** Verbatim content the agentic analysts read via regex search. */
@@ -85,6 +91,41 @@ declare function serializeSpans(spans: readonly OtlpSpan[]): string;
 /** Write spans to an OTLP-JSONL file (a temp file when no path is given). */
 declare function writeOtlpFile(spans: readonly OtlpSpan[], outPath?: string): Promise<string>;
 
+interface JsonlCorruptionReceipt {
+    receiptVersion: 1;
+    kind: 'jsonl_corruption';
+    status: 'degraded_not_lossless';
+    sourcePath: string;
+    /** Zero-based byte offset of the record, excluding prior line delimiters. */
+    byteOffset: number;
+    /** Exact record byte length excluding LF, but including CR when present. */
+    byteLength: number;
+    /** One-based physical line number. */
+    lineNumber: number;
+    /** SHA-256 of the exact source bytes at byteOffset/byteLength. */
+    sha256: string;
+    /** Traces retains only a fingerprint; exact bytes may be reread from the local source. */
+    rawBytes: 'local_source_only';
+}
+type JsonlReadOptions = {
+    mode?: 'strict';
+} | {
+    mode: 'recover';
+    onCorruption: (receipt: JsonlCorruptionReceipt) => void;
+};
+declare class JsonlParseError extends SyntaxError {
+    readonly sourcePath: string;
+    readonly lineNumber: number;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+    readonly sha256: string;
+    readonly receipt: JsonlCorruptionReceipt;
+    constructor(receipt: JsonlCorruptionReceipt);
+}
+/** Stream JSONL rows without retaining the source file. */
+declare function readJsonl<T>(path: string, options?: JsonlReadOptions): AsyncGenerator<T>;
+declare function takeJsonl<T>(path: string, limit: number, options?: JsonlReadOptions): Promise<T[]>;
+
 /**
  * Harness trace adapter contract.
  *
@@ -97,6 +138,19 @@ declare function writeOtlpFile(spans: readonly OtlpSpan[], outPath?: string): Pr
  * locates these files.
  */
 
+type CorruptionMode = 'recover' | 'strict';
+interface ParseOptions {
+    /** Recover valid JSONL records by default; strict rejects the first corruption. */
+    corruptionMode?: CorruptionMode;
+}
+interface SessionCorruptionReceipt extends JsonlCorruptionReceipt {
+    harness: string;
+    sessionId: string;
+}
+interface SessionIntegrity {
+    status: 'degraded_not_lossless';
+    corruptions: SessionCorruptionReceipt[];
+}
 /** A single discovered session, before parsing. */
 interface SessionRef {
     /** Harness id (matches the nix profile / backend name). */
@@ -109,6 +163,8 @@ interface SessionRef {
     cwd: string | null;
     /** Last-modified epoch ms — used for `--last N` recency ordering. */
     mtimeMs: number;
+    /** Present when parsing recovered valid records around corrupt source records. */
+    integrity?: SessionIntegrity;
 }
 interface LocateOptions {
     /** Limit discovery to sessions whose cwd matches (exact or prefix). */
@@ -124,7 +180,7 @@ interface HarnessTraceAdapter {
     /** Discover session files for this harness on disk. */
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
     /** Parse one discovered session into normalized OTLP spans. */
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
 /**
@@ -169,11 +225,46 @@ declare const ATTR: {
     readonly UPLOADER: "tangle.uploader";
     readonly REDACTION_VERSION: "redaction.version";
     readonly REDACTION_COUNT: "redaction.count";
+    /** Upload contract: bounded root summary plus location-only receipt child spans.
+     *  Receipt hashes are deliberate integrity evidence; raw malformed bytes never upload. */
+    readonly SESSION_INTEGRITY: "traces.session.integrity";
+    readonly CORRUPTION_COUNT: "traces.session.corruption_count";
+    readonly CORRUPTION_DIGEST: "traces.session.corruption_digest";
+    readonly CORRUPTION_RECEIPT_VERSION: "traces.session.corruption.receipt_version";
+    readonly CORRUPTION_RECEIPT_KIND: "traces.session.corruption.kind";
+    readonly CORRUPTION_SOURCE_PATH: "traces.session.corruption.source_path";
+    readonly CORRUPTION_LINE_NUMBER: "traces.session.corruption.line_number";
+    readonly CORRUPTION_BYTE_OFFSET: "traces.session.corruption.byte_offset";
+    readonly CORRUPTION_BYTE_LENGTH: "traces.session.corruption.byte_length";
+    readonly CORRUPTION_SHA256: "traces.session.corruption.sha256";
+    readonly RAW_SOURCE_RETENTION: "traces.session.raw_source_retention";
 };
 /** `tangle.ingest_source` value for CLI-uploaded traces. Wire contract. */
 declare const INGEST_SOURCE_CLI = "cli";
 /** Harness used when none is specified on a single-harness command. */
 declare const DEFAULT_HARNESS = "claude-code";
+declare function sessionIdFromAttributes(attributes: Readonly<Record<string, unknown>>): string | undefined;
+interface SessionIdentityConflict {
+    readonly traceId: string;
+    readonly sessionIds: readonly string[];
+}
+interface SessionIdentityIndex {
+    readonly sessionByTrace: Map<string, string>;
+    readonly conflicts: readonly SessionIdentityConflict[];
+}
+declare function indexSessionIdsByTrace(spans: readonly {
+    trace_id: string;
+    attributes: Readonly<Record<string, unknown>>;
+}[]): SessionIdentityIndex;
+/**
+ * Ensure every locally parsed trace has one session identity without hiding
+ * source conflicts. Existing stable identities win; otherwise the local
+ * session reference is stamped on every span in that trace.
+ */
+declare function stampSessionIdentity(spans: {
+    trace_id: string;
+    attributes: Record<string, unknown>;
+}[], fallbackSessionId: string): void;
 
 /** Parse an ISO-8601 timestamp or an epoch-millis string to epoch ms.
  *  Returns 0 for empty/unparseable input (callers treat 0 as "unknown"). */
@@ -182,6 +273,19 @@ declare function parseIsoToEpochMs(ts: string): number;
  *  date, → epoch ms. Throws on a malformed value (fail-loud, not silent). */
 declare function parseSince(value: string): number;
 
+type JsonSourceErrorKind = 'read' | 'parse';
+declare class JsonSourceError extends Error {
+    readonly sourcePath: string;
+    readonly kind: JsonSourceErrorKind;
+    readonly code?: string;
+    constructor(sourcePath: string, kind: JsonSourceErrorKind, cause: unknown);
+}
+declare function readJsonFile<T>(path: string): Promise<T>;
+
+declare function recordSessionCorruption(ref: SessionRef, receipt: JsonlCorruptionReceipt): void;
+declare function sessionIntegrityAttributes(ref: SessionRef): Record<string, string | number>;
+declare function stampSessionIntegrity(ref: SessionRef, spans: OtlpSpan[]): void;
+
 /**
  * Harness adapter registry — resolves a harness id (or alias) to the
  * adapter that knows its on-disk session format.
@@ -218,14 +322,18 @@ declare function selectAdapters(opts: AdapterSelection): HarnessTraceAdapter[];
  * path funnels through here so the spine can group by repo. Repo resolution is
  * computed ONCE per session; it is fail-safe and never throws.
  */
-declare function parseSession(adapter: HarnessTraceAdapter, ref: SessionRef): Promise<OtlpSpan[]>;
+declare function parseSession(adapter: HarnessTraceAdapter, ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
+declare class EmptySessionError extends Error {
+    readonly sourcePath: string;
+    constructor(sourcePath: string);
+}
 /** Locate through every equivalent git worktree for the selected cwd, then
  *  dedupe and apply a boundary-aware final filter. */
 declare function locateSessions(adapter: HarnessTraceAdapter, opts?: {
     cwd?: string;
     sinceMs?: number;
 }): Promise<SessionRef[]>;
-interface ScanOptions extends AdapterSelection {
+interface ScanOptions extends AdapterSelection, ParseOptions {
     /** Filter by working directory (exact/prefix). */
     cwd?: string;
     /** Only sessions modified at/after this epoch ms. */
@@ -234,17 +342,17 @@ interface ScanOptions extends AdapterSelection {
     last?: number;
     /** Cancel the scan; iteration stops between sessions. */
     signal?: AbortSignal;
-    /** Per-adapter locate/parse failure (the scan continues). */
+    /** Handle a locate/parse failure and continue. Without this callback, failures propagate. */
     onError?: (error: unknown, ref?: SessionRef) => void;
 }
 interface ScannedSession {
     adapter: HarnessTraceAdapter;
     ref: SessionRef;
-    /** Non-empty parsed spans for the session. */
+    /** Parsed spans for the session. */
     spans: OtlpSpan[];
 }
-/** Yield every non-empty session across the selected adapters. Locate/parse
- *  errors route to `onError` and skip that adapter/session, never aborting. */
+/** Yield every session across the selected adapters. Locate/parse errors
+ *  propagate unless an explicit `onError` callback handles them. */
 declare function scanSessions(opts: ScanOptions): AsyncGenerator<ScannedSession>;
 
 type RepoResolutionSource = 'none' | 'ref-cwd' | 'repaired-cwd' | 'span-path' | 'span-workdir';
@@ -303,7 +411,7 @@ declare class ClaudeAdapter implements HarnessTraceAdapter {
     readonly aliases: readonly ["claude", "claudish", "openclaw", "nanoclaw"];
     private root;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
     /** Parse `<session>/subagents/agent-*.jsonl`, parenting each under its Agent call. */
     private foldSubagents;
 }
@@ -329,7 +437,7 @@ declare class CodexAdapter implements HarnessTraceAdapter {
     readonly aliases: readonly ["codex-acp"];
     private root;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
 /**
@@ -406,7 +514,7 @@ declare class QwenAdapter implements HarnessTraceAdapter {
     readonly aliases: readonly ["qwen-code"];
     private root;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
 /**
@@ -427,7 +535,7 @@ declare class FactoryAdapter implements HarnessTraceAdapter {
     readonly aliases: readonly ["factory-droids", "droid"];
     private root;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
 /**
@@ -443,7 +551,7 @@ declare class PiAdapter implements HarnessTraceAdapter {
     readonly harness = "pi";
     private root;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
 /**
@@ -476,9 +584,9 @@ declare class AmpAdapter implements HarnessTraceAdapter {
  * `assistant.usage` (ephemeral: `model`, `inputTokens`, `outputTokens`).
  *
  * Sub-agents interleave in the same stream — tool calls/results are joined by
- * `toolCallId`, never adjacency. Lines may contain stray newlines/separators;
- * parse line-tolerant. Schema from GitHub docs (high conf); parse unverified
- * against local data.
+ * `toolCallId`, never adjacency. Isolated invalid records produce corruption
+ * receipts while valid records continue. Schema from GitHub docs (high conf);
+ * parse unverified against local data.
  */
 
 declare class CopilotAdapter implements HarnessTraceAdapter {
@@ -486,14 +594,14 @@ declare class CopilotAdapter implements HarnessTraceAdapter {
     readonly aliases: readonly ["copilot"];
     private root;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
-    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
 /**
  * Forge adapter (antinomyhq/forge) — `/dump` JSON exports.
  *
  * Forge's primary store is SQLite (`~/.forge/.forge.db`, `conversations.context`
- * column). Reading it live needs a native sqlite dep, so v1 parses the
+ * column). Reading it live needs a native sqlite dep, so this adapter parses the
  * dependency-free `/dump` artifact instead: `<cwd>/YYYY-MM-DD_HH-MM-SS-dump.json`,
  * a single flattened `Context{ conversation_id, messages[] }`.
  *
@@ -620,7 +728,7 @@ declare const CORRECTIVE_REACTIONS: readonly Reaction[];
  *
  * These are the deterministic loop/thrash detectors that already exist in
  * `@tangle-network/agent-eval`:
- *   - stuckLoopView         — same tool + same args ≥ N times (the loop signal)
+ *   - stuckLoopView         — same tool + same args ≥ N times in a short interval
  *   - computeToolUseMetrics — duplicate-call / retry / error rates per run
  *
  * `toolWasteView` is intentionally NOT used: its default heuristic needs
@@ -637,6 +745,7 @@ declare const CORRECTIVE_REACTIONS: readonly Reaction[];
 
 interface PipelineReport {
     stuckLoops: StuckLoopReport;
+    failureClusters: FailureClusterReport;
     toolUse: ToolUseMetrics[];
 }
 interface PipelineOptions {
@@ -702,7 +811,7 @@ declare function analyzeReactions(spans: readonly OtlpSpan[]): ReactionReport;
  * Skill + subagent adoption metrics — deterministic.
  *
  * Reports three things:
- *   1. skill penetration — % of sessions that invoked any skill
+ *   1. explicit skill invocation rate over sessions with dedicated telemetry
  *   2. per-skill invocation frequency
  *   3. subagent (Task/Agent) spawn frequency
  *
@@ -716,11 +825,24 @@ declare function analyzeReactions(spans: readonly OtlpSpan[]): ReactionReport;
  */
 
 interface AdoptionReport {
-    sessionCount: number;
+    /** Identified sessions plus traces that lack session identity. */
+    executionGroupCount: number;
+    identifiedSessionCount: number;
+    unassignedTraceCount: number;
+    /** Traces omitted from session grouping because their source IDs disagree. */
+    sessionIdentityConflicts: readonly SessionIdentityConflict[];
     /** Sessions that invoked ≥1 skill (explicitly, via the Skill tool). */
     sessionsWithSkill: number;
-    /** sessionsWithSkill / sessionCount (0 when no sessions). */
-    skillPenetration: number;
+    /** sessionsWithSkill / skillTelemetrySessions; null when invocation is not measurable. */
+    skillPenetration: number | null;
+    /** Whether explicit Skill events can measure all, some, or none of the selected sessions. */
+    skillTelemetryStatus: 'measured' | 'partial' | 'unsupported' | 'unknown';
+    /** Sessions whose harness exposes a dedicated Skill event. */
+    skillTelemetrySessions: number;
+    /** Sessions containing materialized skill instructions or a skill catalog. */
+    sessionsWithMaterializedSkills: number;
+    /** Sessions with tool inputs that reference a SKILL.md path. */
+    sessionsWithSkillFileReference: number;
     /** Explicit `Skill` tool invocations per skill name, corpus-wide. */
     skillInvocations: Record<string, number>;
     /** Total explicit `Skill` tool invocations. */
@@ -762,9 +884,8 @@ declare function analyzeAdoption(spans: readonly OtlpSpan[], opts?: AdoptionOpti
  * harness — so traces reuses those shipped detectors instead of
  * reimplementing loop/stall detection.
  *
- * Tool `args` is the verbatim tool input we stored on the span's `content`;
- * `stuckLoopView` hashes it (`argHash`) so identical repeated calls collapse
- * to one loop finding.
+ * Tool `args` is the captured OpenInference input value; `stuckLoopView`
+ * hashes it (`argHash`) so identical repeated calls collapse to one finding.
  */
 
 interface RuntimeTrace {
@@ -807,10 +928,19 @@ interface AnalyzeOptions {
 interface AnalyzeResult {
     /** Path to the OTLP-JSONL artifact (convert to canonical for HALO). */
     otlpPath: string;
+    execution: ExecutionReport;
     result: Awaited<ReturnType<ReturnType<typeof buildDefaultAnalystRegistry>['run']>>;
 }
 declare function analyzeSpans(spans: readonly OtlpSpan[], opts?: AnalyzeOptions): Promise<AnalyzeResult>;
 
+interface TraceExecutionOptions {
+    readonly experimentId?: string;
+    readonly candidateId?: string;
+}
+/** Map normalized spans into agent-eval's shared execution accounting. */
+declare function summarizeOtlpExecution(otlpJsonl: string, opts?: TraceExecutionOptions): ExecutionReport;
+declare function summarizeSpanExecution(spans: readonly OtlpSpan[], opts?: TraceExecutionOptions): ExecutionReport;
+
 interface PolicyEvidenceToolSummary {
     readonly name: string;
     readonly calls: number;
@@ -824,6 +954,7 @@ interface PolicyEvidenceRecord {
     readonly schemaVersion: 1;
     readonly kind: 'traces.policy_evidence.session';
     readonly generatedAt: string;
+    readonly execution: ExecutionReport;
     readonly session: {
         readonly harness: string;
         readonly sessionId: string;
@@ -898,6 +1029,7 @@ interface TraceSessionIndexRow {
     readonly models: readonly string[];
     readonly tools: PolicyEvidenceRecord['metrics']['tools'];
     readonly signals: PolicyEvidenceRecord['signals'];
+    readonly execution: ExecutionReport;
 }
 interface TraceIndexedFile {
     readonly kind: 'instruction-doc' | 'evolve-jsonl' | 'evolve-json' | 'reflection' | 'handoff' | 'other';
@@ -1285,17 +1417,36 @@ declare function traceStreamEventsFromSpans(spans: readonly OtlpSpan[], opts?: T
 declare function serializeTraceStreamEvent(event: TraceStreamEvent): string;
 declare function streamSessions(opts: TraceStreamOptions): Promise<void>;
 
+/**
+ * Render analyst findings as a markdown report.
+ *
+ * Findings are grouped by area, ordered by severity. Each carries its
+ * claim, the deterministic evidence excerpt, and the recommended action —
+ * the actionable output for improving a stuck/looping agent.
+ */
+
+interface ReportSource {
+    sessionId: string;
+    path: string;
+    subject: string;
+    role: 'operator' | 'child' | 'unknown';
+    parentSessionId?: string;
+    integrity?: 'complete' | 'degraded_not_lossless';
+    corruptionCount?: number;
+    corruptionDigest?: string;
+    corruptions?: readonly SessionCorruptionReceipt[];
+}
+
 interface TracesConfig {
     readonly registry?: AnalystRegistry;
     readonly analysts?: readonly Analyst[];
     readonly liveAnalysts?: readonly TraceLiveAnalyst[];
     readonly externalAnalyzers?: readonly ExternalAnalyzer[];
-    readonly improvementAdapter?: ImprovementAdapter;
 }
 interface TraceInvestigationOptions {
     readonly spans: readonly OtlpSpan[];
     readonly harness: string;
-    readonly sessionCount: number;
+    readonly sources?: readonly ReportSource[];
     readonly cwds?: readonly string[];
     readonly minLoopOccurrences?: number;
     readonly ai?: AxAIService;
@@ -1308,28 +1459,6 @@ interface TraceInvestigationOptions {
     readonly generatedAt?: string;
     readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
 }
-interface TraceRecommendation {
-    readonly schemaVersion: 1;
-    readonly id: string;
-    readonly severity: AnalystFinding['severity'];
-    readonly title: string;
-    readonly action: string;
-    readonly rationale: string;
-    readonly evidenceRefs: readonly AnalystFinding['evidence_refs'][number][];
-    readonly findingIds: readonly string[];
-    readonly validationPlan: string;
-    readonly source: 'analyst' | 'deterministic' | 'external';
-}
-interface TraceClaim {
-    readonly schemaVersion: 1;
-    readonly id: string;
-    readonly severity: AnalystFinding['severity'];
-    readonly text: string;
-    readonly area: string;
-    readonly sourceFindingId: string;
-    readonly evidenceRefs: readonly AnalystFinding['evidence_refs'][number][];
-    readonly validationPlan?: string;
-}
 interface TraceEvidenceRow {
     readonly schemaVersion: 1;
     readonly kind: 'traces.improvement_evidence';
@@ -1339,69 +1468,27 @@ interface TraceEvidenceRow {
     readonly claim: string;
     readonly evidence: AnalystFinding['evidence_refs'][number];
 }
-interface ImprovementProposal {
-    readonly id: string;
-    readonly title: string;
-    readonly description: string;
-    readonly recommendationIds: readonly string[];
-    readonly patch?: string;
-    readonly validationCommand?: string;
-    readonly evidenceRefs?: readonly AnalystFinding['evidence_refs'][number][];
-}
-interface ImprovementAdapterInput {
-    readonly findings: readonly AnalystFinding[];
-    readonly recommendations: readonly TraceRecommendation[];
-    readonly claims: readonly TraceClaim[];
-    readonly spans: readonly OtlpSpan[];
-    readonly otlpPath: string;
-}
-interface ImprovementAdapter {
-    propose(input: ImprovementAdapterInput): Promise<readonly ImprovementProposal[]>;
-}
-interface FindingStore {
-    append(runId: string, findings: readonly AnalystFinding[]): Promise<void>;
-}
-interface RecommendationWriter {
-    write(recommendations: readonly TraceRecommendation[]): Promise<void>;
-}
-interface TraceReplayProof {
-    readonly schemaVersion: 1;
-    readonly kind: 'traces.improvement_replay';
-    readonly generatedAt: string;
-    readonly status: 'proposal-only' | 'not-run';
-    readonly candidateApplied: false;
-    readonly baseline: {
-        readonly spanCount: number;
-        readonly findingCount: number;
-        readonly recommendationCount: number;
-        readonly stuckLoops: number;
-        readonly reactionSignals: number;
-        readonly toolErrorRuns: number;
-    };
-    readonly proposals: readonly ImprovementProposal[];
-    readonly note: string;
-}
 interface TraceImprovementArtifacts {
     readonly directory: string;
-    readonly findings: string;
-    readonly recommendations: string;
-    readonly proposals: string;
+    readonly result: string;
     readonly evidence: string;
-    readonly claims: string;
     readonly report: string;
-    readonly replay: string;
+    readonly traces: string;
 }
 interface TraceInvestigationResult {
     readonly schemaVersion: 1;
     readonly kind: 'traces.investigation';
     readonly generatedAt: string;
     readonly harness: string;
+    /** Distinct stable session identities observed in the selected spans. */
     readonly sessionCount: number;
+    /** Traces without exactly one stable session identity. */
+    readonly unassignedTraceCount: number;
+    readonly sources?: readonly ReportSource[];
     readonly spanCount: number;
     readonly otlpPath: string;
+    readonly execution: ExecutionReport;
     readonly findings: readonly AnalystFinding[];
-    readonly recommendations: readonly TraceRecommendation[];
-    readonly claims: readonly TraceClaim[];
     readonly pipelines: PipelineReport;
     readonly reactions: ReactionReport;
     readonly adoption: AdoptionReport;
@@ -1414,8 +1501,6 @@ interface TraceFindingPacket {
     readonly generatedAt: string;
     readonly source: string;
     readonly findings: readonly AnalystFinding[];
-    readonly recommendations: readonly TraceRecommendation[];
-    readonly claims: readonly TraceClaim[];
     readonly report: string;
 }
 interface BuildTraceFindingPacketOptions {
@@ -1440,12 +1525,9 @@ interface TraceStoreInvestigationResult extends Omit<TraceFindingPacket, 'kind'>
 }
 interface TraceImprovementResult extends Omit<TraceInvestigationResult, 'kind'> {
     readonly kind: 'traces.improvement';
-    readonly proposals: readonly ImprovementProposal[];
-    readonly replay: TraceReplayProof;
     readonly artifacts?: TraceImprovementArtifacts;
 }
 interface TraceImprovementOptions extends TraceInvestigationOptions {
-    readonly adapter?: ImprovementAdapter;
     readonly outDir?: string;
 }
 declare function buildTraceFindingPacket(opts: BuildTraceFindingPacketOptions): TraceFindingPacket;
@@ -1453,8 +1535,8 @@ declare function loadTracesConfig(path?: string): Promise<TracesConfig | undefin
 declare function mergeTracesConfig(opts: TraceInvestigationOptions, config?: TracesConfig): TraceInvestigationOptions;
 declare function runTraceInvestigation(opts: TraceInvestigationOptions): Promise<TraceInvestigationResult>;
 declare function runTraceStoreInvestigation(opts: TraceStoreInvestigationOptions): Promise<TraceStoreInvestigationResult>;
-declare function writeTraceImprovementArtifacts(result: Pick<TraceImprovementResult, 'findings' | 'recommendations' | 'proposals' | 'claims' | 'report' | 'replay'>, outDir?: string): Promise<TraceImprovementArtifacts>;
-declare function runTraceImprovementLoop(opts: TraceImprovementOptions): Promise<TraceImprovementResult>;
+declare function writeTraceImprovementArtifacts(result: Omit<TraceImprovementResult, 'artifacts'>, outDir?: string): Promise<TraceImprovementArtifacts>;
+declare function runTraceImprovement(opts: TraceImprovementOptions): Promise<TraceImprovementResult>;
 declare function saveReport(path: string, report: string): Promise<void>;
 
 /**
@@ -1530,10 +1612,9 @@ interface SpanRedaction {
 /** Redact every span's attributes + status message. Returns scrubbed spans and
  *  an aggregate report (count + per-rule breakdown) over the whole set. */
 declare function redactSpans(spans: readonly OtlpSpan[], rules?: RedactionRule[]): SpanRedaction;
-/** Defense-in-depth: run an external {@link Redactor} (e.g. an ML PII model) over
- *  every span's captured `content` (prompt/response prose), catching free-form
- *  PII the regex pass misses. Compose AFTER `redactSpans`. Returns scrubbed spans
- *  and the number of `content` fields the model changed. */
+/** Defense-in-depth: run an external {@link Redactor} over captured conversation
+ *  and tool values, catching free-form PII the regex pass misses. Compose AFTER
+ *  `redactSpans`. Returns scrubbed spans and the number of fields changed. */
 declare function applyRedactor(spans: readonly OtlpSpan[], redactor: Redactor): Promise<{
     spans: OtlpSpan[];
     changed: number;
@@ -1564,12 +1645,8 @@ declare function collectSessions(opts?: CollectOptions): Promise<SessionBatch[]>
 /**
  * Local upload-dedup state.
  *
- * Persists which sessions have been uploaded (keyed by harness:sessionId →
- * content hash) so re-running `upload` over an overlapping window doesn't
- * re-send unchanged sessions. The hash is over the redacted span structure, so
- * a session that has GROWN since last upload re-uploads (new spans), while an
- * unchanged one is skipped. Pairs with the server-side `idempotency-key` for
- * belt-and-suspenders dedup.
+ * Persists the final outbound content hash for each harness/session so an
+ * unchanged upload is skipped while changed spans or privacy modes are sent.
  */
 
 interface UploadRecord {
@@ -1581,9 +1658,15 @@ interface UploadRecord {
 /** Keyed by `${harness}:${sessionId}`. */
 type UploadState = Record<string, UploadRecord>;
 declare function uploadKey(harness: string, sessionId: string): string;
-/** Stable content hash of a session's (redacted) spans — changes iff the
- *  session's span set changes, so a grown session re-uploads. */
+/** Stable content hash of complete spans, including captured values and results. */
 declare function sessionHash(spans: readonly OtlpSpan[]): string;
+interface UploadIdentity {
+    stripContent: boolean;
+    redactor: string | null;
+    redactionVersion: string;
+}
+/** Hash the exact outbound events and the privacy mode that produced them. */
+declare function outboundHash(events: readonly TraceSpanEvent[], identity: UploadIdentity): string;
 declare function loadState(): Promise<UploadState>;
 declare function saveState(state: UploadState): Promise<void>;
 /** True when this session+hash has already been uploaded. */
@@ -1593,13 +1676,13 @@ declare function alreadyUploaded(state: UploadState, harness: string, sessionId:
  * Upload local coding-session traces to the Tangle Intelligence Platform.
  *
  * Pipeline per session: locate (time window) → parse to OTLP spans → REDACT
- * (PII/secrets) → augment with metadata → dedup (skip unchanged, already-sent
- * sessions) → POST via the hosted `ingestTraces` client. The redaction happens
+ * (PII/secrets) → apply the selected privacy mode → augment with metadata →
+ * dedup the final events → POST via the hosted `ingestTraces` client. Redaction happens
  * before anything leaves the machine; the dedup is local-state + server
  * idempotency-key.
  *
- * `planUpload` is read-only (select + redact + dedup); `executeUpload` does the
- * actual send (or, with `dryRun`, writes the redacted OTLP it *would* send).
+ * `planUpload` is read-only (select + regex redact); `executeUpload` applies
+ * final privacy options, deduplicates, and sends or writes a dry-run preview.
  */
 
 interface UploadItem {
@@ -1607,7 +1690,9 @@ interface UploadItem {
     /** Redacted spans (safe to send). */
     spans: OtlpSpan[];
     redaction: RedactionReport;
+    /** Source-span hash for inspection. Final outbound hashing happens in executeUpload. */
     hash: string;
+    /** Candidate marker retained for API compatibility; final freshness depends on execute options. */
     isNew: boolean;
 }
 interface UploadPlan {
@@ -1616,7 +1701,7 @@ interface UploadPlan {
     sinceMs?: number;
 }
 type PlanOptions = ScanOptions;
-/** Read-only: select sessions in the window, redact, and mark which are new. */
+/** Read-only: select sessions in the window and apply the built-in regex redaction. */
 declare function planUpload(opts?: PlanOptions): Promise<UploadPlan>;
 /** Map redacted OtlpSpan[] → the hosted TraceSpanEvent[] wire shape, attaching
  *  session metadata to the root span(s). */
@@ -1636,22 +1721,27 @@ interface UploadBackend {
         accepted: number;
     }>;
 }
+declare class PartialUploadError extends Error {
+    readonly sessionKey: string;
+    readonly accepted: number;
+    readonly expected: number;
+    constructor(sessionKey: string, accepted: number, expected: number);
+}
 interface ExecuteOptions {
     dryRun?: boolean;
     /** Where to write the redacted OTLP-JSONL on a dry run. */
     otlpOut?: string;
     /** Custom sink. Defaults to the hosted Tangle Intelligence client from env. */
     backend?: UploadBackend;
-    /** Metadata-only upload: drop captured prompt/response `content` from every
-     *  span before it leaves the machine (still keeps tool calls, tokens, timing,
-     *  loop signal). The strongest privacy posture when prose can't leave. */
+    /** Metadata-only upload: drop captured prompt/response/tool values before the
+     *  spans leave the machine (still keeps tool names, tokens, timing, and loop signal). */
     stripContent?: boolean;
-    /** External PII scrubber applied to `content` AFTER the regex pass — catches
-     *  free-form PII (names, addresses) the rules miss. Ignored if stripContent. */
+    /** External PII scrubber applied to captured conversation and tool values
+     *  AFTER the regex pass. Ignored if stripContent. */
     redactor?: Redactor;
     log?: (msg: string) => void;
 }
-/** Send the NEW items (or, on dryRun, write the redacted OTLP that would send). */
+/** Send the final, new outbound items (or write their dry-run OTLP). */
 declare function executeUpload(plan: UploadPlan, opts?: ExecuteOptions): Promise<UploadResult>;
 
-export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, CORRECTIVE_REACTIONS, ClaudeAdapter, CodexAdapter, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, CopilotAdapter, DEFAULT_HARNESS, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, type FindingStore, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type ImprovementAdapter, type ImprovementAdapterInput, type ImprovementProposal, type InspectSessionIndexOptions, type LiveBatchOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, QwenAdapter, REACTIONS, type Reaction, type ReactionReport, type ReactionSessionReport, type RecommendationWriter, type Redactor, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceClaim, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, 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 TraceRecommendation, type TraceReplayProof, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeLiveBatch, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildTraceFindingPacket, capText, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, cwdMatchesSelection, defaultTraceLiveAnalysts, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, inspectSessionIndex, knownHarnesses, listAdapters, loadState, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeTracesConfig, normalizeRemote, parseIsoToEpochMs, parseSession, parseSince, planUpload, readSessionIndexFile, redactSpans, renderInspectionReport, resolveAdapter, resolveRepoAttrs, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTraceImprovementLoop, runTraceInvestigation, runTraceStoreInvestigation, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionHash, span, stampRepoAttrs, stampSpanWorkdirRepoAttrs, streamSessions, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, traceStreamEventsFromSpans, uploadKey, userPromptSpan, watchSessions, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts };
+export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, CORRECTIVE_REACTIONS, ClaudeAdapter, CodexAdapter, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, CopilotAdapter, type CorruptionMode, DEFAULT_HARNESS, EmptySessionError, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type InspectSessionIndexOptions, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, type ParseOptions, PartialUploadError, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, QwenAdapter, REACTIONS, type Reaction, type ReactionReport, type ReactionSessionReport, type Redactor, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionCorruptionReceipt, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeLiveBatch, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildTraceFindingPacket, capText, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, cwdMatchesSelection, defaultTraceLiveAnalysts, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, indexSessionIdsByTrace, inspectSessionIndex, knownHarnesses, listAdapters, loadState, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeTracesConfig, normalizeRemote, outboundHash, parseIsoToEpochMs, parseSession, parseSince, planUpload, readJsonFile, readJsonl, readSessionIndexFile, recordSessionCorruption, redactSpans, renderInspectionReport, resolveAdapter, resolveRepoAttrs, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTraceImprovement, runTraceInvestigation, runTraceStoreInvestigation, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, span, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, traceStreamEventsFromSpans, uploadKey, userPromptSpan, watchSessions, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts };