@tangle-network/traces 0.23.1 → 1.0.0

package/dist/cli.js

@@ -1,733 +1,1333 @@
 #!/usr/bin/env node
+import {
+  assembleSessionBundle,
+  collectSessionSelection,
+  verifySessionBundle
+} from "./chunk-DLGAKCQJ.js";
+import {
+  conformanceOfSpans,
+  renderValidation
+} from "./chunk-TW43MR5D.js";
+import {
+  findingRejectionDetail
+} from "./chunk-PYH3PL3N.js";
 import {
   DEFAULT_ANALYST_MODEL,
+  DEFAULT_ASK_CONCURRENCY,
   DEFAULT_QUESTION_MAX_COST_USD,
   DEFAULT_QUESTION_TIMEOUT_MS,
-  DEFAULT_SANDBOX_BASE_URL,
-  DEFAULT_SWEEP_THRESHOLD,
-  MAX_TRACE_QUESTION_CHARS,
+  MAX_TRACE_QUESTION_CHARS
+} from "./chunk-O52XK7OB.js";
+import {
+  metadataOnly
+} from "./chunk-V2OCGX57.js";
+import {
+  RefError,
+  resolveRefs,
+  selectSpans,
+  shortestRefs
+} from "./chunk-CL3OQOWX.js";
+import {
+  exportTraceEvidenceFile
+} from "./chunk-6CLC7DKP.js";
+import {
   SkillUsageStore,
-  analysisEngineFromEnv,
-  appendAll,
-  assembleSessionBundle,
-  assertOutsideSourceBundle,
-  assessSpans,
-  buildPolicyEvidenceRecord,
-  buildSessionIndexFromRows,
+  TurnIndex,
   buildSkillUsageReport,
-  cmdReplayVerify,
-  cmdReplayVerifyBatch,
-  cmdVerifyFindings,
-  collectSessionSelection,
-  commandAnalyzer,
-  commandRedactor,
   createSessionFactsReportBuilder,
   defaultSkillUsageStorePath,
-  diffRuns,
-  executeUpload,
-  exportTraceEvidenceFile,
-  externalFailureMessage,
-  fileRunContextSupervisorRunReader,
-  findingRejectionDetail,
-  formatVerdict,
-  haloAnalyzer,
-  hodoscopeAnalyzer,
-  importCodeTraceBench,
-  indexSessionIdsByTrace,
-  inspectSessionIndex,
-  isBridgeMismatchError,
-  iterSerializedSpans,
-  knownHarnesses,
-  loadTraceQuestionsFile,
-  loadTracesConfig,
-  locateSessions,
-  mergeTracesConfig,
-  normalizeTraceQuestions,
-  openAgenticTraceStore,
-  parseIsoToEpochMs,
-  parseSession,
-  parseSince,
-  parseTimeBound,
-  planUpload,
-  primeAnalyzer,
-  projectSessionBundle,
+  matchRows,
+  priceReport,
   readInstalledSkills,
-  readJsonl,
-  readOtlpInput,
-  readSessionIndexFile,
-  redactSpans,
-  renderInspectionReport,
-  renderRunDiff,
+  readSessionTurnGroups,
   renderSessionFacts,
   renderSkillUsage,
-  renderValidation,
+  sessionIdentityLookup,
+  sessionMatches
+} from "./chunk-UVE5ANVV.js";
+import {
+  knownHarnesses,
+  listAdapters,
+  locateSessions,
+  parseSession,
+  readSessionSpans,
+  readsStoreRoots,
   resolveAdapter,
-  resolveRunWatchTarget,
-  runTraceImprovement,
-  runTraceInvestigation,
-  runTraceQuestions,
-  saveReport,
-  scanSessions,
   selectAdapters,
-  serializePolicyEvidence,
-  serializeSessionIndex,
-  serializeTraceStreamEvent,
-  sessionReportSource,
-  streamSessions,
-  toolArgumentsFromAttributes,
-  totalAgenticFailureMessage,
-  traceStreamEventsFromSpans,
+  sessionsInCwd
+} from "./chunk-3T62R7ON.js";
+import {
+  indexSessionIdsByTrace
+} from "./chunk-TR6O4S4T.js";
+import {
+  appendAll,
+  iterSerializedSpans,
+  readOtlpInput,
+  tracesCommit,
   tracesVersion,
-  validationExitCode,
-  verdictExitCode,
-  verifyFindingsInSandbox,
-  verifySafe,
-  verifySessionBundle,
-  watchRunTarget,
-  watchSessions,
-  writeAnalysisTraceFile,
-  writeInspectionReportFile,
-  writeOtlpFile,
-  writePolicyEvidenceFile,
-  writeSessionIndexFile,
-  writeTraceEvidenceExportFile,
-  writeTraceQuestionsArtifacts
-} from "./chunk-7DVZCCZI.js";
+  writeOtlpFile
+} from "./chunk-NZ5Y7UEL.js";
+import "./chunk-RZL5GAWH.js";
+import {
+  parseSince,
+  parseTimeBound,
+  relativeBoundMs
+} from "./chunk-DU534HAX.js";
 
 // src/cli.ts
-import { readFileSync } from "fs";
-import { mkdir as mkdir2, mkdtemp, readFile as readFile2, stat, writeFile as writeFile2 } from "fs/promises";
-import { tmpdir } from "os";
-import { basename, join as join2, resolve } from "path";
-import {
-  parseCorpusFlag,
-  renderVerifiedFindingsSection
-} from "@tangle-network/agent-eval/trajectory-replay";
-import {
-  analyzeSupervisorRun,
-  findSupervisorRunDirs,
-  isRuntimeSupervisorRunDir,
-  renderSupervisorRollupMarkdown,
-  renderSupervisorRunMarkdown,
-  rollupSupervisorRuns
-} from "@tangle-network/agent-eval/supervisor-run";
+import { stat, writeFile } from "fs/promises";
+import { homedir, hostname } from "os";
+import { basename as basename2, dirname as dirname2, resolve as resolve2 } from "path";
 
