skalpel 4.0.30 → 4.0.32

package/card.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// card.mjs — THE CATCH CARD: `skalpel card`.
+//
+// THE PROBLEM (same root as verify-shadow / catches): your agent is both the executor AND the reporter
+// of its own work, so when it says "done / tests pass" nothing independent re-checks. verify-shadow
+// already closes that loop LIVE and logs the real verdict. THIS turns a single, already-verified catch
+// into a clean, copy-pasteable artifact you can drop into Slack / a PR / X — so the moment the agent
+// gets caught is shareable, and it's the AGENT that's on the hook, never you.
+//
+// WHAT IT IS: a one-command render of the MOST RECENT genuine catch (a GENUINE_FAIL row) that
+// verify-shadow already wrote to ~/.skalpel/verify-shadow.log. The card carries ONLY what the real row
+// holds: the agent's verbatim completion claim, the exact proof/probe command skalpel re-ran, the real
+// verdict (FAIL — the proof exited non-zero; plus a real exit code / HTTP status / failing-count ONLY
+// when the captured output literally contains one), the verbatim tail of the real output, and the real
+// timestamp. Nothing else — no summaries, no aggregates, no cross-model claims, no minutes.
+//
+// HARD RED LINES (why this is safe + honest):
+//   • READ-ONLY over verify-shadow's OWN output. It only READS ~/.skalpel/verify-shadow.log. It NEVER
+//     re-runs a proof, spawns, builds, writes, deploys, or mutates anything, and opens no socket.
+//   • OPT-IN. User-invoked subcommand; prints and exits. The per-turn hook is untouched (byte-identical
+//     when the shadow is off — this file is never imported by the hook path).
+//   • VERIFIED CATCHES ONLY. It renders a row ONLY if that row is a GENUINE_FAIL (the agent's own
+//     test/build/lint really ran and exited non-zero). A HARNESS_ERROR (timeout / missing-script /
+//     wrong-cwd) is proof-machinery noise, never a catch, and is never rendered — we never cry wolf.
+//   • NO FABRICATED NUMBERS. Every value on the card traces to a real field of the real row. The banned
+//     "minutes saved / lost" metric never appears. An exit code / HTTP status / failing count is shown
+//     ONLY when the row's own captured output literally contains it. If there is no catch to show, it
+//     SAYS so honestly — it never invents one.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+import { VERIFY_LOG_PATH, extractFailCount } from "./verify-shadow.mjs";
+
+// Bound the read so a pathological log can never OOM us (verify-shadow already trims to ~1MB/500 lines).
+const MAX_LOG_BYTES = 4 * 1024 * 1024;
+
+// ---------- palette (matches the statusline / setup) ----------
+const R = "\x1b[38;2;233;38;31m"; // skalpel red
+const D = "\x1b[2m";
+const B = "\x1b[1m";
+const X = "\x1b[0m";
+
+// ---------- sanitize (values come from real captured output — strip any control/ANSI bytes) ----------
+// The claim / proof / evidence are captured from the agent's transcript + test output; they must never
+// be able to inject their own escape codes into the terminal or a pasted card. Strip ESC + other C0
+// control chars (keep normal whitespace which we then collapse), and cap length.
+function clean(s, n) {
+  const t = String(s == null ? "" : s)
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "") // ANSI CSI sequences
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, " ") // other control chars → space
+    .replace(/\s+/g, " ")
+    .trim();
+  if (n && t.length > n) return t.slice(0, n - 1) + "…";
+  return t;
+}
+
+// ---------- (1) read + select the catch ----------
+// A row is a genuine catch iff the agent's OWN proof really ran and exited non-zero. verify-shadow
+// records that as outcome==="GENUINE_FAIL" (pass_fail==="FAIL"). HARNESS_ERROR / PASS / no-proof rows
+// are never catches. We tolerate a future "ship-FAIL" label defensively but still exclude harness noise.
+export function isGenuineCatch(row) {
+  if (!row || typeof row !== "object") return false;
+  if (row.outcome === "HARNESS_ERROR" || row.pass_fail === "HARNESS_ERROR") return false;
+  const failed = row.outcome === "GENUINE_FAIL" || row.pass_fail === "FAIL";
+  // A real catch must carry the two things the card indicts the agent with: what it claimed, and the
+  // proof that contradicts it. A row missing either can't be rendered honestly, so it isn't a catch.
+  return failed && !!row.proof_command && !!row.claim_text;
+}
+
+// readCatches() → all genuine-catch rows in the shadow log, oldest→newest as written. Fail-open: any
+// read/parse error yields [] (rendered as the honest "no catches yet" state).
+export function readCatches(logPath = VERIFY_LOG_PATH) {
+  let raw;
+  try {
+    raw = readFileSync(logPath, "utf8");
+  } catch {
+    return [];
+  }
+  if (raw.length > MAX_LOG_BYTES) raw = raw.slice(-MAX_LOG_BYTES);
+  const out = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue; // partial/garbage line — skip
+    }
+    if (isGenuineCatch(row)) out.push(row);
+  }
+  return out;
+}
+
+// selectCatch({ id }) → the catch to render: the newest overall, or (with --id) the newest for that
+// session id. Returns null when there is nothing genuine to show. `catches` is injectable for tests.
+export function selectCatch({ id = null, catches = null, logPath = VERIFY_LOG_PATH } = {}) {
+  const rows = catches || readCatches(logPath);
+  if (!rows.length) return null;
+  const pool = id ? rows.filter((r) => r.session === id) : rows;
+  if (!pool.length) return null;
+  return pool[pool.length - 1]; // rows are append-ordered → last is newest
+}
+
+// ---------- (2) honest verdict extraction ----------
+// A GENUINE_FAIL means, by verify-shadow's own classifyOutcome, that the proof PROCESS exited non-zero
+// (not a timeout, not command-not-found, not a missing script — those are HARNESS_ERROR). So
+// "exited non-zero" is always provably true for a catch row. Beyond that, we surface a SPECIFIC code
+// ONLY when the real captured output literally printed one — never invented.
+export function extractCode(evidence) {
+  const s = String(evidence || "");
+  // HTTP status first (auth/proxy/API proofs surface these): "HTTP/1.1 500", "status: 503",
+  // "responded with 429", "got 401". Only 1xx–5xx are treated as a status.
+  const http = s.match(
+    /\b(?:HTTP\/\d(?:\.\d)?\s+|status(?:\s+code)?[:\s]+|responded with\s+|returned\s+|got\s+)(\d{3})\b/i,
+  );
+  if (http) {
+    const n = Number.parseInt(http[1], 10);
+    if (n >= 100 && n < 600) return { kind: "http", value: n };
+  }
+  // Process exit code: "exit code 1", "exited with code 2", "Process exited with code 1".
+  const exit = s.match(/exit(?:ed)?(?:\s+with)?\s+(?:code\s+)?(\d{1,3})\b/i);
+  if (exit) {
+    const n = Number.parseInt(exit[1], 10);
+    if (Number.isFinite(n)) return { kind: "exit", value: n };
+  }
+  return null;
+}
+
+// verdictPhrase(row) → the honest one-line verdict. Always truthful for a catch row.
+function verdictPhrase(row) {
+  const code = extractCode(row.evidence);
+  const failN = extractFailCount(row.evidence);
+  const count = failN != null ? ` · ${failN} failing` : "";
+  if (code && code.kind === "http") return `FAIL — its own proof got HTTP ${code.value}${count}`;
+  if (code && code.kind === "exit") return `FAIL — its own proof exited ${code.value}${count}`;
+  return `FAIL — its own proof re-ran and exited non-zero${count}`;
+}
+
+// Human timestamp: keep the real ISO instant (never fabricated); show it verbatim.
+function stamp(ts) {
+  const s = clean(ts, 40);
+  return s || "unknown time";
+}
+
+// ---------- (3a) plain-text card (no ANSI — the shareable artifact) ----------
+export function renderPlainCard(row) {
+  const claim = clean(row.claim_text, 200) || "it's done";
+  const proof = clean(row.proof_command, 200) || "its own proof";
+  const evidence = clean(row.evidence, 200);
+  const L = [];
+  L.push("🔬 skalpel — verified catch");
+  L.push("");
+  L.push("The agent claimed:");
+  L.push(`  "${claim}"`);
+  L.push("");
+  L.push("skalpel re-ran the agent's OWN proof, out-of-band:");
+  L.push(`  $ ${proof}`);
+  L.push(`  → ${verdictPhrase(row)}`);
+  if (evidence) {
+    L.push("");
+    L.push("real output (verbatim):");
+    L.push(`  ${evidence}`);
+  }
+  L.push("");
+  L.push(`caught ${stamp(row.ts)}`);
+  L.push("The agent said done. Its own proof, re-run, disagreed.");
+  return L.join("\n");
+}
+
+// ---------- (3b) markdown card (Slack / PR / X) ----------
+export function renderMarkdownCard(row) {
+  const claim = clean(row.claim_text, 200) || "it's done";
+  const proof = clean(row.proof_command, 200) || "its own proof";
+  const evidence = clean(row.evidence, 200);
+  const FENCE = "```";
+  const L = [];
+  L.push("**🔬 skalpel — verified catch**");
+  L.push("");
+  L.push(`> The agent claimed: _"${claim}"_`);
+  L.push("");
+  L.push("skalpel re-ran the agent's own proof, out-of-band:");
+  L.push(FENCE);
+  L.push(`$ ${proof}`);
+  L.push(`→ ${verdictPhrase(row)}`);
+  L.push(FENCE);
+  if (evidence) {
+    L.push("real output (verbatim):");
+    L.push(FENCE);
+    L.push(evidence);
+    L.push(FENCE);
+  }
+  L.push(`_Caught ${stamp(row.ts)}. The agent said done; its own proof, re-run, disagreed._`);
+  return L.join("\n");
+}
+
+// ---------- (3c) styled terminal card ----------
+function renderTerminalCard(row) {
+  const claim = clean(row.claim_text, 200) || "it's done";
+  const proof = clean(row.proof_command, 200) || "its own proof";
+  const evidence = clean(row.evidence, 180);
+  const L = [];
+  L.push("");
+  L.push(`  ${B}🔬 skalpel${X} ${D}·${X} ${B}${R}verified catch${X}`);
+  L.push(`  ${D}${"─".repeat(70)}${X}`);
+  L.push(`  ${D}The agent claimed:${X}`);
+  L.push(`    ${B}"${claim}"${X}`);
+  L.push("");
+  L.push(`  ${D}skalpel re-ran the agent's OWN proof, out-of-band:${X}`);
+  L.push(`    ${D}$${X} ${proof}`);
+  L.push(`    ${R}${B}→ ${verdictPhrase(row)}${X}`);
+  if (evidence) {
+    L.push("");
+    L.push(`  ${D}real output:${X} ${evidence}`);
+  }
+  L.push(`  ${D}${"─".repeat(70)}${X}`);
+  L.push(
+    `  ${D}caught ${stamp(row.ts)} — the agent said done; its own proof, re-run, disagreed.${X}`,
+  );
+  L.push("");
+  return L.join("\n");
+}
+
+// ---------- (4) the honest empty state ----------
+function renderNoCatch({ id }) {
+  const L = [];
+  L.push("");
+  L.push(`  ${B}🔬 skalpel card${X}`);
+  L.push(`  ${D}${"─".repeat(70)}${X}`);
+  if (id) {
+    L.push(`  ${D}No verified catch found for session ${clean(id, 60)}.${X}`);
+  } else {
+    L.push(`  ${D}No verified catch to show yet.${X}`);
+  }
+  L.push("");
+  L.push(
+    `  ${D}A card is minted only from a REAL catch — a turn where your agent claimed "done"${X}`,
+  );
+  L.push(
+    `  ${D}and skalpel re-ran its OWN proof and it genuinely FAILED. Nothing is invented.${X}`,
+  );
+  L.push("");
+  L.push(
+    `  ${D}Turn the live shadow on with ${X}${B}SKALPEL_VERIFY_SHADOW=1${X}${D}, keep coding, and${X}`,
+  );
+  L.push(`  ${D}run ${X}${B}skalpel card${X}${D} again the next time a claim doesn't hold up.${X}`);
+  L.push("");
+  return L.join("\n");
+}
+
+// ---------- (5) top-level render (used by CLI + tests) ----------
+// format ∈ { "terminal" (default), "md", "plain" }. Returns the string to print. `catches` injectable.
+export function renderCard({ id = null, format = "terminal", catches = null } = {}) {
+  const row = selectCatch({ id, catches });
+  if (!row) return renderNoCatch({ id });
+  if (format === "md") return renderMarkdownCard(row);
+  if (format === "plain") return renderPlainCard(row);
+  // Default terminal view = the styled card, followed by a copy-pasteable markdown block for sharing.
+  return (
+    renderTerminalCard(row) +
+    "\n" +
+    `  ${D}copy for Slack / a PR / X ${X}${D}(or: ${X}${B}skalpel card --md | pbcopy${X}${D}):${X}\n\n` +
+    renderMarkdownCard(row) +
+    "\n"
+  );
+}
+
+// ---------- CLI ----------
+function parseArgs(argv) {
+  let id = null;
+  let format = "terminal";
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--last")
+      continue; // newest catch (the default) — accepted for explicitness
+    else if (a === "--id") {
+      id = argv[i + 1] && !argv[i + 1].startsWith("-") ? argv[++i] : null;
+    } else if (a.startsWith("--id=")) id = a.slice("--id=".length);
+    else if (a === "--md" || a === "--markdown") format = "md";
+    else if (a === "--plain" || a === "--text") format = "plain";
+  }
+  return { id, format };
+}
+
+const isMain = (() => {
+  try {
+    return (
+      Boolean(process.argv[1]) &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  try {
+    const { id, format } = parseArgs(process.argv.slice(2));
+    process.stdout.write(renderCard({ id, format }) + "\n");
+  } catch {
+    // READ-ONLY + fail-open: never throw at the user.
+    process.stdout.write("\n  🔬 skalpel — could not read your catch log on this machine.\n\n");
+  }
+  process.exit(0);
+}

package/ledger.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+// ledger.mjs — the PERSONAL TRUTH LEDGER: `skalpel ledger`.
+//
+// THE PROBLEM: your agent is both the executor AND the reporter of its own work. Every "done / tests
+// pass / fixed" it emits is a CLAIM. The claim-verification SHADOW (verify-shadow.mjs) already re-runs
+// the session's OWN proof on each such claim and appends one honest row per claim to
+// ~/.skalpel/verify-shadow.log. That file is already an APPEND-ONLY, LOCAL history of every
+// claim -> verdict. What was missing was a VIEW: the running personal tally of how many "done"s were
+// checked and how many were caught FALSE, with the receipts.
+//
+// THIS is that view. It DERIVES entirely from verify-shadow.log — it NEVER re-runs a proof, NEVER writes
+// a second copy of the history (no double-write), NEVER touches the network, and NEVER touches the
+// per-turn hook. It is a user-invoked, read-only subcommand: opt-in by construction, dark by default,
+// byte-identical to before when not invoked.
+//
+// HARD RED LINES (why this is safe + honest):
+//   • DERIVED, NOT DOUBLE-WRITTEN. The append-only ledger IS verify-shadow.log (written by the shadow).
+//     This module only READS it and renders a view. It writes no ledger file of its own.
+//   • READ-ONLY + LOCAL. Imports only node: core + local sibling modules. Opens no socket. Re-runs nothing
+//     (the pass/fail is the verdict the shadow already recorded).
+//   • NO FABRICATED / ESTIMATED NUMBERS. Every count is a real tally over real logged rows. The ONLY time
+//     figure shown is a MEASURED wall-clock delta between two REAL logged timestamps — the moment a "done"
+//     was caught FALSE (mismatch row) and the moment that SAME proof, in that SAME session, was later
+//     logged PASS. If no such later PASS exists, we show the count ONLY — never an estimate, never a
+//     "minutes saved / lost" tally (that metric stays DEAD).
+//   • FAIL-OPEN. Any read/parse error yields an honest zero-state, never a throw at the user.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+// READ-ONLY reuse of the shadow's single-sourced log path + its honest fail-count extractor. Importing
+// verify-shadow.mjs runs no side effects (its CLI block is guarded on isMain) and modifies nothing there.
+import { VERIFY_LOG_PATH, extractFailCount } from "./verify-shadow.mjs";
+
+// ---------- (1) read the append-only history (verify-shadow.log) ----------
+// One NDJSON row per logged claim:
+//   { ts, session, claim_text, proof_command|null, pass_fail: "PASS"|"FAIL"|"HARNESS_ERROR"|null,
+//     outcome: "PASS"|"GENUINE_FAIL"|"HARNESS_ERROR", mismatch: boolean, evidence }
+// The file is size-capped by the shadow (newest rows kept), so a plain read is safe.
+export function readLedgerRows(path = VERIFY_LOG_PATH) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null; // no shadow log yet → honest zero-state (distinct from "log exists but empty")
+  }
+  const rows = [];
+  for (const line of raw.split("\n")) {
+    const l = line.trim();
+    if (!l) continue;
+    try {
+      const r = JSON.parse(l);
+      if (r && typeof r === "object") rows.push(r);
+    } catch {
+      /* a partial/garbage line — skip it (fail-open) */
+    }
+  }
+  return rows;
+}
+
+// ---------- (2) the MEASURED wall-clock delta (real timestamps only) ----------
+// Parse an ISO timestamp to epoch ms, or null if it isn't a real parseable time.
+function tsMs(ts) {
+  if (typeof ts !== "string") return null;
+  const n = Date.parse(ts);
+  return Number.isFinite(n) ? n : null;
+}
+
+// measureFixDelta(falseRow, rows) → { ms, atTs } for the EARLIEST later row that is, in the SAME session,
+// the SAME proof_command, and a genuine PASS whose timestamp is strictly after the caught-false claim.
+// That is the real moment the false "done" became a true "done": the exact proof that failed later passed.
+// Returns null when no such row exists (then the ledger shows the count only — never an invented minute).
+export function measureFixDelta(falseRow, rows) {
+  const t0 = tsMs(falseRow.ts);
+  if (t0 == null) return null;
+  const session = falseRow.session ?? null;
+  const proof = falseRow.proof_command || null;
+  if (!proof) return null; // can't tie a fix to a claim with no proof — count only
+  let best = null;
+  for (const r of rows) {
+    if (r === falseRow) continue;
+    if ((r.session ?? null) !== session) continue;
+    if ((r.proof_command || null) !== proof) continue;
+    if (r.outcome !== "PASS") continue; // the SAME proof genuinely passing = the real done
+    const t1 = tsMs(r.ts);
+    if (t1 == null || t1 <= t0) continue; // must be strictly LATER than the false claim
+    if (best == null || t1 < best) best = t1;
+  }
+  return best == null ? null : { ms: best - t0, atTs: new Date(best).toISOString() };
+}
+
+// ---------- (3) build the ledger view from the rows ----------
+// verdict per row:
+//   "FALSE"        — mismatch true: claimed done, its OWN proof re-run GENUINELY failed (a caught lie)
+//   "verified"     — pass_fail PASS: claimed done, its OWN proof re-run really passed (a true done)
+//   "unverifiable" — no re-runnable proof, or HARNESS_ERROR (timeout/missing-script/wrong-cwd) — NEVER a lie
+export function buildLedger(rows) {
+  const entries = (rows || []).map((r) => {
+    let verdict;
+    if (r.mismatch === true) verdict = "FALSE";
+    else if (r.pass_fail === "PASS") verdict = "verified";
+    else verdict = "unverifiable";
+    return {
+      ts: r.ts || null,
+      session: r.session ?? null,
+      claim_text: r.claim_text || "",
+      // Ship-status rows (category:"ship") record the check under probe_command, not proof_command —
+      // fall back so a caught ship-lie shows its real probe command, not an empty one.
+      proof_command: r.proof_command || r.probe_command || null,
+      evidence: r.evidence || "",
+      fail_count: extractFailCount(r.evidence),
+      verdict,
+      _row: r,
+    };
+  });
+
+  // "Checked" = claims we got a genuine re-run verdict for (a true PASS or a caught FALSE). Unverifiable
+  // rows (no proof / harness noise) are logged but NOT counted as checked — we can't stand behind them.
+  const checked = entries.filter((e) => e.verdict === "FALSE" || e.verdict === "verified").length;
+  const falseEntries = entries.filter((e) => e.verdict === "FALSE");
+  // Attach the MEASURED fix delta where — and only where — a real later same-proof PASS exists.
+  for (const e of falseEntries) {
+    const d = measureFixDelta(e._row, rows || []);
+    e.fix_delta_ms = d ? d.ms : null;
+    e.fixed_at = d ? d.atTs : null;
+  }
+  return {
+    total: entries.length,
+    checked,
+    falseCount: falseEntries.length,
+    verifiedCount: entries.filter((e) => e.verdict === "verified").length,
+    unverifiableCount: entries.filter((e) => e.verdict === "unverifiable").length,
+    entries,
+    falseEntries,
+  };
+}
+
+// ---------- (4) render ----------
+function clip(s, n) {
+  const t = String(s || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return t.length > n ? t.slice(0, n - 1) + "…" : t;
+}
+
+// Format a MEASURED millisecond delta as a human duration. Input is a real (t_pass - t_false) delta; this
+// only formats it — it never rounds up into an invented number. Sub-second deltas read as "<1s".
+export function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return null;
+  const s = Math.floor(ms / 1000);
+  if (s < 1) return "<1s";
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  if (h > 0) return `${h}h ${m}m`;
+  if (m > 0) return `${m}m ${sec}s`;
+  return `${sec}s`;
+}
+
+const MAX_RECEIPTS = 5;
+
+export function renderLedger(ledger, { logPath = VERIFY_LOG_PATH } = {}) {
+  const L = [];
+  L.push("");
+  L.push(
+    '  🔬 skalpel — personal truth ledger (every "done" your agent claimed, checked by its own proof)',
+  );
+  L.push("  " + "─".repeat(74));
+
+  if (ledger == null) {
+    L.push("");
+    L.push("  No claim-verification history yet on this machine.");
+    L.push(
+      "  Enable the shadow with SKALPEL_VERIFY_SHADOW=1, then keep coding — every turn your agent",
+    );
+    L.push('  claims "done / tests pass" gets its own proof re-run and appended to the ledger.');
+    L.push("");
+    return L.join("\n");
+  }
+
+  const { checked, falseCount } = ledger;
+  L.push("");
+  // THE HEADLINE — both numbers are real counts over the real append-only log.
+  L.push(
+    `  ${checked} done-claim${checked === 1 ? "" : "s"} checked, ${falseCount} verified FALSE.`,
+  );
+
+  if (ledger.total === 0) {
+    L.push("");
+    L.push("  The ledger is empty — no completion claims logged yet. I'll append every one live.");
+    L.push("");
+    return L.join("\n");
+  }
+
+  if (falseCount === 0) {
+    L.push("");
+    L.push('  No caught lies — every checked "done" held up against its own proof. Clean ledger.');
+    if (ledger.unverifiableCount > 0) {
+      L.push(
+        `  (${ledger.unverifiableCount} claim(s) logged but unverifiable — no re-runnable proof or harness noise; not counted.)`,
+      );
+    }
+    L.push("");
+    return L.join("\n");
+  }
+
+  L.push("");
+  L.push(
+    "  Every FALSE below is real — the agent's own proof, re-run, did NOT pass at claim time:",
+  );
+  L.push("");
+
+  const top = ledger.falseEntries.slice(-MAX_RECEIPTS).reverse();
+  top.forEach((e, i) => {
+    const failN = e.fail_count != null ? ` (${e.fail_count} failing)` : "";
+    L.push(`  ${i + 1}. your agent said:`);
+    L.push(`       "${clip(e.claim_text, 72)}"`);
+    L.push(`     but its own \`${clip(e.proof_command, 64)}\` had just FAILED${failN}:`);
+    if (e.evidence) L.push(`       ${clip(e.evidence, 72)}`);
+    // MEASURED time — shown ONLY when a real later same-proof PASS exists in the log. Never estimated.
+    if (e.fix_delta_ms != null) {
+      const dur = formatDuration(e.fix_delta_ms);
+      if (dur)
+        L.push(
+          `     ⏱  ${dur} later, that same proof was logged PASS (measured, real timestamps).`,
+        );
+    } else {
+      L.push("     ⏱  no later PASS logged for this proof yet — count only, no time estimated.");
+    }
+    L.push("");
+  });
+
+  if (falseCount > top.length)
+    L.push(`  …and ${falseCount - top.length} more FALSE in the ledger.`);
+  if (ledger.unverifiableCount > 0) {
+    L.push(
+      `  (${ledger.unverifiableCount} claim(s) logged but unverifiable — no re-runnable proof or harness noise; not counted as checked.)`,
+    );
+  }
+  L.push("  " + "─".repeat(74));
+  L.push(`  Append-only local history: ${logPath}`);
+  L.push("");
+  return L.join("\n");
+}
+
+// ---------- CLI ----------
+const isMain = (() => {
+  try {
+    return (
+      Boolean(process.argv[1]) &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  try {
+    // Optional override so the verifier can point the ledger at a crafted log (tests / self-check).
+    const logPath = process.env.SKALPEL_LEDGER_LOG || VERIFY_LOG_PATH;
+    const rows = readLedgerRows(logPath);
+    const ledger = rows == null ? null : buildLedger(rows);
+    process.stdout.write(renderLedger(ledger, { logPath }) + "\n");
+  } catch {
+    // READ-ONLY + fail-open: never throw at the user.
+    process.stdout.write(
+      "\n  🔬 skalpel — could not read your claim-verification ledger on this machine.\n\n",
+    );
+  }
+  process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "4.0.30",
+  "version": "4.0.32",
   "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

@@ -62,6 +62,8 @@ const KNOWN_SUBS = new Set([
   "autopsy",
   "xray",
   "catches",
+  "card",
+  "ledger",
   "__build",
   "__verify-report",
 ]);
@@ -77,6 +79,8 @@ usage:
   skalpel autopsy                               local, read-only receipt of your verified patterns
   skalpel xray                                  re-run your last session's own proof — did "done" hold up?
   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 uninstall [--purge]                   remove the hooks + local data from this machine
 
 options:
@@ -112,6 +116,11 @@ function validateArgv() {
       process.exit(0);
     }
     if (BOOL_FLAGS.has(a)) continue; // valueless flag (e.g. `uninstall --purge`)
+    // `skalpel card` owns its own flags (--last / --id <id> / --md / --plain) and forwards them to
+    // card.mjs. They are NOT setup options, so setup must not reject them as unknown — pass any token
+    // after the `card` subcommand straight through (card.mjs validates its own flags). Global -v/-h
+    // above still win for a bare `skalpel -v`. Scoped to `card` so no other subcommand's contract shifts.
+    if (i > 0 && argv[0] === "card") continue;
     if (a.startsWith("-")) {
       console.error(`skalpel: unknown option \`${a}\`\n\n${USAGE}`);
       process.exit(2);
@@ -878,6 +887,25 @@ async function main() {
     spawnSync("node", [join(__dir, "catches.mjs"), ...argv.slice(1)], { stdio: "inherit" });
     return;
   }
+  // `skalpel card` — THE CATCH CARD: a LOCAL, READ-ONLY, ZERO-NETWORK render of ONE already-verified
+  // catch that the live shadow (verify-shadow) wrote to ~/.skalpel/verify-shadow.log — the agent's
+  // verbatim "done" claim, the exact proof command skalpel re-ran, the real FAIL verdict, and the
+  // verbatim output tail — as a clean, copy-pasteable card for Slack / a PR / X. It never re-runs a
+  // proof, never touches the network; renders only a GENUINE_FAIL row (never harness noise) and, if
+  // there's no catch to show, says so honestly. `--md`/`--plain` pick the export; `--id <session>`
+  // targets a specific session; `--last` (default) is the newest catch.
+  if (sub === "card") {
+    spawnSync("node", [join(__dir, "card.mjs"), ...argv.slice(1)], { stdio: "inherit" });
+    return;
+  }
+  // `skalpel ledger` — the PERSONAL TRUTH LEDGER: a LOCAL, READ-ONLY view DERIVED from the append-only
+  // verify-shadow.log — your running tally of "done" claims checked and how many were verified FALSE,
+  // with the receipts and (only where a real red->green timestamp delta exists) the measured time.
+  // Never re-runs a proof, never touches the network, never estimates a number.
+  if (sub === "ledger") {
+    spawnSync("node", [join(__dir, "ledger.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).