@tangle-network/traces 0.17.1 → 0.19.0

package/README.md

@@ -566,6 +566,23 @@ Do not pass `--llm`; the command is model-backed by definition.
 
 ## Session facts
 
+The SDK also accepts verified retained captures through
+`parseRetainedSession({ harness, nativeSessionId, files, signal? })`.
+Pass files as `{ path, content }` with their original relative layout.
+Runtime or the caller owns custody, digest verification and capture completeness.
+The reader uses existing adapters and selects a file only when native records
+establish the supplied session identity.
+It does not inspect the host session catalog or infer identity from filenames.
+Directory-only stores and formats without a recorded native identity remain unavailable.
+The returned source files, duplicate snapshots and unselected files explain the selection.
+Identical or append-only copies count once; divergent histories remain unavailable.
+Parsing is bounded to 1024 text files, 16 MiB per file, and 64 MiB total.
+No model calls occur.
+Call `buildSessionFactsReport(selection.spans, { includeContent: false })` to
+withhold native bodies from the resulting facts.
+The reader itself returns spans containing native content, for local trusted consumers only.
+
+
 The same facts sheet includes observed tool outcomes, captured input/output byte
 volumes, call-to-result intervals, compaction boundaries and available context
 sizes, spawn intervals, and existing skill invocation/document-read evidence.

package/dist/{chunk-SGQOMHZP.js → chunk-YVCHWHCA.js}

@@ -1025,8 +1025,8 @@ var OTLP_WRITE_CHUNK_CHARS = 4 * 1024 * 1024;
 async function writeOtlpFile(spans, outPath) {
   const { mkdtemp: mkdtemp8, open: open2 } = await import("fs/promises");
   const { tmpdir: tmpdir8 } = await import("os");
-  const { join: join35 } = await import("path");
-  const path = outPath ?? join35(await mkdtemp8(join35(tmpdir8(), "traces-")), "spans.otlp.jsonl");
+  const { join: join36 } = await import("path");
+  const path = outPath ?? join36(await mkdtemp8(join36(tmpdir8(), "traces-")), "spans.otlp.jsonl");
   const handle = await open2(path, "w");
   try {
     let chunk = "";
@@ -1488,6 +1488,7 @@ var AmpAdapter = class {
     const spans = [
       span({ traceId, spanId: rootId, parentSpanId: null, name: "session", kind: "AGENT", startTime: start, service: SERVICE, agent: SERVICE })
     ];
+    if (thread.id) spans[0].attributes["tangle.sessionId"] = thread.id;
     const toolByUseId = /* @__PURE__ */ new Map();
     let step = 0;
     for (const m of messages) {
@@ -2212,6 +2213,7 @@ function normalizeClaudeIds(spans) {
     const sourceTraceId = item.trace_id;
     const sourceSpanId = item.span_id;
     const sourceParentSpanId = item.parent_span_id;
+    item.attributes["tangle.sessionId"] = sourceTraceId;
     item.attributes[CLAUDE_SOURCE_TRACE_ID] = sourceTraceId;
     item.attributes[CLAUDE_SOURCE_SPAN_ID] = sourceSpanId;
     if (sourceParentSpanId !== null) {
@@ -3985,9 +3987,9 @@ function itemCountsJson(counts) {
 }
 function placeInnerSpans(pending, windows) {
   return pending.map((entry) => {
-    const { parent, join: join35 } = joinItem(windows, entry.startMs, entry.endMs);
+    const { parent, join: join36 } = joinItem(windows, entry.startMs, entry.endMs);
     if (parent) entry.span.parent_span_id = parent.span_id;
-    entry.span.attributes["traces.codex.item_join"] = join35;
+    entry.span.attributes["traces.codex.item_join"] = join36;
     return entry.span;
   });
 }
@@ -5130,6 +5132,7 @@ var CodexExecAdapter = class {
           service: SERVICE4,
           agent: SERVICE4,
           extra: {
+            "tangle.sessionId": threadId,
             "traces.codex.stream_format": "exec-jsonl",
             "traces.session.role": "operator"
           }
@@ -5594,6 +5597,7 @@ var FactoryAdapter = class {
         "session.output_tokens": settings.tokenUsage.outputTokens ?? 0
       } : void 0
     });
+    if (sessionLine?.id) root.attributes["tangle.sessionId"] = sessionLine.id;
     return [root, ...spans];
   }
 };
@@ -5653,6 +5657,7 @@ var ForgeAdapter = class {
     const spans = [
       span({ traceId, spanId: rootId, parentSpanId: null, name: "session", kind: "AGENT", startTime: (/* @__PURE__ */ new Date(0)).toISOString(), service: SERVICE7, agent: SERVICE7 })
     ];
+    if (ctx.conversation_id) spans[0].attributes["tangle.sessionId"] = ctx.conversation_id;
     const toolByCallId = /* @__PURE__ */ new Map();
     let step = 0;
     let lastLlm = rootId;
@@ -5833,6 +5838,7 @@ var GeminiFamilyAdapter = class {
         agent: this.service
       })
     ];
+    if (session.sessionId) spans[0].attributes["tangle.sessionId"] = session.sessionId;
     let step = 0;
     for (const m of messages) {
       const mid = m.id ?? `m${step}`;
@@ -6418,6 +6424,7 @@ var PiAdapter = class {
       agent: SERVICE9,
       extra: { "traces.pi.stop_reason": terminal.stopReason }
     });
+    if (sessionLine?.id) root.attributes["tangle.sessionId"] = sessionLine.id;
     return [root, ...spans];
   }
 };
