skalpel 4.0.27 → 4.0.28

package/insights.mjs

@@ -24,6 +24,12 @@ export const INSIGHTS_PATH = join(DIR, "insights.ndjson");
 // user-visible bar). Both the flag semantics and the file path live HERE — the one light module both the
 // writer and the reader (and the hook's spawn gate) already import — so they can never drift apart.
 export const REVEAL_PATH = join(DIR, "verify-reveal.json");
+// verify-verdict: the POSITIVE half of the same surface — the quiet green "✓ verified" stamp written on
+// a PASS (the agent claimed done and its OWN proof, re-run, really passed). Same writer (verify-shadow.mjs)
+// and reader (skalpel-statusline.mjs), same opt-in flag as the red reveal. Ambient greens are what let the
+// rare red catch land like a thunderclap — without a stream of honest verified stamps a lone red reads as
+// noise, not a verdict. Path single-sourced HERE alongside REVEAL_PATH so writer + reader never drift.
+export const VERDICT_PATH = join(DIR, "verify-verdict.json");
 // SKALPEL_VERIFY_REVEAL is OPT-IN and OFF BY DEFAULT. Unset / "" / "0" / "off" / "false" / "no" → DARK
 // (byte-identical to the shadow-only behavior). Only an explicit truthy value arms the visible reveal.
 export function revealEnabled(env) {

package/package.json

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

@@ -60,6 +60,7 @@ const KNOWN_SUBS = new Set([
   "logout",
   "uninstall",
   "autopsy",
+  "xray",
   "__build",
   "__verify-report",
 ]);
@@ -73,6 +74,7 @@ usage:
   skalpel login                                 (re-)run the Google sign-in
   skalpel logout                                clear the saved session
   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 uninstall [--purge]                   remove the hooks + local data from this machine
 
 options:
@@ -432,6 +434,13 @@ function promptLaunch(targets) {
 
 async function reportLiveAndLaunch(message) {
   console.log(message);
+  // FIRST-RUN X-RAY pointer: offer the user their own first catch — an independent re-run of the proof
+  // from the session they just had. A pointer, not an auto-run (an interactive install must never spawn a
+  // 60s test suite unasked); the command itself does the honest work when they choose to run it.
+  console.log(
+    `   ${D}Want to check the session you just had? Run ${X}${B}skalpel xray${X}${D} — I'll re-run your` +
+      ` agent's own proof and tell you if "done" really held up.${X}\n`,
+  );
   await promptLaunch(detectLaunchers());
 }
 
@@ -867,6 +876,15 @@ async function main() {
     spawnSync("node", [join(__dir, "verify-shadow.mjs"), "--report"], { stdio: "inherit" });
     return;
   }
+  // `skalpel xray` — the FIRST-RUN X-RAY: independently re-run the session you JUST had. Finds your most
+  // recent Claude Code transcript, reconstructs your agent's OWN last proof (test/build/typecheck/lint),
+  // re-runs it once, and stamps it verified or caught. Local, read-only against ~/.claude/projects; the
+  // only thing it executes is your session's own allowlisted proof. Reports a real verdict from a real
+  // re-run — never a minutes-lost tally, never a fabricated number.
+  if (sub === "xray") {
+    spawnSync("node", [join(__dir, "verify-shadow.mjs"), "--xray"], { stdio: "inherit" });
+    return;
+  }
   // Persist --api/--user to ~/.skalpel/client.json so the hooks can read them without shell-env
   // plumbing (env vars SKALPEL_API / SKALPEL_USER still win at hook runtime).
   if (apiFlag || userFlag) {

package/skalpel-statusline.mjs

@@ -11,9 +11,10 @@ import { readFileSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { tailLines } from "./transcript.mjs";
-import { cleanText, REVEAL_PATH, revealEnabled } from "./insights.mjs";
+import { cleanText, REVEAL_PATH, VERDICT_PATH, revealEnabled } from "./insights.mjs";
 
 const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
 const RESET = "\x1b[0m";
@@ -22,6 +23,11 @@ const RESET = "\x1b[0m";
 // wallpapers). verify-shadow.mjs writes the reveal the moment a GENUINE_FAIL mismatch is re-run; it also
 // retracts it if a later proof re-run PASSES. This TTL covers the abandoned case (user moved on).
 const REVEAL_TTL_MS = 90_000;
+// LIVE VERDICT green stamp — the earned "✓ verified" written on a clean PASS. DELIBERATELY short-lived:
+// it flashes right after the claim, then recedes so a stream of greens stays ambient (quiet trust) and
+// never competes with the loud red catch. Short TTL is the whole point — a green that lingers is clutter;
+// a green that blinks by, turn after turn, is what makes the rare red land like a thunderclap.
+const VERDICT_TTL_MS = 20_000;
 
 // Claude Code pipes a JSON status payload on stdin (transcript_path, session_id, …). Read it ONLY when
 // stdin is actually piped — never block on a TTY (manual invocation) where reading fd 0 would hang.
@@ -116,6 +122,30 @@ function revealNote() {
   }
 }
 
+// The LIVE VERDICT green stamp: read the verdict state verify-shadow.mjs wrote on a clean PASS. Returns
+// the plain "✓ verified" line (fresh + honest — the statusline never invents it, it only renders what the
+// re-run recorded) or null. Auto-clears past its short TTL so a stale green never lingers. GATED entirely
+// on SKALPEL_VERIFY_REVEAL: when off, this is never called and the bar is byte-identical to the original.
+function verdictNote() {
+  try {
+    const r = JSON.parse(readFileSync(VERDICT_PATH, "utf8"));
+    if (!r || typeof r.line !== "string" || !r.line.trim()) return null;
+    const age = Date.now() - Date.parse(r.ts);
+    if (!Number.isFinite(age) || age > VERDICT_TTL_MS) {
+      try {
+        rmSync(VERDICT_PATH, { force: true }); // stale → retract so it never lingers
+      } catch {
+        /* best-effort; a leftover verdict still self-expires by TTL on the next read */
+      }
+      return null;
+    }
+    const clean = cleanText(r.line).trim(); // last-line defense: this goes RAW to the live terminal
+    return clean || null;
+  } catch {
+    return null; // no verdict pending, or unreadable → print nothing (fail-open)
+  }
+}
+
 async function main() {
   const payload = readPayload();
 
@@ -128,6 +158,14 @@ async function main() {
       process.stdout.write(`${BOLD}${reveal}${RESET}`);
       return;
     }
+    // No red catch pending → the quiet green half. A fresh PASS stamp shows dim (ambient, not shouting)
+    // for a short beat. Lower priority than the red catch, higher than the re-ask count: it's the most
+    // recent verdict on the last claim, and it's what earns the trust the red catch spends.
+    const verdict = verdictNote();
+    if (verdict) {
+      process.stdout.write(`${DIM}${GREEN}${verdict}${RESET}`);
+      return;
+    }
   }
 
   // Acute + reproducible: the user has re-asked / interrupted repeatedly this stretch. Surface the count

package/verify-shadow.mjs

@@ -27,6 +27,7 @@
 import {
   appendFileSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   writeFileSync,
   renameSync,
@@ -42,7 +43,7 @@ import { realpathSync } from "node:fs";
 import { tailLines } from "./transcript.mjs";
 // Local sibling modules only (no sockets — RED LINE #4 holds): recordInsight logs the reveal fire for
 // measurement; REVEAL_PATH/revealEnabled are the single-sourced state-file path + opt-in flag.
-import { recordInsight, REVEAL_PATH, revealEnabled } from "./insights.mjs";
+import { recordInsight, REVEAL_PATH, VERDICT_PATH, revealEnabled } from "./insights.mjs";
 
 const DIR = join(homedir(), ".skalpel");
 export const VERIFY_LOG_PATH = join(DIR, "verify-shadow.log");
@@ -710,12 +711,52 @@ function clearReveal() {
   }
 }
 
+// ---- the POSITIVE half: the quiet green VERDICT STAMP (LIVE VERDICT). On a PASS (claim + the session's
+// OWN proof re-run really exited 0) we write a dim-green "✓ verified" stamp the statusline renders for a
+// short beat. HONESTY: every token traces to the real run — the real reconstructed proof command and the
+// literal fact that its process exited 0. NO number is shown here (a pass has no count to invent). The
+// ambient stream of these earned greens is what makes the rare red catch feel like a verdict, not noise.
+
+// buildVerdictLine(row) → the plain-text green stamp (no ANSI — the statusline styles + re-sanitizes).
+export function buildVerdictLine(row) {
+  const proof = clipText(row.proof_command, 48) || "its own proof";
+  return `✓ skalpel verified — re-ran \`${proof}\`, exit 0. It's real.`;
+}
+
+// writeVerdict(row) — atomic write of the green-stamp state file the statusline reads. Best-effort.
+function writeVerdict(row) {
+  try {
+    mkdirSync(DIR, { recursive: true });
+    const rec = {
+      ts: row.ts,
+      session: row.session || null,
+      proof_command: row.proof_command,
+      line: buildVerdictLine(row),
+    };
+    const tmp = `${VERDICT_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify(rec));
+    renameSync(tmp, VERDICT_PATH); // atomic swap — a concurrent statusline never sees a half write
+  } catch {
+    /* the verdict stamp is a bonus; a write failure must never affect the shadow */
+  }
+}
+
+// clearVerdict() — a fresh RED catch supersedes any lingering green (never show both at once).
+function clearVerdict() {
+  try {
+    rmSync(VERDICT_PATH, { force: true });
+  } catch {
+    /* stale verdict self-expires via the statusline's short TTL anyway */
+  }
+}
+
 // maybeSurfaceReveal(row) — the single opt-in branch. OFF by default → does nothing (fully dark).
 function maybeSurfaceReveal(row) {
   try {
     if (!revealEnabled(process.env)) return; // SKALPEL_VERIFY_REVEAL unset/off → dark, no-op
     if (row.outcome === "GENUINE_FAIL" && row.mismatch === true) {
       writeReveal(row);
+      clearVerdict(); // a real catch overrides any stale green — never show a ✓ next to a ✗
       // MEASURABLE: one reveal_shown insight per fire → fire-rate + (later) retention, no fabricated data.
       recordInsight({
         kind: "reveal_shown",
@@ -725,7 +766,15 @@ function maybeSurfaceReveal(row) {
       });
     } else if (row.outcome === "PASS") {
       clearReveal(); // resolved — don't wallpaper a catch the agent already fixed
+      writeVerdict(row); // …and stamp the earned green so the ambient trust-line keeps building
+      recordInsight({
+        kind: "verdict_shown",
+        display: buildVerdictLine(row),
+        proof: row.proof_command,
+        session: row.session || null,
+      });
     }
+    // HARNESS_ERROR / REFUSED: neither a catch nor a clean pass — surface nothing, touch no state file.
   } catch {
     /* reveal surfacing is a bonus; never affect the shadow path */
   }
@@ -883,8 +932,130 @@ export function renderVerifyReport() {
   return L.join("\n");
 }
 
+// ======================= FIRST-RUN X-RAY: `skalpel xray` =======================
+// A one-shot, user-INVOKED replay over the session you JUST had: find your most recent Claude Code
+// transcript, read the agent's last completion claim, reconstruct the session's OWN proof, re-run it
+// once, and stamp it verified or caught. Same engine as the live shadow — the only new thing is finding
+// the newest transcript and printing a human verdict. Explicit invocation IS the opt-in; it re-runs only
+// the session's own allowlisted proof (never anything from prompt/claim CONTENT). It reports ONLY a real
+// verdict from a real re-run — NEVER a minutes-lost tally, never a fabricated number (the banned
+// confession). Local, read-only against ~/.claude/projects; opens no socket. Never throws.
+const CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
+
+// newestTranscript() → absolute path of the most-recently-modified *.jsonl under ~/.claude/projects, or
+// null. Bounded: one level of project dirs (Claude's layout), newest mtime wins. Fail-open on any error.
+export function newestTranscript(root = CLAUDE_PROJECTS_DIR) {
+  let best = null;
+  let bestMtime = -Infinity;
+  let dirs;
+  try {
+    dirs = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return null; // no ~/.claude/projects → nothing to x-ray
+  }
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue;
+    const sub = join(root, d.name);
+    let files;
+    try {
+      files = readdirSync(sub);
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (!f.endsWith(".jsonl")) continue;
+      const p = join(sub, f);
+      try {
+        const m = statSync(p).mtimeMs;
+        if (m > bestMtime) {
+          bestMtime = m;
+          best = p;
+        }
+      } catch {
+        /* vanished mid-scan — skip */
+      }
+    }
+  }
+  return best;
+}
+
+// xrayLastSession() → runs the replay and PRINTS the verdict. Returns a small result object (also used by
+// tests). Ansi via the same palette the statusline uses; honest by construction — no derived numbers.
+export async function xrayLastSession({ transcriptPath } = {}) {
+  const RED = "\x1b[38;2;233;38;31m";
+  const GREEN = "\x1b[38;2;124;184;108m";
+  const DIM = "\x1b[2m";
+  const BOLD = "\x1b[1m";
+  const X = "\x1b[0m";
+  const say = (s) => process.stdout.write(s + "\n");
+
+  const tp = transcriptPath || newestTranscript();
+  if (!tp) {
+    say(
+      `\n  ${DIM}No recent Claude Code session found to check (looked in ~/.claude/projects).${X}\n`,
+    );
+    return { status: "no_session" };
+  }
+  const entries = readEntries(tp);
+  if (!entries.length) {
+    say(`\n  ${DIM}Your most recent session had nothing readable to check.${X}\n`);
+    return { status: "empty" };
+  }
+
+  const { claim, text } = detectCompletionClaim(lastAssistantText(entries));
+  say(`\n  ${BOLD}skalpel x-ray${X} ${DIM}· replaying the session you just had${X}`);
+  if (!claim) {
+    // No completion claim in the last turn — nothing was asserted done, so there's nothing to catch.
+    say(
+      `\n  ${DIM}Your agent's last turn didn't claim it was done — nothing to independently verify.${X}\n`,
+    );
+    return { status: "no_claim" };
+  }
+  say(`  ${DIM}claim:${X} "${clipText(text, 72)}"`);
+
+  const proof = reconstructProof(entries, null);
+  if (!proof) {
+    // Honest limit: it claimed done but ran no test/build/typecheck we could re-run out-of-band.
+    say(
+      `\n  ${DIM}It said done, but ran no test/build/typecheck this session — nothing skalpel can` +
+        ` independently re-run. No verdict (and no guess).${X}\n`,
+    );
+    return { status: "no_proof" };
+  }
+  const proofStr = [proof.cmd, ...proof.args].join(" ").slice(0, 120);
+  say(`  ${DIM}re-running its own proof:${X} ${proofStr}${DIM} …${X}`);
+
+  const result = await rerunProof(proof);
+  const outcome = result.outcome || (result.pass ? "PASS" : "GENUINE_FAIL");
+  if (outcome === "PASS") {
+    say(
+      `\n  ${GREEN}✓ verified${X} — re-ran \`${proofStr}\`, exit 0. Your agent's "done" holds up.\n`,
+    );
+    return { status: "pass", proof: proofStr };
+  }
+  if (outcome === "GENUINE_FAIL") {
+    const failN = extractFailCount(result.evidence);
+    const count = failN != null ? ` (${failN} failing)` : "";
+    say(
+      `\n  ${RED}${BOLD}✗ caught${X} — your agent said "${clipText(text, 60)}" but \`${proofStr}\`` +
+        ` just failed${count}. It's not done.`,
+    );
+    if (result.evidence) say(`  ${DIM}real output:${X} ${clipText(result.evidence, 180)}`);
+    say("");
+    return { status: "caught", proof: proofStr, evidence: result.evidence };
+  }
+  // HARNESS_ERROR / REFUSED — the proof machinery broke, NOT the agent's work. Never render this as a
+  // catch (crying wolf on a timeout / missing script / wrong cwd is exactly what kills the trust).
+  say(
+    `\n  ${DIM}Couldn't independently verify — the proof \`${proofStr}\` errored` +
+      `${result.evidence ? ` (${clipText(result.evidence, 120)})` : ""}. Not a catch.${X}\n`,
+  );
+  return { status: "harness_error", proof: proofStr };
+}
+
 // CLI: `node verify-shadow.mjs --run`  → detached worker launched by the per-turn hook.
 //      `node verify-shadow.mjs --report`→ print the instrument (also reachable via `skalpel __verify-report`).
+//      `node verify-shadow.mjs --xray`  → the one-shot FIRST-RUN X-RAY (reachable via `skalpel xray`).
 // Robust main detection (mirrors skalpel-setup.mjs): compare REAL paths, not a hand-built file:// URL —
 // the staged path lives under the home dir, which on macOS/Windows can contain a space that would break
 // `new URL("file://"+path)` and wrongly disable the CLI. Importing this module (tests) never trips it.
@@ -903,6 +1074,10 @@ if (isMain) {
   if (arg === "--report") {
     process.stdout.write(renderVerifyReport() + "\n");
     process.exit(0);
+  } else if (arg === "--xray") {
+    xrayLastSession({ transcriptPath: process.env.SKALPEL_VERIFY_TRANSCRIPT || null })
+      .then(() => process.exit(0))
+      .catch(() => process.exit(0));
   } else if (arg === "--run") {
     recordVerifyShadow({
       transcriptPath: process.env.SKALPEL_VERIFY_TRANSCRIPT || null,