-// src/mcp.ts
-import { rm } from "fs/promises";
-import { dirname } from "path";
-import { buildTraceAnalysisToolDescriptors, redact, shareAllowed, UNTRUSTED_TRACE_TEXT } from "@tangle-network/agent-eval/traces";
-import { createStdioToolServer } from "@tangle-network/agent-runtime/mcp";
-var MCP_RESULT_BYTE_CAP = 512 * 1024;
-async function traceMcpTools(options) {
-  const { spans } = redactSpans(options.spans);
-  const verdict = assessSpans(spans);
-  if (!shareAllowed(verdict)) {
-    const findings = verdict.findings.map((f) => `${f.category}/${f.detector} (${f.count})`).join(", ");
-    throw new Error(
-      `mcp: refusing to serve \u2014 redacted spans are still ${verdict.status}` + (findings ? `: ${findings}` : "") + (verdict.unreadable.length > 0 ? `; unreadable: ${verdict.unreadable.join("; ")}` : "")
-    );
-  }
-  const file = await writeAnalysisTraceFile(spans);
-  const store = await openAgenticTraceStore(file);
-  const descriptors = buildTraceAnalysisToolDescriptors({ store }).filter((d) => d.name !== "readSpanSource");
-  const tools = descriptors.map((descriptor) => ({
-    name: descriptor.name,
-    description: descriptor.description,
-    inputSchema: descriptor.parameters,
-    annotations: {
-      readOnlyHint: descriptor.readOnly,
-      idempotentHint: descriptor.idempotent,
-      destructiveHint: false,
-      openWorldHint: false
-    },
-    handler: async (args) => {
-      const { value } = redact(await descriptor.handler(args));
-      const result = { untrusted: UNTRUSTED_TRACE_TEXT, result: value };
-      const bytes = Buffer.byteLength(JSON.stringify(result));
-      if (bytes > MCP_RESULT_BYTE_CAP) {
-        throw new RangeError(
-          `${descriptor.name}: result is ${bytes} bytes, above the ${MCP_RESULT_BYTE_CAP}-byte cap; narrow the request`
-        );
-      }
-      return result;
-    }
-  }));
-  return { tools, otlpPath: file.otlpPath };
-}
-async function serveTraceMcp(options) {
-  const { tools, otlpPath } = await traceMcpTools(options);
-  const server = createStdioToolServer({ serverName: "traces", serverVersion: tracesVersion(), tools });
-  try {
-    await server.serve();
-  } finally {
-    await rm(dirname(otlpPath), { recursive: true, force: true });
+// src/analyst-log.ts
+var ANALYST_FAILURE = /\[analyst\] (?:FAIL|WARN) |\bmodel call \d+ FAIL\b/u;
+function analystLog(msg, fields) {
+  const rejection = findingRejectionDetail(msg, fields);
+  if (rejection !== void 0) {
+    process.stderr.write(rejection ? `${msg} \u2014 ${rejection}
+` : `${msg}
+`);
+    return;
   }
+  if (!ANALYST_FAILURE.test(msg)) return;
+  const error = typeof fields?.error === "string" && fields.error ? fields.error : void 0;
+  const errorClass = typeof fields?.error_class === "string" && fields.error_class ? `${fields.error_class}: ` : "";
+  process.stderr.write(error ? `${msg} \u2014 ${errorClass}${error}
+` : `${msg}
+`);
 }
 
-// src/cli.ts
-import { explainTraceContract as explainTraceContract2 } from "@tangle-network/agent-eval";
-
-// src/check.ts
-import { mkdir, readFile, writeFile } from "fs/promises";
-import { join } from "path";
-import {
-  compileTraceContractSpec,
-  evaluateTraceContract,
-  explainTraceContract,
-  lintTraceContractSpec
-} from "@tangle-network/agent-eval";
-var CHECK_EXIT = Object.freeze({
-  pass: 0,
-  fail: 1,
-  /** The contract is malformed or contradicts itself, or a rule could not run. */
-  badContract: 2,
-  unreadable: 3,
-  ambiguous: 4
-});
-var AmbiguousTraceInputError = class extends Error {
-  name = "AmbiguousTraceInputError";
-};
-var ContractFileError = class extends Error {
-  name = "ContractFileError";
-};
-async function loadContract(path) {
-  let text;
-  try {
-    text = await readFile(path, "utf8");
-  } catch (error) {
-    throw new ContractFileError(`cannot read contract ${path}: ${errorText(error)}`);
-  }
-  let json;
-  try {
-    json = JSON.parse(text);
-  } catch (error) {
-    throw new ContractFileError(`contract ${path} is not JSON: ${errorText(error)}`);
+// src/moved.ts
+var LAST_0X_RELEASE = "@tangle-network/traces@0.23.1";
+var FREE_TEXT_FLAGS = /* @__PURE__ */ new Set(["--question"]);
+function flagIndexes(argv, flag) {
+  const at = [];
+  for (let i = 1; i < argv.length; i++) {
+    if (FREE_TEXT_FLAGS.has(argv[i])) {
+      i++;
+      continue;
+    }
+    if (argv[i] === flag) at.push(i);
+  }
+  return at;
+}
+function dropFlag(argv, flag, takesValue) {
+  const drop = /* @__PURE__ */ new Set();
+  for (const i of flagIndexes(argv, flag)) {
+    drop.add(i);
+    if (takesValue) drop.add(i + 1);
+  }
+  return argv.filter((_, i) => !drop.has(i));
+}
+function renameFlag(argv, from, to) {
+  if (flagIndexes(argv, to).length > 0) return void 0;
+  const at = new Set(flagIndexes(argv, from));
+  return argv.map((word, i) => at.has(i) ? to : word);
+}
+function flagToPositional(argv, flag) {
+  const values = flagIndexes(argv, flag).flatMap((i) => argv[i + 1] === void 0 ? [] : [argv[i + 1]]);
+  const rest = dropFlag(argv, flag, true);
+  let at = 1;
+  while (at < rest.length && !rest[at].startsWith("-")) at++;
+  return [...rest.slice(0, at), ...values, ...rest.slice(at)];
+}
+function commandOf(argv) {
+  return argv[0] === "help" ? argv[1] : argv[0];
+}
+function renameCommand(argv, to) {
+  return argv[0] === "help" ? ["help", to, ...argv.slice(2)] : [to, ...argv.slice(1)];
+}
+var INPUT_FORMATS = ["auto", "otlp", "sandbox-events", "openinference", "claude-code", "codex"];
+var HARNESS_FORMATS = /* @__PURE__ */ new Set(["claude-code", "codex"]);
+function withoutInputFormat(argv) {
+  let harness;
+  const drop = /* @__PURE__ */ new Set();
+  for (const i of flagIndexes(argv, "--format")) {
+    const kind = argv[i + 1];
+    if (kind === void 0 || !INPUT_FORMATS.includes(kind)) continue;
+    drop.add(i);
+    drop.add(i + 1);
+    if (HARNESS_FORMATS.has(kind)) harness = kind;
+  }
+  const out = argv.filter((_, i) => !drop.has(i));
+  if (harness !== void 0 && flagIndexes(out, "--harness").length === 0) out.push("--harness", harness);
+  return out;
+}
+var OTLP_OUT_COMMANDS = /* @__PURE__ */ new Set(["convert", "export", "upload"]);
+var MOVED = [
+  {
+    was: ["import-codetracebench", "replay-verify", "replay-verify-batch", "verify-findings"],
+    now: `removed. The last version with them: npx --yes ${LAST_0X_RELEASE} <command>`,
+    pinned: true
+  },
+  {
+    was: ["--analyzer", "--analyzer-prompt", "--verify-findings", "--replay-corpus", "--verify-out", "--trajectory-dir", "--revision"],
+    now: "removed",
+    pinned: true
+  },
+  {
+    was: ["--redactor"],
+    now: "traces convert X --out f, your scrubber on f, then traces upload f"
+  },
+  {
+    was: ["--format chat-trajectory"],
+    now: "removed (traces@0.23.1)",
+    pinned: true
+  },
+  { was: ["index"], now: "traces list --format json" },
+  { was: ["inspect"], now: "traces analyze <ref>" },
+  { was: ["evidence"], now: "traces facts --format json" },
+  { was: ["bundle-view"], now: "traces facts <bundle-dir> --no-content" },
+  {
+    was: ["--source-bundle"],
+    now: "a positional ref: traces analyze <bundle-dir>",
+    rewrite: (argv) => flagToPositional(argv, "--source-bundle")
+  },
+  { was: ["--view"], now: "removed (bundle-view is traces facts <bundle-dir> --no-content)" },
+  {
+    was: ["--format policy-evidence", "--format intelligence-spans"],
+    now: "removed (traces@0.23.1)",
+    pinned: true
+  },
+  {
+    was: ["--session", "--otlp", "--supervisor-run-dir"],
+    now: "a positional ref: traces analyze X",
+    rewrite: (argv) => ["--session", "--otlp", "--supervisor-run-dir"].reduce(flagToPositional, [...argv])
+  },
+  {
+    was: ["--all"],
+    now: "the default: every harness is read, and --harness ID narrows",
+    rewrite: (argv) => dropFlag(argv, "--all", false)
+  },
+  {
+    was: ["--workflow", "--max-workflow-sessions"],
+    now: "the default: a named session brings its spawned children, up to 100",
+    rewrite: (argv) => dropFlag(dropFlag(argv, "--workflow", false), "--max-workflow-sessions", true)
+  },
+  {
+    was: INPUT_FORMATS.map((kind) => `--format ${kind}`),
+    now: "removed: the input is sniffed, and --harness ID forces a reader for a file ref",
+    rewrite: withoutInputFormat
+  },
+  { was: [], label: "--harness default claude-code", now: "every harness by default; --harness ID narrows" },
+  { was: ["investigate"], now: "traces analyze \u2026", rewrite: (argv) => renameCommand(argv, "analyze") },
+  { was: ["export"], now: "traces convert <file> (--out FILE, or stdout)", rewrite: (argv) => renameCommand(argv, "convert") },
+  {
+    was: ["--otlp-out"],
+    now: "--out F on convert and upload --dry-run; analyze and ask keep no span copy, so write one with traces convert <ref> --out F",
+    rewrite: (argv) => {
+      const command = commandOf(argv);
+      return command !== void 0 && OTLP_OUT_COMMANDS.has(command) ? renameFlag(argv, "--otlp-out", "--out") : void 0;
+    }
+  },
+  { was: ["--metadata", "--attr"], now: "removed", pinned: true },
+  {
+    was: ["--min-loop"],
+    now: "removed: a loop is 3 identical calls",
+    rewrite: (argv) => dropFlag(argv, "--min-loop", true)
+  },
+  { was: [], label: "upload with no selection", now: "traces upload --since 24h (upload needs a ref, --current or --since)" },
+  {
+    was: ["--evidence"],
+    now: "check \u2026 --out DIR: evidence for each trace that did not pass; without --out, check writes nothing",
+    rewrite: (argv) => renameFlag(argv, "--evidence", "--out")
+  },
+  { was: [], label: "facts JSON by default", now: "text by default, 25 lines a session; pass --format json to parse the sheet" },
+  {
+    was: ["--no-refresh", "--store", "--sweep"],
+    now: "removed: skills always reads what sessions appended since its last run, keeps its store under $XDG_STATE_HOME/traces, and counts a command that reads 3 or more skills as a catalog sweep",
+    rewrite: (argv) => dropFlag(dropFlag(dropFlag(argv, "--no-refresh", false), "--store", true), "--sweep", true)
+  },
+  {
+    was: ["improve"],
+    now: "traces analyze \u2026 --out DIR (report.md and findings.json; no span copy)",
+    rewrite: (argv) => {
+      const renamed = renameCommand(argv, "analyze");
+      return renameFlag(renamed, "--dir", "--out") ?? renamed;
+    }
+  },
+  {
+    was: ["--llm", "--model", "--budget"],
+    commands: ["analyze", "investigate", "improve"],
+    label: "analyze --llm, --model, --budget",
+    now: 'analyze calls no model: traces ask <ref> --question "\u2026" --budget USD [--model ID]'
+  },
+  {
+    was: ["--config"],
+    now: "removed: run your own analysts through the SDK, analyzeSpans(spans, { registry })"
+  },
+  {
+    was: ["stream"],
+    now: "traces watch --format jsonl: the same traces.stream envelope, as session, finding and tick events",
+    rewrite: (argv) => {
+      const renamed = renameCommand(argv, "watch");
+      return renamed[0] === "help" || flagIndexes(renamed, "--format").length > 0 ? renamed : [...renamed, "--format", "jsonl"];
+    }
+  },
+  {
+    was: ["--mode", "--no-spans", "--no-findings"],
+    commands: ["stream", "watch"],
+    now: "removed: traces watch --format jsonl prints session, finding and tick events, with no span or batch events",
+    rewrite: (argv) => dropFlag(dropFlag(dropFlag(argv, "--mode", true), "--no-spans", false), "--no-findings", false)
+  },
+  {
+    was: ["--replay"],
+    commands: ["stream", "watch"],
+    now: "--once: one pass, then exit",
+    rewrite: (argv) => flagIndexes(argv, "--once").length > 0 ? dropFlag(argv, "--replay", false) : renameFlag(argv, "--replay", "--once")
+  },
+  {
+    was: ["--window", "--interval"],
+    commands: ["stream", "watch"],
+    now: "--since Nm (default 30m; the window slides with time). Sessions are read every 5 s, a run tree every 2 s",
+    rewrite: (argv) => windowToSince(dropFlag(argv, "--interval", true))
+  },
+  { was: [], label: "SDK watchSessions", now: "streamSessions({ onEvent }): the session, finding and tick events traces watch prints" },
+  {
+    was: ["validate"],
+    now: "traces check <f> --contract conformance (exit 1 only when the file is not a trace; the report is stdout)",
+    rewrite: (argv) => {
+      if (flagIndexes(argv, "--out").length > 0) return void 0;
+      const renamed = renameCommand(argv, "check");
+      return renamed[0] === "help" ? renamed : [...renamed, "--contract", "conformance"];
+    }
+  },
+  {
+    was: ["verify-safe"],
+    now: "traces check <path> --share-safe (--known-secret-env is unchanged)",
+    rewrite: (argv) => {
+      const renamed = renameCommand(argv, "check");
+      return renamed[0] === "help" ? renamed : [...renamed, "--share-safe"];
+    }
+  },
+  {
+    was: ["--profile"],
+    commands: ["verify-safe", "check"],
+    now: "removed: a share verdict always uses the share profile",
+    rewrite: (argv) => dropFlag(argv, "--profile", true)
+  },
+  { was: ["--junit"], commands: ["check"], now: "check \u2026 --format junit > FILE: the JUnit XML is the verdict on stdout" },
+  {
+    was: ["--annotations"],
+    commands: ["check"],
+    now: "check \u2026 --format github: the annotations are the verdict on stdout",
+    rewrite: (argv) => {
+      if (flagIndexes(argv, "--format").length > 0) return void 0;
+      const at = new Set(flagIndexes(argv, "--annotations"));
+      return argv.flatMap((word, i) => at.has(i) ? ["--format", "github"] : [word]);
+    }
+  },
+  {
+    was: ["--explain"],
+    commands: ["check"],
+    now: "traces check --contract FILE with no ref explains FILE",
+    rewrite: (argv) => {
+      const rest = dropFlag(argv, "--explain", false);
+      let at = 1;
+      while (at < rest.length && !rest[at].startsWith("-")) at++;
+      return [rest[0], ...rest.slice(at)];
+    }
+  },
+  { was: [], label: "check exit 3 (unreadable) and 4 (ambiguous)", now: "exit 2, with code unreadable or ambiguous in the JSON error on stderr" },
+  {
+    was: ["--kind"],
+    commands: ["diff"],
+    label: "diff --kind",
+    now: "removed: diff compares tool calls only, by tool, status and argument; model calls and events are never steps",
+    rewrite: (argv) => dropFlag(argv, "--kind", true)
+  },
+  { was: [], label: "diff exit 2 (unreadable) and 3 (no outcome)", now: "exit 2, with code unreadable or no-outcome in the JSON error on stderr" },
+  {
+    was: ["--dir"],
+    commands: ["ask"],
+    label: "ask --dir",
+    now: "--out DIR: answers.json and report.md",
+    rewrite: (argv) => renameFlag(argv, "--dir", "--out")
+  },
+  {
+    was: ["--question-budget", "--question-timeout", "--concurrency"],
+    commands: ["ask"],
+    label: "ask --question-budget, --question-timeout, --concurrency",
+    now: `removed: each question spends at most min(--budget, $${DEFAULT_QUESTION_MAX_COST_USD}) within ${DEFAULT_QUESTION_TIMEOUT_MS / 1e3} s, ${DEFAULT_ASK_CONCURRENCY} at once`,
+    rewrite: (argv) => dropFlag(dropFlag(dropFlag(argv, "--question-budget", true), "--question-timeout", true), "--concurrency", true)
+  },
+  { was: [], label: "ask without --budget", now: "add --budget USD: the most the run may spend" },
+  {
+    was: [],
+    label: "ask exit 1 when a question failed",
+    now: "exit 2, with code partial; answers.json under --out still holds every answer. A refused key or model: code auth or model"
+  }
+];
+function windowToSince(argv) {
+  const at = flagIndexes(argv, "--window")[0];
+  if (at === void 0) return [...argv];
+  const minutes = argv[at + 1];
+  if (minutes === void 0 || !/^\d+$/u.test(minutes)) return void 0;
+  const rest = dropFlag(argv, "--window", true);
+  return flagIndexes(rest, "--since").length > 0 ? rest : [...rest, "--since", `${minutes}m`];
+}
+function findMoved(argv) {
+  return findAllMoved(argv)[0];
+}
+function findAllMoved(argv) {
+  const found = [];
+  for (const row of MOVED) {
+    const command = commandOf(argv);
+    if (row.commands && (command === void 0 || !row.commands.includes(command))) continue;
+    for (const spelling of row.was) {
+      if (uses(argv, spelling)) found.push({ row, spelling });
+    }
   }
-  try {
-    const findings = lintTraceContractSpec(json);
-    const errors = findings.filter((f) => f.level === "error");
-    if (errors.length > 0) {
-      throw new ContractFileError(
-        `contract ${path} contradicts itself:
-${errors.map((f) => `  ${f.path}: ${f.message} [${f.code}]`).join("\n")}`
-      );
+  return found;
+}
+function uses(argv, spelling) {
+  if (!spelling.startsWith("--")) {
+    return argv[0] === spelling || argv[0] === "help" && argv[1] === spelling;
+  }
+  const [flag, value] = spelling.split(" ");
+  return flagIndexes(argv, flag).some((i) => value === void 0 || argv[i + 1] === value);
+}
+function pinnedCommand(argv) {
+  return ["npx", "--yes", LAST_0X_RELEASE, ...argv].map(shellWord).join(" ");
+}
+function tracesCommand(argv) {
+  return ["traces", ...argv].map(shellWord).join(" ");
+}
+function movedMessage(found, argv) {
+  const all = findAllMoved(argv);
+  const pinned = all.find(({ row }) => row.pinned);
+  if (pinned) return `${pinned.spelling} was removed in traces 1.0. The last version with it runs as: ${pinnedCommand(argv)}`;
+  let rewritten = argv;
+  let mechanical = false;
+  const unwritten = [];
+  for (const moved of all) {
+    const next = moved.row.rewrite?.(rewritten);
+    if (next) {
+      rewritten = next;
+      mechanical = true;
+    } else {
+      unwritten.push(moved);
     }
-    return {
-      contract: compileTraceContractSpec(json),
-      warnings: findings.map((f) => `${f.path}: ${f.message} [${f.code}]`)
-    };
-  } catch (error) {
-    if (error instanceof ContractFileError) throw error;
-    throw new ContractFileError(`contract ${path}: ${errorText(error)}`);
   }
+  const instead = mechanical ? tracesCommand(rewritten) : found.row.now;
+  const also = unwritten.filter(({ spelling }) => mechanical || spelling !== found.spelling).map(({ row, spelling }) => `${spelling}: ${row.now}`);
+  return `${found.spelling} was removed in traces 1.0. Instead: ${instead}${also.length > 0 ? ` (${also.join("; ")})` : ""}`;
 }
-var SNIFF_ROWS = 20;
-async function sniffCheckInput(path) {
-  const rows = [];
-  for await (const row of readJsonl(path)) {
-    rows.push(row);
-    if (rows.length >= SNIFF_ROWS) break;
-  }
-  const objects = rows.filter(isObject);
-  if (objects.length === 0) throw new Error(`${path} holds no JSON rows`);
-  const kinds = [];
-  if (objects.every((r) => typeof r.trace_id === "string" && typeof r.span_id === "string")) kinds.push("otlp");
-  if (objects.some((r) => (typeof r.sessionId === "string" || typeof r.session_id === "string") && typeof r.type === "string") && !objects.some(hasSpanId)) {
-    kinds.push("claude-code");
-  }
-  if (objects.some((r) => CODEX_LINE_TYPES.has(String(r.type)) && isObject(r.payload))) kinds.push("codex");
-  if (objects.every(isEvidenceRow)) kinds.push("evidence");
-  if (kinds.length === 1) return kinds[0];
-  if (kinds.length === 0) {
-    throw new Error(`${path} is not a trace this command reads (OTLP spans, a Claude Code or Codex session, or trace evidence)`);
-  }
-  throw new AmbiguousTraceInputError(
-    `${path} reads as ${kinds.join(" and ")}; pass --format ${kinds.join(" or --format ")}`
-  );
+function renderMovedTable() {
+  const lines = ["Moved in traces 1.0. Each old spelling exits 2 and prints its row.", ""];
+  for (const row of MOVED) {
+    lines.push(`  ${row.label ?? row.was.join(", ")}`);
+    lines.push(`      ${row.now}`);
+  }
+  return `${lines.join("\n")}
+`;
 }
-var CODEX_LINE_TYPES = /* @__PURE__ */ new Set(["session_meta", "response_item", "event_msg", "turn_context"]);
-function hasSpanId(row) {
-  return typeof row.span_id === "string";
-}
-function isEvidenceRow(row) {
-  if (hasSpanId(row)) return false;
-  if (row.kind === "traces.policy_evidence.session") return true;
-  if (Array.isArray(row.messages) || typeof row.role === "string" && "content" in row) return true;
-  return typeof row.trace_id === "string" && typeof row.name === "string" && isObject(row.attributes);
-}
-function contractSpansFromOtlp(spans) {
-  return spans.map((span) => {
-    const startedAt = epochMs(span.start_time);
-    const endedAt = epochMs(span.end_time);
-    const args = toolArgumentsFromAttributes(span.attributes);
-    const truncated = span.attributes["traces.input.truncated"] === true;
-    return {
-      spanId: span.span_id,
-      parentSpanId: span.parent_span_id,
-      name: span.name,
-      ...startedAt === void 0 ? {} : { startedAt },
-      ...endedAt === void 0 ? {} : { endedAt },
-      ...span.status.code === "ERROR" ? { status: "error" } : span.status.code === "OK" ? { status: "ok" } : {},
-      // A truncated argument capture is not the call's arguments.
-      ...args.argsCaptured && !truncated ? { args: args.args } : { argsCaptured: false },
-      attributes: span.attributes
-    };
-  });
+function shellWord(word) {
+  return /^[\w@%+=:,./-]+$/u.test(word) ? word : `'${word.replace(/'/gu, `'\\''`)}'`;
 }
-function epochMs(value) {
-  try {
-    return parseIsoToEpochMs(value);
-  } catch {
-    return void 0;
+
+// src/record-lines.ts
+import { createReadStream } from "fs";
+import { readdir } from "fs/promises";
+import { basename, dirname, join } from "path";
+import { createInterface } from "readline";
+var CALL_ID = /"(?:call_id|tool_use_id)":"([^"]+)"|"id":"(toolu_[^"]+)"|"gen_ai\.tool\.call\.id":\s*"([^"]+)"|"key":\s*"gen_ai\.tool\.call\.id",\s*"value":\s*\{\s*"stringValue":\s*"([^"]+)"/gu;
+var OUTPUT_RECORD = /"type":"(?:[a-z_]+_output|tool_result)"/u;
+var TIMESTAMP = /"timestamp":"([^"]+)"/u;
+var USER_ROLE = /"role":"user"/u;
+var flat = (text) => text.replace(/\s+/gu, " ").trim();
+var citedText = (text) => flat(text.replace(/… \[\+\d+ chars\]$/u, ""));
+function strings(value, into = []) {
+  if (typeof value === "string") into.push(value);
+  else if (Array.isArray(value)) for (const item of value) strings(item, into);
+  else if (value && typeof value === "object") for (const item of Object.values(value)) strings(item, into);
+  return into;
+}
+function resultText(record, id) {
+  if (!record || typeof record !== "object") return null;
+  const payload = record.payload;
+  if (payload && typeof payload.output === "string") return payload.output;
+  const content = record.message?.content;
+  if (!Array.isArray(content)) return null;
+  const block = content.find((item) => item && typeof item === "object" && item.tool_use_id === id);
+  if (block === void 0) return null;
+  return typeof block.content === "string" ? block.content : strings(block.content).join("\n");
+}
+async function sessionRecordFiles(path) {
+  const files = [path];
+  if (!path.endsWith(".jsonl")) return files;
+  const subagents = join(dirname(path), basename(path, ".jsonl"), "subagents");
+  const names = await readdir(subagents).catch(() => []);
+  for (const name of names.filter((entry) => entry.endsWith(".jsonl")).sort()) files.push(join(subagents, name));
+  return files;
+}
+async function readRecordLines(files, query) {
+  const calls = /* @__PURE__ */ new Map();
+  const outputs = /* @__PURE__ */ new Map();
+  const texts = /* @__PURE__ */ new Map();
+  const wantedTurns = /* @__PURE__ */ new Map();
+  for (const turn of query.turns ?? []) {
+    const ms = Date.parse(turn.at);
+    if (Number.isFinite(ms)) wantedTurns.set(ms, [...wantedTurns.get(ms) ?? [], { key: flat(turn.text), text: citedText(turn.text) }]);
+  }
+  const turns = /* @__PURE__ */ new Map();
+  const scan = query.callIds.size > 0 || wantedTurns.size > 0 ? files : [];
+  for (const file of scan) {
+    let line = 0;
+    try {
+      const lines = createInterface({ input: createReadStream(file, { encoding: "utf8" }), crlfDelay: Infinity });
+      for await (const raw of lines) {
+        line += 1;
+        const here = { file, line };
+        let parsed;
+        const parse = () => {
+          if (parsed === void 0) {
+            try {
+              parsed = JSON.parse(raw);
+            } catch {
+              parsed = null;
+            }
+          }
+          return parsed;
+        };
+        const isOutput = query.callIds.size > 0 && OUTPUT_RECORD.test(raw);
+        for (const match of query.callIds.size > 0 ? raw.matchAll(CALL_ID) : []) {
+          const id = match[1] ?? match[2] ?? match[3] ?? match[4];
+          if (!query.callIds.has(id)) continue;
+          if (!isOutput) {
+            if (!calls.has(id)) calls.set(id, here);
+          } else if (!outputs.has(id)) {
+            outputs.set(id, here);
+            if (query.outputTextFor?.has(id)) {
+              const text = resultText(parse(), id);
+              if (text !== null) texts.set(id, text);
+            }
+          }
+        }
+        if (wantedTurns.size === 0 || !USER_ROLE.test(raw)) continue;
+        const stamp = TIMESTAMP.exec(raw)?.[1];
+        const wanted = stamp === void 0 ? void 0 : wantedTurns.get(Date.parse(stamp));
+        if (wanted === void 0) continue;
+        const record = parse();
+        if (record === null) continue;
+        const said = strings(record).map(flat);
+        const item = record.type === "response_item";
+        for (const { key: body, text } of wanted) {
+          const key = `${Date.parse(stamp)}\0${body}`;
+          const prior = turns.get(key);
+          if ((prior === void 0 || item && !prior.item) && said.some((value) => value.includes(text))) turns.set(key, { at: here, item });
+        }
+      }
+    } catch {
+    }
   }
+  return {
+    call: (id) => calls.get(id) ?? null,
+    output: (id) => outputs.get(id) ?? null,
+    outputText: (id) => texts.get(id) ?? null,
+    turn: (at, text) => turns.get(`${Date.parse(at)}\0${flat(text)}`)?.at ?? null
+  };
 }
-function groupByTrace(spans) {
-  const groups = /* @__PURE__ */ new Map();
+function callIdsOf(spans) {
+  const ids = /* @__PURE__ */ new Map();
   for (const span of spans) {
-    const list = groups.get(span.trace_id) ?? [];
-    list.push(span);
-    groups.set(span.trace_id, list);
-  }
-  return [...groups].map(([traceId, list]) => ({ traceId, spans: list }));
-}
-async function runCheck(contract, spans, opts) {
-  const traces = [];
-  for (const group of groupByTrace(spans)) {
-    const verdict = evaluateTraceContract(contract, contractSpansFromOtlp(group.spans));
-    const check = { traceId: group.traceId, spanCount: group.spans.length, verdict };
-    if (verdict.status !== "pass") {
-      check.evidenceDir = await writeEvidence(opts.evidenceRoot, contract, group.traceId, group.spans, verdict);
+    const shared = span.attributes["gen_ai.tool.call.id"];
+    const native = span.attributes["traces.codex.source_span_id"];
+    const id = typeof shared === "string" && shared !== "" ? shared : typeof native === "string" && native.startsWith("tool:") ? native.slice("tool:".length) : void 0;
+    if (id !== void 0 && id !== "") ids.set(span.span_id, id);
+  }
+  return ids;
+}
+function lastLine(text) {
+  const lines = text.split("\n").map((line) => line.trimEnd()).filter((line) => line.trim() !== "");
+  return lines.at(-1) ?? null;
+}
+async function citeFacts(sessions, matches, citings) {
+  const citedSessions = [];
+  const citedMatches = /* @__PURE__ */ new Map();
+  for (const facts of sessions) {
+    const key = facts.sessionId ?? facts.traceId;
+    const citing = citings.get(key);
+    if (citing === void 0) {
+      citedSessions.push(facts);
+      continue;
     }
-    traces.push(check);
-  }
-  const status = traces.some((t) => t.verdict.status === "error") ? "error" : traces.every((t) => t.verdict.status === "pass") ? "pass" : "fail";
-  const exitCode = status === "pass" ? CHECK_EXIT.pass : status === "fail" ? CHECK_EXIT.fail : CHECK_EXIT.badContract;
-  return { contract: contract.name, status, exitCode, traces };
-}
-async function writeEvidence(root, contract, traceId, spans, verdict) {
-  const dir = join(root, `${safeName(contract.name)}-${safeName(traceId).slice(0, 40)}`);
-  await mkdir(dir, { recursive: true });
-  const cited = new Set(verdict.violations.map((v) => v.spanId).filter((id) => id !== void 0));
-  const redacted = redactSpans(spans.filter((s) => cited.has(s.span_id)));
-  await writeFile(join(dir, "verdict.json"), `${JSON.stringify({ traceId, verdict }, null, 2)}
-`);
-  await writeFile(join(dir, "contract.json"), `${JSON.stringify(contract, null, 2)}
-`);
-  await writeFile(join(dir, "explain.txt"), `${explainTraceContract(contract)}
-`);
-  await writeFile(join(dir, "cited-spans.jsonl"), redacted.spans.map((s) => JSON.stringify(s)).join("\n") + (redacted.spans.length ? "\n" : ""));
-  return dir;
-}
-function safeName(value) {
-  return value.replace(/[^A-Za-z0-9._-]+/g, "_");
-}
-function ruleLines(verdict) {
-  const branchPassed = /* @__PURE__ */ new Map();
-  for (const e of verdict.ruleExecutions) {
-    if (e.alternative === void 0) continue;
-    branchPassed.set(e.alternative, (branchPassed.get(e.alternative) ?? true) && e.status === "pass");
-  }
-  const anyBranchPassed = [...branchPassed.values()].some(Boolean);
-  return verdict.ruleExecutions.map((e) => {
-    const rule = e.alternative ? `${e.alternative}/${e.rule}` : e.rule;
-    const status = e.alternative && anyBranchPassed && !branchPassed.get(e.alternative) ? "skipped" : e.status;
-    return {
-      rule,
-      status,
-      ...e.error === void 0 ? {} : { error: e.error },
-      details: verdict.violations.filter((x) => x.rule === rule).map((x) => x.detail)
+    const own = matches.filter((match) => match.kind === "command" && match.sessionId === facts.sessionId);
+    const wanted = (spanIds) => [...spanIds].flatMap((spanId) => {
+      const id = spanId === void 0 ? void 0 : citing.callIds.get(spanId);
+      return id === void 0 ? [] : [id];
+    });
+    const failure = { spanId: "spanId" in facts.firstFailure && typeof facts.firstFailure.spanId === "string" ? facts.firstFailure.spanId : void 0 };
+    const commands = facts.commands.value ?? [];
+    const files = facts.changedFiles.value ?? [];
+    const outputTextFor = new Set(wanted(own.map((match) => match.spanId)));
+    const firstCall = (file) => file.spanIds.find((spanId) => citing.callIds.has(spanId));
+    const lines = await readRecordLines(await sessionRecordFiles(citing.path), {
+      callIds: /* @__PURE__ */ new Set([
+        ...wanted([failure.spanId]),
+        ...wanted(commands.flatMap((row) => [row.lastSpanId, ...row.nonZeroExits.map((exit) => exit.spanId)])),
+        ...wanted(files.map(firstCall)),
+        ...outputTextFor
+      ]),
+      outputTextFor,
+      turns: facts.humanTurns.value ?? []
+    });
+    const result = (spanId) => {
+      const id = spanId === void 0 ? void 0 : citing.callIds.get(spanId);
+      return id === void 0 ? null : lines.output(id) ?? lines.call(id);
     };
-  });
-}
-function renderCheckText(report) {
-  const lines = [];
-  for (const t of report.traces) {
-    const v = t.verdict;
-    lines.push(`${v.status.toUpperCase()}  contract ${report.contract}  trace ${t.traceId}  (${t.spanCount} spans, ${v.notes})`);
-    for (const r of ruleLines(v)) {
-      lines.push(`  ${r.status.padEnd(7)} ${r.rule}${r.error ? `  ${r.error}` : ""}`);
-      if (r.status === "fail") for (const detail of r.details.slice(0, 5)) lines.push(`          ${detail}`);
+    const call = (spanId) => {
+      const id = spanId === void 0 ? void 0 : citing.callIds.get(spanId);
+      return id === void 0 ? null : lines.call(id);
+    };
+    const short = (record) => record === null ? null : record.file === citing.path ? { line: record.line } : record;
+    for (const match of own) {
+      const id = citing.callIds.get(match.spanId);
+      const text = id === void 0 || match.failed == null ? null : lines.outputText(id);
+      citedMatches.set(match, { ...match, record: result(match.spanId), lastLine: text === null ? null : lastLine(text) });
     }
-    if (t.evidenceDir) lines.push(`  evidence \u2192 ${t.evidenceDir}`);
-  }
-  return lines.join("\n");
-}
-function renderJUnit(report) {
-  const suites = report.traces.map((t) => {
-    const rules = ruleLines(t.verdict);
-    const count = (status) => rules.filter((r) => r.status === status).length;
-    const cases = rules.map((r) => {
-      const open = `    <testcase classname="${xml(report.contract)}" name="${xml(r.rule)}">`;
-      if (r.status === "pass") return `${open}</testcase>`;
-      if (r.status === "skipped") return `${open}
-      <skipped message="another alternative passed"/>
-    </testcase>`;
-      if (r.status === "error") {
-        return `${open}
-      <error message="${xml(r.error ?? "rule could not be evaluated")}"/>
-    </testcase>`;
-      }
-      return `${open}
-      <failure message="${xml(r.details[0] ?? "rule failed")}">${xml(r.details.join("\n"))}</failure>
-    </testcase>`;
+    citedSessions.push({
+      ...facts,
+      recordFile: citing.path,
+      humanTurns: facts.humanTurns.value === null ? facts.humanTurns : { ...facts.humanTurns, value: facts.humanTurns.value.map((turn) => ({ ...turn, record: short(lines.turn(turn.at, turn.text)) })) },
+      changedFiles: facts.changedFiles.value === null ? facts.changedFiles : { ...facts.changedFiles, value: files.map((file) => ({ ...file, record: short(call(firstCall(file))) })) },
+      commands: facts.commands.value === null ? facts.commands : {
+        ...facts.commands,
+        // `lastSpanId` only finds the latest run's record; the row carries the record instead.
+        value: commands.map(({ lastSpanId, ...row }) => ({
+          ...row,
+          record: short(result(lastSpanId)),
+          nonZeroExits: row.nonZeroExits.map((exit) => ({ ...exit, record: short(result(exit.spanId)) }))
+        }))
+      },
+      firstFailure: failure.spanId === void 0 ? facts.firstFailure : { ...facts.firstFailure, record: short(result(failure.spanId)) }
     });
-    return [
-      `  <testsuite name="${xml(`${report.contract} @ ${t.traceId}`)}" tests="${rules.length}" failures="${count("fail")}" errors="${count("error")}" skipped="${count("skipped")}">`,
-      ...cases,
-      "  </testsuite>"
-    ].join("\n");
-  });
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<testsuites name="traces check">
-${suites.join("\n")}
-</testsuites>
-`;
+  }
+  return { sessions: citedSessions, matches: matches.map((match) => citedMatches.get(match) ?? match) };
 }
-function renderGithubAnnotations(report) {
-  const lines = [];
-  for (const t of report.traces) {
-    for (const r of ruleLines(t.verdict)) {
-      if (r.status === "pass" || r.status === "skipped") continue;
-      const detail = r.status === "error" ? `could not be evaluated: ${r.error ?? "unknown"}` : r.details.join("\n");
-      lines.push(`::error title=${ghProperty(`${report.contract}: ${r.rule}`)}::${ghData(`trace ${t.traceId}: ${detail}`)}`);
+
+// src/facts-jsonl.ts
+async function turnFactsJsonl(sources, host, window) {
+  const rows = [];
+  let sessions = 0;
+  const unread = [];
+  for await (const { spans, source } of sources) {
+    for (const group of readSessionTurnGroups(spans, window)) {
+      if (group.records === 0) {
+        unread.push({ sessionId: group.sessionId, traceId: null, source, reason: "no record could be read" });
+        continue;
+      }
+      sessions += 1;
+      const lines = source === null ? null : await readRecordLines([source], { callIds: /* @__PURE__ */ new Set(), turns: group.turns });
+      for (const turn of group.turns) {
+        const record = lines?.turn(turn.at, turn.text) ?? null;
+        rows.push(JSON.stringify({
+          host,
+          harness: group.harness,
+          session: group.sessionId,
+          cwd: group.cwd,
+          at: turn.at,
+          author: turn.author,
+          text: turn.text,
+          answered: turn.answered,
+          reply: turn.reply,
+          interrupted: turn.interrupted,
+          signals: turn.signals,
+          spanId: turn.spanId,
+          recordFile: source,
+          record: record === null ? null : { file: record.file, line: record.line }
+        }));
+      }
     }
   }
-  return lines.join("\n");
-}
-function xml(value) {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, "");
-}
-function ghData(value) {
-  return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
-}
-function ghProperty(value) {
-  return ghData(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
-}
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function errorText(error) {
-  return error instanceof Error ? error.message : String(error);
+  return { text: rows.length === 0 ? "" : `${rows.join("\n")}
+`, sessions, turns: rows.length, unread };
 }
 
-// src/cli.ts
-function parseArgs(argv) {
-  const a = {
-    command: argv[0] === "--help" || argv[0] === "-h" ? "help" : argv[0] ?? "help",
-    help: argv[0] === "--help" || argv[0] === "-h",
+// src/commands.ts
+import { resolve } from "path";
+var CliError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+  }
+};
+var UsageError = class extends CliError {
+  constructor(message) {
+    super(message, "usage");
+    this.name = "UsageError";
+  }
+};
+function emptyArgs(command) {
+  return {
+    command,
+    refs: [],
     harness: "claude-code",
     harnessExplicit: false,
-    all: false,
     last: 0,
     current: false,
     latestTurn: false,
-    workflow: false,
-    maxWorkflowSessions: 100,
-    llm: false,
-    interval: 5,
-    intervalExplicit: false,
-    window: 30,
-    minLoop: 3,
-    dryRun: false,
-    yes: false,
     noContent: false,
-    analyzers: [],
-    replay: false,
-    once: false,
-    noSpans: false,
-    noFindings: false,
-    attrs: [],
-    concurrency: 4,
-    verifyFindings: false,
-    replayCorpora: [],
     questions: [],
-    annotations: false,
-    explain: false
+    contracts: [],
+    shareSafe: false,
+    once: false,
+    dryRun: false,
+    yes: false,
+    unused: false,
+    knownSecretEnvs: []
   };
-  for (let i = 1; i < argv.length; i++) {
-    const arg = argv[i];
-    const next = () => argv[++i];
-    switch (arg) {
-      case "--harness":
-        a.harness = next() ?? a.harness;
-        a.harnessExplicit = true;
-        break;
-      case "--all":
-        a.all = true;
-        break;
-      case "--last":
-        a.last = Number(next());
-        break;
-      case "--current":
-        a.current = true;
-        break;
-      case "--latest-turn":
-        a.latestTurn = true;
-        break;
-      case "--workflow":
-        a.workflow = true;
-        break;
-      case "--max-workflow-sessions":
-        a.maxWorkflowSessions = Number(next());
-        break;
-      case "--session":
-        a.session = next();
-        break;
-      case "--cwd":
-        a.cwd = next();
-        break;
-      case "--supervisor-run-dir":
-        a.supervisorRunDir = next();
-        break;
-      case "--trajectory-dir":
-        a.trajectoryDir = next();
-        break;
-      case "--revision":
-        a.revision = next();
-        break;
-      case "--concurrency":
-        a.concurrency = Number(next());
-        break;
-      case "--since":
-        a.since = next();
-        break;
-      case "--until":
-        a.until = next();
-        break;
-      case "--out":
-        a.out = next();
-        break;
-      case "--dir":
-        a.dir = next();
-        break;
-      case "--otlp":
-        a.otlp = next();
-        break;
-      case "--source-bundle":
-        a.sourceBundle = next();
-        break;
-      case "--otlp-out":
-        a.otlpOut = next();
-        break;
-      case "--llm":
-        a.llm = true;
-        break;
-      case "--budget":
-        a.budget = Number(next());
-        break;
-      case "--model":
-        a.model = next();
-        break;
-      case "--config":
-        a.config = next();
-        break;
-      case "--mode":
-        a.mode = next();
-        break;
-      case "--view":
-        a.view = next();
-        break;
-      case "--metadata":
-        a.metadata = next();
-        break;
-      case "--attr": {
-        const v = next();
-        if (v) a.attrs.push(v);
-        break;
-      }
-      case "--interval":
-        a.interval = Number(next());
-        a.intervalExplicit = true;
-        break;
-      case "--window":
-        a.window = Number(next());
-        break;
-      case "--min-loop":
-        a.minLoop = Number(next());
-        break;
-      case "--dry-run":
-        a.dryRun = true;
-        break;
-      case "--no-content":
-        a.noContent = true;
-        break;
-      case "--replay":
-        a.replay = true;
-        break;
-      // `stream --once` has always meant "one pass"; `watch --once` means the
-      // same thing over a run directory, so one flag drives both.
-      case "--once":
-        a.once = true;
-        a.replay = true;
-        break;
-      case "--no-spans":
-        a.noSpans = true;
-        break;
-      case "--no-findings":
-        a.noFindings = true;
-        break;
-      case "--analyzer": {
-        const v = next();
-        if (v) a.analyzers.push(v);
-        break;
-      }
-      case "--verify-findings":
-        a.verifyFindings = true;
-        break;
-      case "--replay-corpus": {
-        const v = next();
-        if (v) a.replayCorpora.push(v);
-        break;
-      }
-      case "--verify-out":
-        a.verifyOut = next();
-        break;
-      case "--analyzer-prompt":
-        a.analyzerPrompt = next();
-        break;
-      case "--question": {
-        const v = next();
-        if (v !== void 0) a.questions.push(v);
-        break;
+}
+function positiveInteger(flag, raw) {
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < 1) throw new UsageError(`${flag} must be a positive whole number, got "${raw}"`);
+  return value;
+}
+function positiveNumber(flag, raw, unit) {
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) throw new UsageError(`${flag} must be a positive number of ${unit}`);
+  return value;
+}
+function timeBound(flag, raw) {
+  try {
+    parseTimeBound(raw, flag);
+  } catch (error) {
+    throw new UsageError(error instanceof Error ? error.message : String(error));
+  }
+  return raw;
+}
+function harnessId(raw) {
+  if (!resolveAdapter(raw)) throw new UsageError(`unknown harness "${raw}"; known: ${knownHarnesses().join(", ")}`);
+  return raw;
+}
+var FLAGS = {
+  "--current": { help: "the caller's own session: CODEX_THREAD_ID, else CLAUDE_CODE_SESSION_ID", set: (a) => {
+    a.current = true;
+  } },
+  "--last": { value: "N", help: "the N newest sessions by file mtime, never the caller's own", set: (a, v) => {
+    a.last = positiveInteger("--last", v);
+  } },
+  "--since": { value: "T", help: "every session with a record since T: 30m, 2h, 7d or an ISO time", set: (a, v) => {
+    a.since = timeBound("--since", v);
+  } },
+  "--until": { value: "T", help: "close the --since window (exclusive); same forms", set: (a, v) => {
+    a.until = timeBound("--until", v);
+  } },
+  "--cwd": { value: "DIR", help: "sessions recorded in DIR or under it, or in a worktree of its repo", set: (a, v) => {
+    a.cwd = resolve(v);
+  } },
+  "--harness": { value: "ID", help: "read only this harness; with a file ref, force its reader", set: (a, v) => {
+    a.harness = harnessId(v);
+    a.harnessExplicit = true;
+  } },
+  "--latest-turn": { help: "only the latest task turn of a resumed Codex or Claude Code session", set: (a) => {
+    a.latestTurn = true;
+  } },
+  "--format": { value: "F", help: "the output format", set: (a, v) => {
+    a.format = v;
+  } },
+  "--out": { value: "PATH", help: "write the output to PATH; stdout gets one summary line", set: (a, v) => {
+    a.out = v;
+  } },
+  "--no-content": { help: "omit conversation, commands, paths and assignments", set: (a) => {
+    a.noContent = true;
+  } },
+  "--match": {
+    value: "RE",
+    help: "one row per human turn, agent message or shell command matching RE (a command: ok, failed or ?)",
+    freeText: true,
+    set: (a, v) => {
+      try {
+        new RegExp(v);
+      } catch (error) {
+        throw new UsageError(`--match is not a regular expression: ${error instanceof Error ? error.message : String(error)}`);
       }
-      case "--questions":
-        a.questionsFile = next();
-        break;
-      case "--question-budget":
-        a.questionBudget = Number(next());
-        break;
-      case "--question-timeout":
-        a.questionTimeout = Number(next());
-        break;
-      case "--redactor":
-        a.redactorCmd = next();
-        break;
-      case "--format":
-        a.format = next();
-        break;
-      case "--contract":
-        a.contract = next();
-        break;
-      case "--junit":
-        a.junit = next();
-        break;
-      case "--evidence":
-        a.evidence = next();
-        break;
-      case "--annotations":
-        a.annotations = true;
-        break;
-      case "--explain":
-        a.explain = true;
-        break;
-      case "--help":
-      case "-h":
-        a.help = true;
-        break;
-      case "--yes":
-      case "-y":
-        a.yes = true;
-        break;
-      default:
-        if (arg?.startsWith("--")) throw new Error(`unknown flag: ${arg}`);
-        if (arg && !a.input) a.input = arg;
-        else if (arg) throw new Error(`unexpected positional argument: ${arg}`);
+      a.match = v;
+    }
+  },
+  "--question": { value: "TEXT", help: `a question (repeatable, at most ${MAX_TRACE_QUESTION_CHARS} characters)`, freeText: true, set: (a, v) => {
+    a.questions.push(v);
+  } },
+  "--questions": { value: "FILE", help: "a JSON array of questions: strings or {id?, question, answerSchema?}", set: (a, v) => {
+    a.questionsFile = v;
+  } },
+  "--budget": { value: "USD", help: "required: the most the run may spend, shared by every question", set: (a, v) => {
+    a.budget = positiveNumber("--budget", v, "USD");
+  } },
+  "--model": { value: "ID", help: `the analyst model (default ${DEFAULT_ANALYST_MODEL})`, set: (a, v) => {
+    a.model = v;
+  } },
+  "--contract": { value: "FILE|conformance", help: "gate on a trace contract file, or on conformance (repeatable)", set: (a, v) => {
+    a.contracts.push(v);
+  } },
+  "--share-safe": {
+    help: "gate on whether each path is safe to share, read as bytes: SAFE passes, UNSAFE fails, UNKNOWN cannot decide",
+    set: (a) => {
+      a.shareSafe = true;
+    }
+  },
+  "--once": { help: "one pass, then exit", set: (a) => {
+    a.once = true;
+  } },
+  "--dry-run": { help: "redact and preview; send nothing", set: (a) => {
+    a.dryRun = true;
+  } },
+  "--yes": { help: "skip the confirmation prompt", set: (a) => {
+    a.yes = true;
+  } },
+  "--unused": { help: "only installed skills with no use in the window", set: (a) => {
+    a.unused = true;
+  } },
+  "--known-secret-env": {
+    value: "NAME",
+    help: "with --share-safe: an environment variable whose value must appear nowhere (repeatable)",
+    set: (a, v) => {
+      a.knownSecretEnvs.push(v);
     }
   }
-  return a;
-}
-var OTLP_INPUT_COMMANDS = /* @__PURE__ */ new Set([
-  "analyze",
-  "check",
-  "facts",
-  "investigate",
-  "improve",
-  "ask",
-  "stream",
-  "validate",
-  "mcp"
-]);
-function validateOtlpSelection(args) {
-  if (args.otlp === void 0) return args;
-  if (!OTLP_INPUT_COMMANDS.has(args.command)) {
-    throw new Error(
-      `${args.command} does not read --otlp. --otlp reads OTLP-JSONL on ${[...OTLP_INPUT_COMMANDS].join(", ")}; use --otlp-out <path> to write the artifact.`
+};
+var ALIASES = { "-y": "--yes" };
+var SELECT = ["--current", "--last", "--since", "--cwd", "--harness", "--latest-turn"];
+var MANY = Number.POSITIVE_INFINITY;
+var COMMANDS = [
+  {
+    name: "list",
+    usage: "list [<store-root>] [--last N | --since T] [--cwd DIR] [--harness ID] [--format text|json]",
+    job: "Find a session: one row per session, newest first, across every harness, never the caller's own.",
+    flags: [
+      { flag: "--last", help: "the N newest sessions (default 20)" },
+      "--since",
+      "--cwd",
+      { flag: "--harness", help: "only this harness's sessions" },
+      { flag: "--format", help: "text (default), or json with id, path, bytes and parent id" }
+    ],
+    formats: ["text", "json"],
+    refs: [0, 1],
+    jq: [
+      [".sessions[].ref", "the short ref any command takes"],
+      [".sessions[] | {id, cwd, firstPrompt}", "which session is which"],
+      [".selection.unreadSessions", "sessions that could not be read, and why"]
+    ],
+    examples: ["traces list --cwd . --last 5", "traces list --since 1d --harness codex", "traces list --format json | jq -r '.sessions[0].id'"],
+    overview: [["Which sessions ran?", "traces list [--cwd .] [--last N]"]]
+  },
+  {
+    name: "facts",
+    usage: "facts <ref\u2026> | --current | --last N | --since T [flags]",
+    job: "What happened, exactly, for $0: who acted, turns, tools, commands, PRs, first failure, tokens, cost, time lost.",
+    flags: [
+      ...SELECT.slice(0, 3),
+      "--until",
+      ...SELECT.slice(3),
+      "--match",
+      "--no-content",
+      { flag: "--format", help: "text (default, 25 lines a session), json (the sheet), or jsonl: one row per typed turn" },
+      { flag: "--out", help: "write the sheet to PATH; stdout gets one summary line" }
+    ],
+    formats: ["text", "json", "jsonl"],
+    refs: [0, MANY],
+    select: "required",
+    jq: [
+      [".sessions[0].humanTurns.value[] | {at, text, spanId}", "each typed turn, its time and span"],
+      [".sessions[0].commands.value[]", "programs run: runs, failed, inScripts"],
+      [".sessions[0].measurements.tools[] | {name, calls, failed: .outcomes.error}", "tool calls by name, and failures"],
+      [".sessions[0] | {firstFailure, tokens, cost, agent: .agent.value}", "first failure, tokens, cost, who acted"]
+    ],
+    examples: ["traces facts --current", "traces facts 019a3c7e --format json | jq '.sessions[0].measurements.waste'", "traces facts --since 30d --match '^gh pr merge'"],
+    overview: [
+      ["What happened (turns, PRs, failure, cost)? $0", "traces facts <ref> | --current | --since 1d"],
+      ["Did we already try X / what was said? $0", "traces facts <ref> | --since 30d --match '<re>'"]
+    ]
+  },
+  {
+    name: "analyze",
+    usage: "analyze <ref\u2026> | --current | --last N | --since T [flags]",
+    job: "What went wrong, ranked, for $0: failing commands, stalls, interrupts, findings, and what the trace cannot answer.",
+    notes: ["At most 40 lines; several sessions get a table of the 15 with the most waste. A Runtime run dir reports its tree."],
+    flags: [
+      ...SELECT.slice(0, 3),
+      "--until",
+      ...SELECT.slice(3),
+      { flag: "--format", help: "text (default, at most 40 lines) or json: facts, packet, measures, conformance, cannotAnswer" },
+      { flag: "--out", value: "DIR", help: "write report.md and findings.json under DIR; stdout gets one summary line" }
+    ],
+    formats: ["text", "json"],
+    refs: [0, MANY],
+    select: "required",
+    jq: [
+      [".packet.findings[] | {severity, subject, claim}", "the findings, HIGH first"],
+      [".cannotAnswer[] | {analysis, reason}", "what the trace cannot answer, and why"],
+      [".facts.sessions[0].measurements.waste", "failing streaks, stalls, reverts"]
+    ],
+    examples: ["traces analyze --current", "traces analyze 019a3c7e --out analysis", "traces analyze --since 1d --cwd ."],
+    overview: [["Where did it waste time or get interrupted? $0", "traces analyze <ref>"]]
+  },
+  {
+    name: "ask",
+    usage: "ask <ref\u2026> | --current | --last N | --since T --question TEXT [flags]",
+    job: "A question facts cannot answer, with checked trace:// citations: the only command that calls a model.",
+    notes: [
+      `Each question spends at most min(--budget, $${DEFAULT_QUESTION_MAX_COST_USD}) within ${DEFAULT_QUESTION_TIMEOUT_MS / 1e3} s; ${DEFAULT_ASK_CONCURRENCY} run at once. Some unanswered: exit 2.`,
+      "Needs TANGLE_API_KEY (or OPENAI_API_KEY) and uv, or TRACES_PYTHON naming a Python with agent-eval-rpc[dspy]."
+    ],
+    flags: [
+      ...SELECT,
+      "--question",
+      "--questions",
+      "--budget",
+      "--model",
+      { flag: "--format", help: "text (default): the report; json: each answer, its citations, failure and cost" },
+      { flag: "--out", value: "DIR", help: "write answers.json and report.md under DIR; stdout gets one summary line" }
+    ],
+    formats: ["text", "json"],
+    refs: [0, MANY],
+    select: "required",
+    jq: [[".questions[] | {id, status, answer, failure}", "each answer, or why it has none"]],
+    examples: [
+      'traces ask --current --question "Which command failed first?" --budget 1',
+      "traces ask 019a3c7e --questions questions.json --budget 5 --out answers",
+      `traces ask --last 3 --question "Did it verify the fix?" --budget 2 --format json | jq '.questions[0].answer'`
+    ],
+    overview: [["A question facts can't answer (model, $)", 'traces ask <ref> --question "\u2026" --budget 1']]
+  },
+  {
+    name: "check",
+    usage: "check <ref\u2026> | --current | --last N | --since T  --contract FILE|conformance | --share-safe  [flags]",
+    job: "The one gate: does this run pass a trace contract or conform, and is this file safe to share?",
+    notes: [
+      "A gate is required. --share-safe reads each path as bytes, never as a trace. --contract F with no ref explains F.",
+      "Exit 0 pass, 1 any gate fails, 2 a gate could not decide: a bad contract, a rule or verdict that could not run, an unreadable ref."
+    ],
+    flags: [
+      "--contract",
+      "--share-safe",
+      "--known-secret-env",
+      ...SELECT.slice(0, 4),
+      { flag: "--harness", help: "force the reader of a file ref (claude-code, codex, \u2026)" },
+      { flag: "--format", help: "text (default), json, junit or github: the verdict, on stdout" },
+      { flag: "--out", value: "DIR", help: "write evidence for each gate that did not pass under DIR" }
+    ],
+    formats: ["text", "json", "junit", "github"],
+    refs: [0, MANY],
+    select: "required",
+    jq: [
+      [".gates[] | {gate, status}", "each gate and what it decided"],
+      [".gates[].report.traces[]?.verdict.violations", "each rule a run broke, with span ids"]
+    ],
+    examples: [
+      "traces check run.otlp.jsonl --contract contract.json --format junit > contract.xml",
+      "traces check spans.otlp.jsonl --contract conformance",
+      "traces check handoff.md --share-safe --known-secret-env TANGLE_API_KEY"
+    ],
+    overview: [
+      ["Does this run pass? (CI)", "traces check <ref> --contract c.json|conformance"],
+      ["Is this safe to share?", "traces check <path> --share-safe"]
+    ]
+  },
+  {
+    name: "diff",
+    usage: "diff <a> <b> [--format text|json]",
+    job: "Where two runs of one task split: the first tool call that differs, with both calls.",
+    notes: [
+      "A side is a session id or 8+ char prefix or suffix, a session file, OTLP, file#<trace id> or file#branch=<id>.",
+      "Calls compare by tool, status and argument (the command, the file, or the input), after each run's",
+      "cwd, worktree, temp dirs and hex ids become <cwd>, <worktree>, <tmp> and <hex>. Model calls are not compared.",
+      "Exit 0 agree, 1 diverge, 2 could not compare: a side cannot be read, or neither records an outcome."
+    ],
+    flags: [{ flag: "--format", help: "text (default) or json" }],
+    formats: ["text", "json"],
+    refs: [2, 2],
+    jq: [
+      [".diff.firstDivergence", "where and how the runs first split (index is 0-based)"],
+      [".a.steps[.diff.firstDivergence.a].text", "A's call at that step, normalized"]
+    ],
+    examples: [
+      "traces diff 0199a1b2 0199c3d4",
+      "traces diff passing.otlp.jsonl failing.otlp.jsonl",
+      "traces diff run.otlp.jsonl#branch=a run.otlp.jsonl#branch=b --format json"
+    ],
+    overview: [["Where did two runs diverge?", "traces diff <a> <b>"]]
+  },
+  {
+    name: "watch",
+    usage: "watch [<id\u2026> | <store-root>] [--since T] [--once]  |  watch <run-dir|span file> [--once]",
+    job: "Live supervision: what the analyze rules find in every session active in the last 30 minutes, or one run tree.",
+    notes: [
+      "Sessions are read every 5 s; a run tree every 2 s, until its result lands (exit 1 when the run ended with an error).",
+      "A run dir or span file prints its tree as text, and its findings with --format jsonl."
+    ],
+    flags: [
+      { flag: "--since", help: "sessions active in the last T (default 30m; it slides with time), or since an ISO time" },
+      "--cwd",
+      { flag: "--harness", help: "only this harness's sessions; with a file ref, force its reader" },
+      { flag: "--once", help: "one pass, then exit" },
+      { flag: "--format", help: "text (default): a line per new finding, or the run tree; jsonl: the traces.stream events" }
+    ],
+    formats: ["text", "jsonl"],
+    refs: [0, MANY],
+    jq: [
+      ['select(.event == "finding") | .finding | {severity, ruleId, claim}', "each new finding"],
+      ['select(.event == "tick") | .unreadSessions', "sessions a pass could not read, and why"]
+    ],
+    examples: ["traces watch --once", "traces watch runs/my-run --once", "traces watch --since 2h --format jsonl"],
+    overview: [["What is happening right now?", "traces watch [<run-dir>] [--once]"]]
+  },
+  {
+    name: "bundle",
+    usage: "bundle <ref> | --current --out DIR      (then: traces bundle verify DIR)",
+    job: "Keep one session's evidence beyond log rotation: session/, spans, facts, git log, sha256 manifest.",
+    notes: ["A bundle directory is a ref: traces facts DIR reads it."],
+    flags: ["--current", { flag: "--harness", help: "force the reader of a file ref" }, { flag: "--out", value: "DIR", help: "a new or empty directory for the bundle" }],
+    refs: [0, 1],
+    select: "required",
+    examples: ["traces bundle 019a3c7e --out evidence/019a3c7e", "traces bundle --current --out evidence/now", "traces bundle verify evidence/019a3c7e"],
+    overview: [["Keep a session's evidence", "traces bundle <ref> --out <dir> \xB7 bundle verify <dir>"]]
+  },
+  {
+    name: "bundle verify",
+    usage: "bundle verify <dir> [--format text|json]",
+    job: "Check a bundle against its manifest: every listed file with its size and SHA-256, nothing unlisted.",
+    notes: ["Exit 0 verified, 1 any difference."],
+    flags: [{ flag: "--format", help: "text (default) or json" }],
+    formats: ["text", "json"],
+    refs: [1, 1],
+    jq: [
+      [".ok", "true when every file matches"],
+      [".issues[] | {kind, path, detail}", "each difference"]
+    ],
+    examples: ["traces bundle verify evidence/019a3c7e", "traces bundle verify evidence/019a3c7e --format json | jq .issues"]
+  },
+  {
+    name: "convert",
+    usage: "convert <ref\u2026> | --current | --last N | --since T [--out FILE] [--no-content]",
+    job: "Hand spans to another tool: contract OTLP-JSONL, to --out or stdout.",
+    notes: ["Sandbox events, Codex live streams and OpenInference files are sniffed; --harness forces a reader."],
+    flags: [
+      ...SELECT,
+      { flag: "--no-content", help: "metadata only: drop prompts, replies, tool input and output, error text, paths and briefs" },
+      { flag: "--out", help: "write the spans to PATH; stdout gets one summary line" },
+      { flag: "--format", help: "the --out summary line: text (default) or json {out, spans, droppedAttributes}" }
+    ],
+    formats: ["text", "json"],
+    refs: [0, MANY],
+    select: "required",
+    jq: [[".droppedAttributes", "with --out and --no-content: the attribute keys the metadata-only rule removed"]],
+    examples: [
+      "traces convert --current --out spans.otlp.jsonl",
+      "traces convert raw.otlp.jsonl --no-content --out metadata.otlp.jsonl --format json",
+      "traces convert live-stream.jsonl --harness codex-exec > spans.otlp.jsonl"
+    ],
+    overview: [["Hand spans to another tool", "traces convert <ref> --out <file>"]]
+  },
+  {
+    name: "upload",
+    usage: "upload <ref\u2026> | --current | --since T [--dry-run] [--no-content] [--yes]",
+    job: "Send redacted sessions to Tangle Intelligence; one still UNSAFE or UNKNOWN once redacted is refused (exit 1).",
+    notes: ["Env: TANGLE_INGEST_URL, TANGLE_INGEST_API_KEY (or TANGLE_API_KEY), TANGLE_TENANT_ID."],
+    flags: [
+      "--current",
+      "--since",
+      "--cwd",
+      "--harness",
+      "--dry-run",
+      { flag: "--no-content", help: "strip prompt and response text; send metadata only" },
+      "--yes",
+      { flag: "--out", help: "with --dry-run: write the redacted OTLP preview to PATH" }
+    ],
+    refs: [0, MANY],
+    examples: ["traces upload --since 24h --dry-run", "traces upload 019a3c7e --yes", "traces upload spans.otlp.jsonl --dry-run --out preview.otlp.jsonl"],
+    overview: [["Ship sessions to Intelligence", "traces upload <ref>|--since T [--dry-run]"]]
+  },
+  {
+    name: "skills",
+    usage: "skills [--since T] [--unused] [--format text|json]",
+    job: "Which skills are used, and which installed skills never are; no model call.",
+    notes: ["Reads Claude Code, Codex and Kimi Code sessions; each run reads only bytes appended since the last."],
+    flags: [
+      { flag: "--since", help: "count use since T: 30m, 2h, 7d or an ISO time (default 30d)" },
+      "--unused",
+      { flag: "--format", help: "text (default), or json with the refresh cost and sweep exclusions" }
+    ],
+    formats: ["text", "json"],
+    refs: [0, 0],
+    jq: [
+      [".rows[] | {skill, sessions}", "use per skill"],
+      [".unused[].skill", "installed skills never used in the window"]
+    ],
+    examples: ["traces skills --since 30d", "traces skills --unused", "traces skills --format json | jq '.rows[] | {skill, sessions}'"],
+    overview: [["Which skills are used?", "traces skills [--unused]"]]
+  },
+  {
+    name: "mcp",
+    usage: "mcp <ref\u2026> | --current | --last N | --since T",
+    job: "Serve agent-eval's read-only span tools over stdio, for an MCP client with no shell.",
+    notes: [
+      "Spans and results are redacted, and it refuses to start if redacted spans are UNSAFE or UNKNOWN.",
+      "Each result carries an untrusted-text notice and is capped at 512 KiB."
+    ],
+    flags: SELECT.slice(0, 5),
+    refs: [0, MANY],
+    select: "required",
+    examples: ["traces mcp spans.otlp.jsonl", "traces mcp --last 5", "claude mcp add traces -- traces mcp spans.otlp.jsonl"],
+    overview: [["Serve span tools over MCP", "traces mcp <ref>|--last N"]]
+  }
+];
+function usesOf(spec) {
+  return spec.flags.map((use) => typeof use === "string" ? { flag: use } : use);
+}
+var SPECS = COMMANDS;
+function commandAt(argv) {
+  if (argv[0] === "bundle" && argv[1] === "verify") return SPECS.find((spec) => spec.name === "bundle verify");
+  return SPECS.find((spec) => spec.name === argv[0]);
+}
+function appliesTo(flag) {
+  return SPECS.filter((spec) => usesOf(spec).some((use) => use.flag === flag)).map((spec) => spec.name);
+}
+function formatHelp(formats) {
+  return `${formats[0]} (default) or ${formats.slice(1).join(" or ")}`;
+}
+var OVERVIEW_COLUMN = 49;
+function renderGlobalHelp() {
+  const rows = SPECS.flatMap((spec) => (spec.overview ?? []).map(([question, example]) => `  ${question.padEnd(OVERVIEW_COLUMN - 1)} ${example}`));
+  const formats = [...new Set(SPECS.flatMap((spec) => spec.formats ?? []))];
+  return [
+    "traces: what your agents did, where they wasted time, whether a run passes",
+    "Start here for one session: traces facts <ref> (25 lines); one field: add --format json | jq '<path>'",
+    "",
+    ...rows,
+    "",
+    "ref: session id, or 8+ char unique prefix or suffix; session file; OTLP file/dir; bundle dir; run dir; store root",
+    "Select: --current  --last N  --since/--until 2h|1d|ISO  --cwd DIR  --harness ID  --latest-turn",
+    `Output: --format ${formats.join("|")}  --out PATH  --no-content`,
+    "Exit: 0 yes \xB7 1 no (fail, diverged, unsafe) \xB7 2 could not answer (stderr says why)",
+    "traces <command> --help for flags, jq paths and examples \xB7 moved from 0.x: traces help moved",
+    ""
+  ].join("\n");
+}
+var FLAG_COLUMN = 20;
+function renderCommandHelp(spec) {
+  const flagLines = usesOf(spec).map((use) => {
+    const flag = FLAGS[use.flag];
+    const value = use.flag === "--format" && spec.formats ? spec.formats.join("|") : use.value ?? flag.value;
+    const left = value ? `${use.flag} ${value}` : use.flag;
+    const help = use.help ?? (use.flag === "--format" && spec.formats ? formatHelp(spec.formats) : flag.help);
+    return `  ${left.padEnd(FLAG_COLUMN - 1)} ${help}`;
+  });
+  const lines = [`Usage: traces ${spec.usage}`, spec.job, ...spec.notes ?? []];
+  if (flagLines.length > 0) lines.push("", ...flagLines);
+  if (spec.jq && spec.jq.length > 0) {
+    const width = Math.max(...spec.jq.map(([path]) => path.length));
+    const format = spec.formats?.includes("json") ? "json" : "jsonl";
+    lines.push("", `jq paths (--format ${format}):`, ...spec.jq.map(([path, what]) => `  ${path.padEnd(width)}  ${what}`));
+  }
+  lines.push("", "Examples:", ...spec.examples.map((example) => `  ${example}`));
+  return `${lines.join("\n")}
+`;
+}
+function unknownCommand(word) {
+  return new UsageError(word.startsWith("-") ? `${word} needs a command before it: traces <command> ${word} \u2026; traces --help lists the commands` : `unknown command ${word}; traces --help lists the commands`);
+}
+function parseCommandLine(argv) {
+  const [first, second] = argv;
+  if (first === void 0 || first === "--help" || first === "-h") return { kind: "print", text: renderGlobalHelp() };
+  if (first === "--version" || first === "-v" || first === "version") {
+    return { kind: "print", text: `traces ${tracesVersion()} (${tracesCommit()})
+` };
+  }
+  if (first === "help") {
+    if (second === void 0) return { kind: "print", text: renderGlobalHelp() };
+    if (second === "moved") return { kind: "print", text: renderMovedTable() };
+    const spec2 = commandAt(argv.slice(1));
+    if (!spec2) throw unknownCommand(second);
+    return { kind: "print", text: renderCommandHelp(spec2) };
+  }
+  const spec = commandAt(argv);
+  if (!spec) throw unknownCommand(first);
+  const rest = argv.slice(spec.name.split(" ").length);
+  try {
+    const args = parseFlags(spec, rest);
+    if (args === "help") return { kind: "print", text: renderCommandHelp(spec) };
+    checkArgs(spec, args, argv);
+    return { kind: "run", args };
+  } catch (error) {
+    if (error instanceof UsageError && (rest.includes("--help") || rest.includes("-h"))) {
+      return { kind: "print", text: renderCommandHelp(spec) };
+    }
+    throw error;
+  }
+}
+function parseFlags(spec, rest) {
+  const args = emptyArgs(spec.name);
+  const allowed = new Set(usesOf(spec).map((use) => use.flag));
+  let help = false;
+  for (let i = 0; i < rest.length; i++) {
+    const word = rest[i];
+    if (word === "--help" || word === "-h") {
+      help = true;
+      continue;
+    }
+    if (!word.startsWith("-") || word === "-") {
+      args.refs.push(word);
+      continue;
+    }
+    const name = ALIASES[word] ?? word;
+    const flag = FLAGS[name];
+    if (!flag) throw new UsageError(`unknown flag ${word} for ${spec.name}; traces ${spec.name} --help lists its flags`);
+    if (!allowed.has(name)) throw new UsageError(`${name} does not apply to ${spec.name}; it applies to: ${appliesTo(name).join(", ")}`);
+    if (flag.value === void 0) {
+      flag.set(args, "");
+      continue;
+    }
+    const value = rest[i + 1];
+    if (value === void 0 || !flag.freeText && value.startsWith("--")) {
+      throw new UsageError(`${name} needs a value: ${name} ${flag.value}`);
+    }
+    i++;
+    flag.set(args, value);
+  }
+  if (help) return "help";
+  args.input = args.refs[0];
+  return args;
+}
+function checkArgs(spec, args, argv) {
+  const [min, max] = spec.refs;
+  if (args.refs.length > max) {
+    throw new UsageError(max === 0 ? `${spec.name} takes no ref, got ${args.refs[0]}: traces ${spec.usage}` : `unexpected argument ${args.refs[max]}: traces ${spec.usage}`);
+  }
+  if (args.refs.length < min) throw new UsageError(`${spec.name} needs ${min === 1 ? "one ref" : `${min} refs`}: traces ${spec.usage}`);
+  if (args.format !== void 0 && spec.formats && !spec.formats.includes(args.format)) {
+    throw new UsageError(`unknown ${spec.name} format "${args.format}" (expected ${spec.formats.join(" or ")})`);
+  }
+  const selected = args.refs.length > 0 || args.current || args.last > 0 || args.since !== void 0;
+  if (spec.name === "upload" && !selected) {
+    throw new UsageError(`upload with no selection was removed in traces 1.0. Instead: ${tracesCommand([...argv, "--since", "24h"])}`);
+  }
+  if (spec.name === "check") checkGates(args);
+  const explains = spec.name === "check" && !selected;
+  if (spec.select === "required" && !selected && !explains) {
+    const flags = new Set(usesOf(spec).map((use) => use.flag));
+    const ways = ["a ref", ...["--current", "--last N", "--since T"].filter((way) => flags.has(way.split(" ")[0]))];
+    const choice = ways.length === 1 ? ways[0] : `${ways.slice(0, -1).join(", ")} or ${ways.at(-1)}`;
+    throw new UsageError(
+      `${spec.name} needs ${choice}${flags.has("--cwd") ? "; --cwd and --harness only narrow" : ""}. traces list finds a session`
     );
   }
-  if (args.input) throw new Error("--otlp cannot be combined with an input file");
-  if (args.session) throw new Error("--otlp reads a file and cannot be combined with --session");
-  if (args.supervisorRunDir) throw new Error("--otlp cannot be combined with --supervisor-run-dir");
-  if (args.workflow || args.latestTurn) {
-    throw new Error("--workflow and --latest-turn expand harness sessions and cannot be combined with --otlp");
+  if (spec.name === "ask" && args.budget === void 0) {
+    throw new UsageError(`ask needs --budget USD, the most the run may spend: ${tracesCommand([...argv, "--budget", "1"])} (each question spends at most min(USD, $${DEFAULT_QUESTION_MAX_COST_USD}))`);
   }
-  return args;
 }
-var CURRENT_SESSION_COMMANDS = /* @__PURE__ */ new Set([
-  "analyze",
-  "facts",
-  "investigate",
-  "improve",
-  "ask",
-  "convert",
-  "index",
-  "evidence",
-  "bundle",
-  "stream"
-]);
-var WORKFLOW_COMMANDS = /* @__PURE__ */ new Set([
-  "analyze",
-  "facts",
-  "investigate",
-  "improve",
-  "ask",
-  "convert",
-  "index",
-  "evidence"
-]);
-function applyCurrentSessionSelection(args) {
-  if (!args.current) return args;
-  if (!CURRENT_SESSION_COMMANDS.has(args.command)) {
-    throw new Error(`--current is not supported by ${args.command}`);
-  }
-  if (args.input) throw new Error("--current cannot be combined with an input file");
-  if (args.supervisorRunDir) throw new Error("--current cannot be combined with --supervisor-run-dir");
-  if (args.session) throw new Error("--current cannot be combined with --session");
-  if (args.last > 0) throw new Error("--current cannot be combined with --last");
-  if (args.all) throw new Error("--current cannot be combined with --all");
-  const adapter = resolveAdapter(args.harness);
-  if (adapter?.harness !== "codex") {
-    throw new Error("--current uses CODEX_THREAD_ID and requires --harness codex");
-  }
-  const sessionId = process.env.CODEX_THREAD_ID?.trim();
-  if (!sessionId) throw new Error("--current requires CODEX_THREAD_ID from the active Codex session");
-  return { ...args, session: sessionId };
-}
-function validateViewSelection(args) {
-  if (args.view === void 0 || args.command === "bundle-view") return args;
-  throw new Error(
-    `--view is not supported by ${args.command}. A view is a projection of an assembled bundle: run \`traces bundle ... --out <dir>\` first, then \`traces bundle-view <dir> --view evidence-only --out <view-dir>\`.`
-  );
+function checkGates(args) {
+  if (args.contracts.length === 0 && !args.shareSafe) {
+    throw new UsageError("check needs a gate: --contract FILE|conformance (repeatable), or --share-safe");
+  }
+  if (args.shareSafe && (args.current || args.last > 0 || args.since !== void 0)) {
+    throw new UsageError("--share-safe reads the paths you name; --current, --last and --since select sessions for a contract. Run them as two checks");
+  }
+  if (args.shareSafe && args.refs.length === 0) throw new UsageError("--share-safe needs the files or directories to read: traces check <path> --share-safe");
+  if (args.knownSecretEnvs.length > 0 && !args.shareSafe) throw new UsageError("--known-secret-env applies with --share-safe");
+}
+function wantsJsonErrors(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    if (FLAGS[argv[i]]?.freeText) {
+      i++;
+      continue;
+    }
+    if (argv[i] === "--format" && (argv[i + 1] === "json" || argv[i + 1] === "jsonl")) return true;
+  }
+  return false;
+}
+function writeError(message, code, json, extra = {}) {
+  process.stderr.write(json ? `${JSON.stringify({ error: message, code, ...extra })}
+` : `error: ${message}
+`);
 }
-function validateUntilSelection(args) {
-  if (args.until === void 0 || args.command === "facts") return args;
-  throw new Error(`--until is not supported by ${args.command}; it bounds the facts window (traces facts --since <t> --until <t>)`);
+function reportError(error, json) {
+  const message = error instanceof Error ? error.message : String(error);
+  const code = error instanceof RefError || error instanceof CliError ? error.code : "unreadable";
+  const candidates = error instanceof RefError && error.candidates.length > 0 ? { candidates: error.candidates } : {};
+  writeError(message, code, json, candidates);
+  process.exitCode = 2;
 }
-function validateWorkflowSelection(args) {
-  if (!args.workflow && !args.latestTurn) return args;
-  if (!WORKFLOW_COMMANDS.has(args.command)) {
-    throw new Error(`${args.workflow ? "--workflow" : "--latest-turn"} is not supported by ${args.command}`);
+async function runTraces(argv, handlers) {
+  try {
+    const moved = findMoved(argv);
+    if (moved) throw new UsageError(movedMessage(moved, argv));
+    const parsed = parseCommandLine(argv);
+    if (parsed.kind === "print") {
+      process.stdout.write(parsed.text);
+      return;
+    }
+    await handlers[parsed.args.command](parsed.args);
+  } catch (error) {
+    reportError(error, wantsJsonErrors(argv));
   }
-  if (args.input) throw new Error("--workflow and --latest-turn cannot be combined with an input file");
-  if (args.supervisorRunDir) {
-    throw new Error("--workflow and --latest-turn cannot be combined with --supervisor-run-dir");
+}
+
+// src/cli.ts
+var MAX_CHILD_SESSIONS = 100;
+function callerSession(harness) {
+  const codex = process.env.CODEX_THREAD_ID?.trim();
+  const claude = process.env.CLAUDE_CODE_SESSION_ID?.trim();
+  if (codex && harness !== "claude-code") return { harness: "codex", sessionId: codex };
+  if (claude && harness !== "codex") return { harness: "claude-code", sessionId: claude };
+  return void 0;
+}
+var CURRENT_VARIABLES = "CODEX_THREAD_ID (Codex) or CLAUDE_CODE_SESSION_ID (Claude Code)";
+function applyCurrentSessionSelection(args) {
+  if (!args.current) return args;
+  if (args.refs.length > 0) throw new UsageError("--current names the caller's own session; pass --current or a ref, not both");
+  if (args.last > 0) throw new UsageError("--current cannot be combined with --last");
+  const named = args.harnessExplicit ? resolveAdapter(args.harness)?.harness ?? args.harness : void 0;
+  if (named !== void 0 && named !== "codex" && named !== "claude-code") {
+    throw new UsageError(
+      `--current reads ${CURRENT_VARIABLES}; ${named} sets neither. Name this session with \`traces list --cwd . --last 1\``
+    );
   }
-  const selected = resolveAdapter(args.harness);
-  const supportsTaskTurns = selected?.harness === "codex" || selected?.harness === "claude-code";
-  if (args.latestTurn && (args.all || !supportsTaskTurns)) {
-    throw new Error("--latest-turn requires --harness codex or claude-code");
+  const caller = callerSession(named);
+  if (!caller) {
+    throw new UsageError(
+      `--current needs ${CURRENT_VARIABLES}, and neither is set. On another harness, \`traces list --cwd . --last 1\` names this session`
+    );
+  }
+  return { ...args, refs: [caller.sessionId], input: caller.sessionId, harness: caller.harness, harnessExplicit: true };
+}
+function supportsTaskTurns(adapter) {
+  return adapter?.harness === "codex" || adapter?.harness === "claude-code";
+}
+function validateLatestTurn(args) {
+  if (args.latestTurn && args.harnessExplicit && !supportsTaskTurns(resolveAdapter(args.harness))) {
+    throw new UsageError("--latest-turn reads Codex and Claude Code sessions; pass --harness codex or claude-code, or no --harness");
   }
   return args;
 }
+async function resolveSelection(args) {
+  if (args.refs.length === 0) return void 0;
+  const resolved = await resolveRefs(args.refs, { harness: args.harnessExplicit ? args.harness : void 0 });
+  const sessions = [];
+  const spans = [];
+  let home;
+  for (const ref of resolved) {
+    if (ref.kind === "session") sessions.push({ adapter: ref.adapter, ref: { ...ref.session, cwd: ref.session.cwd ?? args.cwd ?? null } });
+    else if (ref.kind === "store-root") home = ref.path;
+    else spans.push(ref);
+  }
+  if (args.latestTurn) {
+    if (spans[0]) throw new UsageError(`--latest-turn reads harness sessions; ${spans[0].ref} is a span source`);
+    const other = sessions.find(({ adapter }) => !supportsTaskTurns(adapter));
+    if (other) throw new UsageError(`--latest-turn reads Codex and Claude Code sessions; ${other.ref.sessionId} is ${other.adapter.harness}`);
+    const narrowed = args.harnessExplicit && supportsTaskTurns(resolveAdapter(args.harness));
+    if (home !== void 0 && sessions.length === 0 && !narrowed) {
+      throw new UsageError("--latest-turn over a store root requires --harness codex or claude-code");
+    }
+  }
+  return { sessions, spans, ...home !== void 0 ? { home } : {} };
+}
+async function withSelection(args) {
+  if (args.selection || args.refs.length === 0) return args;
+  return { ...args, selection: await resolveSelection(args) };
+}
 async function confirm(question) {
   if (!process.stdin.isTTY) return false;
   const rl = (await import("readline/promises")).createInterface({
@@ -742,116 +1342,174 @@ async function confirm(question) {
   }
 }
 function adaptersFor(args) {
-  return selectAdapters({ all: args.all, harnesses: [args.harness] });
-}
-async function discover(args) {
-  const sinceMs = args.since ? parseSince(args.since) : void 0;
-  const out = [];
-  for (const adapter of adaptersFor(args)) {
-    let refs = await locateSessions(adapter, { cwd: args.cwd, sinceMs });
-    if (args.last > 0) refs = refs.slice(0, args.last);
-    out.push({ adapter, refs });
-  }
-  return out;
+  let adapters = args.harnessExplicit ? selectAdapters({ harnesses: [args.harness] }) : [...listAdapters()];
+  if (args.latestTurn && !args.harnessExplicit) adapters = adapters.filter(supportsTaskTurns);
+  return args.selection?.home !== void 0 ? adapters.filter(readsStoreRoots) : adapters;
 }
-function missingPath(error) {
-  return typeof error === "object" && error !== null && error.code === "ENOENT";
+async function discover(args, defaultLast) {
+  return narrow(args, await locateAll(args, args.since ? parseSince(args.since) : void 0), defaultLast);
 }
-async function resolveSelectedSession(args) {
-  if (!args.session) throw new Error("resolveSelectedSession requires --session");
-  const adapter = resolveAdapter(args.harness);
-  if (!adapter && !args.all) throw new Error(`unknown harness "${args.harness}"`);
-  try {
-    const st = await stat(args.session);
-    if (!adapter) {
-      throw new Error("--session <path> requires --harness when --all is set");
+async function locateAll(args, sinceMs) {
+  const sessions = [];
+  const unread = [];
+  for (const adapter of adaptersFor(args)) {
+    try {
+      for (const ref of await locateSessions(adapter, { sinceMs, home: args.selection?.home })) sessions.push({ adapter, ref });
+    } catch (error) {
+      unread.push({ sessionId: null, traceId: null, source: `${adapter.harness} sessions`, reason: errorText(error) });
     }
-    return {
-      adapter,
-      ref: {
-        harness: adapter.harness,
-        sessionId: args.session,
-        path: args.session,
-        // --session is an explicit file; honor --cwd so adoption can find the
-        // project's current or legacy skill-run log (locate() infers cwd in the scan path).
-        cwd: args.cwd ?? null,
-        mtimeMs: st.mtimeMs
-      }
-    };
-  } catch (error) {
-    if (!missingPath(error)) throw error;
   }
-  const matches = [];
-  for (const candidate of args.all ? adaptersFor(args) : [adapter]) {
-    const refs = await locateSessions(candidate, { cwd: args.cwd });
-    for (const ref of refs) {
-      if (ref.sessionId === args.session) matches.push({ adapter: candidate, ref });
+  return { sessions: sessions.sort((a, b) => b.ref.mtimeMs - a.ref.mtimeMs), unread };
+}
+async function narrow(args, located, defaultLast) {
+  const sinceMs = args.since ? parseSince(args.since) : void 0;
+  let sessions = sinceMs === void 0 ? located.sessions : located.sessions.filter(({ ref }) => ref.mtimeMs >= sinceMs);
+  if (args.cwd) {
+    const kept = /* @__PURE__ */ new Set();
+    for (const adapter of new Set(sessions.map((session) => session.adapter))) {
+      const refs = sessions.filter((session) => session.adapter === adapter).map((session) => session.ref);
+      for (const ref of await sessionsInCwd(adapter, refs, args.cwd)) kept.add(ref);
     }
+    sessions = sessions.filter(({ ref }) => kept.has(ref));
   }
-  if (matches.length === 1) return matches[0];
-  if (matches.length === 0) {
-    throw new Error(
-      `no ${args.all ? "selected" : adapter.harness} session with ID "${args.session}"; run \`traces list\` to select an ID, or pass an explicit session path`
-    );
+  const last = args.last > 0 ? args.last : args.since ? void 0 : defaultLast;
+  if (last === void 0) return { sessions, unread: located.unread };
+  const caller = callerSession()?.sessionId;
+  return { sessions: sessions.filter(({ ref }) => ref.sessionId !== caller).slice(0, last), unread: located.unread };
+}
+function groupsInOrder(sessions) {
+  const groups = [];
+  for (const { adapter, ref } of sessions) {
+    const last = groups[groups.length - 1];
+    if (last?.adapter === adapter) last.refs.push(ref);
+    else groups.push({ adapter, refs: [ref] });
   }
-  throw new AmbiguousTraceInputError(
-    `session ID "${args.session}" is ambiguous across ${matches.length} files; select one harness or pass its explicit session path`
-  );
+  return groups;
+}
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
 }
-function llmAnalysisEngine(args, model) {
-  return analysisEngineFromEnv({ model, maxCostUsd: args.budget, log: analystLog });
+function warnUnread(args, unread, command = "facts") {
+  if (unread.length === 0) return;
+  const select = args.current ? ["--current"] : args.refs.map(shellWord);
+  if (args.harnessExplicit && !args.current) select.push("--harness", args.harness);
+  if (args.since) select.push("--since", shellWord(args.since));
+  if (args.until) select.push("--until", shellWord(args.until));
+  if (args.last > 0) select.push("--last", String(args.last));
+  if (args.cwd) select.push("--cwd", shellWord(args.cwd));
+  if (args.latestTurn) select.push("--latest-turn");
+  process.stderr.write(`${unread.length} unreadable: ${["traces", command, ...select].join(" ")} --format json | jq .selection
+`);
 }
 function analystModelFor(args) {
   return args.model ?? process.env.TRACES_ANALYST_MODEL ?? DEFAULT_ANALYST_MODEL;
 }
-function requiredBridgeVersion() {
-  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-  const version = pkg.dependencies?.["@tangle-network/agent-eval"];
-  if (typeof version !== "string" || !version) {
-    throw new Error("package.json is missing the @tangle-network/agent-eval dependency");
-  }
-  return version;
-}
-function assertRequestedAnalysesRan(args, result) {
-  const messages = [];
-  if (args.llm && totalAgenticFailureMessage(result.agenticPerAnalyst)) {
-    messages.push(totalAgenticFailureMessage(result.agenticPerAnalyst, { requiredBridgeVersion: requiredBridgeVersion() }));
+var PROMPT_CHARS = 80;
+function oneLine(text, chars) {
+  const flat2 = text.replace(/\s+/gu, " ").trim();
+  return flat2.length <= chars ? flat2 : `${flat2.slice(0, chars - 1)}\u2026`;
+}
+function formatDuration(ms) {
+  if (ms === null) return "?";
+  const seconds = Math.round(ms / 1e3);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+  return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
+async function listRow(adapter, ref, shortRef, session) {
+  const first = session.firstAt;
+  const last = session.lastAt;
+  let bytes = null;
+  try {
+    bytes = (await stat(ref.path)).size;
+  } catch {
   }
-  const external = externalFailureMessage(result.external);
-  if (external) messages.push(external);
-  if (messages.length > 0) throw new Error(messages.join("\n"));
+  return {
+    ref: shortRef,
+    id: ref.sessionId,
+    harness: adapter.harness,
+    path: ref.path,
+    bytes,
+    parentSessionId: session.parentSessionId,
+    lastActivity: last ?? new Date(ref.mtimeMs).toISOString(),
+    durationMs: first !== null && last !== null ? Date.parse(last) - Date.parse(first) : null,
+    humanTurns: session.humanTurns.length,
+    cwd: session.cwd ?? ref.cwd,
+    firstPrompt: session.firstPrompt === null ? null : oneLine(session.firstPrompt, PROMPT_CHARS)
+  };
 }
 async function cmdList(args) {
-  const groups = await discover({ ...args, last: args.last || 20 });
-  for (const { adapter, refs } of groups) {
-    console.log(`
-${adapter.harness}: ${refs.length} session(s)`);
-    for (const r of refs) {
-      console.log(`  ${new Date(r.mtimeMs).toISOString()}  ${r.sessionId}  ${r.cwd ?? ""}`);
+  const named = args.selection?.sessions[0]?.ref.sessionId ?? args.selection?.spans[0]?.ref;
+  if (named !== void 0) {
+    throw new UsageError(`list finds sessions; its only ref is a store root, and ${named} is not one (read it with \`traces facts ${named}\`)`);
+  }
+  const every = await locateAll(args);
+  const shortRefs = shortestRefs(every.sessions.map(({ ref }) => ref.sessionId));
+  const found = await narrow(args, every, 20);
+  const rows = [];
+  const unread = [...found.unread];
+  const stats = await TurnIndex.with(async (index) => {
+    const refreshed = await index.refresh(found.sessions);
+    for (const { adapter, ref } of found.sessions) {
+      const held = index.session(adapter, ref);
+      if (!held || held.unread !== null) {
+        unread.push({ sessionId: ref.sessionId, traceId: null, source: ref.path, reason: held?.unread ?? "not indexed" });
+        continue;
+      }
+      rows.push(await listRow(adapter, ref, shortRefs.get(ref.sessionId) ?? ref.sessionId, held.session));
     }
+    return refreshed;
+  });
+  warnUnread(args, unread, "list");
+  if (args.format === "json") {
+    process.stdout.write(`${JSON.stringify({ sessions: rows, selection: { unreadSessions: unread, index: stats } }, null, 2)}
+`);
+    return;
   }
+  const footer = `${rows.length} session${rows.length === 1 ? "" : "s"} \xB7 ${unread.length} unreadable`;
+  const lines = rows.map((row) => [
+    row.ref.padEnd(8),
+    row.harness.padEnd(11),
+    row.lastActivity.slice(0, 16).replace("T", " "),
+    formatDuration(row.durationMs).padStart(7),
+    `${row.humanTurns ?? "?"} turn${row.humanTurns === 1 ? "" : "s"}`.padEnd(9),
+    row.cwd ?? "(no cwd)",
+    row.firstPrompt ? `"${row.firstPrompt}"` : ""
+  ].join("  ").trimEnd());
+  process.stdout.write(`${[...lines, footer].join("\n")}
+`);
 }
-async function collectOtlpSpans(path) {
-  const input = await readOtlpInput(path);
+async function collectOtlpSpans(path, selector) {
+  const { sessionReportSource } = await import("./report-JAMXRTCW.js");
+  let input;
+  try {
+    input = await readOtlpInput(path);
+  } catch (error) {
+    if (!(await stat(path).catch(() => void 0))?.isDirectory()) throw error;
+    throw new Error(
+      `${errorText(error)}. A directory ref is read as OTLP-JSONL unless it is a Runtime run (spawn-journal.jsonl, observer.jsonl or failure.json), a harness store root, or a bundle (manifest.json)`
+    );
+  }
   if (input.spans.length === 0) {
     throw new Error(
-      `no analyzable spans in ${path} (${input.files.length} file(s), ${input.rows.length} row(s), ${input.issues.length} unusable). Run \`traces validate ${path}\` for the per-finding reason.`
+      `no analyzable spans in ${path} (${input.files.length} file(s), ${input.rows.length} row(s), ${input.issues.length} unusable). Run \`traces check ${path} --contract conformance\` for the per-finding reason.`
     );
   }
   const fileByTrace = /* @__PURE__ */ new Map();
   for (const file of input.files) {
     for (const traceId of file.traceIds) if (!fileByTrace.has(traceId)) fileByTrace.set(traceId, file.path);
   }
+  const selected = selector ? selectSpans(input.spans, selector, path) : input.spans;
   const byTrace = /* @__PURE__ */ new Map();
-  for (const span of input.spans) {
+  for (const span of selected) {
     const grouped = byTrace.get(span.trace_id) ?? [];
     grouped.push(span);
     byTrace.set(span.trace_id, grouped);
   }
   return {
-    spans: [...input.spans],
+    spans: [...selected],
     harness: "otlp",
-    cwds: [],
     sources: [...byTrace].map(([traceId, spans]) => sessionReportSource({
       harness: "otlp",
       sessionId: traceId,
@@ -869,128 +1527,189 @@ async function collectOtlpSpans(path) {
   };
 }
 async function collectSpans(args) {
-  if (args.sourceBundle) {
-    if (!["analyze", "investigate", "improve", "ask"].includes(args.command)) throw new Error("--source-bundle is an analysis option");
-    if (args.session || args.otlp || args.input || args.current || args.workflow || args.noContent || args.redactorCmd) {
-      throw new Error("--source-bundle cannot be combined with another input, redaction, or metadata-only selection");
-    }
-    for (const output of [args.out, args.dir, args.otlpOut]) {
-      if (output) await assertOutsideSourceBundle(args.sourceBundle, output);
-    }
-    return collectOtlpSpans(join2(args.sourceBundle, "derived", "trace.otlp.jsonl"));
+  if (args.refs.length > 0 && !args.selection) throw new Error(`internal: ${args.command} read its refs before resolving them`);
+  const sources = args.selection?.spans ?? [];
+  if (sources.length === 0) {
+    const collected2 = await collectSessionSpans(args);
+    warnUnread(args, collected2.unread ?? []);
+    return collected2;
+  }
+  const parts = [];
+  for (const source of sources) {
+    parts.push(source.kind === "run-dir" ? await collectOtlpSpans(source.path) : source.reader === "otlp" ? await collectOtlpSpans(source.path, source.selector) : await collectImportedSpans(source.path, source.reader, source.selector));
+  }
+  if (args.selection?.sessions.length) parts.push(await collectSessionSpans(args));
+  const collected = parts.length === 1 ? parts[0] : mergeCollected(parts);
+  warnUnread(args, collected.unread ?? []);
+  return collected;
+}
+async function forEachSpanBatch(args, onBatch) {
+  let spanCount = 0;
+  const counted = async (spans, harness) => {
+    spanCount += spans.length;
+    await onBatch(spans, harness);
+  };
+  if ((args.selection?.spans.length ?? 0) === 0) {
+    const collected2 = await collectSessionSpans(args, counted);
+    warnUnread(args, collected2.unread ?? []);
+    return { ...collected2, spanCount };
   }
-  if (args.otlp) return collectOtlpSpans(args.otlp);
-  if (args.input) {
-    if (args.workflow) throw new Error("--workflow reads discovered sessions and cannot be combined with an input file");
-    return collectImportedSpans(args);
+  const collected = await collectSpans(args);
+  if (collected.spans.length > 0) await counted(collected.spans, collected.harness);
+  return { ...collected, spans: [], spanCount };
+}
+function mergeCollected(parts) {
+  const spans = [];
+  const sources = [];
+  const unread = [];
+  const workflows = parts.flatMap((part) => part.workflow ? [part.workflow] : []);
+  for (const part of parts) {
+    appendAll(spans, part.spans);
+    appendAll(sources, part.sources);
+    appendAll(unread, part.unread ?? []);
   }
-  const selection = await collectSessionRows(args, false, args.last || 1);
+  return {
+    spans,
+    harness: [...new Set(parts.flatMap((part) => part.harness.split("+")))].join("+"),
+    sources,
+    ...workflows[0] ? { workflow: workflows[0] } : {},
+    ...unread.length > 0 ? { unread } : {}
+  };
+}
+async function collectSessionSpans(args, onBatch) {
+  const { sessionReportSource } = await import("./report-JAMXRTCW.js");
   const spans = [];
   const harnesses = /* @__PURE__ */ new Set();
-  const cwds = [];
   const sources = [];
-  for (const row of selection.rows) {
+  const sweep = onBatch !== void 0 && args.since !== void 0 && (args.selection?.sessions.length ?? 0) === 0;
+  const take = (row) => {
     harnesses.add(row.adapter.harness);
-    appendAll(spans, row.spans);
     sources.push(sessionReportSource(row.ref, row.spans));
-    if (row.ref.cwd) cwds.push(row.ref.cwd);
+  };
+  const selection = await collectSessionRows(args, args.last || 1, sweep ? async (row) => {
+    take(row);
+    await onBatch(row.spans, row.adapter.harness);
+  } : void 0);
+  for (const row of selection.rows) {
+    take(row);
+    appendAll(spans, row.spans);
   }
+  const harness = [...harnesses].join("+") || (args.harnessExplicit ? args.harness : "none");
+  if (onBatch && !sweep && spans.length > 0) await onBatch(spans.splice(0), harness);
   return {
     spans,
-    harness: [...harnesses].join("+") || args.harness,
-    cwds,
+    harness,
     sources,
-    ...selection.workflow ? { workflow: selection.workflow } : {}
+    ...selection.workflow ? { workflow: selection.workflow } : {},
+    ...selection.unread.length > 0 ? { unread: selection.unread } : {}
   };
 }
-async function cmdValidate(args) {
-  const path = args.otlp ?? args.input;
-  if (!path) {
-    throw new Error("validate needs an OTLP-JSONL file or directory: `traces validate <file|dir>`");
-  }
-  const input = await readOtlpInput(path);
-  const report = renderValidation(input.validation, {
-    subject: path,
-    files: input.files,
-    skipped: input.skipped,
-    issues: input.issues,
-    withheld: input.withheld,
-    unreadable: input.unreadable,
-    spans: input.spans
-  });
-  const validation = input.validation;
-  if (args.out) {
-    await saveReport(args.out, report);
-    console.log(
-      `conformance report \u2192 ${args.out}  (${validation.findings.length} finding(s), ${validation.capabilities.filter((capability) => capability.available).length}/${validation.capabilities.length} capabilities available)`
-    );
-  } else {
-    console.log(report);
-  }
-  process.exitCode = validationExitCode(validation);
-}
-var EVIDENCE_FORMATS = /* @__PURE__ */ new Set(["policy-evidence", "sandbox-events", "openinference", "intelligence-spans", "chat-trajectory"]);
-async function checkInputArgs(args) {
-  if (!args.input) return args;
-  if (args.otlp || args.session) throw new Error("name the trace once: a positional path, --otlp, or --session");
-  const info = await stat(args.input);
-  let kind;
-  if (args.format && EVIDENCE_FORMATS.has(args.format)) kind = "evidence";
-  else if (args.format === "otlp" || args.format === "claude-code" || args.format === "codex") kind = args.format;
-  else if (args.format) throw new Error(`unknown --format "${args.format}" (otlp, claude-code, codex, or an evidence format)`);
-  else kind = info.isDirectory() ? "otlp" : await sniffCheckInput(args.input);
-  if (kind === "otlp") return { ...args, otlp: args.input, input: void 0 };
-  if (kind === "evidence") return args;
-  return { ...args, harness: kind, harnessExplicit: true, session: args.input, input: void 0 };
-}
 async function cmdCheck(args) {
-  if (!args.contract) {
-    process.stderr.write("error: check needs --contract <contract.json>\n");
-    process.exitCode = CHECK_EXIT.badContract;
-    return;
+  const check = await import("./check-YF6ZHPGG.js");
+  const { explainTraceContract } = await import("@tangle-network/agent-eval");
+  const contracts = /* @__PURE__ */ new Map();
+  for (const path of args.contracts) {
+    if (path === check.CONFORMANCE || contracts.has(path)) continue;
+    try {
+      contracts.set(path, await check.loadContract(path));
+    } catch (error) {
+      throw new UsageError(errorText(error));
+    }
   }
-  let loaded;
-  try {
-    loaded = await loadContract(args.contract);
-  } catch (error) {
-    process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}
+  for (const loaded of contracts.values()) for (const warning of loaded.warnings) process.stderr.write(`warning: ${warning}
+`);
+  const traceGates = args.contracts.length > 0;
+  const selected = args.refs.length > 0 || args.current || args.last > 0 || args.since !== void 0;
+  if (traceGates && !selected && !args.shareSafe) {
+    const explained = args.contracts.map((path) => {
+      const loaded = contracts.get(path);
+      return loaded ? { contract: loaded.contract.name, text: explainTraceContract(loaded.contract) } : { contract: check.CONFORMANCE, text: check.CONFORMANCE_EXPLAINED };
+    });
+    process.stdout.write(args.format === "json" ? `${JSON.stringify({ explain: explained }, null, 2)}
+` : `${explained.map((entry) => entry.text).join("\n\n")}
 `);
-    process.exitCode = CHECK_EXIT.badContract;
     return;
   }
-  for (const warning of loaded.warnings) process.stderr.write(`warning: ${warning}
+  const gates = [];
+  if (traceGates) {
+    const resolved = await withSelection(args);
+    const sources = resolved.selection?.spans ?? [];
+    const otlpOnly = resolved.selection !== void 0 && resolved.selection.sessions.length === 0 && resolved.selection.home === void 0 && sources.every((source) => source.kind === "run-dir" || source.reader === "otlp");
+    let run;
+    const runSpans = async () => {
+      if (run) return run;
+      try {
+        run = await collectSpans(resolved);
+      } catch (error) {
+        if (error instanceof RefError || error instanceof CliError) throw error;
+        throw new CliError(errorText(error), error instanceof check.AmbiguousTraceInputError ? "ambiguous" : "unreadable");
+      }
+      if (run.spans.length === 0) throw new CliError("the trace holds no spans", "unreadable");
+      return run;
+    };
+    for (const path of args.contracts) {
+      if (path !== check.CONFORMANCE) {
+        const report = await check.runCheck(contracts.get(path).contract, (await runSpans()).spans, args.out === void 0 ? {} : { evidenceRoot: args.out });
+        gates.push(check.contractGate(report));
+      } else if (otlpOnly) {
+        for (const source of sources) gates.push(await otlpConformanceGate(check, source.ref, source.path));
+      } else {
+        const { spans } = await runSpans();
+        const subject = args.refs.length > 0 ? args.refs.join(" ") : "the selected sessions";
+        const validation = conformanceOfSpans(spans);
+        gates.push(check.conformanceGate(subject, validation, renderValidation(validation, { subject, spans })));
+      }
+    }
+  }
+  if (args.shareSafe) {
+    const { verifySafe } = await import("./verify-safe-C5ZXZOZ2.js");
+    const knownSecrets = args.knownSecretEnvs.map((name) => {
+      const value = process.env[name];
+      if (!value) throw new UsageError(`--known-secret-env ${name || "(missing name)"}: that environment variable is not set`);
+      return value;
+    });
+    for (const path of args.refs) gates.push(check.shareSafeGate(await verifySafe(path, { knownSecrets })));
+  }
+  const verdict = check.combineGates(gates);
+  if (args.out !== void 0) await check.writeGateEvidence(args.out, verdict);
+  const output = args.format === "json" ? JSON.stringify(verdict, null, 2) : args.format === "junit" ? check.renderVerdictJUnit(verdict).trimEnd() : args.format === "github" ? check.renderVerdictGithub(verdict) : check.renderVerdictText(verdict);
+  if (output) process.stdout.write(`${output}
 `);
-  if (args.explain) {
-    console.log(explainTraceContract2(loaded.contract));
-    return;
+  if (verdict.exitCode === check.CHECK_EXIT.couldNotDecide) {
+    const undecided = verdict.gates.filter((gate) => gate.status === "unknown").map((gate) => gate.gate);
+    writeError(`${undecided.join(", ")} could not decide; the verdict on stdout says why`, "unknown-verdict", args.format === "json");
   }
-  let spans;
+  process.exitCode = verdict.exitCode;
+}
+async function otlpConformanceGate(check, subject, path) {
+  let input;
   try {
-    spans = (await collectSpans(await checkInputArgs(args))).spans;
-    if (spans.length === 0) throw new Error("the trace holds no spans");
+    input = await readOtlpInput(path);
   } catch (error) {
-    process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}
-`);
-    process.exitCode = error instanceof AmbiguousTraceInputError ? CHECK_EXIT.ambiguous : CHECK_EXIT.unreadable;
-    return;
-  }
-  const report = await runCheck(loaded.contract, spans, { evidenceRoot: args.evidence ?? join2(".traces", "check") });
-  console.log(renderCheckText(report));
-  if (args.junit) await writeFile2(args.junit, renderJUnit(report), "utf8");
-  if (args.out) await writeFile2(args.out, `${JSON.stringify(report, null, 2)}
-`, "utf8");
-  if (args.annotations || process.env.GITHUB_ACTIONS === "true") {
-    const annotations = renderGithubAnnotations(report);
-    if (annotations) console.log(annotations);
+    throw new CliError(errorText(error), "unreadable");
   }
-  process.exitCode = report.exitCode;
+  const text = renderValidation(input.validation, {
+    subject,
+    files: input.files,
+    skipped: input.skipped,
+    issues: input.issues,
+    withheld: input.withheld,
+    unreadable: input.unreadable,
+    spans: input.spans
+  });
+  return check.conformanceGate(subject, input.validation, text);
 }
 async function cmdConvert(args) {
-  const { spans, workflow } = await collectSpans(args);
-  if (spans.length === 0) throw new Error("no spans found for the given selection");
-  warnIncompleteWorkflow(workflow);
-  const path = await writeOtlpFile(spans, args.otlpOut);
-  console.log(`wrote ${spans.length} spans \u2192 ${path}`);
+  const collected = await collectSpans(args);
+  if (collected.spans.length === 0) throw new Error("no spans found for the given selection");
+  warnIncompleteWorkflow(collected.workflow);
+  const { spans, dropped } = args.noContent ? metadataOnly(collected.spans) : { spans: collected.spans, dropped: [] };
+  if (args.out === void 0) {
+    for (const line of iterSerializedSpans(spans)) process.stdout.write(line);
+    return;
+  }
+  const out = await writeOtlpFile(spans, args.out);
+  console.log(args.format === "json" ? JSON.stringify({ out, spans: spans.length, droppedAttributes: dropped }) : `wrote ${spans.length} spans \u2192 ${out}${args.noContent ? ` (metadata only: ${dropped.length} attribute key(s) dropped)` : ""}`);
 }
 function workflowIssueText(issue) {
   if (issue.kind === "cycle") return `cycle: ${issue.sessionIds.join(" -> ")}`;
@@ -1005,442 +1724,340 @@ function workflowIssueText(issue) {
   }
   return `${issue.kind} ${issue.sessionId}, referenced as ${issue.relation} by ${issue.referencedBySessionId}`;
 }
+var WORKFLOW_ISSUES_NAMED = 3;
 function warnIncompleteWorkflow(workflow) {
   if (!workflow || workflow.complete) return;
+  const { issues } = workflow;
+  const more = issues.length - WORKFLOW_ISSUES_NAMED;
   process.stderr.write(
-    `warning: session workflow is incomplete (${workflow.issues.length} issue(s)): ${workflow.issues.map(workflowIssueText).join("; ")}
+    `warning: session workflow is incomplete (${issues.length} issue(s)): ${issues.slice(0, WORKFLOW_ISSUES_NAMED).map(workflowIssueText).join("; ")}${more > 0 ? `; and ${more} more` : ""}
 `
   );
 }
-async function collectSessionRows(args, bindExplicitSource = false, defaultLast = 20) {
-  const groups = args.session ? [await resolveSelectedSession(args).then(({ adapter, ref }) => ({ adapter, refs: [ref] }))] : await discover({ ...args, last: args.last || defaultLast });
-  return collectSessionSelection(groups, {
-    workflow: args.workflow,
-    maxWorkflowSessions: args.maxWorkflowSessions,
+async function collectSessionRows(args, defaultLast, onRow) {
+  const named = args.selection?.sessions ?? [];
+  const source = args.selection?.spans[0];
+  if (source && named.length === 0) {
+    throw new Error(`${args.command} reads harness sessions; ${source.ref} is a span source`);
+  }
+  const found = named.length > 0 ? { sessions: named, unread: [] } : await discover(args, defaultLast);
+  const unread = [...found.unread];
+  const selection = await collectSessionSelection(groupsInOrder(found.sessions), {
+    workflow: named.length > 0 || !args.since,
+    parents: false,
+    maxWorkflowSessions: MAX_CHILD_SESSIONS,
     taskScope: args.latestTurn ? "latest" : "all",
-    bindSources: bindExplicitSource && Boolean(args.session)
-  });
-}
-async function cmdEvidence(args) {
-  const selection = await collectSessionRows(args, true);
-  const rows = selection.rows.filter((row) => row.spans.length > 0);
-  if (rows.length === 0) throw new Error("no spans found for the given selection");
-  warnIncompleteWorkflow(selection.workflow);
-  const otlpPath = args.otlpOut ? await writeOtlpFile(rows.flatMap((row) => row.spans), args.otlpOut) : void 0;
-  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const records = await Promise.all(rows.map(
-    (row) => buildPolicyEvidenceRecord(row.ref, row.spans, {
-      generatedAt,
-      minLoopOccurrences: args.minLoop,
-      maxLoopExamples: 25,
-      otlpPath,
-      sourceSha256: row.sourceSha256
-    })
-  ));
-  if (args.out) {
-    const path = await writePolicyEvidenceFile(records, args.out);
-    console.log(`policy evidence \u2192 ${path}  (${records.length} session rows${otlpPath ? `, OTLP: ${otlpPath}` : ""})`);
-  } else {
-    process.stdout.write(serializePolicyEvidence(records));
-  }
-}
-async function cmdIndex(args) {
-  const selection = await collectSessionRows(args);
-  const rows = selection.rows.filter((row) => row.spans.length > 0);
-  if (rows.length === 0) throw new Error("no spans found for the given selection");
-  warnIncompleteWorkflow(selection.workflow);
-  const index = await buildSessionIndexFromRows(rows, {
-    minLoopOccurrences: args.minLoop,
-    selection: {
-      command: "index",
-      harness: args.harnessExplicit ? args.harness : void 0,
-      all: args.all || void 0,
-      last: args.last || void 0,
-      session: args.session,
-      cwd: args.cwd,
-      since: args.since,
-      latestTurn: args.latestTurn || void 0,
-      ...selection.workflow ? { workflow: selection.workflow } : {}
+    home: args.selection?.home,
+    ...onRow ? { onRow } : {},
+    onUnreadable: ({ ref, error, seed }) => {
+      if (seed && named.length > 0) throw new RefError(`${ref.sessionId} could not be read (${ref.path}): ${errorText(error)}`, "unreadable");
+      unread.push({ sessionId: ref.sessionId, traceId: null, source: ref.path, reason: errorText(error) });
     }
   });
-  if (args.out) {
-    const path = await writeSessionIndexFile(index, args.out);
-    console.log(`session index \u2192 ${path}  (${index.totals.sessions} session rows)`);
-  } else {
-    process.stdout.write(serializeSessionIndex(index));
-  }
+  return { ...selection, unread };
 }
 async function cmdBundle(args) {
-  if (!args.session) {
-    throw new Error("bundle needs --session <id|path>; run `traces list` to pick a session ID");
-  }
-  if (!args.out) throw new Error("bundle needs --out <dir> \u2014 a new or empty directory for the bundle");
-  const { adapter, ref } = await resolveSelectedSession(args);
-  const result = await assembleSessionBundle({
-    adapter,
-    ref,
-    outDir: args.out,
-    minLoopOccurrences: args.minLoop,
-    log: analystLog
-  });
+  const named = args.selection;
+  if (named?.sessions.length !== 1 || named.spans.length > 0) {
+    throw new UsageError(
+      named?.spans[0] ? `bundle keeps one harness session's evidence; ${named.spans[0].ref} is a span source` : "bundle needs one session: traces bundle <id|path> --out <dir>; run `traces list` to pick a session ID"
+    );
+  }
+  if (!args.out) throw new UsageError("bundle needs --out <dir>: a new or empty directory for the bundle");
+  const { adapter, ref } = named.sessions[0];
+  const result = await assembleSessionBundle({ adapter, ref, outDir: args.out });
   const { manifest } = result;
-  console.log(
-    `session bundle (${manifest.view} view) \u2192 ${result.directory}  (${manifest.files.length} file(s), ${manifest.ledgerSlices.length} ledger slice(s), ${manifest.absent.length} recorded absent)`
-  );
+  console.log(`session bundle \u2192 ${result.directory}  (${manifest.files.length} file(s), ${manifest.absent.length} recorded absent)`);
 }
 async function cmdMcp(args) {
-  if (args.help) {
-    process.stdout.write(`traces mcp \u2014 read-only MCP server over stdio for the selected traces
-
-Usage:
-  traces mcp --otlp <file|dir>                  any OTLP-JSONL
-  traces mcp --harness claude-code --last 5     recent harness sessions (any selection flag)
-
-Register with a client, for example:
-  claude mcp add traces -- traces mcp --otlp ./spans.otlp.jsonl
-
-Every tool is read-only and idempotent and says so in its MCP annotations.
-Spans (including causal links) and results are redacted, the server refuses
-to start if the redacted spans are still UNSAFE or UNKNOWN, each result
-carries an untrusted-text notice, and a result above 512 KiB is refused
-rather than truncated. readSpanSource is not served: windowed reads of
-original source bytes cannot be redacted.
-`);
-    return;
-  }
-  const selected = validateOtlpSelection(validateWorkflowSelection(applyCurrentSessionSelection(args)));
-  const collected = await collectSpans(selected);
-  if (collected.spans.length === 0) throw new Error("mcp: no spans found for the given selection");
+  const { createServedSpans, serveTraceMcp } = await import("./mcp-ZPGTJQYQ.js");
+  const served = createServedSpans();
+  const collected = await forEachSpanBatch(args, async (spans) => served.add(spans));
+  if (collected.spanCount === 0) throw new Error("mcp: no spans found for the given selection");
   warnIncompleteWorkflow(collected.workflow);
-  process.stderr.write(`traces mcp: serving ${collected.spans.length} span(s) over stdio
+  process.stderr.write(`traces mcp: serving ${collected.spanCount} span(s) over stdio
 `);
-  await serveTraceMcp({ spans: collected.spans });
+  await serveTraceMcp({ served: served.finish() });
 }
-async function cmdDiff(argv) {
-  const inputs = [];
-  const kinds = [];
-  let format = "text";
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--help" || arg === "-h") {
-      process.stdout.write(`traces diff \u2014 where two runs of one task first diverge
-
-Usage:
-  traces diff <a> <b> [--kind TOOL]... [--format text|json]
-
-Each side is an OTLP file or directory, any file convert reads, file#<trace id>,
-or file#branch=<id> for one arm (agent.branch.id or agent.branch.arm, and every
-span below it \u2014 refused if the label names more than one subtree). Steps pair
-by span id, then position with the same name and kind, then name and kind
-anywhere. Exit 0 when the runs agree on outcome, 1 when they diverge, 2 when a
-side cannot be read, 3 when the steps line up with no divergence but neither
-side carries a definitive OK/ERROR status or a TOOL step \u2014 there is no
-recorded outcome to call agreement on.
-`);
-      return;
-    }
-    if (arg === "--format") format = argv[++i] ?? "";
-    else if (arg === "--kind") kinds.push(argv[++i] ?? "");
-    else if (arg.startsWith("--")) throw new Error(`diff: unknown flag ${arg}`);
-    else inputs.push(arg);
-  }
-  if (inputs.length !== 2) {
-    throw new Error("diff needs two runs: traces diff <a> <b> (a file, a directory, file#<trace id> or file#branch=<id>)");
-  }
-  if (format !== "json" && format !== "text") throw new Error(`diff: --format must be json or text, got "${format}"`);
-  if (kinds.some((kind) => !kind)) throw new Error("diff: --kind needs a span kind, e.g. --kind TOOL");
-  const report = await diffRuns(inputs[0], inputs[1], { kinds });
-  process.stdout.write(format === "json" ? `${JSON.stringify(report, null, 2)}
+async function cmdDiff(args) {
+  const { diffRuns, renderRunDiff } = await import("./diff-ZZ6KYBPP.js");
+  const report = await diffRuns(args.refs[0], args.refs[1]);
+  if (!report.diff.firstDivergence && report.caveat) {
+    throw new CliError(`the runs' tool calls line up with no difference, but there is no outcome to call agreement on: ${report.caveat}`, "no-outcome");
+  }
+  process.stdout.write(args.format === "json" ? `${JSON.stringify(report, null, 2)}
 ` : renderRunDiff(report));
   if (report.diff.firstDivergence) process.exitCode = 1;
-  else if (report.caveat) process.exitCode = 3;
 }
-async function cmdBundleVerify(argv) {
-  let dir;
-  let format = "text";
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--format") format = argv[++i] ?? "";
-    else if (arg.startsWith("--")) throw new Error(`bundle verify: unknown flag ${arg}`);
-    else if (dir === void 0) dir = arg;
-    else throw new Error(`bundle verify: unexpected argument ${arg}`);
-  }
-  if (!dir) throw new Error("bundle verify needs the bundle directory: traces bundle verify <dir>");
-  if (format !== "json" && format !== "text") throw new Error(`bundle verify: --format must be json or text, got "${format}"`);
-  const result = await verifySessionBundle(dir);
-  if (format === "json") {
+async function cmdBundleVerify(args) {
+  const result = await verifySessionBundle(args.input);
+  if (args.format === "json") {
     process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
   } else {
     const lines = [
-      `${result.ok ? "VERIFIED" : "FAILED"}  ${result.view} bundle ${result.directory}`,
+      `${result.ok ? "VERIFIED" : "FAILED"}  bundle ${result.directory}`,
       `  ${result.matched}/${result.listed} listed file(s) match their recorded size and SHA-256`,
       ...result.issues.map((issue) => `  ${issue.kind.padEnd(11)} ${issue.path}: ${issue.detail}`)
     ];
-    if (result.source) lines.push(`  source bundle manifest: ${result.source.status} (${result.source.directory})`);
     process.stdout.write(`${lines.join("\n")}
 `);
   }
   if (!result.ok) process.exitCode = 1;
 }
-var PROJECTABLE_VIEWS = ["evidence-only"];
-async function cmdBundleView(args) {
-  if (!args.input) {
-    throw new Error("bundle-view needs the bundle directory to project; run `traces bundle --out <dir>` first");
-  }
-  if (!args.view) {
-    throw new Error(`bundle-view needs --view <${PROJECTABLE_VIEWS.join("|")}>`);
-  }
-  if (!PROJECTABLE_VIEWS.includes(args.view)) {
-    throw new Error(`unknown view "${args.view}"; projectable views: ${PROJECTABLE_VIEWS.join(", ")}`);
-  }
-  if (!args.out) throw new Error("bundle-view needs --out <dir> \u2014 a new or empty directory for the view");
-  const result = await projectSessionBundle({
-    bundleDir: args.input,
-    outDir: args.out,
-    view: args.view
-  });
-  const { manifest, leakCheck } = result;
-  console.log(
-    `${manifest.view} view \u2192 ${result.directory}  (${manifest.files.length} file(s) carried, ${manifest.excluded.length} excluded, ${leakCheck.matches} session-text match(es) against ${leakCheck.sourceSignatures} signature(s) from ${leakCheck.comparedSources.length} excluded source(s))`
-  );
+function hostOf(args) {
+  const root = args.selection?.home;
+  if (root !== void 0) return basename2(root) === "home" ? basename2(dirname2(root)) : basename2(root);
+  return hostname().split(".")[0].toLowerCase();
 }
-async function cmdFacts(args) {
-  const format = args.format ?? "json";
-  if (format !== "json" && format !== "text") {
-    throw new Error(`unknown facts format "${format}" (expected json or text)`);
-  }
-  const window = args.since !== void 0 || args.until !== void 0 ? {
-    ...args.since !== void 0 ? { since: new Date(parseSince(args.since)).toISOString() } : {},
-    ...args.until !== void 0 ? { until: new Date(parseTimeBound(args.until, "--until")).toISOString() } : {}
-  } : void 0;
-  const builder = createSessionFactsReportBuilder({ includeContent: !args.noContent, window });
-  let report;
-  const discoversWindow = window !== void 0 && !args.session && !args.otlp && !args.input && !args.sourceBundle && !args.workflow;
-  if (discoversWindow) {
-    const harnesses = /* @__PURE__ */ new Set();
-    for await (const scanned of scanSessions({
-      adapters: adaptersFor(args),
-      cwd: args.cwd,
-      sinceMs: window.since === void 0 ? void 0 : Date.parse(window.since),
-      last: args.last > 0 ? args.last : void 0,
-      taskScope: args.latestTurn ? "latest" : "all",
-      onError: (error, ref) => {
-        if (!ref) throw error;
-        builder.addUnread({
-          sessionId: ref.sessionId,
-          traceId: null,
-          source: ref.path,
-          reason: error instanceof Error ? error.message : String(error)
-        });
-      }
-    })) {
-      harnesses.add(scanned.adapter.harness);
-      builder.add(scanned.spans);
-    }
-    report = { ...builder.build(), harness: [...harnesses].join("+") || args.harness };
-  } else {
-    const collected = await collectSpans(args);
-    if (collected.spans.length === 0) throw new Error("no spans found for the given selection");
-    warnIncompleteWorkflow(collected.workflow);
-    builder.add(collected.spans);
-    report = { ...builder.build(), harness: collected.harness };
-  }
-  const unreadInWindow = report.selection?.unreadSessions ?? [];
-  if (unreadInWindow.length > 0) {
-    const named = unreadInWindow.slice(0, 3).map((entry) => entry.source ?? entry.sessionId ?? entry.traceId);
-    process.stderr.write(
-      `warning: ${unreadInWindow.length} session(s) could not be read; each is named with its reason in selection.unreadSessions (${named.join(", ")}${unreadInWindow.length > named.length ? ", \u2026" : ""})
-`
-    );
-  }
-  const unread = report.sessions.filter((facts) => facts.recordSpans === 0);
-  if (unread.length > 0) {
-    throw new Error(
-      `no records could be read from ${unread.length} selected session(s): ` + unread.map((facts) => `${facts.sessionId ?? facts.traceId} (${facts.unreadRecords.value ?? 0} unread record(s))`).join(", ") + ". The facts sheet would state zeros the spans cannot support."
-    );
-  }
-  const rendered = format === "json" ? `${JSON.stringify(report, null, 2)}
-` : renderSessionFacts(report);
-  if (args.out) {
-    await writeFile2(args.out, rendered, "utf8");
-    console.log(`session facts \u2192 ${args.out}  (${report.sessions.length} session(s), $0, no model call)`);
-    return;
-  }
-  process.stdout.write(rendered);
-}
-async function cmdInspect(args) {
-  if (!args.input) throw new Error("inspect needs an index file; run `traces index --out session-index.json` first");
-  const index = await readSessionIndexFile(args.input);
-  const report = inspectSessionIndex(index);
-  if (args.out) {
-    const path = await writeInspectionReportFile(report, args.out);
-    console.log(`inspection report \u2192 ${path}  (${report.totals.findings} finding(s), high ${report.totals.high})`);
-  } else {
-    process.stdout.write(renderInspectionReport(report));
-  }
-}
-async function cmdExport(args) {
-  if (!args.input) throw new Error("export needs an input file; run `traces export --help` for examples");
-  const format = traceEvidenceFormat(args.format);
-  const attributes = await loadExportAttributes(args);
-  const outPath = args.out ?? args.otlpOut;
-  if (outPath) {
-    const result2 = await writeTraceEvidenceExportFile(args.input, outPath, { format, attributes });
-    console.log(
-      `exported ${result2.spans.length} OpenInference span(s) from ${result2.format} \u2192 ${result2.path} (${result2.redactionCount} redaction${result2.redactionCount === 1 ? "" : "s"})`
-    );
-    return;
-  }
-  const result = await exportTraceEvidenceFile(args.input, { format, attributes });
-  for (const line of iterSerializedSpans(result.spans)) process.stdout.write(line);
-}
-async function cmdImportCodeTraceBench(args) {
-  if (!args.input) {
-    throw new Error(
-      "import-codetracebench needs the native CodeTraceBench rows JSON or JSONL file"
-    );
-  }
-  if (!args.trajectoryDir) {
-    throw new Error(
-      "import-codetracebench needs --trajectory-dir with <traj_id>/steps.json directories"
-    );
-  }
-  if (!args.out) {
-    throw new Error("import-codetracebench needs a new --out directory");
+async function cmdFacts(args) {
+  const format = args.format ?? "text";
+  const pattern = args.match === void 0 ? void 0 : new RegExp(args.match);
+  if (args.noContent && (pattern !== void 0 || format === "jsonl")) {
+    throw new UsageError(`${pattern ? "--match searches" : "--format jsonl rows carry"} turn text, which --no-content withholds; drop one of them`);
+  }
+  const window = factsWindow(args);
+  const sourceOf = /* @__PURE__ */ new Map();
+  let readingFrom = null;
+  const host = hostOf(args);
+  const matches = [];
+  const citings = /* @__PURE__ */ new Map();
+  const cite = !args.noContent && (format === "json" || pattern !== void 0);
+  const onSession = (reading2) => {
+    const source = readingFrom ?? sourceOf.get(reading2.facts.sessionId ?? "") ?? sourceOf.get(reading2.facts.traceId) ?? null;
+    if (cite && source !== null) {
+      citings.set(reading2.facts.sessionId ?? reading2.facts.traceId, { path: resolve2(source), callIds: callIdsOf(reading2.spans) });
+    }
+    if (pattern === void 0) return;
+    for (const match of sessionMatches(reading2, pattern, window)) matches.push({ ...match, source });
+  };
+  const named = (args.selection?.sessions.length ?? 0) + (args.selection?.spans.length ?? 0);
+  if (pattern !== void 0 && window !== void 0 && named === 0) return searchWindow(args, pattern, window, format);
+  if (format === "jsonl" && pattern === void 0) return writeTurnFacts(args, host, window);
+  const builder = createSessionFactsReportBuilder({
+    includeContent: !args.noContent,
+    window,
+    nameUnread: named === 0,
+    agentIdentity: sessionIdentityLookup(args.selection?.home ?? (process.env.HOME || homedir())),
+    onSession
+  });
+  let report;
+  if (window !== void 0 && named === 0) {
+    const found = await discover(args);
+    const unread2 = [...found.unread];
+    const harnesses = /* @__PURE__ */ new Set();
+    for (const { adapter, ref } of found.sessions) {
+      let spans;
+      try {
+        spans = await parseSession(adapter, ref, { taskScope: args.latestTurn ? "latest" : "all" });
+      } catch (error) {
+        unread2.push({ sessionId: ref.sessionId, traceId: null, source: ref.path, reason: errorText(error) });
+        continue;
+      }
+      harnesses.add(adapter.harness);
+      readingFrom = ref.path;
+      builder.add(spans);
+    }
+    readingFrom = null;
+    for (const entry of unread2) builder.addUnread(entry);
+    warnUnread(args, unread2);
+    report = { ...builder.build(), harness: [...harnesses].join("+") || (args.harnessExplicit ? args.harness : null) };
+  } else {
+    const collected = await collectSpans(args);
+    if (collected.spans.length === 0 && (collected.unread ?? []).length === 0) throw new Error("no spans found for the given selection");
+    warnIncompleteWorkflow(collected.workflow);
+    for (const source of collected.sources) sourceOf.set(source.sessionId, source.path);
+    const files = args.selection?.spans ?? [];
+    if (files.length === 1 && collected.sources.length === 0) readingFrom = files[0].path;
+    builder.add(collected.spans);
+    readingFrom = null;
+    for (const entry of collected.unread ?? []) builder.addUnread(entry);
+    report = { ...builder.build(), harness: collected.harness };
   }
-  if (!args.revision) {
-    throw new Error(
-      "import-codetracebench needs --revision with a full 40- or 64-character hexadecimal commit or digest"
+  const unread = report.sessions.filter((facts) => facts.recordSpans === 0);
+  if (unread.length > 0) {
+    throw new RefError(
+      `no records could be read from ${unread.length} selected session(s): ` + unread.map((facts) => `${facts.sessionId ?? facts.traceId} (${facts.unreadRecords.value ?? 0} unread record(s))`).join(", ") + ". The facts sheet would state zeros the spans cannot support.",
+      "unreadable"
     );
   }
-  const controller = new AbortController();
-  const interrupt = () => controller.abort(
-    new Error("import-codetracebench interrupted")
-  );
-  process.once("SIGINT", interrupt);
-  process.once("SIGTERM", interrupt);
-  try {
-    const result = await importCodeTraceBench({
-      rowsPath: args.input,
-      trajectoryDir: args.trajectoryDir,
-      outDir: args.out,
-      revision: args.revision,
-      concurrency: args.concurrency,
-      signal: controller.signal
+  if (pattern !== void 0) {
+    return writeMatches(args, format, {
+      generatedAt: report.generatedAt,
+      sessions: report.sessions.length,
+      selection: report.selection,
+      matches: (await citeFacts(report.sessions, matches, citings)).matches
     });
-    const traceCount = result.receipt.counts.traces;
-    const stepCount = result.receipt.counts.steps;
-    const spanCount = result.receipt.counts.spans;
-    console.log(
-      `imported ${traceCount} CodeTraceBench ${traceCount === 1 ? "trajectory" : "trajectories"} (${stepCount} ${stepCount === 1 ? "step" : "steps"}, ${spanCount} ${spanCount === 1 ? "span" : "spans"}) \u2192 ${result.directory}; receipt: ${result.receiptPath}`
-    );
-  } finally {
-    process.removeListener("SIGINT", interrupt);
-    process.removeListener("SIGTERM", interrupt);
   }
-}
-function traceEvidenceFormat(raw) {
-  const format = raw ?? "auto";
-  if (format !== "auto" && format !== "policy-evidence" && format !== "sandbox-events" && format !== "openinference" && format !== "intelligence-spans" && format !== "chat-trajectory") {
-    throw new Error("--format must be auto, policy-evidence, sandbox-events, openinference, intelligence-spans, or chat-trajectory");
+  report = await priceReport(report);
+  const rendered = format === "json" ? `${JSON.stringify({ ...report, sessions: (await citeFacts(report.sessions, [], citings)).sessions })}
+` : renderSessionFacts(report);
+  const summary = `session facts \u2192 ${args.out}  (${report.sessions.length} session(s), $0, no model call)`;
+  await writeOutput(args, rendered, summary);
+}
+async function writeTurnFacts(args, host, window) {
+  const unread = [];
+  const named = (args.selection?.sessions.length ?? 0) + (args.selection?.spans.length ?? 0);
+  async function* sources() {
+    if (window !== void 0 && named === 0) {
+      const found = await discover(args);
+      unread.push(...found.unread);
+      for (const { adapter, ref } of found.sessions) {
+        try {
+          yield { source: ref.path, spans: await readSessionSpans(adapter, ref, { taskScope: args.latestTurn ? "latest" : "all", includeSubagents: false }) };
+        } catch (error) {
+          unread.push({ sessionId: ref.sessionId, traceId: null, source: ref.path, reason: errorText(error) });
+        }
+      }
+      return;
+    }
+    const collected = await collectSpans(args);
+    warnIncompleteWorkflow(collected.workflow);
+    unread.push(...collected.unread ?? []);
+    const byTrace = /* @__PURE__ */ new Map();
+    for (const span of collected.spans) {
+      const held = byTrace.get(span.trace_id);
+      if (held) held.push(span);
+      else byTrace.set(span.trace_id, [span]);
+    }
+    const ids = indexSessionIdsByTrace(collected.spans).sessionByTrace;
+    for (const [trace, spans] of byTrace) {
+      const source = collected.sources.find((entry) => entry.sessionId === (ids.get(trace) ?? trace))?.path ?? (args.selection?.spans.length === 1 ? args.selection.spans[0].path : null);
+      yield { spans, source };
+    }
   }
-  return format;
+  const result = await turnFactsJsonl(sources(), host, window);
+  unread.push(...result.unread);
+  if (named > 0 && result.unread.length > 0) throw new RefError(`no records could be read: ${result.unread.map((entry) => entry.sessionId).join(", ")}`, "unreadable");
+  warnUnread(args, unread);
+  await writeOutput(args, result.text, `turns \u2192 ${args.out}  (${result.turns} typed turn(s) in ${result.sessions} session(s), $0, no model call)`);
+}
+function factsWindow(args) {
+  if (args.since === void 0 && args.until === void 0) return void 0;
+  return {
+    ...args.since !== void 0 ? { since: new Date(parseSince(args.since)).toISOString() } : {},
+    ...args.until !== void 0 ? { until: new Date(parseTimeBound(args.until, "--until")).toISOString() } : {}
+  };
 }
-function parseAttributeValue(raw) {
-  if (raw === "true") return true;
-  if (raw === "false") return false;
-  if (/^-?\d+(?:\.\d+)?$/.test(raw)) {
-    const number = Number(raw);
-    if (Number.isFinite(number)) return number;
+async function writeOutput(args, rendered, summary) {
+  if (args.out) {
+    await writeFile(args.out, rendered, "utf8");
+    console.log(summary);
+    return;
   }
-  return raw;
+  process.stdout.write(rendered);
 }
-async function loadExportAttributes(args) {
-  const attributes = {};
-  if (args.metadata) {
-    const parsed = JSON.parse(await readFile2(args.metadata, "utf8"));
-    if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      throw new Error("--metadata must point to a JSON object");
+async function writeMatches(args, format, found) {
+  const matches = [...found.matches].sort((left, right) => Date.parse(left.at) - Date.parse(right.at));
+  const document = {
+    schemaVersion: 1,
+    kind: "traces.session_matches",
+    generatedAt: found.generatedAt,
+    pattern: args.match,
+    sessions: found.sessions,
+    selection: found.selection,
+    matches
+  };
+  const rendered = format === "json" ? `${JSON.stringify(document, null, 2)}
+` : format === "jsonl" ? matches.map((match) => `${JSON.stringify(match)}
+`).join("") : renderMatches(args.match, found.sessions, matches);
+  await writeOutput(args, rendered, `matches \u2192 ${args.out}  (${matches.length} in ${found.sessions} session(s), $0, no model call)`);
+}
+async function searchWindow(args, pattern, window, format) {
+  const found = await discover(args);
+  const unread = [...found.unread];
+  const outsideWindow = [];
+  const matches = [];
+  const since = window.since === void 0 ? Number.NEGATIVE_INFINITY : Date.parse(window.since);
+  const until = window.until === void 0 ? Number.POSITIVE_INFINITY : Date.parse(window.until);
+  let sessions = 0;
+  const stats = await TurnIndex.with(async (index) => {
+    const refreshed = await index.refresh(found.sessions);
+    for (const { adapter, ref } of found.sessions) {
+      const held = index.session(adapter, ref);
+      if (!held || held.unread !== null) {
+        unread.push({ sessionId: ref.sessionId, traceId: null, source: ref.path, reason: held?.unread ?? "not indexed" });
+        continue;
+      }
+      const { session } = held;
+      if (Date.parse(session.lastAt ?? "") < since || Date.parse(session.firstAt ?? "") >= until) {
+        outsideWindow.push(session.sessionId ?? ref.sessionId);
+        continue;
+      }
+      sessions += 1;
+      for (const match of matchRows(session.sessionId, await index.rows(adapter, ref), pattern, window)) {
+        matches.push({ ...match, source: ref.path });
+      }
     }
-    Object.assign(attributes, parsed);
-  }
-  for (const attr of args.attrs) {
-    const eq = attr.indexOf("=");
-    if (eq <= 0) throw new Error(`--attr must be key=value, got ${attr}`);
-    attributes[attr.slice(0, eq)] = parseAttributeValue(attr.slice(eq + 1));
+    return refreshed;
+  });
+  warnUnread(args, unread);
+  await writeMatches(args, format, {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    sessions,
+    selection: {
+      since: window.since ?? null,
+      until: window.until ?? null,
+      sessionRule: "a session is searched when its records, first to last, overlap [since, until)",
+      turnRule: "only rows that started inside [since, until) match",
+      outsideWindow: outsideWindow.sort(),
+      unreadSessions: unread,
+      index: stats
+    },
+    matches
+  });
+}
+function renderMatches(pattern, sessions, matches) {
+  const lines = [`${matches.length} match(es) for /${pattern}/ in ${sessions} session(s), deterministic, $0`];
+  for (const match of matches) {
+    const outcome = match.kind !== "command" ? "" : `${(match.failed === true ? "failed" : match.failed === false ? "ok" : "?").padEnd(6)}  `;
+    lines.push(`${match.at}  ${(match.sessionId ?? "?").slice(0, 8)}  ${match.kind.padEnd(7)}  ${outcome}${match.text}`);
+    if (match.record) lines.push(`  ${match.record.file}:${match.record.line}${match.lastLine == null ? "" : `  last: ${match.lastLine.slice(0, 300)}`}`);
   }
-  return attributes;
+  return `${lines.join("\n")}
+`;
 }
 async function cmdAnalyze(args) {
-  if (args.supervisorRunDir) return cmdAnalyzeSupervisorRun(args.supervisorRunDir, args);
-  const result = await investigate(args, { loadDefaultConfig: false });
-  let report = result.report;
-  let verifySummary = "";
-  if (args.verifyFindings) {
-    const run = await verifyAnalyzeFindings(args, result);
-    report = `${report}
-${renderVerifiedFindingsSection(run)}`;
-    verifySummary = `, verified: ${run.counts.reproduced} reproduced / ${run.counts["fix-flipped"]} fix-flipped / ${run.counts.divergent} divergent / ${run.counts["not-replayable"]} not-replayable \u2192 ${run.out}`;
-  }
+  const runDir = args.selection?.spans.find((source) => source.kind === "run-dir");
+  if (runDir) {
+    if (args.refs.length > 1) throw new UsageError(`analyze reports one supervision tree at a time; ${runDir.ref} is a run directory`);
+    const { writeSupervisorReport } = await import("./supervisor-report-RMPLLBGZ.js");
+    return writeSupervisorReport(runDir.path, args.out);
+  }
+  const { createTraceInvestigation, writeAnalysisArtifacts } = await import("./improvement-OJQ6365E.js");
+  const { renderAnalysis, renderAnalysisReport } = await import("./report-JAMXRTCW.js");
+  const investigation = createTraceInvestigation({
+    harness: args.harnessExplicit ? args.harness : "none",
+    facts: { window: factsWindow(args), agentIdentity: sessionIdentityLookup(args.selection?.home ?? (process.env.HOME || homedir())) },
+    log: analystLog
+  });
+  const collected = await forEachSpanBatch(args, (spans, harness) => investigation.add(spans, { harness }));
+  if (collected.spanCount === 0) throw new Error("no spans found for the given selection");
+  warnIncompleteWorkflow(collected.workflow);
+  for (const entry of collected.unread ?? []) investigation.addUnread(entry);
+  const result = await investigation.finish(collected);
   if (args.out) {
-    await saveReport(args.out, report);
+    const artifacts = await writeAnalysisArtifacts(renderAnalysisReport(result), result.packet, args.out);
     console.log(
-      `report \u2192 ${args.out}  (${result.findings.length} findings, ${result.pipelines.stuckLoops.findings.length} loops, OTLP: ${result.otlpPath}${verifySummary})`
-    );
-  } else {
-    console.log(report);
-  }
-  assertRequestedAnalysesRan(args, result);
-}
-async function verifyAnalyzeFindings(args, result) {
-  if (args.replayCorpora.length === 0) {
-    throw new Error(
-      "analyze --verify-findings needs the executable trajectory source: pass --replay-corpus name=<labels.json>::<preparedDir> (repeatable). Harness sessions carry no docker_config, so findings cannot be replayed from the session store alone."
-    );
-  }
-  if (result.findings.length === 0) {
-    throw new Error("analyze --verify-findings: the analysis produced no findings to verify");
-  }
-  const out = args.verifyOut ?? (args.out ? `${args.out}.verify` : "traces-verify-findings");
-  return verifyFindingsInSandbox(result.findings, {
-    source: { kind: "corpus", corpora: args.replayCorpora.map(parseCorpusFlag) },
-    out,
-    sandbox: {
-      apiKey: process.env.SANDBOX_API_KEY ?? "",
-      baseUrl: process.env.SANDBOX_API_URL ?? DEFAULT_SANDBOX_BASE_URL
-    }
-  });
-}
-async function cmdAnalyzeSupervisorRun(runDir, args) {
-  const single = await isRuntimeSupervisorRunDir(runDir);
-  const runDirs = single ? [runDir] : await findSupervisorRunDirs(runDir);
-  if (runDirs.length === 0) {
-    throw new Error(
-      `no supervisor run found at ${runDir} \u2014 expected a Runtime run containing spawn-journal.jsonl, observer.jsonl, or failure.json, or a parent directory containing such runs`
+      `analysis \u2192 ${artifacts.directory}  (report.md, findings.json: ${result.packet.findings.length} finding(s), ${result.cannotAnswer.length} question(s) it cannot answer, $0)`
     );
+    return;
   }
-  const reports = await Promise.all(
-    runDirs.map((dir) => analyzeSupervisorRun(fileRunContextSupervisorRunReader(dir)))
-  );
-  const markdown = single ? renderSupervisorRunMarkdown(reports[0]) : renderSupervisorRollupMarkdown(rollupSupervisorRuns(reports), `Supervisor rollup \u2014 ${runDir}`);
-  if (args.out) {
-    await saveReport(args.out, markdown);
-    console.log(`supervisor report \u2192 ${args.out}  (${runDirs.length === 1 ? "1 run" : `${runDirs.length} runs`})`);
-  } else {
-    console.log(markdown);
+  if (args.format === "json") {
+    const { schemaVersion, kind, generatedAt, harness, facts, packet, measures, conformance, cannotAnswer } = result;
+    process.stdout.write(`${JSON.stringify({ schemaVersion, kind, generatedAt, harness, facts, packet, measures, conformance, cannotAnswer })}
+`);
+    return;
   }
+  process.stdout.write(renderAnalysis(result));
 }
-async function collectImportedSpans(args) {
-  if (!args.input) throw new Error("input file missing");
-  const attributes = await loadExportAttributes(args);
-  const result = await exportTraceEvidenceFile(args.input, {
-    format: traceEvidenceFormat(args.format),
-    attributes
-  });
-  const { sessionByTrace } = indexSessionIdsByTrace(result.spans);
+async function collectImportedSpans(path, format, selector) {
+  const { sessionReportSource } = await import("./report-JAMXRTCW.js");
+  const result = await exportTraceEvidenceFile(path, { format });
+  const spans = selector ? selectSpans(result.spans, selector, path) : result.spans;
+  const { sessionByTrace } = indexSessionIdsByTrace(spans);
   const sessions = /* @__PURE__ */ new Map();
-  for (const span of result.spans) {
+  for (const span of spans) {
     const sessionId = sessionByTrace.get(span.trace_id);
     if (!sessionId) continue;
     const grouped = sessions.get(sessionId) ?? [];
@@ -1448,367 +2065,252 @@ async function collectImportedSpans(args) {
     sessions.set(sessionId, grouped);
   }
   return {
-    spans: result.spans,
+    spans,
     harness: result.format,
-    cwds: [],
-    sources: [...sessions].map(([sessionId, spans]) => sessionReportSource({
+    sources: [...sessions].map(([sessionId, grouped]) => sessionReportSource({
       harness: result.format,
       sessionId,
-      path: args.input,
+      path,
       cwd: null,
       mtimeMs: 0
-    }, spans, sessionId))
+    }, grouped, sessionId))
   };
 }
-function analystLog(msg, fields) {
-  const rejection = findingRejectionDetail(msg, fields);
-  if (rejection !== void 0) {
-    process.stderr.write(rejection ? `${msg} \u2014 ${rejection}
-` : `${msg}
-`);
-    return;
-  }
-  const error = typeof fields?.error === "string" && fields.error ? fields.error : void 0;
-  const errorClass = typeof fields?.error_class === "string" && fields.error_class ? `${fields.error_class}: ` : "";
-  process.stderr.write(error ? `${msg} \u2014 ${errorClass}${error}
-` : `${msg}
-`);
-}
-function externalAnalyzersFromArgs(args) {
-  return args.analyzers.map(
-    (spec) => spec === "halo" ? haloAnalyzer({ defaultPrompt: args.analyzerPrompt, model: args.model }) : spec === "hodoscope" ? hodoscopeAnalyzer({ summarizeModel: args.model }) : spec === "prime" ? primeAnalyzer({ defaultPrompt: args.analyzerPrompt, ...args.model ? { model: args.model } : {} }) : commandAnalyzer({ name: spec, command: spec, args: (p, prompt) => prompt ? [p, prompt] : [p] })
-  );
-}
-async function cmdInvestigate(args) {
-  const result = await investigate(args);
-  if (args.out) {
-    await saveReport(args.out, result.report);
-    console.log(`investigation report \u2192 ${args.out}  (${result.findings.length} findings with actions, OTLP: ${result.otlpPath})`);
-  } else {
-    console.log(result.report);
+async function cmdAsk(args) {
+  const { analysisEngineFromEnv, bridgeVersion, missingAskRequirements, UnservableModelError } = await import("./analyst-model-call-JVUOYZ5V.js");
+  const { createTraceQuestionCorpus, isBridgeMismatchError, loadTraceQuestionsFile, normalizeTraceQuestions, runTraceQuestions, writeTraceQuestionsArtifacts } = await import("./ask-XLS3VANY.js");
+  let questions;
+  try {
+    questions = [
+      ...args.questionsFile ? await loadTraceQuestionsFile(args.questionsFile) : [],
+      ...args.questions.map((question) => ({ question }))
+    ];
+    if (questions.length === 0) throw new UsageError('ask needs --question "<text>" (repeatable) or --questions <questions.json>');
+    normalizeTraceQuestions(questions);
+  } catch (error) {
+    throw error instanceof CliError ? error : new UsageError(errorText(error));
   }
-  assertRequestedAnalysesRan(args, result);
-}
-function conformanceOptions(collected) {
-  return {
-    ...collected.conformance ? { conformance: collected.conformance } : {},
-    ...collected.conformanceSubject ? { conformanceSubject: collected.conformanceSubject } : {},
-    ...collected.conformanceFiles ? { conformanceFiles: collected.conformanceFiles } : {},
-    ...collected.conformanceSkipped ? { conformanceSkipped: collected.conformanceSkipped } : {},
-    ...collected.conformanceIssues ? { conformanceIssues: collected.conformanceIssues } : {},
-    ...collected.conformanceWithheld ? { conformanceWithheld: collected.conformanceWithheld } : {},
-    ...collected.conformanceUnreadable ? { conformanceUnreadable: collected.conformanceUnreadable } : {}
-  };
-}
-async function investigate(args, options = {}) {
-  const collected = await collectSpans(args);
-  const { spans, harness, cwds, sources, workflow } = collected;
-  if (spans.length === 0) throw new Error("no spans found for the given selection");
-  const config = args.config !== void 0 || options.loadDefaultConfig !== false ? await loadTracesConfig(args.config) : void 0;
-  const analystModel = analystModelFor(args);
-  const engine = args.llm ? llmAnalysisEngine(args, analystModel) : void 0;
-  return runTraceInvestigation(mergeTracesConfig({
-    sourceBundle: args.sourceBundle ? { path: args.sourceBundle } : void 0,
-    spans,
-    harness,
-    sources,
-    workflow,
-    cwds,
-    minLoopOccurrences: args.minLoop,
-    engine,
-    model: args.llm ? analystModel : args.model,
-    budgetUsd: args.budget,
-    otlpOutPath: args.otlpOut,
-    externalAnalyzers: externalAnalyzersFromArgs(args),
-    analyzerPrompt: args.analyzerPrompt,
-    log: analystLog,
-    ...conformanceOptions(collected)
-  }, config));
-}
-async function cmdImprove(args) {
-  const collected = await collectSpans(args);
-  const { spans, harness, cwds, sources, workflow } = collected;
-  if (spans.length === 0) throw new Error("no spans found for the given selection");
-  const config = await loadTracesConfig(args.config);
-  const analystModel = analystModelFor(args);
-  const engine = args.llm ? llmAnalysisEngine(args, analystModel) : void 0;
-  const result = await runTraceImprovement({
-    ...mergeTracesConfig({
-      sourceBundle: args.sourceBundle ? { path: args.sourceBundle } : void 0,
-      spans,
-      harness,
-      sources,
-      workflow,
-      cwds,
-      minLoopOccurrences: args.minLoop,
-      engine,
-      model: args.llm ? analystModel : args.model,
-      budgetUsd: args.budget,
-      otlpOutPath: args.otlpOut,
-      externalAnalyzers: externalAnalyzersFromArgs(args),
-      analyzerPrompt: args.analyzerPrompt,
+  const missing = missingAskRequirements();
+  if (missing.length > 0) throw new CliError(`ask needs ${missing.join("; and ")}. Nothing was spent`, "setup");
+  const budget = args.budget;
+  const controller = new AbortController();
+  let refused;
+  let engine;
+  try {
+    engine = analysisEngineFromEnv({
+      model: analystModelFor(args),
+      maxCostUsd: Math.min(budget, DEFAULT_QUESTION_MAX_COST_USD),
+      timeoutMs: DEFAULT_QUESTION_TIMEOUT_MS,
       log: analystLog,
-      ...conformanceOptions(collected)
-    }, config),
-    outDir: args.dir ?? args.out
-  });
-  const dir = result.artifacts?.directory;
-  if (!dir) throw new Error("improve did not produce an artifact directory");
-  console.log(
-    `improvement artifacts \u2192 ${dir}  (${result.findings.length} findings with actions and checks, OTLP: ${result.otlpPath})`
-  );
-  assertRequestedAnalysesRan(args, result);
-}
-async function cmdAsk(args) {
-  if (args.out) throw new Error("ask writes a directory of artifacts; pass --dir <dir> instead of --out");
-  if (args.llm) throw new Error("ask always uses the model-backed engine; drop --llm");
-  const questions = [
-    ...args.questionsFile ? await loadTraceQuestionsFile(args.questionsFile) : [],
-    ...args.questions.map((question) => ({ question }))
-  ];
-  if (questions.length === 0) {
-    throw new Error('ask needs --question "<text>" (repeatable) or --questions <questions.json>');
-  }
-  normalizeTraceQuestions(questions);
-  if (args.questionBudget !== void 0 && (!Number.isFinite(args.questionBudget) || args.questionBudget <= 0)) {
-    throw new Error("--question-budget must be a positive number of USD");
-  }
-  if (args.budget !== void 0 && (!Number.isFinite(args.budget) || args.budget <= 0)) {
-    throw new Error("--budget must be a positive number of USD");
-  }
-  const questionTimeoutMs = args.questionTimeout === void 0 ? void 0 : Math.round(args.questionTimeout * 1e3);
-  if (questionTimeoutMs !== void 0 && (!Number.isSafeInteger(questionTimeoutMs) || questionTimeoutMs < 1e3)) {
-    throw new Error("--question-timeout must be a number of seconds, at least 1");
-  }
-  const engine = analysisEngineFromEnv({
-    model: analystModelFor(args),
-    maxCostUsd: args.questionBudget ?? Math.min(args.budget ?? Infinity, DEFAULT_QUESTION_MAX_COST_USD),
-    ...questionTimeoutMs !== void 0 ? { timeoutMs: questionTimeoutMs } : {},
-    log: analystLog
-  });
-  const collected = await collectSpans(args);
-  if (collected.spans.length === 0) throw new Error("no spans found for the given selection");
+      // A refused key or model fails every question the same way: stop them all at the first.
+      onPermanentFailure: (failure) => {
+        refused ??= failure;
+        controller.abort(new Error(failure.message));
+      }
+    });
+  } catch (error) {
+    if (error instanceof UnservableModelError) throw new CliError(error.message, error.failure.code);
+    throw error;
+  }
+  const corpus = createTraceQuestionCorpus();
+  const collected = await forEachSpanBatch(args, async (spans) => corpus.add(spans));
+  if (collected.spanCount === 0) throw new CliError("no spans found for the given selection", "unreadable");
   warnIncompleteWorkflow(collected.workflow);
-  const directory = resolve(args.dir ?? await mkdtemp(join2(tmpdir(), "traces-ask-")));
-  await mkdir2(directory, { recursive: true });
-  const controller = new AbortController();
   const interrupt = () => controller.abort(new Error("ask interrupted"));
   process.once("SIGINT", interrupt);
   let result;
   try {
     result = await runTraceQuestions({
       questions,
-      spans: collected.spans,
+      corpus: corpus.finish(),
       engine,
       harness: collected.harness,
-      concurrency: args.concurrency,
-      ...args.budget !== void 0 ? { budgetUsd: args.budget } : {},
-      ...args.sourceBundle ? { sourceBundle: { path: args.sourceBundle } } : {},
-      otlpOutPath: args.otlpOut ?? join2(directory, "traces.otlp.jsonl"),
+      concurrency: DEFAULT_ASK_CONCURRENCY,
+      budgetUsd: budget,
       signal: controller.signal,
       log: analystLog
     });
+  } catch (error) {
+    throw error instanceof RangeError ? new UsageError(error.message) : error;
   } finally {
     process.removeListener("SIGINT", interrupt);
   }
-  const artifacts = await writeTraceQuestionsArtifacts(result, directory);
-  process.stdout.write(result.report);
+  const artifacts = args.out === void 0 ? void 0 : await writeTraceQuestionsArtifacts(result, args.out);
   for (const warning of result.warnings) process.stderr.write(`warning: ${warning}
 `);
-  process.stderr.write(
-    `ask artifacts \u2192 ${artifacts.directory}  (${result.totals.answered}/${result.totals.questions} answered, wall ${(result.totals.wallTimeMs / 1e3).toFixed(1)} s, answers: ${artifacts.result})
-`
+  if (refused) {
+    const record = artifacts ? `; ${artifacts.result} records each question` : "";
+    throw new CliError(`${refused.message}. ask stopped every question at the first refused call${record}`, refused.code);
+  }
+  const { totals } = result;
+  const cost = totals.cost.usd;
+  if (artifacts) {
+    process.stdout.write(args.format === "json" ? `${JSON.stringify({ out: artifacts.directory, answered: totals.answered, questions: totals.questions, costUsd: cost })}
+` : `answers \u2192 ${artifacts.directory}  (answers.json, report.md: ${totals.answered}/${totals.questions} answered, ${cost === null ? "cost uncaptured" : `$${cost > 0 && cost < 0.01 ? cost.toPrecision(2) : cost.toFixed(2)}`}, ${(totals.wallTimeMs / 1e3).toFixed(1)} s)
+`);
+  } else if (args.format === "json") {
+    const { report: _report, ...machine } = result;
+    process.stdout.write(`${JSON.stringify(machine)}
+`);
+  } else {
+    process.stdout.write(result.report);
+  }
+  if (result.ok) return;
+  const failed = result.questions.filter((answer) => answer.status === "failed");
+  const where = artifacts ? artifacts.result : args.format === "json" ? "the JSON on stdout" : "the report above";
+  const hint = failed.some((answer) => isBridgeMismatchError(answer.failure?.message ?? "")) ? ` The DSPy bridge protocol is version-locked: TRACES_PYTHON needs agent-eval-rpc[dspy]==${bridgeVersion()}, or unset it to let uv run that version.` : "";
+  throw new CliError(
+    `${failed.length} of ${result.questions.length} question(s) unanswered (${failed.map((answer) => `${answer.id}: ${answer.failure?.kind}`).join(", ")}); ${where} says why.${hint}`,
+    "partial"
   );
-  if (!result.ok) {
-    const failed = result.questions.filter((answer) => answer.status === "failed");
-    const lines = [
-      `${failed.length} of ${result.questions.length} question(s) failed; the answers file holds every result.`,
-      ...failed.map((answer) => `  ${answer.id}: ${answer.failure?.kind}: ${answer.failure?.message.slice(0, 300)}`)
-    ];
-    if (failed.some((answer) => isBridgeMismatchError(answer.failure?.message ?? ""))) {
-      lines.push(
-        `hint: the DSPy bridge protocol is version-locked \u2014 the TRACES_PYTHON interpreter needs agent-eval-rpc[dspy]==${requiredBridgeVersion()} (matching this package's @tangle-network/agent-eval).`
-      );
-    }
-    throw new Error(lines.join("\n"));
-  }
-}
-function summarizeFindingEvidence(finding) {
-  const first = finding.evidence[0];
-  if (!first) return "no evidence";
-  return `${first.label}: ${first.value}`;
-}
-function formatLiveFinding(finding) {
-  const ts = new Date(finding.observedAt).toISOString().slice(11, 19);
-  const where = `[${finding.session.harness}] ${finding.session.sessionId.slice(0, 8)}`;
-  const cwd = finding.session.cwd ? ` \xB7 ${finding.session.cwd}` : "";
-  return [
-    `${ts} ${finding.severity.toUpperCase()} ${where}: ${finding.title}${cwd}`,
-    `  evidence: ${summarizeFindingEvidence(finding)}`,
-    `  action: ${finding.action}`,
-    `  check: ${finding.check}`
-  ].join("\n");
 }
-function streamMode(raw) {
-  if (raw === void 0) return "visualizer";
-  if (raw === "visualizer" || raw === "findings" || raw === "agent") return raw;
-  throw new Error(`unknown stream mode "${raw}" (expected visualizer, findings, or agent)`);
-}
-function streamPreset(args) {
-  const mode = streamMode(args.mode);
-  return {
-    mode,
-    includeSpans: !args.noSpans && mode === "visualizer",
-    includeFindings: !args.noFindings,
-    includeBatches: true,
-    includeReports: mode === "agent"
-  };
+var LIVE_SEVERITY = { info: "INFO", low: "LOW", medium: "MED", high: "HIGH" };
+function liveFindingLine(finding, ref) {
+  const spans = [...new Set(finding.evidence.flatMap((item) => item.spanIds ?? []))];
+  const cite = spans.length === 0 ? "" : ` (span${spans.length === 1 ? "" : "s"} ${spans.slice(0, 2).join(", ")}${spans.length > 2 ? ", \u2026" : ""})`;
+  return `${finding.observedAt.slice(11, 19)} ${LIVE_SEVERITY[finding.severity]} ${ref} ${finding.session.harness} ${finding.ruleId}: ${finding.claim}${cite}`;
 }
-async function streamExplicitSession(args, extraAnalysts) {
-  if (!args.session) throw new Error("streamExplicitSession needs --session");
-  const adapter = resolveAdapter(args.harness);
-  if (!adapter) throw new Error(`unknown harness "${args.harness}"`);
-  const preset = streamPreset(args);
-  const st = await stat(args.session);
-  const ref = {
-    harness: adapter.harness,
-    sessionId: basename(args.session),
-    path: resolve(args.session),
-    cwd: args.cwd ?? null,
-    mtimeMs: st.mtimeMs
-  };
-  const spans = await parseSession(adapter, ref);
-  for (const event of traceStreamEventsFromSpans(spans, {
-    ref,
-    includeSpans: preset.includeSpans,
-    includeFindings: preset.includeFindings,
-    extraAnalysts
-  })) {
-    process.stdout.write(serializeTraceStreamEvent(event));
-  }
-}
-async function cmdStream(args) {
-  const config = await loadTracesConfig(args.config);
-  const preset = streamPreset(args);
-  const source = args.otlp ?? args.input;
-  if (source) {
-    const { spans, harness } = args.otlp ? await collectOtlpSpans(args.otlp) : await collectImportedSpans(args);
-    const ref = {
-      harness,
-      sessionId: basename(source),
-      path: resolve(source),
-      cwd: args.cwd ?? null,
-      mtimeMs: Date.now()
+async function* spanRuns(args, path) {
+  const { spans } = await collectSpans(args);
+  const { sessionByTrace } = indexSessionIdsByTrace(spans);
+  const byTrace = /* @__PURE__ */ new Map();
+  for (const span of spans) {
+    const group = byTrace.get(span.trace_id);
+    if (group) group.push(span);
+    else byTrace.set(span.trace_id, [span]);
+  }
+  for (const [traceId, group] of byTrace) {
+    const attribute = (key) => {
+      const value = group[0].attributes[key];
+      return typeof value === "string" && value.length > 0 ? value : null;
     };
-    for (const event of traceStreamEventsFromSpans(spans, {
-      ref,
-      includeSpans: preset.includeSpans,
-      includeFindings: preset.includeFindings,
-      extraAnalysts: config?.liveAnalysts
-    })) {
-      process.stdout.write(serializeTraceStreamEvent(event));
-    }
-    return;
-  }
-  if (args.session) {
-    await streamExplicitSession(args, config?.liveAnalysts);
-    return;
-  }
-  const all = args.all || !args.harnessExplicit && !args.cwd;
-  const controller = new AbortController();
-  process.once("SIGINT", () => controller.abort());
-  if (!args.replay) {
-    process.stderr.write(
-      `traces stream: ${preset.mode} JSONL feed for ${all ? "all harnesses" : args.harness}, last ${args.window}m, every ${args.interval}s. Ctrl-C to stop.
-`
-    );
+    yield { session: { harness: attribute("service.name") ?? "otlp", sessionId: sessionByTrace.get(traceId) ?? traceId, cwd: attribute("tangle.cwd"), path }, spans: group };
   }
-  await streamSessions({
-    all,
-    harnesses: all ? void 0 : [args.harness],
-    cwd: args.cwd,
-    last: args.last > 0 ? args.last : args.replay ? 1 : void 0,
-    windowMs: args.window * 6e4,
-    intervalMs: args.interval * 1e3,
-    once: args.replay,
-    includeSpans: preset.includeSpans,
-    includeFindings: preset.includeFindings,
-    includeBatches: preset.includeBatches,
-    includeReports: preset.includeReports,
-    extraAnalysts: config?.liveAnalysts,
-    signal: controller.signal,
-    onEvent: (event) => {
-      process.stdout.write(serializeTraceStreamEvent(event));
-    },
-    onError: (err, ref) => {
-      const where = ref ? ` [${ref.harness}] ${ref.sessionId}` : "";
-      process.stderr.write(`stream error${where}: ${err instanceof Error ? err.message : String(err)}
-`);
-    }
-  });
 }
 async function cmdWatch(args) {
-  const target = args.supervisorRunDir ?? args.input;
-  if (target !== void 0) return cmdWatchRunTarget(target, args);
-  const all = args.all || !args.harnessExplicit && !args.cwd;
+  const named = args.selection;
+  const source = named?.spans[0];
+  if (source && (named.spans.length > 1 || named.sessions.length > 0)) {
+    throw new UsageError("watch follows one run tree or span file at a time, or harness sessions: traces watch <run-dir|file> or traces watch <id\u2026>");
+  }
+  const jsonl = args.format === "jsonl";
+  if (source && !jsonl) return cmdWatchRunTarget(source.path, args);
+  const { streamSessions, watchSource } = await import("./live-Y64AJ6MA.js");
+  const since = args.since ?? "30m";
+  const windowMs = relativeBoundMs(since);
+  const sessions = named?.sessions.length ? named.sessions : void 0;
+  const scope = source ? source.ref : sessions ? `${sessions.length} named session${sessions.length === 1 ? "" : "s"}` : `every session active ${windowMs === void 0 ? "since" : "in the last"} ${since}`;
   const controller = new AbortController();
   process.once("SIGINT", () => controller.abort());
-  process.stderr.write(
-    `traces watch: observing ${all ? "all harnesses" : args.harness}, sessions active in the last ${args.window}m, every ${args.interval}s. Loop + semantic live findings; read-only; Ctrl-C to stop.
-`
-  );
-  await watchSessions({
-    all,
-    harnesses: all ? void 0 : [args.harness],
-    cwd: args.cwd,
-    windowMs: args.window * 6e4,
-    intervalMs: args.interval * 1e3,
-    minLoopOccurrences: args.minLoop,
-    signal: controller.signal,
-    onLoop: (l) => {
-      const ts = (/* @__PURE__ */ new Date()).toISOString().slice(11, 19);
-      process.stdout.write(
-        `${ts} LOOP [${l.harness}] ${l.sessionId.slice(0, 8)}: \`${l.toolName}\` repeated \xD7${l.occurrences} with identical args (${(l.windowMs / 1e3).toFixed(0)}s)${l.cwd ? ` \xB7 ${l.cwd}` : ""}
-`
-      );
-    },
-    onFinding: (finding) => {
-      process.stdout.write(`${formatLiveFinding(finding)}
+  if (!args.once) process.stderr.write(`traces watch: ${scope}, every 5 s; read-only. Ctrl-C to stop.
+`);
+  const ids = [];
+  const reported = /* @__PURE__ */ new Set();
+  let last;
+  let findings = 0;
+  const onEvent = (event) => {
+    if (jsonl) process.stdout.write(`${JSON.stringify(event)}
+`);
+    if (event.event === "session") ids.push(event.session.sessionId);
+    else if (event.event === "finding") {
+      findings += 1;
+      const id = event.finding.session.sessionId;
+      if (!jsonl) process.stdout.write(`${liveFindingLine(event.finding, shortestRefs(ids).get(id) ?? id)}
 `);
+    } else {
+      last = event;
+      if (args.once) return;
+      for (const unread2 of event.unreadSessions) {
+        const key = unread2.sessionId ?? unread2.source;
+        if (reported.has(key)) continue;
+        reported.add(key);
+        process.stderr.write(`unreadable ${key}: ${unread2.reason}
+`);
+      }
     }
-  });
+  };
+  const loop = { once: args.once, signal: controller.signal, onEvent };
+  if (source) await watchSource(() => spanRuns(args, source.path), loop);
+  else {
+    await streamSessions({
+      adapters: adaptersFor(args),
+      ...sessions ? { sessions } : {},
+      ...named?.home !== void 0 ? { home: named.home } : {},
+      cwd: args.cwd,
+      ...windowMs !== void 0 ? { windowMs } : { sinceMs: parseSince(since) },
+      ...loop
+    });
+  }
+  if (!args.once || !last) return;
+  const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+  if (!jsonl) process.stdout.write(`${scope}: ${count(last.sessions, "session")} read \xB7 ${count(findings, "finding")}
+`);
+  const unread = last.unreadSessions.length;
+  if (unread > 0) {
+    process.stderr.write(`${unread} unreadable: traces watch \u2026 --once --format jsonl | jq 'select(.event == "tick") | .unreadSessions'
+`);
+  }
 }
 async function cmdWatchRunTarget(dir, args) {
-  const target = await resolveRunWatchTarget(resolve(dir));
+  const { resolveRunWatchTarget, watchRunTarget } = await import("./run-watch-PLWTIRSV.js");
+  const target = await resolveRunWatchTarget(resolve2(dir));
   const controller = new AbortController();
   if (!args.once) {
     process.once("SIGINT", () => controller.abort());
     process.stderr.write(
-      `traces watch: tailing ${target.requested} every ${args.interval}s; read-only, ${target.runDir === null ? "span source only \u2014 Ctrl-C to stop" : "stops when result.json lands. Ctrl-C to stop"}.
+      `traces watch: tailing ${target.requested} every 2s; read-only, ${target.runDir === null ? "span source only \u2014 Ctrl-C to stop" : "stops when result.json lands. Ctrl-C to stop"}.
 `
     );
   }
-  const snapshot = await watchRunTarget(target, {
-    once: args.once,
-    // A tree view wants a tighter poll than the session observer's 5s default:
-    // a blocking question is worth surfacing the moment it lands.
-    intervalMs: args.intervalExplicit ? Math.max(250, args.interval * 1e3) : 2e3,
-    signal: controller.signal
-  });
+  const snapshot = await watchRunTarget(target, { once: args.once, intervalMs: 2e3, signal: controller.signal });
   const result = snapshot.journal?.result ?? null;
   if (result !== null && result.errorMessage !== null) process.exitCode = 1;
 }
+async function* refSessions(args) {
+  const named = args.selection;
+  if (!named) return;
+  for (const { adapter, ref } of named.sessions) yield { ref, spans: await parseSession(adapter, ref) };
+  for (const source of named.spans) {
+    const collected = source.kind === "spans" && source.reader !== "otlp" ? await collectImportedSpans(source.path, source.reader, source.selector) : await collectOtlpSpans(source.path, source.kind === "spans" ? source.selector : void 0);
+    const mtimeMs = (await stat(source.path)).mtimeMs;
+    const byTrace = /* @__PURE__ */ new Map();
+    for (const span of collected.spans) {
+      const grouped = byTrace.get(span.trace_id);
+      if (grouped) grouped.push(span);
+      else byTrace.set(span.trace_id, [span]);
+    }
+    for (const [traceId, spans] of byTrace) {
+      const { sessionByTrace } = indexSessionIdsByTrace(spans);
+      const ref = {
+        harness: collected.harness,
+        sessionId: sessionByTrace.get(traceId) ?? traceId,
+        path: source.path,
+        cwd: args.cwd ?? null,
+        mtimeMs
+      };
+      yield { ref, spans };
+    }
+  }
+}
 async function cmdUpload(args) {
-  const sinceMs = args.since ? parseSince(args.since) : Date.now() - 24 * 60 * 60 * 1e3;
-  const all = args.all || !args.harnessExplicit;
-  const plan = await planUpload({
-    all,
-    harnesses: args.harnessExplicit ? [args.harness] : void 0,
+  const { executeUpload, planUpload, planUploadFrom } = await import("./upload-R6NMKSGQ.js");
+  const named = args.selection;
+  const fromRefs = named !== void 0 && named.sessions.length + named.spans.length > 0;
+  if (!fromRefs && args.since === void 0) {
+    throw new UsageError(`upload over a store root needs a window: traces upload ${named?.home ?? "<store-root>"} --since 24h`);
+  }
+  const sinceMs = fromRefs ? void 0 : parseSince(args.since);
+  const all = !args.harnessExplicit;
+  const unread = [];
+  const plan = fromRefs ? await planUploadFrom(refSessions(args)) : await planUpload({
+    ...named?.home !== void 0 ? { adapters: adaptersFor(args), home: named.home } : { all, harnesses: args.harnessExplicit ? [args.harness] : void 0 },
     cwd: args.cwd,
-    sinceMs
+    sinceMs,
+    onError: (error, ref) => {
+      unread.push({ sessionId: ref?.sessionId ?? null, traceId: null, source: ref?.path ?? null, reason: errorText(error) });
+    }
   });
-  const redactorParts = args.redactorCmd?.split(/\s+/).filter(Boolean) ?? [];
-  const redactor = redactorParts[0] ? commandRedactor({ command: redactorParts[0], args: redactorParts.slice(1) }) : void 0;
+  warnUnread(args, unread);
   const candidates = plan.items;
   const byDetector = {};
   let totalRedactions = 0;
@@ -1817,7 +2319,9 @@ async function cmdUpload(args) {
     for (const [r, n] of Object.entries(i.redaction.byDetector)) byDetector[r] = (byDetector[r] ?? 0) + n;
   }
   const w = (s) => process.stderr.write(s);
-  w(`
+  w(sinceMs === void 0 ? `
+Refs: ${args.refs.join(" ")}
+` : `
 Window: since ${new Date(sinceMs).toISOString()}
 `);
   w(`Sessions found: ${plan.items.length}  \xB7  final privacy-mode dedup runs before upload
@@ -1825,7 +2329,7 @@ Window: since ${new Date(sinceMs).toISOString()}
   w(`PII/secrets redacted: ${totalRedactions}${Object.keys(byDetector).length ? ` (${Object.entries(byDetector).map(([r, n]) => `${r}:${n}`).join(", ")})` : ""}
 `);
   for (const i of candidates.slice(0, 25)) {
-    w(`  + [${i.ref.harness}] ${i.ref.sessionId.slice(0, 8)}  ${i.spans.length} spans  ${i.redaction.redactionCount} redacted  ${i.ref.cwd ?? ""}
+    w(`  + [${i.ref.harness}] ${i.ref.sessionId.slice(0, 8)}  ${i.spans.length} spans  ${i.redaction.redactionCount} redacted  ${args.noContent ? "" : i.ref.cwd ?? ""}
 `);
   }
   if (candidates.length > 25) w(`  \u2026 and ${candidates.length - 25} more
@@ -1835,9 +2339,12 @@ Window: since ${new Date(sinceMs).toISOString()}
     return;
   }
   if (args.dryRun) {
-    const res2 = await executeUpload(plan, { dryRun: true, otlpOut: args.otlpOut, stripContent: args.noContent, redactor });
+    const res2 = await executeUpload(plan, { dryRun: true, otlpOut: args.out, stripContent: args.noContent });
     reportRefused(res2.refused);
-    console.log(`dry run: ${candidates.length - res2.skippedSessions - res2.refused.length} session(s), ${totalRedactions} redaction(s). Redacted OTLP -> ${res2.otlpPath}`);
+    if (res2.verdict) console.log(`share verdict: ${res2.verdict.status} (the redacted${args.noContent ? ", metadata-only" : ""} payload; UNSAFE and UNKNOWN are refused)`);
+    console.log(
+      `dry run: ${candidates.length - res2.skippedSessions - res2.refused.length} session(s), ${totalRedactions} redaction(s).` + (res2.otlpPath ? ` Redacted OTLP -> ${res2.otlpPath}` : " Pass --out FILE to keep the redacted OTLP.")
+    );
     console.log("No upload performed. Set TANGLE_INGEST_URL / TANGLE_INGEST_API_KEY / TANGLE_TENANT_ID and drop --dry-run to send.");
     return;
   }
@@ -1849,7 +2356,7 @@ Window: since ${new Date(sinceMs).toISOString()}
     }
   }
   const res = await executeUpload(plan, { log: (m) => w(`${m}
-`), stripContent: args.noContent, redactor });
+`), stripContent: args.noContent });
   reportRefused(res.refused);
   console.log(
     `Uploaded ${res.uploadedSessions} session(s), ${res.acceptedSpans} spans accepted, ${res.redactionCount} redaction(s); ${res.skippedSessions} already-uploaded skipped; ${res.refused.length} refused.`
@@ -1872,525 +2379,54 @@ function reportRefused(refused) {
     process.exitCode = 1;
   }
 }
-async function cmdVerifySafe(argv) {
-  let target;
-  let format = "text";
-  let profile = "share";
-  const knownSecrets = [];
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--format") format = argv[++i] ?? "";
-    else if (arg === "--profile") profile = argv[++i] ?? "";
-    else if (arg === "--known-secret-env") {
-      const name = argv[++i] ?? "";
-      const value = process.env[name];
-      if (!value) throw new Error(`verify-safe: environment variable ${name || "(missing name)"} is not set`);
-      knownSecrets.push(value);
-    } else if (arg === "--help" || arg === "-h") {
-      usageVerifySafe();
-      return;
-    } else if (arg.startsWith("--")) throw new Error(`verify-safe: unknown flag ${arg}`);
-    else if (target === void 0) target = arg;
-    else throw new Error(`verify-safe: unexpected argument ${arg}`);
-  }
-  if (!target) throw new Error("verify-safe needs a file or directory: traces verify-safe <file|dir>");
-  if (format !== "json" && format !== "text") throw new Error(`verify-safe: --format must be json or text, got "${format}"`);
-  if (profile !== "default" && profile !== "share" && profile !== "strict") {
-    throw new Error(`verify-safe: --profile must be default, share or strict, got "${profile}"`);
-  }
-  const result = await verifySafe(target, { profile, knownSecrets });
-  process.stdout.write(format === "json" ? `${JSON.stringify(result, null, 2)}
-` : `${formatVerdict(result)}
-`);
-  process.exitCode = verdictExitCode(result);
-}
-async function cmdSkills(argv) {
-  let since;
-  let format = "text";
-  let unusedOnly = false;
-  let refresh = true;
-  let storePath = defaultSkillUsageStorePath();
-  let sweepThreshold = DEFAULT_SWEEP_THRESHOLD;
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--since") since = parseSince(argv[++i] ?? "");
-    else if (arg === "--format") format = argv[++i] ?? "";
-    else if (arg === "--unused") unusedOnly = true;
-    else if (arg === "--no-refresh") refresh = false;
-    else if (arg === "--store") storePath = argv[++i] ?? "";
-    else if (arg === "--sweep") sweepThreshold = Number(argv[++i]);
-    else if (arg === "--help" || arg === "-h") {
-      usageSkills();
-      return;
-    } else throw new Error(`skills: unknown argument ${arg}`);
-  }
-  if (format !== "json" && format !== "text") throw new Error(`skills: --format must be json or text, got "${format}"`);
-  if (!storePath) throw new Error("skills: --store needs a path");
-  if (!Number.isInteger(sweepThreshold) || sweepThreshold < 1) throw new Error("skills: --sweep must be a positive integer");
+var SKILLS_SINCE = "30d";
+async function cmdSkills(args) {
+  const since = parseSince(args.since ?? SKILLS_SINCE);
+  const storePath = defaultSkillUsageStorePath();
   const store = await SkillUsageStore.load(storePath);
-  const refreshed = refresh ? await store.refresh() : null;
-  if (refreshed) await store.save();
-  const report = buildSkillUsageReport(store.list(), await readInstalledSkills(), storePath, { since, sweepThreshold, refresh: refreshed });
-  if (unusedOnly) {
-    if (format === "json") process.stdout.write(`${JSON.stringify(report.unused, null, 2)}
+  const refreshed = await store.refresh();
+  await store.save();
+  const report = buildSkillUsageReport(store.list(), await readInstalledSkills(), storePath, { since, refresh: refreshed });
+  const json = args.format === "json";
+  if (args.unused) {
+    if (json) process.stdout.write(`${JSON.stringify(report.unused, null, 2)}
 `);
     else for (const skill of report.unused) process.stdout.write(`${skill.skill}	${skill.installedIn.join(",")}
 `);
     return;
   }
-  process.stdout.write(format === "json" ? `${JSON.stringify(report, null, 2)}
+  process.stdout.write(json ? `${JSON.stringify(report, null, 2)}
 ` : `${renderSkillUsage(report)}
 `);
 }
-function usageSkills() {
-  console.log(`traces skills [--since 30d|ISO] [--format text|json] [--unused] [--no-refresh] [--store PATH] [--sweep N]
-
-Count skill use across Claude Code, Codex, and Kimi Code sessions on this machine, with no
-model call. Each run reads only transcript bytes appended since the previous run and
-keeps the events in a store (default ${defaultSkillUsageStorePath()}), so counts
-survive a harness deleting old transcripts.
-
-  model   Claude Code Skill tool calls that loaded a skill
-  slash   Claude Code /name commands that expanded to a skill or prompt
-  read    Codex or Kimi commands that successfully read <skill>/SKILL.md
-
---since       count events at or after 30m / 2h / 7d or an ISO date (default: all stored)
---unused      print only installed skills with no use in the window
---no-refresh  answer from the store without reading transcripts
---store       store path
---sweep       one Codex or Kimi command reading N or more skills is a catalog sweep, not use;
-              its reads are excluded and counted separately (default ${DEFAULT_SWEEP_THRESHOLD})
-
-OpenCode, Pi, Gemini and other harnesses are not indexed.`);
-}
-function usageVerifySafe() {
-  console.log(`traces verify-safe <file|dir> [--profile default|share|strict] [--known-secret-env NAME]... [--format text|json]
-
-Check whether files are safe to share, without changing them. A directory is read
-recursively. .json files are parsed whole, .jsonl and .ndjson line by line, and
-any other file is scanned as text.
-
-  SAFE                 nothing found                                   exit 0
-  SAFE_WITH_WARNINGS   only warnings (raw content, identifiers, media) exit 0
-  UNSAFE               a credential, or personal data under share/strict exit 1
-  UNKNOWN              a file, line or byte range could not be read      exit 2
-
---profile           default | share (default) | strict; see agent-eval docs/redaction.md
---known-secret-env  name of an environment variable holding a secret to look for in
-                    any encoding (repeatable); the value is never printed
---format            text (default) | json
-
-Findings name the file, line and JSON Pointer, never the matched value.`);
-}
-function usageExport() {
-  console.log(`traces export: convert trace evidence files to OpenInference JSONL
-
-Usage:
-  traces export <input.jsonl|input.json> --out <spans.jsonl> [--format auto]
-  traces export <input.json> --attr task.id=abc --attr arm=baseline --out spans.jsonl
-  traces export <input.json> --metadata run-metadata.json --out spans.jsonl
-  traces export <input.jsonl|input.json> > spans.jsonl
-
-Input formats:
-  policy-evidence  Compact JSONL rows from \`traces evidence --out policy-evidence.jsonl\`
-  sandbox-events   JSON arrays with start/raw/result/done/error events
-  openinference    Existing OpenInference JSONL; rewrites through traces redaction
-  intelligence-spans  JSONL rows exported from Tangle Intelligence trace spans
-  chat-trajectory  A message array or objects with a messages array
-  auto             Detect the format from the file contents (default)
-
-Examples:
-  traces evidence --all --since 24h --out policy-evidence.jsonl
-  traces export policy-evidence.jsonl --out spans.openinference.jsonl
-  traces export sandbox-events.json --format sandbox-events --out spans.openinference.jsonl
-  traces export intelligence-spans.jsonl --out spans.openinference.jsonl
-  traces export sandbox-events.json --attr task.id=aec-001 --attr outcome.score=1 --out spans.openinference.jsonl
-  halo spans.openinference.jsonl --prompt "Analyze this trace slice" --max-turns 1
-
-Safety:
-  export runs the same local redaction (agent-eval's redaction core) used by upload before writing spans.
-  --metadata must be a JSON object; --attr key=value is repeatable and overrides matching metadata keys.`);
-}
-function usageImportCodeTraceBench() {
-  console.log(`traces import-codetracebench: write one label-free OTLP file per trajectory
-
-Usage:
-  traces import-codetracebench <rows.jsonl|rows.json> \\
-    --trajectory-dir <normalized-dir> --out <new-trace-dir> \\
-    --revision <40-or-64-character-hex> [--concurrency 4]
-
-Input layout:
-  <normalized-dir>/<traj_id>/steps.json
-  <normalized-dir>/<traj_id>/task.md    optional
-
-The command validates every native step, rejects annotation leakage, writes
-<traj_id>.otlp.jsonl files, and records input and output SHA-256 hashes in
-codetracebench-import.json. The output directory must not already exist.`);
-}
-function usageValidate() {
-  console.log(`traces validate: report what a trace can and cannot answer
-
-Usage:
-  traces validate <file.jsonl|dir> [--out conformance.md]
-
-Reads OTLP-JSONL and prints the conformance report from
-@tangle-network/agent-trace-contract:
-
-  - findings by severity, each naming the CONSEQUENCE of the defect and the
-    capabilities it blocks
-  - the capability table: token-accounting, cost-attribution, tool-usage,
-    loop-convergence, tree-comparison, steering-chain, latency-analysis \u2014
-    available or not, with the trace's own reason
-  - rows that could not be read at all, with the line and the reason
-
-A directory reads the OTLP files under it, recursively \u2014 only the otlp/
-subdirectory when the producer made one. A run directory's raw event, stream and
-SDK logs are also *.jsonl; they are listed with what they actually hold, not read
-as several hundred broken spans. Identical re-declarations of a span across
-per-shot files are counted as repeats, not defects; only a repeat with DIFFERENT
-content is an error.
-
-Exit code:
-  0  no error findings, and at least one capability available (warnings mean
-     thinner analysis, not wrong analysis)
-  1  an error finding, or nothing analysable at all \u2014 an empty file, or one
-     whose every line was unreadable, answers no question and is not a pass
-
-Nothing is fixed up: a span with an unreadable timestamp is reported, never
-repaired, because a synthesized value puts invented work into a total.
-
-Examples:
-  traces validate spans.otlp.jsonl
-  traces validate results/sessions --out conformance.md
-  traces validate spans.otlp.jsonl && traces analyze --otlp spans.otlp.jsonl`);
+function prepare(args) {
+  return validateLatestTurn(applyCurrentSessionSelection(args));
 }
-function usage() {
-  console.log(`traces: analyze agent traces \u2014 yours, or any system's
-
-Two ways in:
-  --otlp <file|dir>   Spans a system already emitted in the
-                      @tangle-network/agent-trace-contract shape. No adapter, no
-                      translation. This is how you integrate a NEW system.
-  --harness <id>      Run an adapter over a coding agent's proprietary session
-                      store (Claude Code, Codex, OpenCode, \u2026) \u2014 the legacy edge,
-                      for formats we do not control.
-
-Commands:
-  validate  Report what a trace can and cannot answer (exit 1 on error findings)
-  check     Gate a run on a trace contract: check <trace> --contract <file.json>
-            [--junit out.xml] [--out report.json] [--evidence dir] [--annotations].
-            check --contract <file.json> --explain prints what the contract checks.
-            <trace> is claude -p stream-json output, OTLP spans (file or dir),
-            a Claude Code or Codex session file, or trace evidence; --format
-            names it when the sniff cannot.
-            Exit 0 pass, 1 fail, 2 bad contract or a rule could not run,
-            3 unreadable trace, 4 ambiguous trace reference
-  list      List discovered sessions
-  analyze   Run analyst suite + loop/waste pipelines over OTLP (--otlp), sessions,
-            or an input file; names every analysis the spans could not support
-            (--supervisor-run-dir <dir> reports a supervision tree instead)
-  investigate Run typed investigation flow, including BYO config + evidence-backed actions
-  improve   Write findings, evidence, report, and canonical trace artifacts
-  ask       Answer free-form questions over the selected sessions with the
-            model-backed engine: questions run concurrently under one budget,
-            every trace:// citation is checked, and answers.json + report.md
-            are written to --dir (exit 1 when any question fails)
-  facts     Print the deterministic session-facts sheet for the selected
-            sessions: tool calls excluding synthesized spans, subagent spawns
-            with task names, human turns in order, the final message per task,
-            changed paths, first/last record times, the harness token total, and
-            the first failure by agent-eval's fixed precedence (or none), the
-            session's recorded working directory, and for each human turn the
-            agent message it answered.
-            No model call, no budget, $0. Every fact names the span ids it came
-            from; a fact the spans cannot support is null with its reason.
-            --since/--until select every session with a record in the window and
-            count only that window's turns; a session that cannot be read is named
-            in selection.unreadSessions. Without a window: exit 1 when a selected
-            session cannot be read. --format json (default) or text
-  skills    Count skill use across Claude Code, Codex, and Kimi Code sessions on this
-            machine, and list installed skills with no use in the window.
-            Incremental: a run reads only transcript bytes appended since the
-            last run. No model call. traces skills --help
-  convert   Emit OTLP-JSONL only, to --otlp-out (HALO: use analyze --analyzer halo)
-  index     Emit a reusable session index JSON for later investigation
-  bundle    Assemble one session's durable evidence directory: transcript +
-            subagents, derived index/report/evidence/OTLP, the repo's .evolve
-            ledger sliced to the session window, git log, and a sha256 manifest
-            (needs --session <id|path> and --out <new-dir>). This is the FULL
-            view: it holds the session's own words, for a reader who cites them
-  mcp       Serve the selected traces to an MCP client over stdio: 7 read-only,
-            idempotent trace tools; spans and results redacted, results capped
-            and marked untrusted (traces mcp --help)
-  diff <a> <b>
-            Pair two runs' steps (by span id, then position with the same name
-            and kind, then name and kind anywhere) and mark the first divergence:
-            changed, replaced, only-in-a, only-in-b or reordered. Each side is an
-            OTLP file or directory, any file convert reads, file#<trace id>, or
-            file#branch=<id> for one arm (agent.branch.id or agent.branch.arm).
-            --kind TOOL (repeatable) keeps only steps of that span kind.
-            Exit 0 agree, 1 diverge, 2 unreadable, 3 no recorded outcome to
-            call agreement on (--format text|json)
-  bundle verify <bundle-dir>
-            Check a bundle against its manifest: every listed file present with
-            its recorded size and SHA-256, no unlisted or non-regular file beside
-            them, and for a view, the source manifest it was projected from.
-            Exit 1 on any difference (--format text|json)
-  bundle-view <bundle-dir>
-            Project an assembled bundle into a narrower view for a consumer that
-            must NOT read the session's own words. --view evidence-only carries
-            the counted artifacts and structured ledger rows, excludes the
-            transcript, the report, the spans and every prose file by name, and
-            refuses to write a view whose text repeats an excluded source
-  inspect   Read a session index and print ranked improvement findings
-  export    Convert evidence/events files to OpenInference JSONL for HALO
-  import-codetracebench
-            Convert CodeTracer-normalized CodeTraceBench trajectories in bulk
-  replay-verify
-            Replay a trajectory prefix in a sandbox, execute step k both recorded
-            and corrected, and emit an executed-proof verdict (--help for flags)
-  replay-verify-batch
-            Measure replayability + fix-flip rates across gold-labeled corpora:
-            arm A per replayable case, LLM-generated arm-B fixes (--help for flags)
-  verify-findings
-            Execute recorded analyst findings as sandbox replay proofs: each
-            finding \u2192 reproduced | fix-flipped | divergent | not-replayable,
-            with a receipt directory per finding (--help for flags)
-  evidence  Emit compact session-evidence JSONL for downstream policy miners
-  stream    Emit JSONL trace stream events for live visualizers or replay
-  watch     Online observer: tail active sessions, notify on loops + semantic findings
-            (watch <target> tails ONE run tree instead: a run directory or a span file)
-  upload    Redact + upload sessions in a time window to the Tangle Intelligence Platform;
-            a session whose final events are UNSAFE or UNKNOWN is refused (exit 1)
-  verify-safe <file|dir>
-            Say whether files are safe to share: SAFE, SAFE_WITH_WARNINGS, UNSAFE
-            (exit 1) or UNKNOWN (exit 2). Read-only (--help for flags)
-
-Options:
-  --harness <id>   Harness or alias (default: claude-code). Known: ${knownHarnesses().join(", ")}
-  --all            Sweep every known harness
-  --last <n>       Most-recent N sessions
-  --current        Analyze the active Codex session named by CODEX_THREAD_ID
-  --latest-turn    Limit a resumed Codex or Claude Code session to its latest task turn
-  --session <id|path> Analyze one listed session ID or one explicit harness session file
-  --workflow       Expand selected sessions through stable parent/child session IDs
-  --max-workflow-sessions <n>
-                   Stop workflow expansion before parsing more than N files (default 100)
-  --cwd <dir>      Filter sessions by working directory
-  --supervisor-run-dir <dir>
-                   analyze: report a SUPERVISION TREE instead of harness sessions \u2014
-                   steers, spawn waves, concurrency, idle wall, cost by role,
-                   accepted vs rejected. Rolls up when the dir holds many runs.
-                   analyze reads Runtime journals and recorded startup failures.
-                   watch reads a live Runtime journal and OTLP span files.
-  --since <t>      30m / 2h / 7d (before now) or an ISO date. Selection commands read
-                   sessions modified at or after it; upload: its window (default 24h).
-                   facts: opens a time window and selects EVERY session with a record
-                   in it, not only the newest; its turn facts keep only turns inside it
-  --until <t>      facts: closes the window (exclusive), same forms as --since
-  --out <path>     Write report to a file
-  --dir <path>     improve/ask: write artifacts to this directory
-  --otlp <file|dir>  READ OTLP-JSONL emitted by any system, skipping the adapters.
-                   A directory reads the OTLP files under it \u2014 only the otlp/
-                   subdirectory when the producer made one \u2014 and names the JSONL
-                   that is not OTLP instead of reading it as broken spans.
-                   Supported by: validate, analyze, facts, investigate, improve, ask,
-                   stream, mcp. Writing commands take --otlp-out.
-  --source-bundle <dir>  Analyze a retained full bundle; explicitly grant source-field reads.
-                   Available for analyze, investigate, improve, and ask.
-  --otlp-out <path>  WRITE the OTLP-JSONL artifact here (also evidence
-                   provenance / dry-run upload preview)
-  --format <kind>  analyze/export: auto | policy-evidence | sandbox-events | openinference | intelligence-spans | chat-trajectory
-                   facts: json (default) | text
-  --metadata <json> analyze/export file: attach JSON object fields as span attributes
-  --attr <k=v>     analyze/export file: attach one span attribute (repeatable)
-  --mode <kind>    stream: visualizer | findings | agent (default visualizer)
-  --view <name>    bundle-view: which projection to write. evidence-only is the
-                   writer's view; the full view is the bundle itself, so there is
-                   nothing to project into it
-  --replay, --once stream: scan once and exit (default for positional input / --session)
-  --once           watch <target>: print ONE snapshot and exit, for scripts and agents
-  --no-spans       stream: omit per-span pulse events
-  --no-findings    stream: omit semantic live-finding events
-  --llm            Enable agentic RLM analysts. Runs on the Tangle router by
-                   default (TANGLE_API_KEY); OPENAI_API_KEY alone targets OpenAI,
-                   OPENAI_BASE_URL overrides the endpoint. Needs Python with
-                   agent-eval-rpc[dspy] (TRACES_PYTHON selects the interpreter),
-                   version-matched to this package's @tangle-network/agent-eval.
-                   Exits 1 when every agentic analyst fails, with each reason.
-                   ask uses the same engine and credentials without --llm.
-  --model <id>     Model for --llm, HALO, and Hodoscope (default for --llm: ${DEFAULT_ANALYST_MODEL})
-  --config <path>  investigate/improve/stream: JS config with analysts, liveAnalysts, or external analyzers
-  --budget <usd>   USD cap for agentic analysts; ask: one ceiling shared by every question
-  --question <text> ask: a question (repeatable, at most ${MAX_TRACE_QUESTION_CHARS} characters)
-  --questions <file> ask: JSON array of questions, strings or
-                   { id?, question, instructions?, answerSchema? }
-  --question-budget <usd>
-                   ask: provider ceiling for one question (default: the smaller
-                   of --budget and $${DEFAULT_QUESTION_MAX_COST_USD})
-  --question-timeout <seconds>
-                   ask: wall-clock deadline for one question's investigation
-                   (default: ${DEFAULT_QUESTION_TIMEOUT_MS / 1e3})
-  --concurrency <n> ask: questions running at once (default 4);
-                   import-codetracebench: trajectories imported at once
-  --analyzer <id>  analyze: also run halo, hodoscope, prime, or an installed command (repeatable);
-                   exits 1 after writing the report when any requested analyzer fails
-                   prime posts the full span projection to an OpenAI-compatible bridge
-                   (TRACES_PRIME_BRIDGE_URL, default http://localhost:4181;
-                   TRACES_PRIME_MODEL, default prime/zai/glm-5.2; TRACES_PRIME_TIMEOUT_MS)
-  --analyzer-prompt <p>  analyze: prompt passed to external analyzers (default: diagnose)
-  --verify-findings analyze: execute the findings as sandbox replay proofs and mark
-                   each VERIFIED (receipt path) or UNVERIFIABLE (reason). Needs
-                   --replay-corpus + a running sandbox (SANDBOX_API_KEY/_URL)
-  --replay-corpus name=<labels.json>::<preparedDir>
-                   trajectory source for --verify-findings (repeatable)
-  --verify-out <dir> receipt root for --verify-findings (default: <--out>.verify)
-  --interval <s>   watch/stream: poll interval seconds (sessions 5, run tree 2)
-  --window <m>     watch/stream: only sessions active in the last N minutes (default 30)
-  --min-loop <n>   Min identical repeated calls to flag a loop (default 3)
-  --dry-run        upload: redact + dedup + preview, write OTLP, but do NOT send
-  --no-content     facts: omit conversation, commands, paths and assignments;
-                   upload: strip prompt/response text; send metadata only
-  --redactor <cmd> upload: external PII scrubber (JSON array stdin\u2192stdout) after the redaction core
-  --yes, -y        upload: skip the confirmation prompt
-  --version, -v    Print the installed traces version
-  --help, -h       Show help (use \`traces validate --help\`, \`traces export --help\`,
-                   or \`traces import-codetracebench --help\`)
-
-Watch a run tree (any depth; driver spend and child spend stay separate,
-and a cost the harness never priced reads "unknown", never $0):
-  traces watch runs/my-run                 live tree: status, budget, driver vs child spend
-  traces watch runs/my-run --once          one snapshot, then exit
-  traces watch traces.otlp.jsonl           OTLP spans only \u2014 works for ANY emitter
-  traces analyze --supervisor-run-dir runs/my-run   the full tree report
-
-Upload env: TANGLE_INGEST_URL (or TANGLE_ORCHESTRATOR_URL), TANGLE_INGEST_API_KEY (or TANGLE_API_KEY), TANGLE_TENANT_ID`);
+function reading(handler) {
+  return async (args) => handler(await withSelection(prepare(args)));
 }
-async function main() {
-  const rawArgs = process.argv.slice(2);
-  if (rawArgs[0] === "--version" || rawArgs[0] === "-v" || rawArgs[0] === "version") {
-    console.log(`traces ${tracesVersion()}`);
-    return;
-  }
-  if (rawArgs[0] === "replay-verify") {
-    await cmdReplayVerify(rawArgs.slice(1));
-    return;
-  }
-  if (rawArgs[0] === "replay-verify-batch") {
-    await cmdReplayVerifyBatch(rawArgs.slice(1));
-    return;
-  }
-  if (rawArgs[0] === "verify-findings") {
-    await cmdVerifyFindings(rawArgs.slice(1));
-    return;
-  }
-  if (rawArgs[0] === "mcp") {
-    await cmdMcp(parseArgs(rawArgs));
-    return;
-  }
-  if (rawArgs[0] === "diff") {
-    try {
-      await cmdDiff(rawArgs.slice(1));
-    } catch (err) {
-      process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
-`);
-      process.exitCode = 2;
-    }
-    return;
-  }
-  if (rawArgs[0] === "bundle" && rawArgs[1] === "verify") {
-    await cmdBundleVerify(rawArgs.slice(2));
-    return;
-  }
-  if (rawArgs[0] === "verify-safe") {
-    await cmdVerifySafe(rawArgs.slice(1));
-    return;
-  }
-  if (rawArgs[0] === "skills") {
-    await cmdSkills(rawArgs.slice(1));
-    return;
-  }
-  const parsedArgs = parseArgs(rawArgs);
-  if (parsedArgs.help) {
-    if (parsedArgs.command === "import-codetracebench" || parsedArgs.command === "help" && parsedArgs.input === "import-codetracebench") usageImportCodeTraceBench();
-    else if (parsedArgs.command === "export" || parsedArgs.command === "help" && parsedArgs.input === "export") usageExport();
-    else if (parsedArgs.command === "validate" || parsedArgs.command === "help" && parsedArgs.input === "validate") usageValidate();
-    else usage();
-    return;
-  }
-  const args = validateOtlpSelection(
-    validateViewSelection(validateWorkflowSelection(validateUntilSelection(applyCurrentSessionSelection(parsedArgs))))
-  );
-  switch (args.command) {
-    case "help":
-      if (args.input === "import-codetracebench") usageImportCodeTraceBench();
-      else if (args.input === "export") usageExport();
-      else if (args.input === "validate") usageValidate();
-      else usage();
-      break;
-    case "list":
-      await cmdList(args);
-      break;
-    case "analyze":
-      await cmdAnalyze(args);
-      break;
-    case "validate":
-      await cmdValidate(args);
-      break;
-    case "check":
-      await cmdCheck(args);
-      break;
-    case "investigate":
-      await cmdInvestigate(args);
-      break;
-    case "improve":
-      await cmdImprove(args);
-      break;
-    case "ask":
-      await cmdAsk(args);
-      break;
-    case "facts":
-      await cmdFacts(args);
-      break;
-    case "convert":
-      await cmdConvert(args);
-      break;
-    case "index":
-      await cmdIndex(args);
-      break;
-    case "bundle":
-      await cmdBundle(args);
-      break;
-    case "bundle-view":
-      await cmdBundleView(args);
-      break;
-    case "inspect":
-      await cmdInspect(args);
-      break;
-    case "export":
-      await cmdExport(args);
-      break;
-    case "import-codetracebench":
-      await cmdImportCodeTraceBench(args);
-      break;
-    case "evidence":
-      await cmdEvidence(args);
-      break;
-    case "stream":
-      await cmdStream(args);
-      break;
-    case "watch":
-      await cmdWatch(args);
-      break;
-    case "upload":
-      await cmdUpload(args);
-      break;
-    default:
-      usage();
-  }
-}
-main().catch((err) => {
-  process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
-`);
-  process.exitCode = process.argv[2] === "check" ? CHECK_EXIT.badContract : 1;
+var NODE_SQLITE_WARNING = "SQLite is an experimental feature and might change at any time";
+var emitWarning = process.emitWarning.bind(process);
+process.emitWarning = ((warning, ...rest) => {
+  const type = typeof rest[0] === "string" ? rest[0] : rest[0]?.type;
+  const text = typeof warning === "string" ? warning : warning.message;
+  if (type === "ExperimentalWarning" && text === NODE_SQLITE_WARNING) return;
+  emitWarning(warning, ...rest);
+});
+await runTraces(process.argv.slice(2), {
+  list: reading(cmdList),
+  facts: reading(cmdFacts),
+  analyze: reading(cmdAnalyze),
+  ask: reading(cmdAsk),
+  // check resolves its refs itself, after its contracts load, and --share-safe
+  // reads paths as bytes: a bad contract exits before any trace is read.
+  check: async (args) => cmdCheck(prepare(args)),
+  diff: cmdDiff,
+  watch: reading(cmdWatch),
+  bundle: reading(cmdBundle),
+  "bundle verify": cmdBundleVerify,
+  convert: reading(cmdConvert),
+  upload: reading(cmdUpload),
+  skills: cmdSkills,
+  mcp: reading(cmdMcp)
 });