skalpel 4.0.35 → 4.0.36

package/analytics.mjs

@@ -0,0 +1,622 @@
+#!/usr/bin/env node
+// analytics.mjs — `skalpel analytics`: an INTERACTIVE, keyboard-navigable, LOCAL analytics view.
+//
+// WHAT IT IS: one screen over the honest data skalpel already keeps on this machine — the caught
+// lies (verify-shadow.log FALSE rows), the MEASURED red→green cost (real timestamp deltas only),
+// the steer count, and the per-session re-ask trend — navigable with ↑/↓ (or j/k), Enter to drill
+// into a catch, Esc/h/Backspace to go back, q or Ctrl-C to quit.
+//
+// HARD RED LINES (same contract as ledger.mjs / card.mjs):
+//   • READ-ONLY + LOCAL + ZERO-NETWORK. Imports only node: core + local sibling modules (their CLI
+//     blocks are isMain-guarded, so importing runs nothing). Opens no socket, re-runs no proof,
+//     writes no file. It renders what is already on disk — nothing else.
+//   • NO FABRICATED / ESTIMATED NUMBERS. Every figure reproduces from a real logged row:
+//       - caught lies   = ledger FALSE rows (mismatch:true) in verify-shadow.log
+//       - measured cost = Σ of (later same-session same-proof PASS ts − caught-FALSE ts) — real
+//         timestamps via measureFixDelta; a catch with no later PASS contributes NOTHING
+//       - steers        = count of valid JSON lines in ~/.skalpel/steers.ndjson (the append-only
+//         STEERS SOURCE CONTRACT log; one atomic line per APPLIED steer) — a COUNT only; the banned
+//         "minutes saved" metric never appears
+//       - re-ask trend  = per-session counts of recorded re-ask/interrupt resets in
+//         ~/.skalpel/insights.ndjson (metrics.ndjson rows carry no session identity, so deriving a
+//         per-session series from them would be invention — we don't)
+//     Anything absent renders as an honest "no data yet" — never a made-up zero-padded trend.
+//   • NODE CORE ONLY. No npm dependency (no ink/blessed/chalk) — a new dep is itself a
+//     cross-device + supply-chain risk for a read-only stats viewer.
+//   • THE TERMINAL IS SACRED. Non-TTY (pipe/CI) prints a plain static snapshot and exits 0 without
+//     ever touching raw mode. Interactive mode uses the ALTERNATE screen (scrollback untouched) and
+//     ONE idempotent cleanup() — raw off, cursor shown, alt-screen left, listeners removed — that
+//     runs on EVERY exit path: q/Esc/Ctrl-C, 'exit', SIGINT/SIGTERM/SIGHUP, and any thrown error.
+//   • FAIL-OPEN. Any read/parse/render error → cleanup + one honest plain line + exit 0. Never a
+//     stack trace at the user, never a hung or broken terminal.
+import { readFileSync } from "node:fs";
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { emitKeypressEvents } from "node:readline";
+// READ-ONLY reuse of the honest engine. ledger.mjs derives everything from verify-shadow.log;
+// verify-shadow.mjs single-sources the log path + the fail-count extractor. Importing either runs
+// nothing (their CLI blocks are isMain-guarded).
+import { readLedgerRows, buildLedger, measureFixDelta, formatDuration } from "./ledger.mjs";
+import { VERIFY_LOG_PATH, extractFailCount } from "./verify-shadow.mjs";
+
+// ---------- palette (the same vocabulary as ledger.mjs / card.mjs / the statusline) ----------
+const R = "\x1b[38;2;233;38;31m"; // skalpel red
+const G = "\x1b[38;2;124;184;108m"; // success green
+const CYAN = "\x1b[36m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+const SKALPEL_DIR = join(homedir(), ".skalpel");
+const STEERS_PATH = join(SKALPEL_DIR, "steers.ndjson");
+const INSIGHTS_PATH = join(SKALPEL_DIR, "insights.ndjson");
+// Bound every read so a pathological file can never OOM us (same cap as card.mjs).
+const MAX_READ_BYTES = 4 * 1024 * 1024;
+const SPARK = "▁▂▃▄▅▆▇";
+
+// ---------- sanitize (claims/evidence come from captured agent output — never trust them) ----------
+// Strip ANSI CSI sequences + other C0 control chars so logged content can never inject its own
+// escape codes into the live terminal (same defense as card.mjs), then collapse whitespace and cap.
+export function clean(s, n) {
+  const t = String(s == null ? "" : s)
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "")
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (n && t.length > n) return t.slice(0, n - 1) + "…";
+  return t;
+}
+
+// ---------- (1) gather the four panels — every number derived from real local data ----------
+// Steers: the honest count from ~/.skalpel/steers.ndjson — the append-only STEERS SOURCE CONTRACT
+// log (see skalpel-hook.mjs): one atomic line per APPLIED steer, {"ts",saved_min_delta}, never
+// rewritten. This MIRRORS the merged skalpel-statusline.mjs readState() exactly: steers = count of
+// valid JSON lines (trim, skip blank/garbage, JSON.parse guard, must be a non-null object);
+// saved_min = Σ of finite positive saved_min_delta (rounded 1 dp). Readers MUST fail open
+// (absent/unreadable → {steers:0, saved_min:0}) and MUST NOT mutate the file. The whole file is
+// read for an EXACT count (the TUI renders on demand, not every terminal tick — no hot-path cost);
+// the try/catch fails open on a huge/corrupt file, so it never hangs. The banned "minutes saved"
+// metric is never displayed — savedMin is computed only to honor the contract, not shown.
+export function readSteersState(steersPath = STEERS_PATH) {
+  try {
+    const raw = readFileSync(steersPath, "utf8");
+    let steers = 0;
+    let savedMin = 0;
+    for (const line of raw.split("\n")) {
+      const l = line.trim();
+      if (!l) continue;
+      let rec;
+      try {
+        rec = JSON.parse(l);
+      } catch {
+        continue; // a partial/garbage line — skip it (fail-open), keep counting the rest
+      }
+      if (!rec || typeof rec !== "object") continue;
+      steers += 1; // one valid line == one applied steer (append-only ⇒ exact, race-free count)
+      if (Number.isFinite(rec.saved_min_delta) && rec.saved_min_delta > 0)
+        savedMin += rec.saved_min_delta;
+    }
+    return { steers, savedMin: Math.round(savedMin * 10) / 10 };
+  } catch {
+    return { steers: 0, savedMin: 0 }; // absent/unreadable → honest zero-state (fail-open)
+  }
+}
+
+// Re-ask trend: per-session counts of recorded re-ask/interrupt resets from insights.ndjson.
+// A `kind:"reset"` row is the hook's record of a REAL detected re-ask cascade ("we've gone back
+// and forth N× — resetting"), stamped with session_id. Sessions appear in file order (the file is
+// append-only, so first appearance == chronological order); a session with rows but no resets is
+// an honest 0. metrics.ndjson is NOT a fallback: its rows ({ts,event,outcome,ms}) carry no session
+// identity and no re-ask signal, so no per-session series can be derived from it without inventing
+// one. No usable rows → null (rendered "no data yet").
+const RE_ASK_KINDS = new Set(["reset", "re_ask", "reask", "re-ask", "interrupt"]);
+export function readReaskTrend(insightsPath = INSIGHTS_PATH) {
+  let raw;
+  try {
+    raw = readFileSync(insightsPath, "utf8");
+  } catch {
+    return null;
+  }
+  if (raw.length > MAX_READ_BYTES) raw = raw.slice(-MAX_READ_BYTES);
+  const order = [];
+  const bySession = new Map();
+  for (const line of raw.split("\n")) {
+    const l = line.trim();
+    if (!l) continue;
+    let r;
+    try {
+      r = JSON.parse(l);
+    } catch {
+      continue; // partial/garbage line — skip (fail-open)
+    }
+    const sid = typeof r?.session_id === "string" && r.session_id ? r.session_id : null;
+    if (!sid) continue; // no session identity → can't attribute honestly
+    if (!bySession.has(sid)) {
+      bySession.set(sid, { session: sid, count: 0, firstTs: r.ts || null });
+      order.push(sid);
+    }
+    if (RE_ASK_KINDS.has(r.kind)) bySession.get(sid).count += 1;
+  }
+  if (order.length === 0) return null;
+  return order.map((sid) => bySession.get(sid));
+}
+
+// spark(values) → a unicode sparkline, one glyph per value, scaled to the REAL max (0 → ▁).
+export function spark(values) {
+  const max = Math.max(...values, 0);
+  return values
+    .map((v) => {
+      if (max <= 0) return SPARK[0];
+      const idx = Math.min(SPARK.length - 1, Math.round((v / max) * (SPARK.length - 1)));
+      return SPARK[Math.max(0, idx)];
+    })
+    .join("");
+}
+
+// collectData() — one read-only pass over the local files. Every field is either a real derived
+// number or null ("no data yet"). Never throws (each source fails open independently).
+export function collectData({
+  logPath = process.env.SKALPEL_LEDGER_LOG || VERIFY_LOG_PATH,
+  steersPath = STEERS_PATH,
+  insightsPath = INSIGHTS_PATH,
+} = {}) {
+  let rows = null;
+  try {
+    rows = readLedgerRows(logPath);
+  } catch {
+    rows = null;
+  }
+  let ledger = null;
+  try {
+    ledger = rows == null ? null : buildLedger(rows);
+  } catch {
+    ledger = null;
+  }
+  // Caught lies, newest first (the navigable list). Sanitize once here — content is untrusted.
+  const catches = (ledger ? [...ledger.falseEntries] : []).reverse().map((e) => ({
+    ts: e.ts,
+    session: e.session,
+    claim_text: clean(e.claim_text, 2000),
+    proof_command: clean(e.proof_command, 400),
+    evidence: clean(e.evidence, 2000),
+    fail_count: e.fail_count,
+    fix_delta_ms: e.fix_delta_ms ?? measureFixDelta(e._row, rows || [])?.ms ?? null,
+    fixed_at: e.fixed_at ?? measureFixDelta(e._row, rows || [])?.atTs ?? null,
+  }));
+  // Measured cost: Σ of REAL red→green deltas. A catch with no later same-session same-proof PASS
+  // contributes NOTHING (never estimated).
+  let costMs = 0;
+  let costPairs = 0;
+  for (const c of catches) {
+    if (c.fix_delta_ms != null && Number.isFinite(c.fix_delta_ms)) {
+      costMs += c.fix_delta_ms;
+      costPairs += 1;
+    }
+  }
+  const { steers } = readSteersState(steersPath);
+  const trend = readReaskTrend(insightsPath);
+  return {
+    logPath,
+    ledger, // null → no verify-shadow.log yet
+    catches,
+    costMs,
+    costPairs,
+    unmeasured: catches.length - costPairs,
+    steers, // count of applied-steer lines in steers.ndjson (0 when absent — fail-open, never null)
+    trend, // null → no per-session insight rows
+    empty: ledger == null && !steers && trend == null,
+  };
+}
+
+// ---------- (2) panel text (shared by the static snapshot and the interactive view) ----------
+function costLine(data) {
+  if (data.ledger == null) return "no data yet";
+  if (data.catches.length === 0) return "0 — nothing to measure";
+  if (data.costPairs === 0)
+    return `no measured red→green pair yet — ${data.catches.length} caught, none re-passed its own proof later (count only, nothing estimated)`;
+  const dur = formatDuration(data.costMs) || "<1s";
+  const excl =
+    data.unmeasured > 0
+      ? ` · ${data.unmeasured} caught without a later PASS — excluded, never estimated`
+      : "";
+  return `${dur} measured red→green across ${data.costPairs} caught lie${data.costPairs === 1 ? "" : "s"} (real timestamps)${excl}`;
+}
+
+function steersLine(data) {
+  // steers is always a finite ≥0 count (steers.ndjson reader fails open to 0, never null), so this
+  // is honestly present even at "0 (count only)" — matching the statusline's always-on `N steers`.
+  return `${data.steers} (count only)`;
+}
+
+function trendLine(data, width) {
+  if (data.trend == null) return "no data yet";
+  const n = Math.max(1, Math.min(data.trend.length, Math.max(4, width)));
+  const last = data.trend.slice(-n);
+  const counts = last.map((s) => s.count);
+  const total = counts.reduce((a, b) => a + b, 0);
+  const max = Math.max(...counts, 0);
+  return `${spark(counts)}  ${total} re-ask reset${total === 1 ? "" : "s"} across last ${last.length} session${last.length === 1 ? "" : "s"} (max ${max}/session)`;
+}
+
+function catchesHeadline(data) {
+  if (data.ledger == null) return "no data yet";
+  const { checked, falseCount } = data.ledger;
+  return `${falseCount} verified FALSE · ${checked} done-claim${checked === 1 ? "" : "s"} checked`;
+}
+
+// ---------- (3) the static snapshot (non-TTY / raw-mode-unavailable path) — plain text ----------
+export function renderStatic(data) {
+  const L = [];
+  L.push("");
+  L.push("  🔬 skalpel analytics — local, read-only, derived from your own logs");
+  L.push("  " + "─".repeat(74));
+  if (data.empty) {
+    L.push("");
+    L.push('  nothing caught yet — keep coding, I\'ll log every "done" your agent claims.');
+    L.push("");
+    L.push("  Enable the shadow with SKALPEL_VERIFY_SHADOW=1; every completion claim gets its own");
+    L.push("  proof re-run and appended to the local ledger. Nothing here is ever estimated.");
+    L.push("");
+    return L.join("\n");
+  }
+  L.push(`  CAUGHT LIES     ${catchesHeadline(data)}`);
+  for (const c of data.catches.slice(0, 5)) {
+    const failN = c.fail_count != null ? ` (${c.fail_count} failing)` : "";
+    L.push(`    · "${clean(c.claim_text, 56)}" — $ ${clean(c.proof_command, 40)}${failN}`);
+  }
+  if (data.catches.length > 5) L.push(`    …and ${data.catches.length - 5} more`);
+  L.push(`  MEASURED COST   ${costLine(data)}`);
+  L.push(`  STEERS APPLIED  ${steersLine(data)}`);
+  L.push(`  RE-ASK TREND    ${trendLine(data, 24)}`);
+  L.push("  " + "─".repeat(74));
+  L.push(`  ledger: ${data.logPath}`);
+  L.push("");
+  return L.join("\n");
+}
+
+// ---------- (4) interactive rendering helpers ----------
+// Visible-width-aware clip that PRESERVES our own CSI sequences (content is already sanitized, so
+// any escape in the string is ours). Astral code points (e.g. 🔬) budget 2 cells. Always ends with
+// RESET when styling was present so a clipped line can never bleed style into the next.
+export function clipAnsi(line, max) {
+  const s = String(line);
+  let out = "";
+  let vis = 0;
+  let i = 0;
+  let hadEsc = false;
+  while (i < s.length) {
+    if (s[i] === "\x1b") {
+      const m = /^\x1b\[[0-9;?]*[ -/]*[@-~]/.exec(s.slice(i));
+      if (m) {
+        out += m[0];
+        hadEsc = true;
+        i += m[0].length;
+        continue;
+      }
+      i += 1; // stray ESC — drop it
+      continue;
+    }
+    const cp = s.codePointAt(i);
+    const ch = String.fromCodePoint(cp);
+    const w = cp > 0xffff ? 2 : 1;
+    if (vis + w > max) break;
+    out += ch;
+    vis += w;
+    i += ch.length;
+  }
+  return hadEsc ? out + RESET : out;
+}
+
+// Plain word-wrap (content is sanitized before wrapping; long words hard-split).
+function wrapText(text, width) {
+  const w = Math.max(4, width);
+  const out = [];
+  let cur = "";
+  for (let word of String(text).split(" ")) {
+    while (word.length > w) {
+      if (cur) {
+        out.push(cur);
+        cur = "";
+      }
+      out.push(word.slice(0, w));
+      word = word.slice(w);
+    }
+    if (!word) continue;
+    if (!cur) cur = word;
+    else if (cur.length + 1 + word.length <= w) cur += " " + word;
+    else {
+      out.push(cur);
+      cur = word;
+    }
+  }
+  if (cur) out.push(cur);
+  return out.length ? out : [""];
+}
+
+function listLines(data, cols, rows, state) {
+  const L = [];
+  L.push(`  ${BOLD}🔬 skalpel analytics${RESET} ${DIM}· local · read-only · your own logs${RESET}`);
+  L.push(`  ${DIM}${"─".repeat(Math.max(4, Math.min(74, cols - 4)))}${RESET}`);
+  if (data.empty) {
+    L.push("");
+    L.push(
+      `  ${BOLD}nothing caught yet${RESET} ${DIM}— keep coding, I'll log every "done" your agent claims.${RESET}`,
+    );
+    L.push("");
+    L.push(
+      `  ${DIM}Enable the shadow with ${RESET}${BOLD}SKALPEL_VERIFY_SHADOW=1${RESET}${DIM} — every completion claim gets its${RESET}`,
+    );
+    L.push(
+      `  ${DIM}own proof re-run and appended locally. Nothing here is ever estimated.${RESET}`,
+    );
+    L.push("");
+    L.push(`  ${DIM}q quit${RESET}`);
+    return L;
+  }
+  const headline =
+    data.ledger == null
+      ? `${DIM}no data yet${RESET}`
+      : `${R}${BOLD}${data.ledger.falseCount} verified FALSE${RESET} ${DIM}· ${data.ledger.checked} done-claims checked${RESET}`;
+  L.push(`  ${CYAN}${BOLD}CAUGHT LIES${RESET}     ${headline}`);
+  // The navigable list — window it so the selection is always visible.
+  const fixedBelow = 6; // cost + steers + trend + rule + footer + breathing room
+  const capacity = Math.max(0, rows - L.length - fixedBelow);
+  const n = data.catches.length;
+  const win = Math.min(capacity, n);
+  let start = 0;
+  if (win > 0) {
+    start = Math.min(Math.max(0, state.sel - win + 1), Math.max(0, n - win));
+    if (state.sel < start) start = state.sel;
+    for (let i = start; i < start + win; i++) {
+      const c = data.catches[i];
+      const sel = i === state.sel;
+      const failN = c.fail_count != null ? ` ${DIM}(${c.fail_count} failing)${RESET}` : "";
+      const mark = sel ? `${R}▸${RESET}` : " ";
+      const claim = clean(c.claim_text, Math.max(12, Math.floor(cols * 0.45)));
+      const proof = clean(c.proof_command, Math.max(8, Math.floor(cols * 0.3)));
+      const body = `"${claim}" ${DIM}· $${RESET} ${proof}${failN}`;
+      L.push(`   ${mark} ${sel ? BOLD : ""}${body}${RESET}`);
+    }
+    if (start + win < n) L.push(`     ${DIM}…and ${n - start - win} more (↓)${RESET}`);
+  } else if (n > 0) {
+    L.push(`     ${DIM}${n} caught — terminal too small to list; drill with Enter${RESET}`);
+  }
+  L.push(`  ${CYAN}${BOLD}MEASURED COST${RESET}   ${DIM}${costLine(data)}${RESET}`);
+  L.push(`  ${CYAN}${BOLD}STEERS APPLIED${RESET}  ${DIM}${steersLine(data)}${RESET}`);
+  L.push(`  ${CYAN}${BOLD}RE-ASK TREND${RESET}    ${trendLine(data, Math.max(4, cols - 46))}`);
+  L.push(`  ${DIM}${"─".repeat(Math.max(4, Math.min(74, cols - 4)))}${RESET}`);
+  L.push(`  ${DIM}↑/↓ j/k move · Enter details · q quit${RESET}`);
+  return L;
+}
+
+function detailLines(data, cols, state) {
+  const c = data.catches[state.sel];
+  const L = [];
+  L.push(
+    `  ${BOLD}🔬 skalpel analytics${RESET} ${DIM}· caught lie ${state.sel + 1} of ${data.catches.length}${RESET}`,
+  );
+  L.push(`  ${DIM}${"─".repeat(Math.max(4, Math.min(74, cols - 4)))}${RESET}`);
+  if (!c) {
+    L.push(`  ${DIM}nothing selected${RESET}`);
+    L.push(`  ${DIM}Esc back · q quit${RESET}`);
+    return L;
+  }
+  const width = Math.max(10, cols - 6);
+  L.push(`  ${DIM}the agent claimed:${RESET}`);
+  for (const w of wrapText(`"${c.claim_text}"`, width)) L.push(`    ${BOLD}${w}${RESET}`);
+  L.push("");
+  L.push(`  ${DIM}its own proof, re-run out-of-band:${RESET}`);
+  for (const w of wrapText(`$ ${c.proof_command || "(none recorded)"}`, width)) L.push(`    ${w}`);
+  const failN = extractFailCount(c.evidence);
+  L.push(
+    `    ${R}${BOLD}→ FAIL${RESET}${failN != null ? ` ${DIM}· ${failN} failing${RESET}` : ""}`,
+  );
+  if (c.evidence) {
+    L.push("");
+    L.push(`  ${DIM}real output:${RESET}`);
+    for (const w of wrapText(c.evidence, width).slice(0, 6)) L.push(`    ${DIM}${w}${RESET}`);
+  }
+  L.push("");
+  L.push(`  ${DIM}claimed FALSE at${RESET}  ${c.ts || "unknown"}`);
+  if (c.fixed_at != null) {
+    const dur = formatDuration(c.fix_delta_ms);
+    L.push(
+      `  ${DIM}same proof PASSED${RESET} ${c.fixed_at}${dur ? ` ${G}· ${dur} later (measured, real timestamps)${RESET}` : ""}`,
+    );
+  } else {
+    L.push(`  ${DIM}no later PASS logged for this proof — count only, no time estimated.${RESET}`);
+  }
+  if (c.session) L.push(`  ${DIM}session${RESET}         ${DIM}${clean(c.session, 60)}${RESET}`);
+  L.push(`  ${DIM}${"─".repeat(Math.max(4, Math.min(74, cols - 4)))}${RESET}`);
+  L.push(`  ${DIM}j/k scroll · Esc/h back · q quit${RESET}`);
+  return L;
+}
+
+// ---------- (5) the interactive loop — event-driven only, terminal always restored ----------
+function runInteractive(data) {
+  const state = { view: "list", sel: 0, scroll: 0 };
+  let cleaned = false;
+  let pendingDraw = null;
+
+  // ONE cleanup, idempotent, never throws — every exit path funnels through it.
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    try {
+      if (pendingDraw) clearImmediate(pendingDraw);
+    } catch {
+      /* never throw from cleanup */
+    }
+    try {
+      if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    } catch {
+      /* raw mode already off / stdin gone */
+    }
+    try {
+      process.stdout.write("\x1b[?25h\x1b[?1049l"); // show cursor + leave the alternate screen
+    } catch {
+      /* stdout gone — nothing to restore onto */
+    }
+    try {
+      process.stdin.removeAllListeners("keypress");
+      process.stdout.removeAllListeners("resize");
+      process.removeAllListeners("SIGWINCH");
+      process.removeAllListeners("SIGINT");
+      process.removeAllListeners("SIGTERM");
+      process.removeAllListeners("SIGHUP");
+      process.stdin.pause();
+    } catch {
+      /* best-effort */
+    }
+  };
+
+  const die = (msg) => {
+    cleanup();
+    try {
+      process.stdout.write(`${msg}\n`);
+    } catch {
+      /* nothing left to say it to */
+    }
+    process.exit(0);
+  };
+
+  // Raw mode inside try/catch — if the terminal can't do it, fall back to the static snapshot.
+  try {
+    process.stdin.setRawMode(true);
+  } catch {
+    process.stdout.write(renderStatic(data) + "\n");
+    process.exit(0);
+  }
+
+  try {
+    process.on("exit", cleanup); // the backstop: no exit path escapes restoration
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+      process.on(sig, () => {
+        cleanup();
+        process.exit(0);
+      });
+    }
+    process.on("uncaughtException", () => die("skalpel analytics — could not render analytics"));
+    process.on("unhandledRejection", () => die("skalpel analytics — could not render analytics"));
+
+    process.stdout.write("\x1b[?1049h\x1b[?25l"); // alternate screen + hidden cursor
+
+    const draw = () => {
+      try {
+        const cols = Math.max(10, process.stdout.columns || 80);
+        const rowsN = Math.max(3, process.stdout.rows || 24);
+        const lines =
+          state.view === "detail"
+            ? detailLines(data, cols, state)
+            : listLines(data, cols, rowsN, state);
+        // Detail view scrolls when taller than the terminal (keep the footer reachable).
+        let visible = lines;
+        if (state.view === "detail" && lines.length > rowsN) {
+          const maxScroll = lines.length - rowsN;
+          state.scroll = Math.min(Math.max(0, state.scroll), maxScroll);
+          visible = lines.slice(state.scroll, state.scroll + rowsN);
+        } else {
+          visible = lines.slice(0, rowsN);
+        }
+        const body = visible.map((l) => clipAnsi(l, cols - 1)).join("\r\n");
+        process.stdout.write("\x1b[H\x1b[2J" + body);
+      } catch {
+        die("skalpel analytics — could not render analytics");
+      }
+    };
+
+    // Coalesce resize bursts through ONE unref'd immediate — event-driven, never a poll loop.
+    const scheduleDraw = () => {
+      if (pendingDraw) return;
+      pendingDraw = setImmediate(() => {
+        pendingDraw = null;
+        draw();
+      });
+      if (pendingDraw && typeof pendingDraw.unref === "function") pendingDraw.unref();
+    };
+
+    emitKeypressEvents(process.stdin);
+    process.stdin.resume();
+    process.stdin.on("keypress", (str, key) => {
+      try {
+        const k = key || {};
+        const name = k.name || str || "";
+        if ((k.ctrl && name === "c") || name === "q") {
+          cleanup();
+          process.exit(0);
+        }
+        if (state.view === "list") {
+          if (name === "up" || name === "k") state.sel = Math.max(0, state.sel - 1);
+          else if (name === "down" || name === "j")
+            state.sel = Math.min(Math.max(0, data.catches.length - 1), state.sel + 1);
+          else if (name === "return" || name === "enter") {
+            if (data.catches.length > 0) {
+              state.view = "detail";
+              state.scroll = 0;
+            }
+          } else if (name === "escape") {
+            cleanup();
+            process.exit(0);
+          }
+        } else {
+          if (name === "escape" || name === "backspace" || name === "h") {
+            state.view = "list";
+            state.scroll = 0;
+          } else if (name === "up" || name === "k") state.scroll = Math.max(0, state.scroll - 1);
+          else if (name === "down" || name === "j") state.scroll += 1; // clamped in draw()
+        }
+        scheduleDraw();
+      } catch {
+        die("skalpel analytics — could not render analytics");
+      }
+    });
+    process.stdout.on("resize", scheduleDraw); // node's SIGWINCH surface
+    process.on("SIGWINCH", scheduleDraw); // belt-and-suspenders (no-op where unsupported)
+
+    draw();
+  } catch {
+    die("skalpel analytics — could not render analytics");
+  }
+}
+
+// ---------- CLI ----------
+const isMain = (() => {
+  try {
+    return (
+      Boolean(process.argv[1]) &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  let data;
+  try {
+    data = collectData();
+  } catch {
+    process.stdout.write("\nskalpel analytics — no data yet\n\n");
+    process.exit(0);
+  }
+  // NON-TTY DEGRADE (pipes, CI, dumb harnesses): plain static snapshot, exit 0, raw mode untouched.
+  if (!process.stdout.isTTY || !process.stdin.isTTY) {
+    try {
+      process.stdout.write(renderStatic(data) + "\n");
+    } catch {
+      /* a closed pipe still exits 0 */
+    }
+    process.exit(0);
+  }
+  // A totally-fresh machine has nothing to navigate — print the honest empty screen and exit clean
+  // rather than opening an interactive view over four "no data yet" panels.
+  if (data.empty) {
+    process.stdout.write(renderStatic(data) + "\n");
+    process.exit(0);
+  }
+  runInteractive(data);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "4.0.35",
+  "version": "4.0.36",
   "description": "Behavioral graph for AI-assisted coding — learns how you work and steers Claude Code + Codex in real time.",
   "type": "module",
   "bin": {

package/skalpel-setup.mjs

@@ -64,6 +64,7 @@ const KNOWN_SUBS = new Set([
   "catches",
   "card",
   "ledger",
+  "analytics",
   "__build",
   "__verify-report",
 ]);
@@ -81,6 +82,7 @@ usage:
   skalpel catches                               scan your own history for "done" claims over failing tests
   skalpel card [--last|--id <id>] [--md]        share one verified catch: the claim + its own failing proof
   skalpel ledger                                your running tally: N "done"s checked, M verified FALSE
+  skalpel analytics                             interactive local analytics — caught lies, measured cost, steers, re-asks
   skalpel uninstall [--purge]                   remove the hooks + local data from this machine
 
 options:
@@ -906,6 +908,14 @@ async function main() {
     spawnSync("node", [join(__dir, "ledger.mjs"), ...argv.slice(1)], { stdio: "inherit" });
     return;
   }
+  // `skalpel analytics` — INTERACTIVE LOCAL ANALYTICS: a keyboard-navigable, READ-ONLY terminal view
+  // derived from the same honest local data as `skalpel ledger` (verify-shadow.log + steers.ndjson +
+  // insights.ndjson). Zero network, zero writes, zero estimates. Degrades to a plain static snapshot
+  // when stdin/stdout isn't a TTY, and restores the terminal on every exit path.
+  if (sub === "analytics") {
+    spawnSync("node", [join(__dir, "analytics.mjs"), ...argv.slice(1)], { stdio: "inherit" });
+    return;
+  }
   // `skalpel __verify-report` — the claim-verification SHADOW instrument: reads the local
   // verify-shadow.log and prints the three numbers (claim fire-rate, proof-reconstruction rate, and the
   // headline MISMATCH rate = how often the agent claimed done but its OWN proof, re-run, failed).