skalpel 4.0.35 → 4.0.37

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/autopsy.mjs

@@ -275,6 +275,7 @@ function parseClaudeSession(file, rootDir) {
       turns.push({
         session_id: sessionId,
         root: rootDir,
+        rootRaw: typeof o.cwd === "string" && o.cwd ? o.cwd : null, // real cwd for same-file identity
         role,
         turn_idx: idx++,
         ts: o.timestamp || null,
@@ -365,6 +366,7 @@ function parseCodexSession(file) {
   const turns = raw.map((t, idx) => ({
     session_id: sessionId,
     root: rootDir,
+    rootRaw: cwd || null, // real cwd from session_meta.payload.cwd for same-file identity
     role: t.role,
     turn_idx: idx,
     ts: t.ts,
@@ -696,18 +698,22 @@ function projTail(root) {
 // SAME ACTUAL FILE — not a shared basename. Returns a normalized absolute path, or null when the
 // mention cannot be pinned to a real file:
 //   • absolute path in the text        → that path IS the identity (works across every vendor).
-//   • relative path WITH a directory    → resolved against the session's project root (cwd), but ONLY
-//                                         when that root is a real project (never the home catch-all,
-//                                         and never Cursor's rootless bubbles) — otherwise unknowable.
+//   • relative path WITH a directory    → resolved against the session's RAW project cwd (rootRaw), but
+//                                         ONLY when that cwd is known and is a real project (never the
+//                                         home catch-all, and never Cursor's rootless bubbles) —
+//                                         otherwise unknowable.
 //   • bare basename (no directory)      → null. A basename alone can never prove same-file.
-function resolveFileIdentity(rawPath, abs, root) {
+// NOTE: identity MUST anchor on the raw, undecoded cwd — never decodeRoot(), whose lossy `-`→`/`
+// round-trip can fabricate a path that is not on disk (a hyphen in a real dir name becomes a
+// separator) or false-join two distinct projects whose decoded forms collide. decodeRoot stays for
+// DISPLAY labels only.
+function resolveFileIdentity(rawPath, abs, rootRaw) {
   if (!rawPath) return null;
   if (abs) return path.posix.normalize("/" + rawPath.replace(/^\/+/, ""));
   if (!rawPath.includes("/")) return null; // bare basename — not a same-file proof
   if (/^\.\.?\//.test(rawPath)) return null; // "./x" or "../x": ambiguous relative to an unknown subdir
-  const base = decodeRoot(root); // "" when root is null (Cursor) or unknown
-  if (!base || base === HOME) return null; // no real project root to anchor a relative path against
-  return path.posix.normalize(base.replace(/\/+$/, "") + "/" + rawPath);
+  if (!rootRaw || rootRaw === HOME) return null; // cwd unknown (Cursor/Aider) or home catch-all — unknowable
+  return path.posix.normalize(rootRaw.replace(/\/+$/, "") + "/" + rawPath);
 }
 // Detect any email (incl. TLDs truncated by the 200-char span slice, e.g. "name@host.c" or "name@host").
 const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9][A-Za-z0-9.-]*/g;
@@ -1073,7 +1079,7 @@ async function main() {
         if (errOnly && !kind.startsWith("err")) continue;
         // ---- same-file identity index (message text only; tool output is skipped above) ----
         if (kind === "sym:file") {
-          const identity = resolveFileIdentity(ex.rawPath, ex.abs, turn.root);
+          const identity = resolveFileIdentity(ex.rawPath, ex.abs, turn.rootRaw);
           if (identity) {
             if (!filePathMap.has(identity))
               filePathMap.set(identity, { basename: anchor, byTool: new Map() });

package/package.json

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

package/reveal.mjs

@@ -8,9 +8,10 @@
 // Tone: this is the first time the user is seeing what skalpel learned about them, so the note directs
 // the model to TEACH them their own pattern in plain, warm English — never the internal notation, never
 // a stats dump.
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { REVEAL_PATH, revealEnabled, cleanText } from "./insights.mjs";
 
 export function graphReadyNote() {
   const p = join(homedir(), ".skalpel", "insights-ready.json");
@@ -78,3 +79,83 @@ export function graphReadyNote() {
     `actually asked. Keep the whole thing short and human.]`
   );
 }
+
+// ---- verify catch: the AGENT-facing half of the opt-in "aha catch" (SKALPEL_VERIFY_REVEAL) ----------
+//
+// verify-shadow.mjs re-runs the agent's OWN cited proof out of band; on a GENUINE_FAIL mismatch (it
+// claimed "done", its own test/build REALLY failed) it writes ~/.skalpel/verify-reveal.json. The
+// statusline renders that catch as an AMBIENT line the USER can miss within its TTL. This surfaces the
+// SAME catch to the AGENT deterministically, in the NEXT turn's additionalContext, so the model corrects
+// itself instead of standing by a false "done" — the mechanical nudge, not a line someone has to notice.
+//
+// The notified marker: the reveal file records the ts of the failing re-run; we remember the last ts we
+// told the agent about so each distinct catch fires EXACTLY ONCE. It therefore persists across turns until
+// it is injected once OR verify-shadow retracts the reveal on a later PASS — never a 90s TTL that lapses
+// unseen. Scoped to the SAME session that produced the claim, so a stale cross-session catch never fires.
+const NOTIFIED_PATH = join(homedir(), ".skalpel", "verify-reveal-notified.json");
+
+// verifyCatchNote(env, sessionId) -> the bracketed model directive, or null.
+// HONESTY RED LINES (mirrors verify-shadow's reveal): every word traces to the REAL reveal record —
+// the real claim text, the real reconstructed proof command, the real captured failure tail, and a
+// failing COUNT only when the runner actually printed one (r.fail_count is null otherwise). NO fabricated
+// numbers. HARNESS_ERROR (timeout / missing script / wrong cwd) never reaches the reveal file, so this
+// never cries wolf. GATED on SKALPEL_VERIFY_REVEAL: OFF (default) → returns null BEFORE touching disk, so
+// the hook's additionalContext stays byte-identical. Fail-open: any error → null.
+export function verifyCatchNote(env, sessionId) {
+  try {
+    if (!revealEnabled(env)) return null; // opt-in; default OFF → byte-identical, no disk touch
+    let r;
+    try {
+      r = JSON.parse(readFileSync(REVEAL_PATH, "utf8"));
+    } catch {
+      return null; // no catch pending
+    }
+    if (!r || typeof r !== "object" || !r.ts) return null;
+    // Only tell the AGENT about a catch from ITS OWN session — never a stale cross-session one.
+    const sid = sessionId ? String(sessionId) : "";
+    if (!sid || !r.session || String(r.session) !== sid) return null;
+    // Fire at most once per distinct catch (keyed by the failing re-run's ts).
+    try {
+      if (JSON.parse(readFileSync(NOTIFIED_PATH, "utf8"))?.ts === r.ts) return null;
+    } catch {
+      /* no marker yet — first time we've seen this catch */
+    }
+    // Record that we've now notified the agent about THIS catch BEFORE returning the note, so it fires
+    // once. If we can't persist the marker, DROP the note (same one-shot discipline as graphReadyNote /
+    // the auth-expiry note) — better to miss it once than re-inject every turn.
+    try {
+      mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+      const tmp = `${NOTIFIED_PATH}.tmp`;
+      writeFileSync(tmp, JSON.stringify({ ts: r.ts }));
+      renameSync(tmp, NOTIFIED_PATH);
+    } catch {
+      return null;
+    }
+    // Build the directive from REAL fields only (cleanText strips any control chars; slices bound length).
+    const proof =
+      cleanText(String(r.proof_command || ""))
+        .trim()
+        .slice(0, 120) || "its own proof";
+    const claim =
+      cleanText(String(r.claim_text || ""))
+        .trim()
+        .slice(0, 120) || "it's done";
+    const failN =
+      Number.isFinite(r.fail_count) && r.fail_count > 0 ? ` (${r.fail_count} failing)` : "";
+    const evidence = cleanText(String(r.evidence || ""))
+      .trim()
+      .slice(0, 160);
+    return (
+      `[skalpel — a claim-check just RE-RAN the proof you cited and it FAILED. After your last ` +
+      `"${claim}"-type message, skalpel re-ran \`${proof}\` out of band and it did NOT pass${failN}. ` +
+      `This is YOUR OWN test/build re-run independently — not a new opinion, not a flaky guess. Do NOT ` +
+      `tell the user the work is done. Open with ONE short line — "🔬 skalpel · I re-ran \`${proof}\` ` +
+      `and it still fails${failN} — not done yet" — then actually diagnose and fix the failure before ` +
+      `you claim completion again.` +
+      (evidence ? ` The real failing output tail was: ${evidence}` : "") +
+      `]`
+    );
+  } catch {
+    return null; // fail-open: the catch note is a bonus, never break the hook
+  }
+}

package/skalpel-hook.mjs

@@ -14,7 +14,7 @@ import { join } from "node:path";
 import { identity } from "./auth.mjs";
 import { record } from "./metrics.mjs";
 import { recordInsight, cleanText, revealEnabled } from "./insights.mjs";
-import { graphReadyNote } from "./reveal.mjs";
+import { graphReadyNote, verifyCatchNote } from "./reveal.mjs";
 import { tailLines } from "./transcript.mjs";
 
 // Tail budget for the two transcript scans below (last-prompt + cascade). Both only ever look at the
@@ -770,12 +770,15 @@ async function main() {
       session_id: sessionId,
     });
 
-  // A just-finished background build leads (one-shot: surface "your graph's ready" the instant the next
-  // prompt fires, so the user doesn't have to restart a session to see it), then the one-time auth-expiry
-  // note, then ackNote (feedback confirmation), the reset interrupt (most acute), and the server steer.
-  // Any can fire alone.
+  // The AGENT-facing "aha catch" (opt-in, SKALPEL_VERIFY_REVEAL) LEADS: if verify-shadow's detached
+  // re-run caught the agent claiming "done" while its OWN proof GENUINELY failed, tell the agent so it
+  // corrects itself instead of a user having to notice an ambient statusline line. Fires once per catch,
+  // scoped to this session; returns null (byte-identical) when the flag is off. Then a just-finished
+  // background build ("your graph's ready", one-shot), the one-time auth-expiry note, ackNote (feedback
+  // confirmation), the reset interrupt (most acute), and the server steer. Any can fire alone.
+  const verifyNote = verifyCatchNote(process.env, sessionId);
   const readyNote = graphReadyNote();
-  const additionalContext = [readyNote, authNote, ackNote, resetNote, injection]
+  const additionalContext = [verifyNote, readyNote, authNote, ackNote, resetNote, injection]
     .filter(Boolean)
     .join("\n\n");
   if (additionalContext) {

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).

package/verify-shadow.mjs

@@ -384,12 +384,23 @@ function resolveCd(baseCwd, dir) {
   return path.isAbsolute(d) ? path.normalize(d) : path.resolve(baseCwd || process.cwd(), d);
 }
 
+// SHARP-4: a leading `cd <dir>` must not move the re-run OUTSIDE the session's base cwd. An out-of-tree
+// cwd (absolute or `..` escape) would execute an attacker-planted package.json script / Cargo build.rs /
+// eslint config as code — exactly the out-of-band execution the flag check (argsRedirectOutOfTree) blocks.
+// Mirrors isPathEscape's guarantee for the resolved cwd itself. base is never null here → no resolve throw.
+function cwdEscapesBase(cwd, base) {
+  const c = path.resolve(cwd);
+  const b = path.resolve(base);
+  return c !== b && !c.startsWith(b + path.sep);
+}
+
 // parseCommandForProof(command, baseCwd) -> { cmd, args, cwd } | null
 // Walks the segments of ONE shell command; honors a leading `cd <dir>` (sets the re-run cwd) and returns
 // the first allowlisted invocation found. Args are the cleaned literal tokens (no shell interpretation).
 export function parseCommandForProof(command, baseCwd) {
   if (!command || typeof command !== "string") return null;
-  let cwd = baseCwd || process.cwd();
+  const base = baseCwd || process.cwd();
+  let cwd = base;
   for (const rawTokens of splitSegments(command)) {
     const toks = cleanSegment(rawTokens);
     if (!toks.length) continue;
@@ -399,7 +410,8 @@ export function parseCommandForProof(command, baseCwd) {
     }
     const cmd = toks[0];
     const args = toks.slice(1, 65).map((t) => String(t).slice(0, 4096)); // bound arg count + length
-    if (isAllowedProof(cmd, args)) return { cmd, args, cwd };
+    // SHARP-4: refuse an out-of-tree cwd (from a `cd` escape) just as we refuse out-of-tree path flags.
+    if (isAllowedProof(cmd, args)) return cwdEscapesBase(cwd, base) ? null : { cmd, args, cwd };
   }
   return null;
 }