reasonix 0.2.0 → 0.2.2

package/README.md

@@ -58,17 +58,17 @@ actually stays byte-stable.
 
 ## Validated numbers
 
-**τ-bench-lite** — 8 multi-turn tool-use tasks, same tools / same prompt
-on both sides, sole variable is prefix stability. Measured on live
-DeepSeek `deepseek-chat`:
+**τ-bench-lite** — 8 multi-turn tool-use tasks × 3 repeats = 48 runs per
+side. Same tools / same prompt / same client on both sides, sole variable
+is prefix stability. Measured on live DeepSeek `deepseek-chat`:
 
 | metric | baseline (cache-hostile) | Reasonix | delta |
 |---|---:|---:|---:|
-| runs | 8 | 8 | — |
-| **cache hit** | 43.9% | **94.3%** | **+50.3pp** |
-| cost / task | $0.002783 | $0.001621 | **−42% (×0.58)** |
+| runs | 24 | 24 | — |
+| **cache hit** | 46.6% | **94.4%** | **+47.7pp** |
+| cost / task | $0.002599 | $0.001579 | **−39% (×0.61)** |
 | vs Claude Sonnet 4.6 (token-count estimate) | — | — | **~96% cheaper** |
-| pass rate | 100% (8/8) | 88% (7/8) | 1 refusal-task predicate too strict (see [report.md][r]) |
+| pass rate | 96% (23/24) | **100% (24/24)** | Reasonix held the guardrail on every run |
 
 **Verify it yourself — no API key, zero cost:**
 
@@ -86,8 +86,8 @@ stays byte-stable across every model call; baseline's prefix churns on
 every turn. The cache delta is *mechanically* attributable to log
 stability, not to a different system prompt.
 
-Full 16-run report: [`benchmarks/tau-bench/report.md`][r]. Reproduce
-with your own API key: `npx tsx benchmarks/tau-bench/runner.ts`.
+Full 48-run report: [`benchmarks/tau-bench/report.md`][r]. Reproduce
+with your own API key: `npx tsx benchmarks/tau-bench/runner.ts --repeats 3`.
 
 [r]: ./benchmarks/tau-bench/report.md
 

package/dist/cli/index.js

@@ -1420,6 +1420,24 @@ function parseTranscript(raw) {
 }
 
 // src/replay.ts
