@tangle-network/traces 0.10.3 → 0.11.2

package/dist/cli.js

@@ -6,17 +6,20 @@ import {
   appendAll,
   buildPolicyEvidenceRecord,
   buildSessionIndexFromRows,
+  cmdReplayVerify,
   collectSessionSelection,
   commandAnalyzer,
   commandRedactor,
   describeSessionRelationship,
   executeUpload,
   exportTraceEvidenceFile,
+  fileRunContextSupervisorRunReader,
   haloAnalyzer,
   hodoscopeAnalyzer,
   importCodeTraceBench,
   indexSessionIdsByTrace,
   inspectSessionIndex,
+  isFileRunContextDir,
   knownHarnesses,
   loadTracesConfig,
   locateSessions,
@@ -24,9 +27,12 @@ import {
   parseSession,
   parseSince,
   planUpload,
+  readOtlpInput,
   readSessionIndexFile,
   renderInspectionReport,
+  renderValidation,
   resolveAdapter,
+  resolveRunWatchTarget,
   runTraceImprovement,
   runTraceInvestigation,
   saveReport,
@@ -39,18 +45,20 @@ import {
   streamSessions,
   totalAgenticFailureMessage,
   traceStreamEventsFromSpans,
+  validationExitCode,
+  watchRunTarget,
   watchSessions,
   writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
   writeSessionIndexFile,
   writeTraceEvidenceExportFile
-} from "./chunk-LC66I5TE.js";
+} from "./chunk-UY3M7XUF.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
-import { readFile, stat } from "fs/promises";
-import { basename, resolve } from "path";
+import { readdir, readFile, stat } from "fs/promises";
+import { basename, join, resolve } from "path";
 import {
   analyzeSupervisorRun,
   findSupervisorRunDirs,
@@ -81,6 +89,7 @@ function parseArgs(argv) {
     maxWorkflowSessions: 100,
     llm: false,
     interval: 5,
+    intervalExplicit: false,
     window: 30,
     minLoop: 3,
     dryRun: false,
@@ -88,6 +97,7 @@ function parseArgs(argv) {
     noContent: false,
     analyzers: [],
     replay: false,
+    once: false,
     noSpans: false,
     noFindings: false,
     attrs: [],
@@ -149,6 +159,9 @@ function parseArgs(argv) {
       case "--otlp":
         a.otlp = next();
         break;
+      case "--otlp-out":
+        a.otlpOut = next();
+        break;
       case "--llm":
         a.llm = true;
         break;
@@ -174,6 +187,7 @@ function parseArgs(argv) {
       }
       case "--interval":
         a.interval = Number(next());
+        a.intervalExplicit = true;
         break;
       case "--window":
         a.window = Number(next());
@@ -188,7 +202,12 @@ function parseArgs(argv) {
         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":
@@ -227,6 +246,30 @@ function parseArgs(argv) {
   }
   return a;
 }
+var OTLP_INPUT_COMMANDS = /* @__PURE__ */ new Set(["analyze", "investigate", "improve", "stream", "validate"]);
+function migrateWritingOtlpFlag(args) {
+  if (args.otlp === void 0 || OTLP_INPUT_COMMANDS.has(args.command)) return args;
+  if (args.otlpOut !== void 0) {
+    throw new Error(
+      `${args.command} was given both --otlp and --otlp-out. --otlp is the deprecated spelling of --otlp-out on writing commands; pass only --otlp-out.`
+    );
+  }
+  console.error(
+    `warning: --otlp is deprecated on \`${args.command}\` and will be removed in 0.12. --otlp now READS OTLP-JSONL; use --otlp-out <path> to write the artifact. Treating it as --otlp-out for this run.`
+  );
+  return { ...args, otlpOut: args.otlp, otlp: void 0 };
+}
+function validateOtlpSelection(raw) {
+  const args = migrateWritingOtlpFlag(raw);
+  if (args.otlp === void 0) return args;
+  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");
+  }
+  return args;
+}
 var CURRENT_SESSION_COMMANDS = /* @__PURE__ */ new Set([
   "analyze",
   "investigate",
@@ -445,7 +488,45 @@ function selectedSessionSource(ref, spans, sessionIdOverride) {
     } : {}
   };
 }
+async function collectOtlpSpans(path) {
+  const input = await readOtlpInput(path);
+  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.`
+    );
+  }
+  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 byTrace = /* @__PURE__ */ new Map();
+  for (const span of input.spans) {
+    const grouped = byTrace.get(span.trace_id) ?? [];
+    grouped.push(span);
+    byTrace.set(span.trace_id, grouped);
+  }
+  return {
+    spans: [...input.spans],
+    harness: "otlp",
+    cwds: [],
+    sources: [...byTrace].map(([traceId, spans]) => selectedSessionSource({
+      harness: "otlp",
+      sessionId: traceId,
+      path: fileByTrace.get(traceId) ?? path,
+      cwd: null,
+      mtimeMs: 0
+    }, spans, traceId)),
+    conformance: input.validation,
+    conformanceSubject: path,
+    conformanceFiles: input.files,
+    conformanceSkipped: input.skipped,
+    conformanceIssues: input.issues,
+    conformanceWithheld: input.withheld,
+    conformanceUnreadable: input.unreadable
+  };
+}
 async function collectSpans(args) {
+  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);
@@ -469,11 +550,37 @@ async function collectSpans(args) {
     ...selection.workflow ? { workflow: selection.workflow } : {}
   };
 }
+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);
+}
 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.otlp);
+  const path = await writeOtlpFile(spans, args.otlpOut);
   console.log(`wrote ${spans.length} spans \u2192 ${path}`);
 }
 function workflowIssueText(issue) {
@@ -507,7 +614,7 @@ async function cmdEvidence(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 otlpPath = args.otlp ? await writeOtlpFile(rows.flatMap((row) => row.spans), args.otlp) : void 0;
+  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, {
@@ -566,7 +673,7 @@ 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.otlp;
+  const outPath = args.out ?? args.otlpOut;
   if (outPath) {
     const result2 = await writeTraceEvidenceExportFile(args.input, outPath, { format, attributes });
     console.log(
@@ -668,9 +775,23 @@ async function cmdAnalyze(args) {
   assertAgenticAnalystsRan(args, result.agenticPerAnalyst);
 }
 async function cmdAnalyzeSupervisorRun(runDir, args) {
-  const nested = await findSupervisorRunDirs(runDir);
+  const runContextDirs = await findFileRunContextDirs(runDir);
+  const nested = runContextDirs.length > 0 ? [] : await findSupervisorRunDirs(runDir);
   let markdown;
-  if (nested.length > 0) {
+  if (runContextDirs.length > 1) {
+    markdown = renderSupervisorRollupMarkdown(
+      rollupSupervisorRuns(
+        await Promise.all(
+          runContextDirs.map((dir) => analyzeSupervisorRun(fileRunContextSupervisorRunReader(dir)))
+        )
+      ),
+      `Supervisor rollup \u2014 ${runDir}`
+    );
+  } else if (runContextDirs.length === 1) {
+    markdown = renderSupervisorRunMarkdown(
+      await analyzeSupervisorRun(fileRunContextSupervisorRunReader(runContextDirs[0]))
+    );
+  } else if (nested.length > 0) {
     markdown = renderSupervisorRollupMarkdown(
       rollupSupervisorRuns(await Promise.all(nested.map((dir) => analyzeSupervisorRun(dir)))),
       `Supervisor rollup \u2014 ${runDir}`
@@ -679,20 +800,30 @@ async function cmdAnalyzeSupervisorRun(runDir, args) {
     const report = await analyzeSupervisorRun(runDir);
     if (isUnavailable(report.orchestration.workersSpawned)) {
       throw new Error(
-        `no supervisor run found at ${runDir} \u2014 expected <runDir>/ws/.agent/supervisor/<id> (or the pre-rename <runDir>/ws/.loops/supervisor/<id>), or a parent directory containing such runs`
+        `no supervisor run found at ${runDir} \u2014 expected <runDir>/spawn-journal.jsonl (agent-runtime createFileRunContext), <runDir>/ws/.agent/supervisor/<id> (or the pre-rename <runDir>/ws/.loops/supervisor/<id>), or a parent directory containing such runs`
       );
     }
     markdown = renderSupervisorRunMarkdown(report);
   }
+  const runs = Math.max(runContextDirs.length, nested.length, 1);
   if (args.out) {
     await saveReport(args.out, markdown);
-    console.log(
-      `supervisor report \u2192 ${args.out}  (${nested.length > 0 ? `${nested.length} runs` : "1 run"})`
-    );
+    console.log(`supervisor report \u2192 ${args.out}  (${runs === 1 ? "1 run" : `${runs} runs`})`);
   } else {
     console.log(markdown);
   }
 }
+async function findFileRunContextDirs(dir) {
+  if (await isFileRunContextDir(dir)) return [dir];
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  const found = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const child = join(dir, entry.name);
+    if (await isFileRunContextDir(child)) found.push(child);
+  }
+  return found.sort();
+}
 async function collectImportedSpans(args) {
   if (!args.input) throw new Error("input file missing");
   const attributes = await loadExportAttributes(args);
@@ -744,8 +875,20 @@ async function cmdInvestigate(args) {
   }
   assertAgenticAnalystsRan(args, result.agenticPerAnalyst);
 }
+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 { spans, harness, cwds, sources, workflow } = await collectSpans(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 = args.config !== void 0 || options.loadDefaultConfig !== false ? await loadTracesConfig(args.config) : void 0;
   const analystModel = args.model ?? process.env.TRACES_ANALYST_MODEL ?? DEFAULT_ANALYST_MODEL;
@@ -760,14 +903,16 @@ async function investigate(args, options = {}) {
     engine,
     model: args.llm ? analystModel : args.model,
     budgetUsd: args.budget,
-    otlpOutPath: args.otlp,
+    otlpOutPath: args.otlpOut,
     externalAnalyzers: externalAnalyzersFromArgs(args),
     analyzerPrompt: args.analyzerPrompt,
-    log: analystLog
+    log: analystLog,
+    ...conformanceOptions(collected)
   }, config));
 }
 async function cmdImprove(args) {
-  const { spans, harness, cwds, sources, workflow } = await collectSpans(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 = args.model ?? process.env.TRACES_ANALYST_MODEL ?? DEFAULT_ANALYST_MODEL;
@@ -783,10 +928,11 @@ async function cmdImprove(args) {
       engine,
       model: args.llm ? analystModel : args.model,
       budgetUsd: args.budget,
-      otlpOutPath: args.otlp,
+      otlpOutPath: args.otlpOut,
       externalAnalyzers: externalAnalyzersFromArgs(args),
       analyzerPrompt: args.analyzerPrompt,
-      log: analystLog
+      log: analystLog,
+      ...conformanceOptions(collected)
     }, config),
     outDir: args.dir ?? args.out
   });
@@ -854,12 +1000,13 @@ async function streamExplicitSession(args, extraAnalysts) {
 async function cmdStream(args) {
   const config = await loadTracesConfig(args.config);
   const preset = streamPreset(args);
-  if (args.input) {
-    const { spans, harness } = await collectImportedSpans(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(args.input),
-      path: resolve(args.input),
+      sessionId: basename(source),
+      path: resolve(source),
       cwd: args.cwd ?? null,
       mtimeMs: Date.now()
     };
@@ -911,6 +1058,8 @@ async function cmdStream(args) {
   });
 }
 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 controller = new AbortController();
   process.once("SIGINT", () => controller.abort());
@@ -939,6 +1088,26 @@ async function cmdWatch(args) {
     }
   });
 }
+async function cmdWatchRunTarget(dir, args) {
+  const target = await resolveRunWatchTarget(resolve(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"}.
+`
+    );
+  }
+  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 result = snapshot.journal?.result ?? null;
+  if (result !== null && result.errorMessage !== null) process.exitCode = 1;
+}
 async function cmdUpload(args) {
   const sinceMs = args.since ? parseSince(args.since) : Date.now() - 24 * 60 * 60 * 1e3;
   const all = args.all || !args.harnessExplicit;
@@ -976,7 +1145,7 @@ Window: since ${new Date(sinceMs).toISOString()}
     return;
   }
   if (args.dryRun) {
-    const res2 = await executeUpload(plan, { dryRun: true, otlpOut: args.otlp, stripContent: args.noContent, redactor });
+    const res2 = await executeUpload(plan, { dryRun: true, otlpOut: args.otlpOut, stripContent: args.noContent, redactor });
     console.log(`dry run: ${candidates.length - res2.skippedSessions} session(s), ${totalRedactions} redaction(s). Redacted OTLP -> ${res2.otlpPath}`);
     console.log("No upload performed. Set TANGLE_INGEST_URL / TANGLE_INGEST_API_KEY / TANGLE_TENANT_ID and drop --dry-run to send.");
     return;
@@ -1039,24 +1208,75 @@ 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 usage() {
-  console.log(`traces: analyze, observe & upload coding-agent sessions
+  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)
   list      List discovered sessions
-  analyze   Run analyst suite + loop/waste pipelines over sessions or an input file
+  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
-  convert   Emit OTLP-JSONL only (HALO: use analyze --analyzer halo)
+  convert   Emit OTLP-JSONL only, to --otlp-out (HALO: use analyze --analyzer halo)
   index     Emit a reusable session index JSON for later investigation
   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)
   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
 
 Options:
@@ -1074,15 +1294,26 @@ Options:
                    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.
+                   watch: same directory, live. Reads the loops layout, the
+                   agent-runtime createFileRunContext journal, and OTLP span files.
   --since <t>      upload: window, 30m / 2h / 7d or an ISO date (default 24h); analyze: ISO cutoff
   --out <path>     Write report to a file
   --dir <path>     improve: write artifacts to this directory
-  --otlp <path>    OTLP artifact path (also evidence provenance / dry-run upload preview)
+  --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, investigate, improve, stream.
+                   On a WRITING command it is the deprecated spelling of
+                   --otlp-out; it still works, with a warning, until 0.12.
+  --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
   --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)
   --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
@@ -1096,7 +1327,7 @@ Options:
   --budget <usd>   USD cap for agentic analysts
   --analyzer <id>  analyze: also run halo, hodoscope, or an installed command (repeatable)
   --analyzer-prompt <p>  analyze: prompt passed to external analyzers (default: diagnose)
-  --interval <s>   watch/stream: poll interval seconds (default 5)
+  --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
@@ -1104,7 +1335,15 @@ Options:
   --redactor <cmd> upload: external PII scrubber (JSON array stdin\u2192stdout) after the regex pass
   --yes, -y        upload: skip the confirmation prompt
   --version, -v    Print the installed traces version
-  --help, -h       Show help (use \`traces export --help\` or \`traces import-codetracebench --help\`)
+  --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`);
 }
@@ -1114,18 +1353,24 @@ async function main() {
     console.log(`traces ${packageVersion()}`);
     return;
   }
+  if (rawArgs[0] === "replay-verify") {
+    await cmdReplayVerify(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 = validateWorkflowSelection(applyCurrentSessionSelection(parsedArgs));
+  const args = validateOtlpSelection(validateWorkflowSelection(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":
@@ -1134,6 +1379,9 @@ async function main() {
     case "analyze":
       await cmdAnalyze(args);
       break;
+    case "validate":
+      await cmdValidate(args);
+      break;
     case "investigate":
       await cmdInvestigate(args);
       break;