@@ -15311,6 +15318,7 @@ function assertPositiveInteger(name, value) {
 import { createHash as createHash14 } from "crypto";
 import { request as httpRequest } from "http";
 import { request as httpsRequest } from "https";
+import { join as join25 } from "path";
 var DEFAULT_BRIDGE_URL = "http://localhost:4181";
 var DEFAULT_MODEL = "prime/zai/glm-5.2";
 var DEFAULT_TIMEOUT_MS = 12e5;
@@ -15326,9 +15334,9 @@ async function fileDelivery(otlpPath, perAttributeCharCap, signal) {
   signal?.throwIfAborted();
   const { copyFile: copyFile2, mkdtemp: mkdtemp8, stat: stat19 } = await import("fs/promises");
   const { tmpdir: tmpdir8 } = await import("os");
-  const { join: join35 } = await import("path");
-  const cwd = await mkdtemp8(join35(tmpdir8(), "traces-prime-"));
-  await copyFile2(otlpPath, join35(cwd, TRAJECTORY_FILE_NAME));
+  const { join: join36 } = await import("path");
+  const cwd = await mkdtemp8(join36(tmpdir8(), "traces-prime-"));
+  await copyFile2(otlpPath, join36(cwd, TRAJECTORY_FILE_NAME));
   const artifactBytes = (await stat19(otlpPath)).size;
   return { mode: "file-cwd", perAttributeCharCap, renderedChars: artifactBytes, cwd, fileName: TRAJECTORY_FILE_NAME };
 }
@@ -15482,9 +15490,15 @@ var FILE_DELIVERY_CONTRACT_LINES = [
   "Do NOT include a rationale field. Keep every string SHORT \u2014 long strings get corrupted in transport and void your work.",
   `Report at most ${MAX_FINDINGS} findings; a finding cites 1..${MAX_SPAN_IDS_PER_FINDING} span_ids, each copied VERBATIM from a span in ${TRAJECTORY_FILE_NAME}.`,
   '"findings" is [] only for a clean trajectory.',
+  `PAYLOAD CHANNEL \u2014 do this BEFORE your final message: WRITE the complete JSON object (same schema as`,
+  "the reply contract) to a file named findings.json in your working directory, using your tools (python",
+  "or shell). One assistant message has an output-token cap and a cut reply is discarded unread;",
+  "findings.json is the durable channel a large result must travel on. Write it first, incrementally if",
+  "it is long, THEN send your final message: the fenced ```json block when it is short enough to fit,",
+  "otherwise ONE line only \u2014 `findings written to findings.json`.",
   "FINAL MESSAGE RULE: after your REPL work is done, send ONE last message that contains NOTHING BUT the",
-  "fenced ```json block above \u2014 no preamble, no summary, no code identifiers around it. A reply whose last",
-  "message is prose or a partial block is discarded unread."
+  "fenced ```json block (or the one-line pointer above) \u2014 no preamble, no summary, no code identifiers",
+  "around it. A reply whose last message is prose or a partial block is discarded unread."
 ];
 function buildPrompt(question, projection) {
   if (projection.delivery.mode === "file-cwd") {
@@ -15521,7 +15535,7 @@ function buildRepairPrompt(parseDefect, previousReply, finishReason) {
     '   "severity": "critical"|"high"|"medium"|"low"|"info", "area": string (max 40 chars),',
     '   "claim": string (max 200 chars), "action": string (optional, max 200 chars), "confidence": number 0..1}',
     "No rationale field. Keep every string SHORT.",
-    truncated ? "Your previous reply was cut off by the output limit, so re-emit at most 3 findings \u2014 your strongest \u2014 with terse strings (claim and action under 120 chars each); do not reproduce the whole cut-off list." : "Preserve the span ids and verdicts of your previous reply exactly; shorten prose freely.",
+    truncated ? "Your previous reply was cut off by the output limit. Write the corrected JSON to a file named findings.json in your working directory with your tools (at most 3 findings \u2014 your strongest \u2014 with terse strings, claim and action under 120 chars each), then reply with ONE line: findings written to findings.json." : "Preserve the span ids and verdicts of your previous reply exactly; shorten prose freely.",
     "",
     "PREVIOUS REPLY:",
     previousReply
@@ -15556,6 +15570,59 @@ function parseDefectOf(parsed) {
   if (!Array.isArray(parsed.findings)) return 'JSON has no "findings" array';
   return null;
 }
+var FINDINGS_FILE_MAX_BYTES = 256 * 1024;
+var FINDINGS_FILE_NAME = "findings.json";
+async function readFindingsFile2(cwd, signal) {
+  signal?.throwIfAborted();
+  const path = join25(cwd, FINDINGS_FILE_NAME);
+  let raw;
+  const { readFile: readFile20, stat: stat19 } = await import("fs/promises");
+  try {
+    const size = (await stat19(path)).size;
+    if (size > FINDINGS_FILE_MAX_BYTES) {
+      return { parsed: null, receipt: `${FINDINGS_FILE_NAME} is ${size} bytes (cap ${FINDINGS_FILE_MAX_BYTES}); refused` };
+    }
+    raw = await readFile20(path, "utf8");
+  } catch {
+    return void 0;
+  }
+  const direct = extractJsonObject(raw);
+  if (direct !== null && parseDefectOf(direct) === null) {
+    return { parsed: direct, receipt: `${FINDINGS_FILE_NAME} read (${raw.length} chars)` };
+  }
+  const rows = [];
+  let droppedLines = 0;
+  let answer = null;
+  for (const [index, line] of raw.split("\n").entries()) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const row = extractJsonObject(trimmed);
+    if (row === null) {
+      droppedLines += 1;
+      continue;
+    }
+    if (typeof row.answer === "string" && !Array.isArray(row.findings)) {
+      if (answer === null) answer = row.answer;
+      continue;
+    }
+    if (Array.isArray(row.findings)) {
+      rows.push(...row.findings);
+      if (answer === null && typeof row.answer === "string") answer = row.answer;
+      continue;
+    }
+    rows.push(row);
+  }
+  if (rows.length === 0) {
+    return {
+      parsed: null,
+      receipt: `${FINDINGS_FILE_NAME} unreadable (no parseable object${droppedLines > 0 ? `, ${droppedLines} malformed line(s) dropped` : ""})`
+    };
+  }
+  return {
+    parsed: { ...answer !== null ? { answer } : {}, findings: rows },
+    receipt: `${FINDINGS_FILE_NAME} read as JSONL (${rows.length} row(s)${droppedLines > 0 ? `, ${droppedLines} malformed line(s) dropped` : ""})`
+  };
+}
 function findingRowDefect(row, spanTraces) {
   if (!row || typeof row !== "object" || Array.isArray(row)) return "row is not an object";
   const record2 = row;
@@ -15779,11 +15846,25 @@ function primeAnalyzer(opts = {}) {
         parsed = extractJsonObject(repairReply.content);
         parseDefect = parseDefectOf(parsed);
       }
+      let channel = "reply";
+      let channelReceipt = "";
       if (parseDefect !== null) {
-        return failure(
-          reply.content,
-          `${parseDefect} in prime reply${repairAttempted ? " even after the bounded repair turn" : ""}; ` + renderUsage(usage)
-        );
+        const deliveryCwd2 = projection.delivery.mode === "file-cwd" ? projection.delivery.cwd : void 0;
+        const file = deliveryCwd2 !== void 0 ? await readFindingsFile2(deliveryCwd2, analyzeOpts.signal).catch(() => void 0) : void 0;
+        if (file?.parsed !== null && file !== void 0) {
+          parsed = file.parsed;
+          parseDefect = parseDefectOf(parsed);
+          if (parseDefect === null) {
+            channel = FINDINGS_FILE_NAME;
+            channelReceipt = file.receipt;
+          }
+        }
+        if (parseDefect !== null) {
+          return failure(
+            reply.content,
+            `${parseDefect} in prime reply${repairAttempted ? " even after the bounded repair turn" : ""}` + (file === void 0 ? "; no findings.json in the run directory" : `; ${file.receipt}`) + `; ${renderUsage(usage)}`
+          );
+        }
       }
       const rows = parsed.findings.slice(0, MAX_FINDINGS);
       const overflow = parsed.findings.length - rows.length;
@@ -15804,6 +15885,7 @@ function primeAnalyzer(opts = {}) {
         `findings: ${findings.length} mapped, ${rejected.length} rejected` + (overflow > 0 ? `, ${overflow} over the ${MAX_FINDINGS}-finding cap dropped` : ""),
         ...rejected,
         deliveryLine,
+        ...channel !== "reply" ? [`reply channel: ${channel} \u2014 ${channelReceipt}; the chat reply was unparseable, the payload file carried the result`] : [],
         `repair: ${repairAttempted ? "attempted (succeeded)" : "not needed"}`,
         renderUsage(usage),
         ...findings.length === 0 ? ["zero findings \u2014 an honest null, not a failure"] : []
@@ -15908,7 +15990,7 @@ async function applyRedactor(spans, redactor) {
 import { createHash as createHash15 } from "crypto";
 import { mkdtemp as mkdtemp6, readFile as readFile12, writeFile as writeFile8 } from "fs/promises";
 import { tmpdir as tmpdir6 } from "os";
-import { join as join25 } from "path";
+import { join as join26 } from "path";
 import {
   firstNumberAttr as firstNumberAttr2,
   LLM_CACHED_TOKEN_ATTR_KEYS,
@@ -16579,7 +16661,7 @@ async function exportTraceEvidenceFile(inputPath, opts = {}) {
 }
 async function writeTraceEvidenceExportFile(inputPath, outPath, opts = {}) {
   const result = await exportTraceEvidenceFile(inputPath, opts);
-  const path = outPath ?? join25(await mkdtemp6(join25(tmpdir6(), "traces-export-")), "spans.openinference.jsonl");
+  const path = outPath ?? join26(await mkdtemp6(join26(tmpdir6(), "traces-export-")), "spans.openinference.jsonl");
   await writeFile8(path, serializeSpans(result.spans), "utf8");
   return { ...result, path };
 }
@@ -16587,7 +16669,7 @@ async function writeTraceEvidenceExportFile(inputPath, outPath, opts = {}) {
 // src/inspect.ts
 import { mkdtemp as mkdtemp7, readFile as readFile13, writeFile as writeFile9 } from "fs/promises";
 import { tmpdir as tmpdir7 } from "os";
-import { basename as basename14, join as join26 } from "path";
+import { basename as basename14, join as join27 } from "path";
 var severityRank2 = {
   high: 0,
   medium: 1,
@@ -16876,7 +16958,7 @@ async function readSessionIndexFile(path) {
   return parsed;
 }
 async function writeInspectionReportFile(report, outPath) {
-  const path = outPath ?? join26(await mkdtemp7(join26(tmpdir7(), "traces-inspect-")), "inspection-report.md");
+  const path = outPath ?? join27(await mkdtemp7(join27(tmpdir7(), "traces-inspect-")), "inspection-report.md");
   await writeFile9(path, renderInspectionReport(report), "utf8");
   return path;
 }
@@ -17310,7 +17392,7 @@ async function streamSessions(opts) {
 
 // src/supervisor-run-context.ts
 import { readFile as readFile14, stat as stat16 } from "fs/promises";
-import { basename as basename15, join as join27 } from "path";
+import { basename as basename15, join as join28 } from "path";
 import { materializeTreeView } from "@tangle-network/agent-runtime/kernel";
 import {
   readRuntimeSupervisorRun
@@ -17472,14 +17554,14 @@ function parseInstant(v) {
 }
 async function readFileRunContext(runDir, opts = {}) {
   const sources = await readRuntimeSupervisorRun(runDir);
-  const coordination = readCoordinationLog(await readMaybe(join27(runDir, COORDINATION_LOG_FILE)));
+  const coordination = readCoordinationLog(await readMaybe(join28(runDir, COORDINATION_LOG_FILE)));
   return {
     ...sources,
     instanceId: opts.instanceId !== void 0 ? opts.instanceId : sources.instanceId,
     arm: opts.arm !== void 0 ? opts.arm : basename15(runDir),
     workers: sources.workers !== null && coordination.present ? workerSources(sources.workers, coordination) : sources.workers,
     ...sources.journal !== null ? {
-      rootTranscriptRef: join27(runDir, SPAWN_JOURNAL_FILE),
+      rootTranscriptRef: join28(runDir, SPAWN_JOURNAL_FILE),
       traceCommand: `traces watch ${runDir}`
     } : {}
   };
@@ -17488,7 +17570,7 @@ function fileRunContextSupervisorRunReader(runDir, opts = {}) {
   return { runRef: runDir, read: () => readFileRunContext(runDir, opts) };
 }
 async function isFileRunContextDir(runDir) {
-  return stat16(join27(runDir, SPAWN_JOURNAL_FILE)).then((s) => s.isFile()).catch(() => false);
+  return stat16(join28(runDir, SPAWN_JOURNAL_FILE)).then((s) => s.isFile()).catch(() => false);
 }
 function parseJsonObject(text2) {
   if (text2 === null) return null;
@@ -17554,9 +17636,9 @@ function mergeRolls(a, b) {
   };
 }
 async function readRunContextSnapshot(runDir) {
-  const journal = readRunContextJournal(await readMaybe(join27(runDir, SPAWN_JOURNAL_FILE)));
-  const coordination = readCoordinationLog(await readMaybe(join27(runDir, COORDINATION_LOG_FILE)));
-  const resultText = await readMaybe(join27(runDir, RESULT_FILE));
+  const journal = readRunContextJournal(await readMaybe(join28(runDir, SPAWN_JOURNAL_FILE)));
+  const coordination = readCoordinationLog(await readMaybe(join28(runDir, COORDINATION_LOG_FILE)));
+  const resultText = await readMaybe(join28(runDir, RESULT_FILE));
   const result = parseResult(resultText);
   const view = safeTreeView(journal.events);
   const nodes = view === null ? [] : orderNodes(view, journal);
@@ -17739,7 +17821,7 @@ function wrap(text2, indent) {
 
 // src/run-span-tree.ts
 import { readdir as readdir18 } from "fs/promises";
-import { join as join28 } from "path";
+import { join as join29 } from "path";
 import {
   firstNumberAttr as firstNumberAttr3,
   LLM_COST_ATTR_KEYS as LLM_COST_ATTR_KEYS2,
@@ -18014,7 +18096,7 @@ async function findSpanSourceFiles(dir) {
   const found = [];
   const entries = await readdir18(dir, { withFileTypes: true }).catch(() => []);
   for (const entry of entries) {
-    const child = join28(dir, entry.name);
+    const child = join29(dir, entry.name);
     if (entry.isFile()) {
       if (SPAN_FILE_PATTERN.test(entry.name)) found.push(child);
       continue;
@@ -18022,7 +18104,7 @@ async function findSpanSourceFiles(dir) {
     if (!entry.isDirectory()) continue;
     const nested = await readdir18(child, { withFileTypes: true }).catch(() => []);
     for (const inner of nested) {
-      if (inner.isFile() && SPAN_FILE_PATTERN.test(inner.name)) found.push(join28(child, inner.name));
+      if (inner.isFile() && SPAN_FILE_PATTERN.test(inner.name)) found.push(join29(child, inner.name));
     }
   }
   return found.sort();
@@ -18030,7 +18112,7 @@ async function findSpanSourceFiles(dir) {
 
 // src/supervisor-run-watch.ts
 import { readdir as readdir19 } from "fs/promises";
-import { join as join29 } from "path";
+import { join as join30 } from "path";
 function budget(node) {
   const parts = [`${int(node.budget.maxIterations)}it`, `${int(node.budget.maxTokens)}tok`];
   if (node.budget.maxUsd !== void 0) parts.push(`$${node.budget.maxUsd.toFixed(2)}`);
@@ -18174,7 +18256,7 @@ async function resolveRunContextDir(dir) {
   const candidates = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const child = join29(dir, entry.name);
+    const child = join30(dir, entry.name);
     if (await isFileRunContextDir(child)) candidates.push(child);
   }
   if (candidates.length === 1) return candidates[0];
@@ -18510,7 +18592,7 @@ function parseJsonAnswer(text2) {
 
 // src/ask.ts
 import { mkdir as mkdir6, readFile as readFile15, writeFile as writeFile10 } from "fs/promises";
-import { join as join30, resolve as resolve11 } from "path";
+import { join as join31, resolve as resolve11 } from "path";
 import { performance } from "perf_hooks";
 import { CostCeilingReachedError, CostLedger } from "@tangle-network/agent-eval";
 import {
@@ -19065,8 +19147,8 @@ async function writeTraceQuestionsArtifacts(result, outDir) {
   await mkdir6(directory, { recursive: true });
   const paths = {
     directory,
-    result: join30(directory, "answers.json"),
-    report: join30(directory, "report.md"),
+    result: join31(directory, "answers.json"),
+    report: join31(directory, "report.md"),
     traces: result.otlpPath
   };
   const { report, ...machine } = result;
@@ -19130,7 +19212,7 @@ async function watchSessions(opts) {
 // src/bundle-view.ts
 import { createHash as createHash17 } from "crypto";
 import { mkdir as mkdir7, readdir as readdir20, readFile as readFile16, writeFile as writeFile11 } from "fs/promises";
-import { dirname as dirname11, join as join31, resolve as resolve12 } from "path";
+import { dirname as dirname11, join as join32, resolve as resolve12 } from "path";
 var EVIDENCE_ONLY_ALLOW_LIST = [
   {
     path: "derived/session-index.json",
@@ -19254,7 +19336,7 @@ async function findSessionTextLeaks(opts) {
   const index = /* @__PURE__ */ new Map();
   const carried = [];
   for (const path of opts.carriedPaths) {
-    const signatures = sessionTextSignatures(await readFile16(join31(opts.viewDir, path), "utf8"));
+    const signatures = sessionTextSignatures(await readFile16(join32(opts.viewDir, path), "utf8"));
     carried.push({ path, signatures: signatures.size });
     for (const signature of signatures) if (!index.has(signature)) index.set(signature, path);
   }
@@ -19262,7 +19344,7 @@ async function findSessionTextLeaks(opts) {
   const comparedSources = [];
   let sourceSignatures = 0;
   for (const sourcePath of opts.excludedPaths) {
-    const signatures = sessionTextSignatures(await readFile16(join31(opts.sourceDir, sourcePath), "utf8"));
+    const signatures = sessionTextSignatures(await readFile16(join32(opts.sourceDir, sourcePath), "utf8"));
     comparedSources.push(sourcePath);
     sourceSignatures += signatures.size;
     for (const signature of signatures) {
@@ -19321,17 +19403,17 @@ async function projectSessionBundle(opts) {
   const candidates = [];
   for (const path of await listSessionBundleFiles(sourceDir)) {
     if (path === "manifest.json") continue;
-    const bytes2 = await readFile16(join31(sourceDir, path));
+    const bytes2 = await readFile16(join32(sourceDir, path));
     const sha2562 = createHash17("sha256").update(bytes2).digest("hex");
     const recorded = sourceHashes.get(path);
     if (!recorded) {
       throw new Error(
-        `${join31(sourceDir, path)} is not listed in the bundle manifest \u2014 the bundle changed after assembly and cannot be projected; re-run \`traces bundle\``
+        `${join32(sourceDir, path)} is not listed in the bundle manifest \u2014 the bundle changed after assembly and cannot be projected; re-run \`traces bundle\``
       );
     }
     if (recorded.sha256 !== sha2562) {
       throw new Error(
-        `${join31(sourceDir, path)} does not match its manifest hash (${recorded.sha256} recorded, ${sha2562} on disk) \u2014 the bundle changed after assembly and cannot be projected; re-run \`traces bundle\``
+        `${join32(sourceDir, path)} does not match its manifest hash (${recorded.sha256} recorded, ${sha2562} on disk) \u2014 the bundle changed after assembly and cannot be projected; re-run \`traces bundle\``
       );
     }
     const verdict = classifyEvidenceOnlyPath(path);
@@ -19367,7 +19449,7 @@ async function projectSessionBundle(opts) {
       });
       continue;
     }
-    const target = join31(outDir, candidate.path);
+    const target = join32(outDir, candidate.path);
     await mkdir7(dirname11(target), { recursive: true });
     await writeFile11(target, candidate.bytes);
     carriedPaths.push(candidate.path);
@@ -19384,7 +19466,7 @@ async function projectSessionBundle(opts) {
     })),
     matches: 0
   };
-  const sourceManifestBytes = await readFile16(join31(sourceDir, "manifest.json"));
+  const sourceManifestBytes = await readFile16(join32(sourceDir, "manifest.json"));
   const manifest = {
     schemaVersion: 2,
     kind: "traces.session_bundle",
@@ -19572,11 +19654,11 @@ function renderRunDiff(report) {
 // src/upload-state.ts
 import { mkdir as mkdir8, readFile as readFile17, writeFile as writeFile12 } from "fs/promises";
 import { homedir as homedir12 } from "os";
-import { dirname as dirname12, join as join32 } from "path";
+import { dirname as dirname12, join as join33 } from "path";
 import { contentHash } from "@tangle-network/agent-eval";
 function stateFile() {
-  const base = process.env.XDG_STATE_HOME ?? join32(homedir12(), ".local", "state");
-  return join32(base, "tangle-traces", "uploaded.json");
+  const base = process.env.XDG_STATE_HOME ?? join33(homedir12(), ".local", "state");
+  return join33(base, "tangle-traces", "uploaded.json");
 }
 function uploadKey(harness, sessionId) {
   return `${harness}:${sessionId}`;
@@ -19608,7 +19690,7 @@ function alreadyUploaded(state, harness, sessionId, hash2) {
 import { readFile as readFile18 } from "fs/promises";
 import { createRequire as createRequire2 } from "module";
 import { hostname as hostname2 } from "os";
-import { basename as basename16, join as join33 } from "path";
+import { basename as basename16, join as join34 } from "path";
 import { hostedClientFromEnv } from "@tangle-network/agent-eval/hosted";
 import { assessShareSafety as assessShareSafety2, REDACTION_VERSION, redact as redact2, shareAllowed } from "@tangle-network/agent-eval/traces";
 var require2 = createRequire2(import.meta.url);
@@ -19632,7 +19714,7 @@ async function planUpload(opts = {}) {
 async function gitBranch(cwd) {
   if (!cwd) return void 0;
   try {
-    const head = await readFile18(join33(cwd, ".git", "HEAD"), "utf8");
+    const head = await readFile18(join34(cwd, ".git", "HEAD"), "utf8");
     const m = head.match(/^ref:\s*refs\/heads\/(.+)$/m);
     return m?.[1]?.trim();
   } catch {
@@ -19808,7 +19890,7 @@ async function executeUpload(plan, opts = {}) {
 
 // src/verify-safe.ts
 import { lstat as lstat4, readdir as readdir21, readFile as readFile19 } from "fs/promises";
-import { basename as basename17, extname, join as join34, relative as relative7 } from "path";
+import { basename as basename17, extname, join as join35, relative as relative7 } from "path";
 import {
   assessShareSafety as assessShareSafety3,
   combineVerdicts as combineVerdicts2
@@ -19869,7 +19951,7 @@ async function listFiles(target, unreadable) {
   const out = [];
   const walk = async (dir) => {
     for (const entry of (await readdir21(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
-      const path = join34(dir, entry.name);
+      const path = join35(dir, entry.name);
       if (entry.isDirectory()) await walk(path);
       else if (entry.isFile()) out.push(path);
       else unreadable.push(`${relative7(target, path)}: not a regular file`);

package/dist/cli.js

@@ -83,7 +83,7 @@ import {
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceQuestionsArtifacts
-} from "./chunk-SGQOMHZP.js";
+} from "./chunk-YVCHWHCA.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";

package/dist/index.d.ts

@@ -4139,6 +4139,12 @@ interface PrimeAnalyzerOptions {
     repair?: boolean;
     transport?: PrimeTransport;
 }
+interface FindingsFileOutcome {
+    parsed: Record<string, unknown> | null;
+    /** Human-readable receipt for the output: what the file was and what
+     *  happened to it. Present whenever a file was found. */
+    receipt: string;
+}
 /** Default transport: plain node:http/https, NOT fetch — undici's fixed 300s
  *  headers timeout kills prime calls that legitimately run longer; the
  *  analyzer's AbortSignal is the only deadline. */
@@ -4934,4 +4940,37 @@ 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 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 };
+declare const RETAINED_SESSION_READER_VERSION = "1";
+interface RetainedSessionFile {
+    readonly path: string;
+    readonly content: string;
+}
+interface RetainedSessionSelection {
+    readonly status: 'selected' | 'unavailable';
+    readonly reason: string | null;
+    readonly sessionId: string | null;
+    readonly sourceFiles: readonly {
+        readonly path: string;
+        readonly sha256: string;
+    }[];
+    readonly duplicateFiles: readonly string[];
+    readonly unselectedFiles: readonly {
+        readonly path: string;
+        readonly reason: string;
+    }[];
+    readonly spans: readonly OtlpSpan[];
+}
+/**
+ * Parse an explicitly retained capture without consulting the host's session catalog.
+ * Native identity must come from the adapter's records. A path, caller supplied
+ * fallback ID, or worker name never establishes identity. Runtime owns custody,
+ * hash verification, capture completeness, and the binding to its node.
+ */
+declare function parseRetainedSession(input: {
+    readonly harness: string;
+    readonly nativeSessionId: string | null;
+    readonly files: readonly RetainedSessionFile[];
+    readonly signal?: AbortSignal;
+}): Promise<RetainedSessionSelection>;
+
+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 FindingsFileOutcome, 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, RETAINED_SESSION_READER_VERSION, RULE, type Reaction, type ReactionReport, type ReactionSessionReport, type RedactSpansOptions, type Redactor, type RefusedSession, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedOtlpInput, type RetainedSessionFile, type RetainedSessionSelection, 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, parseRetainedSession, 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

@@ -270,7 +270,7 @@ import {
   writeTraceQuestionsArtifacts,
   zaiChatCaller,
   zeroPricedCost
-} from "./chunk-SGQOMHZP.js";
+} from "./chunk-YVCHWHCA.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {
@@ -301,6 +301,112 @@ import {
   redactText,
   shareAllowed
 } from "@tangle-network/agent-eval/traces";
+
+// src/retained-session.ts
+import { createHash } from "crypto";
+import { mkdir, mkdtemp, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
+var RETAINED_SESSION_READER_VERSION = "1";
+async function parseRetainedSession(input) {
+  input.signal?.throwIfAborted();
+  const unselectedFiles = [];
+  const unavailable = (reason) => ({
+    status: "unavailable",
+    reason,
+    sessionId: input.nativeSessionId,
+    sourceFiles: [],
+    duplicateFiles: [],
+    unselectedFiles,
+    spans: []
+  });
+  if (!input.nativeSessionId) return unavailable("Capture has no recorded native session identity.");
+  const adapter = resolveAdapter(input.harness);
+  if (!adapter) return unavailable(`No native trace adapter for ${input.harness}.`);
+  if (input.files.length > 1024) return unavailable("Retained capture exceeds 1024 text files.");
+  let totalBytes = 0;
+  for (const file of input.files) {
+    const bytes = Buffer.byteLength(file.content);
+    totalBytes += bytes;
+    if (bytes > 16 * 1024 ** 2 || totalBytes > 64 * 1024 ** 2) {
+      return unavailable("Retained capture exceeds the 16 MiB per-file or 64 MiB total text limit.");
+    }
+  }
+  const root = await mkdtemp(join(tmpdir(), "traces-retained-"));
+  try {
+    const files = /* @__PURE__ */ new Map();
+    for (const file of input.files) {
+      input.signal?.throwIfAborted();
+      const path = resolve(root, file.path);
+      const rel = relative(root, path);
+      if (!file.path || isAbsolute(file.path) || file.path.includes("\\") || file.path.includes("\0") || rel === "" || rel === ".." || rel.startsWith("../") || files.has(path)) {
+        throw new Error("Retained source paths must be unique relative files inside the capture.");
+      }
+      files.set(path, file);
+    }
+    for (const [path, file] of files) {
+      await mkdir(dirname(path), { recursive: true, mode: 448 });
+      await writeFile(path, file.content, { mode: 384, flag: "wx" });
+    }
+    const selected = [];
+    for (const [path, file] of files) {
+      input.signal?.throwIfAborted();
+      const fallback = `unattributed:${root}:${file.path}`;
+      const ref = { harness: adapter.harness, sessionId: fallback, path, cwd: null, mtimeMs: 0 };
+      try {
+        const sources = adapter.sourcePaths ? await adapter.sourcePaths(ref, { signal: input.signal }) : [path];
+        if (sources.some((source) => !files.has(resolve(source)))) {
+          throw new Error("Parser requires files outside the supplied retained capture.");
+        }
+        const spans = validateOtlpSpans(await adapter.parse(ref, {
+          corruptionMode: "recover",
+          taskScope: "all",
+          captureSources: false,
+          signal: input.signal
+        }), `${adapter.harness} retained adapter output`);
+        const roots = spans.filter((span2) => span2.parent_span_id === null);
+        const identities = new Set(roots.map((span2) => sessionIdFromAttributes(span2.attributes)));
+        if (identities.size !== 1 || !identities.has(input.nativeSessionId)) {
+          unselectedFiles.push({ path: file.path, reason: "No unambiguous matching native identity in parser output." });
+          continue;
+        }
+        stampSessionIntegrity(ref, spans);
+        stampSessionIdentity(spans, input.nativeSessionId);
+        for (const span2 of spans) {
+          for (const [key, value] of Object.entries(span2.attributes)) {
+            if (typeof value === "string" && value.includes(root)) {
+              span2.attributes[key] = value.split(root + "/").join("retained://");
+            }
+          }
+        }
+        selected.push({ file, paths: sources, spans });
+      } catch (error) {
+        input.signal?.throwIfAborted();
+        unselectedFiles.push({ path: file.path, reason: `Native parser could not read this file (${error instanceof Error ? error.name : "Error"}).` });
+      }
+    }
+    if (!selected.length) return unavailable("No retained parser entrypoint established the recorded native session identity.");
+    selected.sort((a, b) => b.file.content.length - a.file.content.length || a.file.path.localeCompare(b.file.path));
+    const chosen = selected[0];
+    if (selected.some((candidate) => !chosen.file.content.startsWith(candidate.file.content))) {
+      return unavailable("Retained files contain divergent histories for the same native session.");
+    }
+    return {
+      status: "selected",
+      reason: null,
+      sessionId: input.nativeSessionId,
+      sourceFiles: chosen.paths.map((path) => {
+        const file = files.get(resolve(path));
+        return { path: file.path, sha256: `sha256:${createHash("sha256").update(file.content).digest("hex")}` };
+      }).sort((a, b) => a.path.localeCompare(b.path)),
+      duplicateFiles: selected.slice(1).map((candidate) => candidate.file.path),
+      unselectedFiles,
+      spans: chosen.spans
+    };
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
 export {
   ACTOR_ATTR,
   ATTR,
@@ -347,6 +453,7 @@ export {
   QwenAdapter,
   REACTIONS,
   RESULT_FILE,
+  RETAINED_SESSION_READER_VERSION,
   RULE,
   SESSION_FACTS_MEASUREMENT_VERSION,
   SESSION_FACTS_VERSION_SUFFIX,
@@ -469,6 +576,7 @@ export {
   outboundHash,
   parseIsoToEpochMs,
   parseJsonAnswer,
+  parseRetainedSession,
   parseSession,
   parseSince,
   planTraceAgenticRoute,

package/docs/trace-analysts.md

@@ -425,10 +425,10 @@ What real runs have shown (GLM-5.3 via a coding-plan endpoint, fork at the pinne
   tokens); its first reply gets cut by the endpoint's output limit mid-JSON, and the
   truncation-aware repair turn (re-emit at most 3 findings, terse strings) recovers it — ok:true,
   findings grounded, exit 0.
-- **File, ~794 spans / 2.1 MB artifact:** ~2.2M input tokens of genuine REPL inspection, but the
-  reply never survives the endpoint's output cap even after repair — the run fails honestly
-  (exit 1, raw reply preserved, no findings invented). At that trajectory size, a model with a
-  larger output budget — or a paged finalization — is the next step, not silence about it.
+- **File, ~794 spans / 2.1 MB artifact:** the reply channel alone never survived the endpoint's
+  output cap. The findings.json payload channel finishes it — the analyzer writes the result with
+  its tools before replying — measured live at **8 findings, 0 rejected, exit 0**, 53 model calls,
+  ~3.1M input tokens of REPL inspection.
 
 ## Write one analyst
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.17.1",
-  "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.19.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": {