+function groupRecordsByTurn(records) {
+  const byTurn = /* @__PURE__ */ new Map();
+  for (const rec of records) {
+    const list = byTurn.get(rec.turn);
+    if (list) list.push(rec);
+    else byTurn.set(rec.turn, [rec]);
+  }
+  return [...byTurn.entries()].sort(([a], [b]) => a - b).map(([turn, records2]) => ({ turn, records: records2 }));
+}
+function computeCumulativeStats(pages, upToIdx) {
+  if (upToIdx < 0) return computeReplayStats([]);
+  const flat = [];
+  for (let i = 0; i <= upToIdx && i < pages.length; i++) {
+    const records = pages[i]?.records;
+    if (records) flat.push(...records);
+  }
+  return computeReplayStats(flat);
+}
 function replayFromFile(path) {
   const parsed = readTranscript(path);
   return { parsed, stats: computeReplayStats(parsed.records) };
@@ -1491,6 +1509,19 @@ function round2(n, digits) {
 }
 
 // src/diff.ts
+function findNextDivergence(pairs, fromIdx) {
+  for (let i = fromIdx + 1; i < pairs.length; i++) {
+    if (pairs[i].kind !== "match") return i;
+  }
+  return -1;
+}
+function findPrevDivergence(pairs, fromIdx) {
+  const start = Math.min(fromIdx - 1, pairs.length - 1);
+  for (let i = start; i >= 0; i--) {
+    if (pairs[i].kind !== "match") return i;
+  }
+  return -1;
+}
 function diffTranscripts(a, b) {
   const aSide = {
     label: a.label,
@@ -1815,7 +1846,7 @@ function redactKey(key) {
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.2.2";
 
 // src/cli/commands/chat.tsx
 import { render } from "ink";
@@ -2566,24 +2597,231 @@ async function chatCommand(opts) {
 // src/cli/commands/diff.ts
 import { writeFileSync as writeFileSync2 } from "fs";
 import { basename } from "path";
-function diffCommand(opts) {
+import { render as render2 } from "ink";
+import React10 from "react";
+
+// src/cli/ui/DiffApp.tsx
+import { Box as Box8, Static as Static2, Text as Text8, useApp as useApp3, useInput } from "ink";
+import React9, { useState as useState5 } from "react";
+
+// src/cli/ui/RecordView.tsx
+import { Box as Box7, Text as Text7 } from "ink";
+import React8 from "react";
+function RecordView({ rec, compact = false }) {
+  const toolArgsMax = compact ? 120 : 200;
+  const toolContentMax = compact ? 200 : 400;
+  if (rec.role === "user") {
+    return /* @__PURE__ */ React8.createElement(Box7, { marginTop: 1 }, /* @__PURE__ */ React8.createElement(Text7, { bold: true, color: "cyan" }, "you \u203A", " "), /* @__PURE__ */ React8.createElement(Text7, null, rec.content));
+  }
+  if (rec.role === "assistant_final") {
+    return /* @__PURE__ */ React8.createElement(Box7, { flexDirection: "column", marginTop: 1 }, /* @__PURE__ */ React8.createElement(Box7, null, /* @__PURE__ */ React8.createElement(Text7, { bold: true, color: "green" }, "assistant"), rec.cost !== void 0 ? /* @__PURE__ */ React8.createElement(Text7, { dimColor: true }, "  $", rec.cost.toFixed(6)) : null, rec.usage ? /* @__PURE__ */ React8.createElement(CacheBadge, { usage: rec.usage }) : null), rec.content ? /* @__PURE__ */ React8.createElement(Text7, null, rec.content) : /* @__PURE__ */ React8.createElement(Text7, { dimColor: true, italic: true }, "(tool-call response only)"));
+  }
+  if (rec.role === "tool") {
+    return /* @__PURE__ */ React8.createElement(Box7, { flexDirection: "column", marginTop: 1 }, /* @__PURE__ */ React8.createElement(Text7, { color: "yellow" }, "tool<", rec.tool ?? "?", ">"), rec.args ? /* @__PURE__ */ React8.createElement(Text7, { dimColor: true }, "  args: ", truncate3(rec.args, toolArgsMax)) : null, /* @__PURE__ */ React8.createElement(Text7, { dimColor: true }, "  \u2192 ", truncate3(rec.content, toolContentMax)));
+  }
+  if (rec.role === "error") {
+    return /* @__PURE__ */ React8.createElement(Box7, { marginTop: 1 }, /* @__PURE__ */ React8.createElement(Text7, { color: "red", bold: true }, "error", " "), /* @__PURE__ */ React8.createElement(Text7, { color: "red" }, rec.error ?? rec.content));
+  }
+  if (rec.role === "done" || rec.role === "assistant_delta") {
+    return null;
+  }
+  return /* @__PURE__ */ React8.createElement(Box7, null, /* @__PURE__ */ React8.createElement(Text7, { dimColor: true }, "[", rec.role, "] ", rec.content));
+}
+function CacheBadge({ usage }) {
+  const hit = usage.prompt_cache_hit_tokens ?? 0;
+  const miss = usage.prompt_cache_miss_tokens ?? 0;
+  const total = hit + miss;
+  if (total === 0) return null;
+  const pct2 = hit / total * 100;
+  const color = pct2 >= 70 ? "green" : pct2 >= 40 ? "yellow" : "red";
+  return /* @__PURE__ */ React8.createElement(Text7, null, /* @__PURE__ */ React8.createElement(Text7, { dimColor: true }, "  \xB7 cache "), /* @__PURE__ */ React8.createElement(Text7, { color }, pct2.toFixed(1), "%"));
+}
+function truncate3(s, max) {
+  return s.length <= max ? s : `${s.slice(0, max)}\u2026 (+${s.length - max} chars)`;
+}
+
+// src/cli/ui/DiffApp.tsx
+function DiffApp({ report }) {
+  const { exit } = useApp3();
+  const maxIdx = Math.max(0, report.pairs.length - 1);
+  const initialIdx = report.firstDivergenceTurn ? report.pairs.findIndex((p) => p.turn === report.firstDivergenceTurn) : 0;
+  const [idx, setIdx] = useState5(Math.max(0, initialIdx));
+  useInput((input, key) => {
+    if (input === "q" || key.ctrl && input === "c") {
+      exit();
+      return;
+    }
+    if (input === "j" || key.downArrow || input === " " || key.return) {
+      setIdx((i) => Math.min(maxIdx, i + 1));
+    } else if (input === "k" || key.upArrow) {
+      setIdx((i) => Math.max(0, i - 1));
+    } else if (input === "g") {
+      setIdx(0);
+    } else if (input === "G") {
+      setIdx(maxIdx);
+    } else if (input === "n") {
+      const next = findNextDivergence(report.pairs, idx);
+      if (next !== -1) setIdx(next);
+    } else if (input === "N" || input === "p") {
+      const prev = findPrevDivergence(report.pairs, idx);
+      if (prev !== -1) setIdx(prev);
+    }
+  });
+  const pair = report.pairs[idx];
+  return /* @__PURE__ */ React9.createElement(Box8, { flexDirection: "column" }, /* @__PURE__ */ React9.createElement(DiffHeader, { report }), /* @__PURE__ */ React9.createElement(Box8, { marginTop: 1, paddingX: 1, justifyContent: "space-between" }, /* @__PURE__ */ React9.createElement(Text8, { color: "cyan", bold: true }, "turn ", pair?.turn ?? "?", " (", idx + 1, " / ", report.pairs.length, ")"), /* @__PURE__ */ React9.createElement(Text8, null, pair ? /* @__PURE__ */ React9.createElement(KindBadge, { kind: pair.kind }) : null)), /* @__PURE__ */ React9.createElement(Box8, { flexDirection: "row", marginTop: 1 }, /* @__PURE__ */ React9.createElement(Pane, { label: report.a.label, headerColor: "blue", records: paneRecords(pair, "a") }), /* @__PURE__ */ React9.createElement(Pane, { label: report.b.label, headerColor: "magenta", records: paneRecords(pair, "b") })), pair?.divergenceNote ? /* @__PURE__ */ React9.createElement(Box8, { marginTop: 1, paddingX: 1 }, /* @__PURE__ */ React9.createElement(Text8, { color: "yellow" }, "\u2605 "), /* @__PURE__ */ React9.createElement(Text8, null, pair.divergenceNote)) : null, /* @__PURE__ */ React9.createElement(Box8, { marginTop: 1, paddingX: 1, borderStyle: "single", borderColor: "gray" }, /* @__PURE__ */ React9.createElement(Text8, { dimColor: true }, /* @__PURE__ */ React9.createElement(Text8, { bold: true }, "j"), "/", /* @__PURE__ */ React9.createElement(Text8, { bold: true }, "\u2193"), " next \xB7 ", /* @__PURE__ */ React9.createElement(Text8, { bold: true }, "k"), "/", /* @__PURE__ */ React9.createElement(Text8, { bold: true }, "\u2191"), " ", "prev \xB7 ", /* @__PURE__ */ React9.createElement(Text8, { bold: true }, "n"), " next-diverge \xB7 ", /* @__PURE__ */ React9.createElement(Text8, { bold: true }, "N"), "/", /* @__PURE__ */ React9.createElement(Text8, { bold: true }, "p"), " ", "prev-diverge \xB7 ", /* @__PURE__ */ React9.createElement(Text8, { bold: true }, "g"), "/", /* @__PURE__ */ React9.createElement(Text8, { bold: true }, "G"), " first/last \xB7 ", /* @__PURE__ */ React9.createElement(Text8, { bold: true }, "q"), " ", "quit")));
+}
+function DiffHeader({ report }) {
+  const a = report.a;
+  const b = report.b;
+  const cacheDelta = b.stats.cacheHitRatio - a.stats.cacheHitRatio;
+  const costDelta2 = a.stats.totalCostUsd > 0 ? (b.stats.totalCostUsd - a.stats.totalCostUsd) / a.stats.totalCostUsd * 100 : 0;
+  const aStable = a.stats.prefixHashes.length <= 1;
+  const bStable = b.stats.prefixHashes.length <= 1;
+  let prefixLine = null;
+  if (aStable !== bStable) {
+    const stableLabel = aStable ? report.a.label : report.b.label;
+    const churnLabel = aStable ? report.b.label : report.a.label;
+    const churnCount = aStable ? b.stats.prefixHashes.length : a.stats.prefixHashes.length;
+    prefixLine = `${stableLabel} stayed byte-stable; ${churnLabel} churned ${churnCount} distinct prefixes.`;
+  } else if (a.stats.prefixHashes[0] && a.stats.prefixHashes[0] === b.stats.prefixHashes[0]) {
+    prefixLine = `shared prefix hash ${a.stats.prefixHashes[0].slice(0, 12)}\u2026 \u2014 cache delta attributable to log stability, not prompt change.`;
+  }
+  return /* @__PURE__ */ React9.createElement(Box8, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1 }, /* @__PURE__ */ React9.createElement(Box8, { justifyContent: "space-between" }, /* @__PURE__ */ React9.createElement(Text8, null, /* @__PURE__ */ React9.createElement(Text8, { color: "cyan", bold: true }, "reasonix diff"), /* @__PURE__ */ React9.createElement(Text8, { dimColor: true }, " \xB7 A="), /* @__PURE__ */ React9.createElement(Text8, { color: "blue" }, a.label), /* @__PURE__ */ React9.createElement(Text8, { dimColor: true }, " vs B="), /* @__PURE__ */ React9.createElement(Text8, { color: "magenta" }, b.label)), /* @__PURE__ */ React9.createElement(Text8, { dimColor: true }, report.pairs.length, " turns aligned")), /* @__PURE__ */ React9.createElement(Box8, { marginTop: 1, gap: 3 }, /* @__PURE__ */ React9.createElement(Text8, null, /* @__PURE__ */ React9.createElement(Text8, { dimColor: true }, "cache "), /* @__PURE__ */ React9.createElement(Text8, null, (a.stats.cacheHitRatio * 100).toFixed(1), "%"), /* @__PURE__ */ React9.createElement(Text8, { dimColor: true }, " \u2192 "), /* @__PURE__ */ React9.createElement(Text8, null, (b.stats.cacheHitRatio * 100).toFixed(1), "%"), /* @__PURE__ */ React9.createElement(Text8, { color: cacheDelta >= 0 ? "green" : "red", bold: true }, "  ", cacheDelta >= 0 ? "+" : "", (cacheDelta * 100).toFixed(1), "pp")), /* @__PURE__ */ React9.createElement(Text8, null, /* @__PURE__ */ React9.createElement(Text8, { dimColor: true }, "cost "), /* @__PURE__ */ React9.createElement(Text8, null, "$", a.stats.totalCostUsd.toFixed(6)), /* @__PURE__ */ React9.createElement(Text8, { dimColor: true }, " \u2192 "), /* @__PURE__ */ React9.createElement(Text8, null, "$", b.stats.totalCostUsd.toFixed(6)), /* @__PURE__ */ React9.createElement(Text8, { color: costDelta2 <= 0 ? "green" : "red", bold: true }, "  ", costDelta2 >= 0 ? "+" : "", costDelta2.toFixed(1), "%")), /* @__PURE__ */ React9.createElement(Text8, null, /* @__PURE__ */ React9.createElement(Text8, { dimColor: true }, "model calls "), /* @__PURE__ */ React9.createElement(Text8, null, a.stats.turns, " \u2192 ", b.stats.turns))), prefixLine ? /* @__PURE__ */ React9.createElement(Box8, { marginTop: 1 }, /* @__PURE__ */ React9.createElement(Text8, { dimColor: true, italic: true }, prefixLine)) : null);
+}
+function Pane({
+  label,
+  headerColor,
+  records
+}) {
+  return /* @__PURE__ */ React9.createElement(
+    Box8,
+    {
+      flexDirection: "column",
+      flexGrow: 1,
+      paddingX: 1,
+      borderStyle: "single",
+      borderColor: headerColor
+    },
+    /* @__PURE__ */ React9.createElement(Text8, { color: headerColor, bold: true }, label),
+    records.length === 0 ? /* @__PURE__ */ React9.createElement(Box8, { marginTop: 1 }, /* @__PURE__ */ React9.createElement(Text8, { dimColor: true, italic: true }, "(no records on this side for this turn)")) : /* @__PURE__ */ React9.createElement(Static2, { items: records.map((rec, i) => ({ key: `${label}-${i}`, rec })) }, ({ key, rec }) => /* @__PURE__ */ React9.createElement(RecordView, { key, rec, compact: true }))
+  );
+}
+function KindBadge({ kind }) {
+  if (kind === "match") {
+    return /* @__PURE__ */ React9.createElement(Text8, { color: "green" }, "\u2713 match");
+  }
+  if (kind === "diverge") {
+    return /* @__PURE__ */ React9.createElement(Text8, { color: "yellow" }, "\u2605 diverge");
+  }
+  if (kind === "only_in_a") {
+    return /* @__PURE__ */ React9.createElement(Text8, { color: "blue" }, "\u2190 only in A");
+  }
+  return /* @__PURE__ */ React9.createElement(Text8, { color: "magenta" }, "\u2192 only in B");
+}
+function paneRecords(pair, side) {
+  if (!pair) return [];
+  const tools = side === "a" ? pair.aTools : pair.bTools;
+  const assistant = side === "a" ? pair.aAssistant : pair.bAssistant;
+  const out = [...tools];
+  if (assistant) out.push(assistant);
+  return out;
+}
+
+// src/cli/commands/diff.ts
+async function diffCommand(opts) {
   const aParsed = readTranscript(opts.a);
   const bParsed = readTranscript(opts.b);
   const report = diffTranscripts(
     { label: opts.labelA ?? basename(opts.a), parsed: aParsed },
     { label: opts.labelB ?? basename(opts.b), parsed: bParsed }
   );
-  console.log(renderSummaryTable(report));
-  if (opts.mdPath) {
+  const wantMarkdown = !!opts.mdPath;
+  const wantPrint = opts.print || !process.stdout.isTTY;
+  const wantTui = opts.tui || !wantPrint && !wantMarkdown;
+  if (wantMarkdown) {
+    console.log(renderSummaryTable(report));
     const md = renderMarkdown(report);
     writeFileSync2(opts.mdPath, md, "utf8");
     console.log(`
 markdown report written to ${opts.mdPath}`);
+    return;
+  }
+  if (wantTui) {
+    const { waitUntilExit } = render2(React10.createElement(DiffApp, { report }), {
+      exitOnCtrlC: true
+    });
+    await waitUntilExit();
+    return;
   }
+  console.log(renderSummaryTable(report));
 }
 
 // src/cli/commands/replay.ts
-function replayCommand(opts) {
+import { render as render3 } from "ink";
+import React12 from "react";
+
+// src/cli/ui/ReplayApp.tsx
+import { Box as Box9, Static as Static3, Text as Text9, useApp as useApp4, useInput as useInput2 } from "ink";
+import React11, { useMemo as useMemo2, useState as useState6 } from "react";
+function ReplayApp({ meta, pages }) {
+  const { exit } = useApp4();
+  const maxIdx = Math.max(0, pages.length - 1);
+  const [idx, setIdx] = useState6(maxIdx);
+  useInput2((input, key) => {
+    if (input === "q" || key.ctrl && input === "c") {
+      exit();
+      return;
+    }
+    if (input === "j" || key.downArrow || input === " " || key.return) {
+      setIdx((i) => Math.min(maxIdx, i + 1));
+    } else if (input === "k" || key.upArrow) {
+      setIdx((i) => Math.max(0, i - 1));
+    } else if (input === "g") {
+      setIdx(0);
+    } else if (input === "G") {
+      setIdx(maxIdx);
+    } else if (input === "h" || key.leftArrow) {
+      setIdx(0);
+    } else if (input === "l" || key.rightArrow) {
+      setIdx(maxIdx);
+    }
+  });
+  const cumStats = useMemo2(() => computeCumulativeStats(pages, idx), [pages, idx]);
+  const summary = {
+    turns: cumStats.turns,
+    totalCostUsd: cumStats.totalCostUsd,
+    claudeEquivalentUsd: cumStats.claudeEquivalentUsd,
+    savingsVsClaudePct: cumStats.savingsVsClaudePct,
+    cacheHitRatio: cumStats.cacheHitRatio
+  };
+  const prefixHash = cumStats.prefixHashes.length === 1 ? cumStats.prefixHashes[0].slice(0, 16) : cumStats.prefixHashes.length === 0 ? "(untracked)" : `(churned \xD7${cumStats.prefixHashes.length})`;
+  const currentPage = pages[idx];
+  const progressLabel = pages.length === 0 ? "empty transcript" : `turn ${idx + 1} / ${pages.length}`;
+  return /* @__PURE__ */ React11.createElement(Box9, { flexDirection: "column" }, /* @__PURE__ */ React11.createElement(
+    StatsPanel,
+    {
+      summary,
+      model: cumStats.models[0] ?? meta?.model ?? "?",
+      prefixHash
+    }
+  ), /* @__PURE__ */ React11.createElement(Box9, { flexDirection: "column", marginTop: 1, paddingX: 1 }, /* @__PURE__ */ React11.createElement(Box9, { justifyContent: "space-between" }, /* @__PURE__ */ React11.createElement(Text9, { color: "cyan", bold: true }, progressLabel), meta ? /* @__PURE__ */ React11.createElement(Text9, { dimColor: true }, meta.source, meta.task ? ` \xB7 ${meta.task}` : "", meta.mode ? ` \xB7 ${meta.mode}` : "") : null), currentPage ? /* @__PURE__ */ React11.createElement(Static3, { items: currentPage.records.map((rec, i) => ({ key: `${idx}-${i}`, rec })) }, ({ key, rec }) => /* @__PURE__ */ React11.createElement(RecordView, { key, rec })) : /* @__PURE__ */ React11.createElement(Text9, { dimColor: true, italic: true }, "no records")), /* @__PURE__ */ React11.createElement(Box9, { marginTop: 1, paddingX: 1, borderStyle: "single", borderColor: "gray" }, /* @__PURE__ */ React11.createElement(Text9, { dimColor: true }, /* @__PURE__ */ React11.createElement(Text9, { bold: true }, "j"), "/", /* @__PURE__ */ React11.createElement(Text9, { bold: true }, "\u2193"), "/", /* @__PURE__ */ React11.createElement(Text9, { bold: true }, "space"), " next \xB7 ", /* @__PURE__ */ React11.createElement(Text9, { bold: true }, "k"), "/", /* @__PURE__ */ React11.createElement(Text9, { bold: true }, "\u2191"), " prev \xB7 ", /* @__PURE__ */ React11.createElement(Text9, { bold: true }, "g"), " first \xB7 ", /* @__PURE__ */ React11.createElement(Text9, { bold: true }, "G"), " last \xB7", " ", /* @__PURE__ */ React11.createElement(Text9, { bold: true }, "q"), " quit")));
+}
+
+// src/cli/commands/replay.ts
+async function replayCommand(opts) {
+  const wantPrint = opts.print || !process.stdout.isTTY || opts.head !== void 0 || opts.tail !== void 0;
+  if (wantPrint) {
+    printReplay(opts);
+    return;
+  }
+  const { parsed } = replayFromFile(opts.path);
+  const pages = groupRecordsByTurn(parsed.records);
+  const { waitUntilExit } = render3(React12.createElement(ReplayApp, { meta: parsed.meta, pages }), {
+    exitOnCtrlC: true
+  });
+  await waitUntilExit();
+}
+function printReplay(opts) {
   const { parsed, stats } = replayFromFile(opts.path);
   if (parsed.meta) {
     const m = parsed.meta;
@@ -2779,16 +3017,27 @@ program.command("stats <transcript>").description("Summarize a JSONL transcript
   statsCommand({ transcript });
 });
 program.command("replay <transcript>").description(
-  "Pretty-print a transcript + rebuild its session summary (cost, cache, prefix stability). No API calls."
-).option("--head <n>", "Show only the first N records", (v) => Number.parseInt(v, 10)).option("--tail <n>", "Show only the last N records", (v) => Number.parseInt(v, 10)).action((transcript, opts) => {
-  replayCommand({
+  "Interactive Ink TUI to scrub through a transcript + rebuild its session summary (cost, cache, prefix stability). No API calls."
+).option("--print", "Dump to stdout instead of mounting the TUI (auto when piped)").option("--head <n>", "stdout mode only \u2014 show first N records", (v) => Number.parseInt(v, 10)).option("--tail <n>", "stdout mode only \u2014 show last N records", (v) => Number.parseInt(v, 10)).action(async (transcript, opts) => {
+  await replayCommand({
     path: transcript,
+    print: !!opts.print,
     head: Number.isFinite(opts.head) ? opts.head : void 0,
     tail: Number.isFinite(opts.tail) ? opts.tail : void 0
   });
 });
-program.command("diff <a> <b>").description("Compare two transcripts: aggregate deltas + first divergence.").option("--md <path>", "Also write a markdown report (blog-ready) to this path").option("--label-a <label>", "Display label for transcript A (default: filename)").option("--label-b <label>", "Display label for transcript B (default: filename)").action((a, b, opts) => {
-  diffCommand({ a, b, mdPath: opts.md, labelA: opts.labelA, labelB: opts.labelB });
+program.command("diff <a> <b>").description(
+  "Compare two transcripts in a split-pane Ink TUI (default) or stdout table. Use n/N to jump across divergences."
+).option("--md <path>", "Write a markdown report (blog-ready) to this path").option("--print", "Force stdout table instead of the TUI (auto when piped)").option("--tui", "Force the TUI even when piped (rare)").option("--label-a <label>", "Display label for transcript A (default: filename)").option("--label-b <label>", "Display label for transcript B (default: filename)").action(async (a, b, opts) => {
+  await diffCommand({
+    a,
+    b,
+    mdPath: opts.md,
+    labelA: opts.labelA,
+    labelB: opts.labelB,
+    print: !!opts.print,
+    tui: !!opts.tui
+  });
 });
 program.command("version").description("Print Reasonix version.").action(versionCommand);
 program.parseAsync(process.argv).catch((err) => {