@tangle-network/traces 0.8.5 → 0.8.12

package/dist/{chunk-D5OMTM4S.js → chunk-PRRWLKSI.js}

@@ -137,7 +137,7 @@ function toOpenInferenceSpan(s) {
   const resourceAttrs = {};
   if (a["service.name"] != null) resourceAttrs["service.name"] = a["service.name"];
   if (a["agent.name"] != null) resourceAttrs["agent.name"] = a["agent.name"];
-  for (const k of ["tangle.subject.key", "git.repository", "git.branch", "git.commit", "tangle.cwd"]) {
+  for (const k of ["tangle.subject.key", "git.repository", "git.branch", "git.commit", "tangle.cwd", "traces.repo_resolution_source"]) {
     if (a[k] != null) resourceAttrs[k] = a[k];
   }
   return {
@@ -160,11 +160,11 @@ function serializeSpans(spans) {
 `;
 }
 async function writeOtlpFile(spans, outPath) {
-  const { mkdtemp: mkdtemp3, writeFile: writeFile4 } = await import("fs/promises");
-  const { tmpdir: tmpdir3 } = await import("os");
-  const { join: join16 } = await import("path");
-  const path = outPath ?? join16(await mkdtemp3(join16(tmpdir3(), "traces-")), "spans.otlp.jsonl");
-  await writeFile4(path, serializeSpans(spans), "utf8");
+  const { mkdtemp: mkdtemp5, writeFile: writeFile6 } = await import("fs/promises");
+  const { tmpdir: tmpdir5 } = await import("os");
+  const { join: join19 } = await import("path");
+  const path = outPath ?? join19(await mkdtemp5(join19(tmpdir5(), "traces-")), "spans.otlp.jsonl");
+  await writeFile6(path, serializeSpans(spans), "utf8");
   return path;
 }
 
@@ -218,6 +218,8 @@ var ATTR = {
   GIT_BRANCH_NAME: "git.branch",
   /** HEAD short sha at conversion time. */
   GIT_COMMIT: "git.commit",
+  /** How traces resolved the session cwd: recorded cwd, repaired cwd, or span path. */
+  REPO_RESOLUTION_SOURCE: "traces.repo_resolution_source",
   GIT_BRANCH: "tangle.git_branch",
   HOST: "tangle.host",
   /** Basename of the session file. (Renamed from the ambiguous `tangle.source`,
@@ -860,14 +862,18 @@ var CodexAdapter = class {
         continue;
       }
       if (opts.sinceMs && st.mtimeMs < opts.sinceMs) continue;
-      const head = (await readFile4(path, "utf8").catch(() => "")).split("\n", 1)[0] ?? "";
+      const head = (await readFile4(path, "utf8").catch(() => "")).split("\n", 40);
       let cwd = null;
       let id = basename3(path).replace(/^rollout-[\dT-]+-/, "").replace(/\.jsonl$/, "");
-      try {
-        const meta = JSON.parse(head);
-        if (meta.payload?.cwd) cwd = meta.payload.cwd;
-        if (meta.payload?.id) id = meta.payload.id;
-      } catch {
+      for (const line of head) {
+        if (!line) continue;
+        try {
+          const l = JSON.parse(line);
+          if (l.type === "session_meta" && l.payload?.id) id = l.payload.id;
+          if (!cwd && l.payload?.cwd) cwd = l.payload.cwd;
+        } catch {
+        }
+        if (cwd) break;
       }
       if (opts.cwd && (!cwd || !cwd.startsWith(opts.cwd))) continue;
       refs.push({ harness: this.harness, sessionId: id, path, cwd, mtimeMs: st.mtimeMs });
@@ -1441,6 +1447,20 @@ var GeminiFamilyAdapter = class {
   chatsRoot() {
     return join8(homedir7(), this.homeDirName, "tmp");
   }
+  /** `<home>/projects.json` maps `{ <absolute-cwd>: <projectName> }`. The session
+   *  dir name (`tmp/<projectHash>/`) is that projectName for registered projects,
+   *  so inverting the map recovers cwd. (Unregistered/older dirs are opaque cwd
+   *  digests and stay null.) Loaded once per locate(). */
+  async loadProjectCwds() {
+    const nameToPath = /* @__PURE__ */ new Map();
+    try {
+      const raw = await readFile8(join8(homedir7(), this.homeDirName, "projects.json"), "utf8");
+      const projects = JSON.parse(raw).projects ?? {};
+      for (const [path, name] of Object.entries(projects)) nameToPath.set(name, path);
+    } catch {
+    }
+    return nameToPath;
+  }
   async locate(opts = {}) {
     const root = this.chatsRoot();
     let projectDirs;
@@ -1449,8 +1469,10 @@ var GeminiFamilyAdapter = class {
     } catch {
       return [];
     }
+    const projectCwds = await this.loadProjectCwds();
     const refs = [];
     for (const pd of projectDirs) {
+      const cwd = projectCwds.get(pd) ?? null;
       const chatsDir = join8(root, pd, "chats");
       let files;
       try {
@@ -1468,8 +1490,8 @@ var GeminiFamilyAdapter = class {
           continue;
         }
         if (opts.sinceMs && st.mtimeMs < opts.sinceMs) continue;
-        if (opts.cwd) continue;
-        refs.push({ harness: this.harness, sessionId: f.replace(/\.json$/, ""), path, cwd: null, mtimeMs: st.mtimeMs });
+        if (opts.cwd && (!cwd || !cwd.startsWith(opts.cwd))) continue;
+        refs.push({ harness: this.harness, sessionId: f.replace(/\.json$/, ""), path, cwd, mtimeMs: st.mtimeMs });
       }
     }
     return refs.sort((a, b) => b.mtimeMs - a.mtimeMs);
@@ -2089,6 +2111,8 @@ function selectAdapters(opts) {
 }
 
 // src/repo.ts
+import { stat as stat11 } from "fs/promises";
+import { dirname, isAbsolute, join as join12, normalize, parse as parsePath } from "path";
 function normalizeRemote(url) {
   const raw = url.trim();
   if (!raw) return null;
@@ -2112,7 +2136,6 @@ function normalizeRemote(url) {
   return null;
 }
 async function readGit(cwd) {
-  const { stat: stat11 } = await import("fs/promises");
   await stat11(`${cwd}/.git`);
   const { execFile } = await import("child_process");
   const { promisify } = await import("util");
@@ -2141,17 +2164,154 @@ async function readGit(cwd) {
     commit
   };
 }
+async function pathStat(path) {
+  try {
+    return await stat11(path);
+  } catch {
+    return null;
+  }
+}
+async function directoryExists(path) {
+  const s = await pathStat(path);
+  return Boolean(s?.isDirectory());
+}
+async function nearestExistingDir(path) {
+  if (!path || !isAbsolute(path)) return null;
+  let cur = normalize(path);
+  for (; ; ) {
+    const s = await pathStat(cur);
+    if (s?.isDirectory()) return cur;
+    if (s?.isFile()) return dirname(cur);
+    const parent = dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+async function findGitRoot(path) {
+  let cur = await nearestExistingDir(path);
+  while (cur) {
+    if (await pathStat(join12(cur, ".git"))) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+  return null;
+}
+async function repairDashedPath(cwd) {
+  if (!isAbsolute(cwd) || await directoryExists(cwd)) return null;
+  const normalized = normalize(cwd);
+  const parsed = parsePath(normalized);
+  const parts = normalized.slice(parsed.root.length).split("/").filter(Boolean);
+  if (parts.length === 0) return null;
+  let current = parsed.root;
+  let index = 0;
+  while (index < parts.length) {
+    const nextPart = parts[index];
+    if (!nextPart) break;
+    const exact = join12(current, nextPart);
+    if (!await directoryExists(exact)) break;
+    current = exact;
+    index += 1;
+  }
+  while (index < parts.length) {
+    let match = null;
+    let consumed = 0;
+    for (let n = parts.length - index; n >= 1; n -= 1) {
+      const segment = parts.slice(index, index + n).join("-");
+      const candidate = join12(current, segment);
+      if (await directoryExists(candidate)) {
+        match = candidate;
+        consumed = n;
+        break;
+      }
+    }
+    if (!match) return null;
+    current = match;
+    index += consumed;
+  }
+  return current !== normalized ? current : null;
+}
+var ABSOLUTE_PATH_RE = /\/(?:home|tmp|private\/tmp|Users|work|workspace|workspaces|mnt|srv|var|opt|repo|app)\/[^\s"'`<>|;]+/g;
+var MAX_SPAN_PATH_CANDIDATES = 64;
+var MAX_SPAN_TEXT_CHARS = 2e5;
+var SOURCE_WEIGHT = {
+  none: 0,
+  "span-path": 5,
+  "ref-cwd": 50,
+  "repaired-cwd": 90,
+  "span-workdir": 100
+};
+function cleanPathCandidate(raw) {
+  let value = raw.trim().replace(/\\n/g, "").replace(/[),\].}]+$/g, "").replace(/:\d+(?::\d+)?$/g, "");
+  value = normalize(value);
+  return isAbsolute(value) ? value : null;
+}
+function looksLikeWorkdirKey(key) {
+  return key === "cwd" || key === "workdir" || key === "workingDirectory" || key === "working_directory";
+}
+function* pathEvidenceFromText(text, source) {
+  if (source === "span-workdir") {
+    const direct = cleanPathCandidate(text);
+    if (direct) yield { path: direct, source, weight: SOURCE_WEIGHT[source] };
+  }
+  for (const match of text.matchAll(ABSOLUTE_PATH_RE)) {
+    const candidate = cleanPathCandidate(match[0]);
+    if (candidate) yield { path: candidate, source: "span-path", weight: SOURCE_WEIGHT["span-path"] };
+  }
+}
+function* pathsFromUnknown(value, key, depth = 0) {
+  if (depth > 4 || value == null) return;
+  if (typeof value === "string") {
+    yield* pathEvidenceFromText(value, looksLikeWorkdirKey(key) ? "span-workdir" : "span-path");
+    const trimmed = value.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}") || trimmed.startsWith("[") && trimmed.endsWith("]")) {
+      try {
+        yield* pathsFromUnknown(JSON.parse(trimmed), key, depth + 1);
+      } catch {
+      }
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) yield* pathsFromUnknown(item, key, depth + 1);
+    return;
+  }
+  if (typeof value === "object") {
+    for (const [childKey, item] of Object.entries(value)) yield* pathsFromUnknown(item, childKey, depth + 1);
+  }
+}
+function extractAbsolutePaths(spans) {
+  const paths = [];
+  const seen = /* @__PURE__ */ new Set();
+  let scannedChars = 0;
+  for (const span2 of spans) {
+    for (const value of [span2.name, span2.status.message, ...Object.values(span2.attributes)]) {
+      for (const evidence of pathsFromUnknown(value)) {
+        scannedChars += evidence.path.length;
+        if (scannedChars > MAX_SPAN_TEXT_CHARS) return paths;
+        const key = `${evidence.source}:${evidence.path}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        paths.push(evidence);
+        if (paths.length >= MAX_SPAN_PATH_CANDIDATES) return paths;
+      }
+    }
+  }
+  return paths;
+}
 async function resolveRepoAttrs(cwd) {
   if (!cwd) return {};
   const attrs = { [ATTR.CWD]: cwd };
-  const basename9 = (() => {
+  const basename10 = (() => {
     const trimmed = cwd.replace(/\/+$/g, "");
     const idx = trimmed.lastIndexOf("/");
     const name = idx === -1 ? trimmed : trimmed.slice(idx + 1);
     return name || trimmed;
   })();
   try {
-    const { remote, branch, commit } = await readGit(cwd);
+    const gitRoot = await findGitRoot(cwd);
+    if (!gitRoot) throw new Error("no git root");
+    const { remote, branch, commit } = await readGit(gitRoot);
     const normalized = remote ? normalizeRemote(remote) : null;
     if (normalized) {
       attrs[ATTR.SUBJECT_KEY] = normalized;
@@ -2164,9 +2324,46 @@ async function resolveRepoAttrs(cwd) {
     if (commit) attrs[ATTR.GIT_COMMIT] = commit;
   } catch {
   }
-  attrs[ATTR.SUBJECT_KEY] = basename9;
+  attrs[ATTR.SUBJECT_KEY] = basename10;
   return attrs;
 }
+async function repoCandidateForPath(path) {
+  return await findGitRoot(path) ?? await nearestExistingDir(path);
+}
+async function resolveSessionRepoAttrs(cwd, spans) {
+  const candidates = /* @__PURE__ */ new Map();
+  const add = (value, source, weight = SOURCE_WEIGHT[source]) => {
+    if (!value) return;
+    const existing = candidates.get(value);
+    if (existing) {
+      existing.score += weight;
+      if (SOURCE_WEIGHT[source] > SOURCE_WEIGHT[existing.source]) existing.source = source;
+      return;
+    }
+    candidates.set(value, { cwd: value, source, score: weight, order: candidates.size });
+  };
+  if (cwd) {
+    add(await repairDashedPath(cwd), "repaired-cwd");
+    add(cwd, "ref-cwd");
+  }
+  for (const evidence of extractAbsolutePaths(spans)) {
+    add(await repoCandidateForPath(evidence.path), evidence.source, evidence.weight);
+  }
+  const resolved = [];
+  for (const candidate of candidates.values()) {
+    const attrs = await resolveRepoAttrs(candidate.cwd);
+    resolved.push({ ...candidate, attrs });
+  }
+  const byScore = (a, b) => b.score - a.score || a.order - b.order;
+  const withGit = resolved.filter((candidate) => candidate.attrs[ATTR.GIT_REPOSITORY]).sort(byScore);
+  const selected = withGit[0] ?? resolved.filter((candidate) => candidate.attrs[ATTR.SUBJECT_KEY]).sort(byScore)[0];
+  if (!selected) return { attrs: {}, cwd: null, source: "none" };
+  return {
+    attrs: { ...selected.attrs, [ATTR.REPO_RESOLUTION_SOURCE]: selected.source },
+    cwd: selected.attrs[ATTR.CWD] ?? selected.cwd,
+    source: selected.source
+  };
+}
 function stampRepoAttrs(spans, attrs) {
   const keys = Object.keys(attrs);
   if (keys.length === 0) return spans;
@@ -2181,8 +2378,9 @@ function stampRepoAttrs(spans, attrs) {
 // src/session-source.ts
 async function parseSession(adapter, ref) {
   const spans = await adapter.parse(ref);
-  const repoAttrs = await resolveRepoAttrs(ref.cwd);
-  stampRepoAttrs(spans, repoAttrs);
+  const repo = await resolveSessionRepoAttrs(ref.cwd, spans);
+  if (repo.cwd) ref.cwd = repo.cwd;
+  stampRepoAttrs(spans, repo.attrs);
   return spans;
 }
 async function* scanSessions(opts) {
@@ -2214,7 +2412,7 @@ async function* scanSessions(opts) {
 // src/evidence.ts
 import { mkdtemp, writeFile } from "fs/promises";
 import { tmpdir } from "os";
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 function stringAttr(span2, key) {
   const value = span2.attributes[key];
   return typeof value === "string" && value.length > 0 ? value : void 0;
@@ -2234,7 +2432,8 @@ function repoFromSpans(spans) {
     attrs.branch ??= stringAttr(span2, ATTR.GIT_BRANCH_NAME);
     attrs.commit ??= stringAttr(span2, ATTR.GIT_COMMIT);
     attrs.cwd ??= stringAttr(span2, ATTR.CWD);
-    if (attrs.subjectKey && attrs.repository && attrs.branch && attrs.commit && attrs.cwd) break;
+    attrs.resolutionSource ??= stringAttr(span2, ATTR.REPO_RESOLUTION_SOURCE);
+    if (attrs.subjectKey && attrs.repository && attrs.branch && attrs.commit && attrs.cwd && attrs.resolutionSource) break;
   }
   return attrs;
 }
@@ -2265,6 +2464,7 @@ async function buildPolicyEvidenceRecord(ref, spans, opts = {}) {
   const loopLimit = opts.maxLoopExamples ?? 25;
   const loopFindings = pipelines.stuckLoops.findings;
   const { firstSpanAt, lastSpanAt } = timeBounds(spans);
+  const repo = repoFromSpans(spans);
   return {
     schemaVersion: 1,
     kind: "traces.policy_evidence.session",
@@ -2273,10 +2473,10 @@ async function buildPolicyEvidenceRecord(ref, spans, opts = {}) {
       harness: ref.harness,
       sessionId: ref.sessionId,
       path: ref.path,
-      cwd: ref.cwd,
+      cwd: repo.cwd ?? ref.cwd,
       mtimeMs: ref.mtimeMs
     },
-    repo: repoFromSpans(spans),
+    repo,
     metrics: {
       spanCount: spans.length,
       llmTurnCount: llmSpans.length,
@@ -2321,7 +2521,7 @@ function serializePolicyEvidence(records) {
 `;
 }
 async function writePolicyEvidenceFile(records, outPath) {
-  const path = outPath ?? join12(await mkdtemp(join12(tmpdir(), "traces-evidence-")), "policy-evidence.jsonl");
+  const path = outPath ?? join13(await mkdtemp(join13(tmpdir(), "traces-evidence-")), "policy-evidence.jsonl");
   await writeFile(path, serializePolicyEvidence(records), "utf8");
   return path;
 }
@@ -2502,7 +2702,7 @@ async function applyRedactor(spans, redactor) {
 import { createHash } from "crypto";
 import { mkdtemp as mkdtemp2, readFile as readFile12, writeFile as writeFile2 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 function isObject(value) {
   return value != null && typeof value === "object" && !Array.isArray(value);
 }
@@ -2654,7 +2854,8 @@ function policyEvidenceToSpans(records) {
       [ATTR.GIT_REPOSITORY]: record.repo.repository,
       [ATTR.GIT_BRANCH_NAME]: record.repo.branch,
       [ATTR.GIT_COMMIT]: record.repo.commit,
-      [ATTR.CWD]: record.repo.cwd ?? record.session.cwd
+      [ATTR.CWD]: record.repo.cwd ?? record.session.cwd,
+      [ATTR.REPO_RESOLUTION_SOURCE]: record.repo.resolutionSource
     };
     return span({
       traceId,
@@ -2873,11 +3074,308 @@ async function exportTraceEvidenceFile(inputPath, opts = {}) {
 }
 async function writeTraceEvidenceExportFile(inputPath, outPath, opts = {}) {
   const result = await exportTraceEvidenceFile(inputPath, opts);
-  const path = outPath ?? join13(await mkdtemp2(join13(tmpdir2(), "traces-export-")), "spans.openinference.jsonl");
+  const path = outPath ?? join14(await mkdtemp2(join14(tmpdir2(), "traces-export-")), "spans.openinference.jsonl");
   await writeFile2(path, serializeSpans(result.spans), "utf8");
   return { ...result, path };
 }
 
+// src/inspect.ts
+import { mkdtemp as mkdtemp3, readFile as readFile13, writeFile as writeFile3 } from "fs/promises";
+import { tmpdir as tmpdir3 } from "os";
+import { basename as basename8, join as join15 } from "path";
+var severityRank = {
+  high: 0,
+  medium: 1,
+  low: 2
+};
+function allContextFiles(index) {
+  return index.context?.roots.flatMap((root) => root.files) ?? [];
+}
+function repoLabel(row) {
+  return row.repo.subjectKey ?? row.repo.repository ?? row.repo.cwd ?? row.session.cwd ?? "(repo unknown)";
+}
+function sessionLabel(row) {
+  const id = row.session.sessionId.length > 12 ? row.session.sessionId.slice(0, 12) : row.session.sessionId;
+  return `${row.session.harness}:${id} (${repoLabel(row)})`;
+}
+function pct(value) {
+  return `${(value * 100).toFixed(value >= 0.1 ? 0 : 1)}%`;
+}
+function topToolErrors(row) {
+  const tools = row.tools.filter((tool) => tool.errors > 0).sort((a, b) => b.errors - a.errors || b.calls - a.calls || a.name.localeCompare(b.name)).slice(0, 3).map((tool) => `${tool.name} ${tool.errors}/${tool.calls}`);
+  return tools.length > 0 ? tools.join(", ") : "no tool-level error breakdown";
+}
+function topLoopTools(row) {
+  const byTool = /* @__PURE__ */ new Map();
+  for (const loop of row.signals.stuckLoops) {
+    const current = byTool.get(loop.toolName) ?? { groups: 0, maxOccurrences: 0 };
+    current.groups += 1;
+    current.maxOccurrences = Math.max(current.maxOccurrences, loop.occurrences);
+    byTool.set(loop.toolName, current);
+  }
+  const loops = [...byTool.entries()].sort(([, a], [, b]) => b.groups - a.groups || b.maxOccurrences - a.maxOccurrences).slice(0, 3).map(([toolName2, stats]) => `${toolName2} ${stats.groups} group(s), max x${stats.maxOccurrences}`);
+  const suffix = row.signals.stuckLoopsOmitted > 0 ? `, +${row.signals.stuckLoopsOmitted} omitted` : "";
+  return loops.length > 0 ? `${loops.join(", ")}${suffix}` : `${row.signals.stuckLoopCount} loop(s)`;
+}
+function sortFindings(findings) {
+  return findings.sort((a, b) => severityRank[a.severity] - severityRank[b.severity] || b.impact - a.impact || a.id.localeCompare(b.id)).map((finding) => ({ ...finding }));
+}
+function contextSourceCounts(index) {
+  return { contextFiles: allContextFiles(index).length };
+}
+function addSessionFindings(index, findings) {
+  const sessions = index.sessions;
+  if (index.totals.sessions === 0) {
+    findings.push({
+      id: "index.no-sessions",
+      severity: "high",
+      area: "index",
+      title: "No sessions were indexed",
+      impact: 100,
+      evidence: ["The index contains 0 session rows."],
+      next: "Run `traces list` for the target harness, then rerun `traces index` with the right --harness, --cwd, --since, or --last."
+    });
+    return;
+  }
+  const missingRepo = sessions.filter((row) => !row.repo.subjectKey && !row.repo.repository && !row.repo.cwd && !row.session.cwd);
+  if (missingRepo.length > 0) {
+    findings.push({
+      id: "repo.missing-attribution",
+      severity: missingRepo.length / index.totals.sessions >= 0.25 ? "high" : "medium",
+      area: "repo",
+      title: `${missingRepo.length}/${index.totals.sessions} session(s) have no repo or cwd`,
+      impact: missingRepo.length,
+      evidence: missingRepo.slice(0, 5).map((row) => `${row.session.harness}:${row.session.sessionId} at ${row.session.path}`),
+      next: "Improve adapter cwd recovery or pass --cwd for explicit session files so findings can be grouped by repo.",
+      refs: missingRepo.slice(0, 5).map((row) => row.session.path)
+    });
+  }
+  const loopSessions = sessions.filter((row) => row.signals.stuckLoopCount > 0).sort((a, b) => b.signals.stuckLoopCount - a.signals.stuckLoopCount);
+  if (loopSessions.length > 0) {
+    const stuckLoops = loopSessions.reduce((sum, row) => sum + row.signals.stuckLoopCount, 0);
+    findings.push({
+      id: "session.repeated-call-loops",
+      severity: stuckLoops >= 10 || loopSessions.length / index.totals.sessions >= 0.3 ? "high" : "medium",
+      area: "session",
+      title: `Repeated tool-call loops in ${loopSessions.length}/${index.totals.sessions} session(s)`,
+      impact: stuckLoops,
+      evidence: [
+        `${stuckLoops} repeated-call loop(s) across ${loopSessions.length} session(s).`,
+        ...loopSessions.slice(0, 5).map((row) => `${sessionLabel(row)}: ${row.signals.stuckLoopCount} loop(s); ${topLoopTools(row)}`)
+      ],
+      next: "Inspect the repeated commands and results in the referenced sessions; fix the instruction or tool path that lets the same failed action repeat.",
+      refs: loopSessions.slice(0, 5).map((row) => row.session.path)
+    });
+  }
+  const errorSessions = sessions.filter((row) => row.metrics.erroredToolCallCount >= 10 || row.metrics.toolErrorRate >= 0.1).sort((a, b) => b.metrics.erroredToolCallCount - a.metrics.erroredToolCallCount || b.metrics.toolErrorRate - a.metrics.toolErrorRate);
+  if (errorSessions.length > 0) {
+    const errors = errorSessions.reduce((sum, row) => sum + row.metrics.erroredToolCallCount, 0);
+    const worstRate = Math.max(...errorSessions.map((row) => row.metrics.toolErrorRate));
+    findings.push({
+      id: "session.tool-errors",
+      severity: errors >= 50 || worstRate >= 0.3 ? "high" : "medium",
+      area: "session",
+      title: `High tool-error count/rate in ${errorSessions.length}/${index.totals.sessions} session(s)`,
+      impact: errors,
+      evidence: errorSessions.slice(0, 5).map((row) => `${sessionLabel(row)}: ${row.metrics.erroredToolCallCount}/${row.metrics.toolCallCount} tool errors (${pct(row.metrics.toolErrorRate)}); ${topToolErrors(row)}`),
+      next: "Fix the most common failing command/tool first, then rerun `traces index` to confirm the error count drops.",
+      refs: errorSessions.slice(0, 5).map((row) => row.session.path)
+    });
+  }
+  const largeSessions = sessions.map((row) => ({ row, tokens: row.metrics.inputTokens + row.metrics.outputTokens })).filter(({ tokens: tokens2 }) => tokens2 >= 5e5).sort((a, b) => b.tokens - a.tokens);
+  if (largeSessions.length > 0) {
+    const largest = largeSessions[0]?.tokens ?? 0;
+    findings.push({
+      id: "session.large-token-runs",
+      severity: largest >= 1e6 ? "medium" : "low",
+      area: "session",
+      title: `${largeSessions.length} session(s) reported at least 500k summed tokens`,
+      impact: largest,
+      evidence: largeSessions.slice(0, 5).map(({ row, tokens: tokens2 }) => `${sessionLabel(row)}: ${tokens2.toLocaleString()} reported summed tokens (${row.metrics.inputTokens.toLocaleString()} in, ${row.metrics.outputTokens.toLocaleString()} out)`),
+      next: "Check whether these sessions need shorter handoffs, smaller files, split tasks, or clearer token accounting before optimizing anything else.",
+      refs: largeSessions.slice(0, 5).map(({ row }) => row.session.path)
+    });
+  }
+}
+function addContextFindings(index, findings) {
+  const files = allContextFiles(index);
+  if (index.totals.sessions > 0 && files.length === 0) {
+    findings.push({
+      id: "context.none-indexed",
+      severity: "medium",
+      area: "context",
+      title: "No nearby repo instructions or .evolve files were indexed",
+      impact: index.totals.sessions,
+      evidence: ["The index has session rows but 0 context files."],
+      next: "Add AGENTS.md or CLAUDE.md near active repos, or ensure session cwd points at the repo so traces can join sessions to local process docs."
+    });
+    return;
+  }
+  const hasContextRoots = (index.context?.totals.roots ?? 0) > 0;
+  if (hasContextRoots && (index.context?.totals.instructionDocs ?? 0) === 0) {
+    findings.push({
+      id: "context.no-instruction-docs",
+      severity: "medium",
+      area: "context",
+      title: "Context roots exist but no AGENTS.md, CLAUDE.md, or GEMINI.md files were found",
+      impact: index.context?.totals.roots ?? 0,
+      evidence: index.context?.roots.slice(0, 5).map((root) => root.root) ?? [],
+      next: "Add a short repo-level instruction file that links to stable process docs and anti-patterns."
+    });
+  }
+  const longInstructionDocs = files.filter((file) => file.kind === "instruction-doc" && (file.lines ?? 0) >= 100 && file.markdown?.hasToc === false).sort((a, b) => (b.lines ?? 0) - (a.lines ?? 0));
+  if (longInstructionDocs.length > 0) {
+    const longest = longInstructionDocs[0]?.lines ?? 0;
+    findings.push({
+      id: "context.long-docs-without-toc",
+      severity: longest >= 200 ? "medium" : "low",
+      area: "context",
+      title: `${longInstructionDocs.length} long instruction doc(s) are missing a Contents section`,
+      impact: longest,
+      evidence: longInstructionDocs.slice(0, 5).map((file) => `${file.path}: ${file.lines ?? 0} lines, ${file.markdown?.headings ?? 0} heading(s), no Contents section`),
+      next: "Add a compact Contents section or split stable rules into linked docs/processes and docs/anti-patterns files.",
+      refs: longInstructionDocs.slice(0, 5).map((file) => file.path)
+    });
+  }
+  const longNarrativeDocs = files.filter((file) => (file.kind === "reflection" || file.kind === "handoff") && (file.lines ?? 0) >= 40 && file.markdown?.hasToc === false).sort((a, b) => (b.lines ?? 0) - (a.lines ?? 0));
+  if (longNarrativeDocs.length > 0) {
+    const longest = longNarrativeDocs[0]?.lines ?? 0;
+    findings.push({
+      id: "context.long-narrative-docs-without-toc",
+      severity: longest >= 120 ? "medium" : "low",
+      area: "context",
+      title: `${longNarrativeDocs.length} long reflection/handoff doc(s) are hard to scan`,
+      impact: longest,
+      evidence: longNarrativeDocs.slice(0, 5).map((file) => `${file.path}: ${file.lines ?? 0} lines, ${file.markdown?.headings ?? 0} heading(s), no Contents section`),
+      next: "Put the decision, evidence, and next action at the top; add Contents only when the note is long enough to revisit.",
+      refs: longNarrativeDocs.slice(0, 5).map((file) => file.path)
+    });
+  }
+  const invalidJsonlFiles = files.filter((file) => (file.jsonl?.invalidRows ?? 0) > 0).sort((a, b) => (b.jsonl?.invalidRows ?? 0) - (a.jsonl?.invalidRows ?? 0));
+  if (invalidJsonlFiles.length > 0) {
+    const invalidRows = invalidJsonlFiles.reduce((sum, file) => sum + (file.jsonl?.invalidRows ?? 0), 0);
+    findings.push({
+      id: "context.invalid-jsonl",
+      severity: "high",
+      area: "context",
+      title: `${invalidRows} invalid JSONL row(s) in indexed context files`,
+      impact: invalidRows,
+      evidence: invalidJsonlFiles.slice(0, 5).map((file) => `${file.path}: ${file.jsonl?.invalidRows ?? 0}/${file.jsonl?.rows ?? 0} invalid row(s)`),
+      next: "Fix or quarantine invalid rows before mining these logs; malformed rows make downstream joins incomplete.",
+      refs: invalidJsonlFiles.slice(0, 5).map((file) => file.path)
+    });
+  }
+  const skillRunFiles = files.filter((file) => basename8(file.path) === "skill-runs.jsonl" && (file.jsonl?.rows ?? 0) > 0).map((file) => {
+    const rows = file.jsonl?.rows ?? 0;
+    const keys = file.jsonl?.keys ?? {};
+    const linkKeyCounts = {
+      transcriptPath: keys.transcriptPath ?? 0,
+      traceDir: keys.traceDir ?? 0,
+      sessionPath: keys.sessionPath ?? 0,
+      sessionId: keys.sessionId ?? 0
+    };
+    const bestLinkKeyRows = Math.max(
+      linkKeyCounts.transcriptPath,
+      linkKeyCounts.traceDir,
+      linkKeyCounts.sessionPath,
+      linkKeyCounts.sessionId
+    );
+    return { file, rows, bestLinkKeyRows, linkKeyCounts };
+  }).filter(({ rows, bestLinkKeyRows }) => bestLinkKeyRows < rows).sort((a, b) => b.rows - b.bestLinkKeyRows - (a.rows - a.bestLinkKeyRows));
+  if (skillRunFiles.length > 0) {
+    const missing = skillRunFiles.reduce((sum, row) => sum + (row.rows - row.bestLinkKeyRows), 0);
+    findings.push({
+      id: "context.skill-run-trace-links",
+      severity: skillRunFiles.some((row) => row.bestLinkKeyRows === 0) ? "medium" : "low",
+      area: "context",
+      title: `${skillRunFiles.length} skill-run file(s) have incomplete direct session-link fields`,
+      impact: missing,
+      evidence: skillRunFiles.slice(0, 5).map(({ file, rows, bestLinkKeyRows, linkKeyCounts }) => `${file.path}: best link key covers ${bestLinkKeyRows}/${rows} row(s); transcriptPath ${linkKeyCounts.transcriptPath}, traceDir ${linkKeyCounts.traceDir}, sessionPath ${linkKeyCounts.sessionPath}, sessionId ${linkKeyCounts.sessionId}`),
+      next: "Write a transcriptPath or sessionId on every skill-run row so traces can connect skill outcomes to the actual session behavior.",
+      refs: skillRunFiles.slice(0, 5).map(({ file }) => file.path)
+    });
+  }
+}
+function inspectSessionIndex(index, opts = {}) {
+  const findings = [];
+  addSessionFindings(index, findings);
+  addContextFindings(index, findings);
+  const ranked = sortFindings(findings).slice(0, opts.maxFindings ?? 25);
+  const sourceCounts = contextSourceCounts(index);
+  return {
+    schemaVersion: 1,
+    kind: "traces.inspection_report",
+    generatedAt: opts.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    source: {
+      indexGeneratedAt: index.generatedAt,
+      sessions: index.totals.sessions,
+      contextFiles: sourceCounts.contextFiles
+    },
+    totals: {
+      findings: ranked.length,
+      high: ranked.filter((finding) => finding.severity === "high").length,
+      medium: ranked.filter((finding) => finding.severity === "medium").length,
+      low: ranked.filter((finding) => finding.severity === "low").length
+    },
+    findings: ranked
+  };
+}
+function renderInspectionReport(report) {
+  const lines = [];
+  lines.push(
+    `traces inspect - ${report.totals.findings} finding(s) from ${report.source.sessions} session(s), ${report.source.contextFiles} context file(s)`
+  );
+  lines.push(`Index generated: ${report.source.indexGeneratedAt ?? "unknown"}`);
+  lines.push(`Report generated: ${report.generatedAt}`);
+  lines.push(`Severity totals: high ${report.totals.high}, medium ${report.totals.medium}, low ${report.totals.low}`);
+  if (report.findings.length === 0) {
+    lines.push("");
+    lines.push("No ranked findings. Keep rerunning this after larger or fresher indexes.");
+    return `${lines.join("\n")}
+`;
+  }
+  report.findings.forEach((finding, i) => {
+    lines.push("");
+    lines.push(`## ${i + 1}. [${finding.severity}] ${finding.title}`);
+    lines.push(`Area: ${finding.area}  Impact: ${finding.impact}`);
+    lines.push("Evidence:");
+    for (const item of finding.evidence) lines.push(`- ${item}`);
+    lines.push(`Next: ${finding.next}`);
+    if (finding.refs && finding.refs.length > 0) {
+      lines.push("Refs:");
+      for (const ref of finding.refs.slice(0, 5)) lines.push(`- ${ref}`);
+    }
+  });
+  return `${lines.join("\n")}
+`;
+}
+function serializeInspectionReport(report) {
+  return `${JSON.stringify(report, null, 2)}
+`;
+}
+function assertSessionIndex(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("session index file must contain a JSON object");
+  }
+  const candidate = value;
+  if (candidate.kind !== "traces.session_index" || candidate.schemaVersion !== 1 || !Array.isArray(candidate.sessions)) {
+    throw new Error("input is not a traces.session_index v1 file");
+  }
+  if (!candidate.totals || typeof candidate.totals !== "object") {
+    throw new Error("session index is missing totals");
+  }
+}
+async function readSessionIndexFile(path) {
+  const parsed = JSON.parse(await readFile13(path, "utf8"));
+  assertSessionIndex(parsed);
+  return parsed;
+}
+async function writeInspectionReportFile(report, outPath) {
+  const path = outPath ?? join15(await mkdtemp3(join15(tmpdir3(), "traces-inspect-")), "inspection-report.md");
+  await writeFile3(path, renderInspectionReport(report), "utf8");
+  return path;
+}
+
 // src/observer.ts
 var sleep = (ms, signal) => new Promise((resolve) => {
   const onAbort = () => {
@@ -3042,14 +3540,236 @@ function analyzeReactions(spans) {
   };
 }
 
+// src/session-index.ts
+import { mkdtemp as mkdtemp4, readdir as readdir11, readFile as readFile14, stat as stat12, writeFile as writeFile4 } from "fs/promises";
+import { tmpdir as tmpdir4 } from "os";
+import { dirname as dirname2, join as join16 } from "path";
+function indexRow(record) {
+  return {
+    session: record.session,
+    repo: record.repo,
+    time: {
+      firstSpanAt: record.metrics.firstSpanAt,
+      lastSpanAt: record.metrics.lastSpanAt
+    },
+    metrics: {
+      spanCount: record.metrics.spanCount,
+      llmTurnCount: record.metrics.llmTurnCount,
+      toolCallCount: record.metrics.toolCallCount,
+      erroredToolCallCount: record.metrics.erroredToolCallCount,
+      inputTokens: record.metrics.inputTokens,
+      outputTokens: record.metrics.outputTokens,
+      toolErrorRate: record.signals.toolErrorRate
+    },
+    models: record.metrics.models,
+    tools: record.metrics.tools,
+    signals: record.signals
+  };
+}
+function uniqueSorted(values) {
+  return [...new Set([...values].filter((value) => Boolean(value)))].sort();
+}
+function buildSessionIndex(records, opts = {}) {
+  const sessions = records.map(indexRow);
+  return {
+    schemaVersion: 1,
+    kind: "traces.session_index",
+    generatedAt: opts.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    ...opts.selection ? { selection: opts.selection } : {},
+    totals: {
+      sessions: sessions.length,
+      spans: sessions.reduce((sum, row) => sum + row.metrics.spanCount, 0),
+      llmTurns: sessions.reduce((sum, row) => sum + row.metrics.llmTurnCount, 0),
+      toolCalls: sessions.reduce((sum, row) => sum + row.metrics.toolCallCount, 0),
+      erroredToolCalls: sessions.reduce((sum, row) => sum + row.metrics.erroredToolCallCount, 0),
+      inputTokens: sessions.reduce((sum, row) => sum + row.metrics.inputTokens, 0),
+      outputTokens: sessions.reduce((sum, row) => sum + row.metrics.outputTokens, 0),
+      stuckLoopSessions: sessions.filter((row) => row.signals.stuckLoopCount > 0).length,
+      stuckLoops: sessions.reduce((sum, row) => sum + row.signals.stuckLoopCount, 0),
+      harnesses: uniqueSorted(sessions.map((row) => row.session.harness)),
+      repos: uniqueSorted(sessions.map((row) => row.repo.subjectKey ?? row.repo.repository ?? row.repo.cwd ?? row.session.cwd ?? void 0)),
+      models: uniqueSorted(sessions.flatMap((row) => row.models)),
+      tools: uniqueSorted(sessions.flatMap((row) => row.tools.map((tool) => tool.name)))
+    },
+    ...opts.context ? { context: opts.context } : {},
+    sessions
+  };
+}
+async function pathStat2(path) {
+  try {
+    return await stat12(path);
+  } catch {
+    return null;
+  }
+}
+async function fileExists(path) {
+  return Boolean((await pathStat2(path))?.isFile());
+}
+async function dirExists(path) {
+  return Boolean((await pathStat2(path))?.isDirectory());
+}
+async function findContextRoot(cwd) {
+  if (!cwd) return null;
+  let current = cwd;
+  const s = await pathStat2(current);
+  if (!s) return null;
+  if (!s.isDirectory()) current = dirname2(current);
+  for (; ; ) {
+    if (await pathStat2(join16(current, ".git")) || await dirExists(join16(current, ".evolve")) || await fileExists(join16(current, "AGENTS.md")) || await fileExists(join16(current, "CLAUDE.md"))) {
+      return current;
+    }
+    const parent = dirname2(current);
+    if (parent === current) return s.isDirectory() ? cwd : dirname2(cwd);
+    current = parent;
+  }
+}
+function countLines(text) {
+  if (text.length === 0) return 0;
+  return text.endsWith("\n") ? text.split("\n").length - 1 : text.split("\n").length;
+}
+function summarizeMarkdown(text) {
+  const lines = text.split("\n");
+  return {
+    headings: lines.filter((line) => /^#{1,6}\s+\S/.test(line)).length,
+    hasToc: /\btable of contents\b/i.test(text) || /^\s*-\s+\[[^\]]+\]\(#[^)]+\)/m.test(text)
+  };
+}
+function summarizeJsonl(text) {
+  const keys = {};
+  let rows = 0;
+  let invalidRows = 0;
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    rows += 1;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        for (const key of Object.keys(parsed)) keys[key] = (keys[key] ?? 0) + 1;
+      }
+    } catch {
+      invalidRows += 1;
+    }
+  }
+  return { rows, invalidRows, keys: Object.fromEntries(Object.entries(keys).sort(([a], [b]) => a.localeCompare(b))) };
+}
+async function summarizeFile(path, kind) {
+  const s = await pathStat2(path);
+  if (!s?.isFile()) return null;
+  const base = { kind, path, bytes: Number(s.size), mtimeMs: Number(s.mtimeMs) };
+  if (!path.endsWith(".md") && !path.endsWith(".jsonl")) return base;
+  try {
+    const text = await readFile14(path, "utf8");
+    const lines = countLines(text);
+    const jsonl = path.endsWith(".jsonl") ? summarizeJsonl(text) : void 0;
+    return {
+      ...base,
+      lines,
+      ...path.endsWith(".md") ? { markdown: summarizeMarkdown(text) } : {},
+      ...jsonl ? { jsonlRows: jsonl.rows, jsonl } : {}
+    };
+  } catch {
+    return base;
+  }
+}
+async function walkMarkdown(root, kind, maxFiles = 100) {
+  const out = [];
+  async function walk(dir) {
+    if (out.length >= maxFiles) return;
+    let entries;
+    try {
+      entries = await readdir11(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (out.length >= maxFiles) return;
+      const path = join16(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(path);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const summary = await summarizeFile(path, kind);
+        if (summary) out.push(summary);
+      }
+    }
+  }
+  await walk(root);
+  return out;
+}
+async function collectContextRoot(root) {
+  const files = [];
+  for (const name of ["AGENTS.md", "CLAUDE.md", "GEMINI.md"]) {
+    const summary = await summarizeFile(join16(root, name), "instruction-doc");
+    if (summary) files.push(summary);
+  }
+  const evolve = join16(root, ".evolve");
+  for (const name of ["skill-runs.jsonl", "governor.jsonl", "experiments.jsonl"]) {
+    const summary = await summarizeFile(join16(evolve, name), "evolve-jsonl");
+    if (summary) files.push(summary);
+  }
+  for (const name of ["scorecard.json"]) {
+    const summary = await summarizeFile(join16(evolve, name), "evolve-json");
+    if (summary) files.push(summary);
+  }
+  files.push(...await walkMarkdown(join16(evolve, "reflections"), "reflection"));
+  files.push(...await walkMarkdown(join16(evolve, "handoffs"), "handoff"));
+  return { root, files: files.sort((a, b) => a.path.localeCompare(b.path)) };
+}
+async function collectContextIndex(records) {
+  const rootSet = /* @__PURE__ */ new Set();
+  for (const record of records) {
+    const root = await findContextRoot(record.repo.cwd ?? record.session.cwd);
+    if (root) rootSet.add(root);
+  }
+  const roots = await Promise.all([...rootSet].sort().map(collectContextRoot));
+  const files = roots.flatMap((root) => root.files);
+  return {
+    totals: {
+      roots: roots.length,
+      files: files.length,
+      instructionDocs: files.filter((file) => file.kind === "instruction-doc").length,
+      evolveFiles: files.filter((file) => file.kind.startsWith("evolve-")).length,
+      jsonlRows: files.reduce((sum, file) => sum + (file.jsonlRows ?? 0), 0),
+      invalidJsonlRows: files.reduce((sum, file) => sum + (file.jsonl?.invalidRows ?? 0), 0)
+    },
+    roots
+  };
+}
+async function buildSessionIndexFromRows(rows, opts = {}) {
+  const generatedAt = opts.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const records = await Promise.all(rows.map(
+    (row) => buildPolicyEvidenceRecord(row.ref, row.spans, {
+      generatedAt,
+      minLoopOccurrences: opts.minLoopOccurrences
+    })
+  ));
+  const context = opts.includeContext === false ? void 0 : await collectContextIndex(records);
+  return buildSessionIndex(records, { ...opts, generatedAt, context });
+}
+async function collectSessionIndex(opts = {}) {
+  const rows = [];
+  for await (const session of scanSessions(opts)) {
+    rows.push({ ref: session.ref, spans: session.spans });
+  }
+  return buildSessionIndexFromRows(rows, opts);
+}
+function serializeSessionIndex(index) {
+  return `${JSON.stringify(index, null, 2)}
+`;
+}
+async function writeSessionIndexFile(index, outPath) {
+  const path = outPath ?? join16(await mkdtemp4(join16(tmpdir4(), "traces-index-")), "session-index.json");
+  await writeFile4(path, serializeSessionIndex(index), "utf8");
+  return path;
+}
+
 // src/upload-state.ts
 import { createHash as createHash2 } from "crypto";
-import { mkdir, readFile as readFile13, writeFile as writeFile3 } from "fs/promises";
+import { mkdir, readFile as readFile15, writeFile as writeFile5 } from "fs/promises";
 import { homedir as homedir11 } from "os";
-import { dirname, join as join14 } from "path";
+import { dirname as dirname3, join as join17 } from "path";
 function stateFile() {
-  const base = process.env.XDG_STATE_HOME ?? join14(homedir11(), ".local", "state");
-  return join14(base, "tangle-traces", "uploaded.json");
+  const base = process.env.XDG_STATE_HOME ?? join17(homedir11(), ".local", "state");
+  return join17(base, "tangle-traces", "uploaded.json");
 }
 function uploadKey(harness, sessionId) {
   return `${harness}:${sessionId}`;
@@ -3064,15 +3784,15 @@ function sessionHash(spans) {
 }
 async function loadState() {
   try {
-    return JSON.parse(await readFile13(stateFile(), "utf8"));
+    return JSON.parse(await readFile15(stateFile(), "utf8"));
   } catch {
     return {};
   }
 }
 async function saveState(state) {
   const f = stateFile();
-  await mkdir(dirname(f), { recursive: true });
-  await writeFile3(f, `${JSON.stringify(state, null, 2)}
+  await mkdir(dirname3(f), { recursive: true });
+  await writeFile5(f, `${JSON.stringify(state, null, 2)}
 `, "utf8");
 }
 function alreadyUploaded(state, harness, sessionId, hash) {
@@ -3080,10 +3800,10 @@ function alreadyUploaded(state, harness, sessionId, hash) {
 }
 
 // src/upload.ts
-import { readFile as readFile14 } from "fs/promises";
+import { readFile as readFile16 } from "fs/promises";
 import { createRequire } from "module";
 import { hostname } from "os";
-import { basename as basename8, join as join15 } from "path";
+import { basename as basename9, join as join18 } from "path";
 import { hostedClientFromEnv } from "@tangle-network/agent-eval/hosted";
 import { REDACTION_VERSION } from "@tangle-network/agent-eval/traces";
 var require2 = createRequire(import.meta.url);
@@ -3107,7 +3827,7 @@ async function planUpload(opts = {}) {
 async function gitBranch(cwd) {
   if (!cwd) return void 0;
   try {
-    const head = await readFile14(join15(cwd, ".git", "HEAD"), "utf8");
+    const head = await readFile16(join18(cwd, ".git", "HEAD"), "utf8");
     const m = head.match(/^ref:\s*refs\/heads\/(.+)$/m);
     return m?.[1]?.trim();
   } catch {
@@ -3117,7 +3837,7 @@ async function gitBranch(cwd) {
 async function sessionMeta(item, uploadedAt) {
   const meta = {
     [ATTR.HARNESS]: item.ref.harness,
-    [ATTR.SESSION_FILE]: basename8(item.ref.path),
+    [ATTR.SESSION_FILE]: basename9(item.ref.path),
     [ATTR.HOST]: hostname(),
     [ATTR.UPLOADED_AT]: uploadedAt,
     [ATTR.UPLOADER]: `tangle-traces@${TRACES_VERSION}`,
@@ -3255,6 +3975,7 @@ export {
   selectAdapters,
   normalizeRemote,
   resolveRepoAttrs,
+  resolveSessionRepoAttrs,
   stampRepoAttrs,
   parseSession,
   scanSessions,
@@ -3275,9 +3996,19 @@ export {
   exportTraceEvidenceText,
   exportTraceEvidenceFile,
   writeTraceEvidenceExportFile,
+  inspectSessionIndex,
+  renderInspectionReport,
+  serializeInspectionReport,
+  readSessionIndexFile,
+  writeInspectionReportFile,
   watchSessions,
   REACTIONS,
   analyzeReactions,
+  buildSessionIndex,
+  buildSessionIndexFromRows,
+  collectSessionIndex,
+  serializeSessionIndex,
+  writeSessionIndexFile,
   uploadKey,
   sessionHash,
   loadState,