skalpel 4.0.23 → 4.0.25

package/insights.mjs

@@ -18,6 +18,18 @@ import { join } from "node:path";
 const DIR = join(homedir(), ".skalpel");
 export const INSIGHTS_PATH = join(DIR, "insights.ndjson");
 
+// ---- verify-reveal: the opt-in "aha catch" surface — single source for the flag + the state-file path.
+// The reveal is WRITTEN by verify-shadow.mjs (the detached proof re-runner, when the agent claimed
+// success but the session's OWN proof re-run GENUINELY failed) and READ by skalpel-statusline.mjs (the
+// 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");
+// 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) {
+  return /^(1|true|on|yes)$/i.test(String((env || {}).SKALPEL_VERIFY_REVEAL || "").trim());
+}
+
 // Unlike metrics.ndjson (write-only telemetry, uncapped), this file is READ by a TUI every render —
 // cap it so it never grows unbounded. Over the byte cap, keep only the newest lines via tmp-file +
 // atomic rename (same idiom as writeSteer), so a concurrent reader never sees a half-written file.

package/install.mjs

@@ -299,13 +299,17 @@ function stripManagedTomlBlocks(txt) {
 
 function codexToml() {
   if (!existsSync(CODEX_DIR)) return "no-codex";
-  const txt = existsSync(CODEX_TOML) ? readFileSync(CODEX_TOML, "utf8") : "";
+  const hadToml = existsSync(CODEX_TOML);
+  const txt = hadToml ? readFileSync(CODEX_TOML, "utf8") : "";
   // Strip current managed blocks and older unmanaged skalpel blocks, so setup heals stale Codex
   // configs that still point at bare PATH commands from pre-staged installs.
   const stripped = stripManagedTomlBlocks(txt);
   let next = stripped.text.replace(/\n{3,}/g, "\n\n").trimEnd();
   if (uninstall) {
-    writeFileSync(CODEX_TOML, next + "\n");
+    // Only rewrite a config.toml that already existed — never CREATE one during an uninstall. A user
+    // with ~/.codex but no config.toml has nothing of ours to strip, so writing `next + "\n"` here
+    // would leave a stray 1-byte file behind an operation that's supposed to clean up.
+    if (hadToml) writeFileSync(CODEX_TOML, next + "\n");
     return stripped.removed ? "removed" : "absent";
   }
   mkdirSync(CODEX_DIR, { recursive: true });
@@ -450,6 +454,7 @@ function cleanupLocalData() {
   rm(join(SKALPEL_DIR, "hooks"), "staged hooks");
   rm(join(SKALPEL_DIR, "ingest-outbox"), "raw transcript snapshots (ingest-outbox)");
   for (const f of [
+    "stats.json", // legacy "time saved" accumulator — nothing writes it now, but old installs left one
     "session.json",
     "steer.json",
     "traj.json",
@@ -466,6 +471,7 @@ function cleanupLocalData() {
     "verify-shadow.log",
     "verify-last.json",
     "verify-shadow.lock",
+    "verify-reveal.json",
   ]) {
     rm(join(SKALPEL_DIR, f), f);
   }

package/package.json

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

package/skalpel-hook.mjs

@@ -13,7 +13,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { identity } from "./auth.mjs";
 import { record } from "./metrics.mjs";
-import { recordInsight, cleanText } from "./insights.mjs";
+import { recordInsight, cleanText, revealEnabled } from "./insights.mjs";
 import { graphReadyNote } from "./reveal.mjs";
 import { tailLines } from "./transcript.mjs";
 
@@ -473,7 +473,13 @@ async function main() {
   // recent test/build/typecheck/lint command and RE-RUNs it out-of-band to log the real PASS/FAIL the
   // agent can't forge. LOG ONLY — it writes nothing to this hook's stdout and never blocks the turn (the
   // re-run, up to 60s, lives in a separate unref'd process). Wrapped so it can never affect the injection.
-  if (process.env.SKALPEL_VERIFY_SHADOW === "1" && payload.transcript_path) {
+  // SKALPEL_VERIFY_REVEAL (the opt-in "aha catch" surface) ALSO arms the re-run — one flag turns on both
+  // the detection and its user-visible reveal. When BOTH are off (the default) this branch is skipped and
+  // the hook's stdout is byte-identical to before; the spawn is detached with stdio ignored regardless.
+  if (
+    (process.env.SKALPEL_VERIFY_SHADOW === "1" || revealEnabled(process.env)) &&
+    payload.transcript_path
+  ) {
     try {
       const { spawn } = await import("node:child_process");
       const { fileURLToPath } = await import("node:url");

package/skalpel-setup.mjs

@@ -30,7 +30,9 @@ const argv = process.argv.slice(2);
 const sub = argv[0] && !argv[0].startsWith("-") ? argv[0] : null;
 const flagOf = (name) => {
   const i = argv.indexOf(name);
-  return i >= 0 && argv[i + 1] ? argv[i + 1] : null;
+  // A flag-looking next token is a missing value, not the value — never swallow it (would poison
+  // client.json and let `--api --version` fall through to a full install).
+  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith("-") ? argv[i + 1] : null;
 };
 const apiFlag = flagOf("--api");
 const userFlag = flagOf("--user");
@@ -92,7 +94,9 @@ function validateArgv() {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (VALUE_FLAGS.has(a)) {
-      i++; // its value is not a token to validate
+      // Only skip a real value; a following flag (-v/--version/--help/unknown) is a missing value
+      // and must still be validated/handled, not eaten.
+      if (argv[i + 1] && !argv[i + 1].startsWith("-")) i++;
       continue;
     }
     if (a === "-v" || a === "--version") {

package/skalpel-statusline.mjs

@@ -7,17 +7,22 @@
 //     that verifiably happened, or
 //   • the current steer's plain-English label (what skalpel is doing now) — a description, not a number.
 // A clean session prints NOTHING. Fail-open: any error → print nothing, exit 0. Never blocks the bar.
-import { readFileSync } from "node:fs";
+import { readFileSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { tailLines } from "./transcript.mjs";
-import { cleanText } from "./insights.mjs";
+import { cleanText, REVEAL_PATH, revealEnabled } from "./insights.mjs";
 
 const CYAN = "\x1b[36m";
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
 const RESET = "\x1b[0m";
 
+// AHA CATCH REVEAL — how long a fresh catch stays on the bar before it auto-clears (so it never
+// 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;
+
 // 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.
 function readPayload() {
@@ -87,9 +92,44 @@ function steerLabel() {
   }
 }
 
+// The opt-in AHA CATCH: read the reveal state file verify-shadow.mjs wrote. Returns the plain reveal
+// line (fresh + honest — the statusline never invents it, it only renders what the re-run recorded) or
+// null. Auto-clears when stale (past the TTL) so an old catch can't wallpaper the bar. GATED entirely on
+// SKALPEL_VERIFY_REVEAL: when off, this is never called and the bar is byte-identical to the original.
+function revealNote() {
+  try {
+    const r = JSON.parse(readFileSync(REVEAL_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 > REVEAL_TTL_MS) {
+      try {
+        rmSync(REVEAL_PATH, { force: true }); // stale → retract so it never lingers
+      } catch {
+        /* best-effort; a leftover reveal 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 reveal pending, or unreadable → print nothing (fail-open)
+  }
+}
+
 function main() {
   const payload = readPayload();
 
+  // AHA CATCH REVEAL (opt-in). The single highest-priority line: the agent claimed done but its OWN proof,
+  // re-run, GENUINELY failed. Fully gated on SKALPEL_VERIFY_REVEAL — when off, this branch never runs and
+  // the statusline output is byte-identical to the count-or-nothing original.
+  if (revealEnabled(process.env)) {
+    const reveal = revealNote();
+    if (reveal) {
+      process.stdout.write(`${BOLD}${reveal}${RESET}`);
+      return;
+    }
+  }
+
   // Acute + reproducible: the user has re-asked / interrupted repeatedly this stretch. Surface the count
   // and point at the receipts — every figure in `skalpel autopsy` re-derives from these same local logs.
   const n = reaskCount(payload.transcript_path);

package/verify-shadow.mjs

@@ -40,6 +40,9 @@ import { execFile } from "node:child_process";
 import { fileURLToPath } from "node:url";
 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";
 
 const DIR = join(homedir(), ".skalpel");
 export const VERIFY_LOG_PATH = join(DIR, "verify-shadow.log");
@@ -50,6 +53,12 @@ const LOCK_PATH = join(DIR, "verify-shadow.lock");
 // but it still gets a hard ceiling so a hung test process can never live forever.
 const RERUN_TIMEOUT_MS = 60_000;
 const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+// The STORED evidence tail is a tight 200 chars (a human-readable receipt). But CLASSIFICATION must see
+// more: a harness sentinel like `npm error Missing script: "test"` is followed by npm's multi-line
+// "To see a list of scripts…" + debug-log-path epilogue, which on modern npm pushes the sentinel ~250
+// chars back — out of a 200-char tail — so a HARNESS_ERROR would be misread as GENUINE_FAIL (crying wolf
+// on a missing script, the exact case we must never surface). Classify on a wider window; store 200.
+const CLASSIFY_TAIL_BYTES = 4000;
 // The proof command lives near the end of the transcript (the agent runs tests, then claims done). A
 // generous tail is fine here (off the hot path); still bounded so a multi-GB transcript can't OOM us.
 const TRANSCRIPT_TAIL_BYTES = 2 * 1024 * 1024;
@@ -501,7 +510,9 @@ export function rerunProof({ cmd, args, cwd }) {
           if (!err) return finish({ pass: true, outcome: "PASS", evidence });
           if (err.killed || err.signal === "SIGTERM")
             evidence = `timeout after ${RERUN_TIMEOUT_MS}ms; ${evidence}`.slice(-200);
-          const outcome = classifyOutcome(err, evidence);
+          // Classify on a WIDER window than we store, so a truncated harness sentinel (e.g. npm's
+          // "Missing script") is still caught as HARNESS_ERROR and never mislabeled GENUINE_FAIL.
+          const outcome = classifyOutcome(err, tail.slice(-CLASSIFY_TAIL_BYTES) || evidence);
           return finish({
             pass: false,
             outcome,
@@ -632,6 +643,94 @@ function appendShadowLog(row) {
   }
 }
 
+// ======================= (4b) the AHA CATCH REVEAL (opt-in, SKALPEL_VERIFY_REVEAL) =======================
+// When the shadow re-run is a GENUINE_FAIL mismatch (agent claimed done, the session's OWN proof REALLY
+// failed) AND the user opted in, we surface a striking, HONEST one-liner the statusline renders. HONESTY
+// RED LINE: every word of the line traces to the real row — the real claim text, the real reconstructed
+// proof command, the real evidence tail. NO fabricated numbers: a failing COUNT is shown ONLY when the
+// real test-runner output printed one. HARNESS_ERROR never reaches here (only GENUINE_FAIL mismatch does),
+// so we never cry wolf on a timeout / missing script / wrong cwd.
+
+function clipText(s, n) {
+  const t = String(s || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return t.length > n ? t.slice(0, n - 1) + "…" : t;
+}
+
+// extractFailCount(evidence) → a positive integer ONLY if the real captured output printed a failure
+// count (jest/vitest/mocha/pytest/cargo/tsc "<n> failed|failing|failures|errors|problems"); else null.
+// A "0 failed" summary yields null (we never render a count we can't stand behind).
+export function extractFailCount(evidence) {
+  const m = String(evidence || "").match(
+    /(\d+)\s+(?:failed|failing|failures?|errors?|problems?)\b/i,
+  );
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+// buildRevealLine(row) → the plain-text reveal (no ANSI — the statusline applies its own styling and
+// re-sanitizes). Uses ONLY real fields from the shadow row.
+export function buildRevealLine(row) {
+  const claim = clipText(row.claim_text, 64) || "it's done";
+  const proof = clipText(row.proof_command, 48) || "its own proof";
+  const failN = extractFailCount(row.evidence);
+  const count = failN != null ? ` (${failN} failing)` : "";
+  return `🔬 skalpel caught it — your agent said "${claim}" but \`${proof}\` just failed${count}. It's not done.`;
+}
+
+// writeReveal(row) — atomic write of the reveal state file the statusline reads. Best-effort; never throws.
+function writeReveal(row) {
+  try {
+    mkdirSync(DIR, { recursive: true });
+    const rec = {
+      ts: row.ts,
+      session: row.session || null,
+      claim_text: row.claim_text,
+      proof_command: row.proof_command,
+      fail_count: extractFailCount(row.evidence),
+      evidence: row.evidence,
+      line: buildRevealLine(row),
+    };
+    const tmp = `${REVEAL_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify(rec));
+    renameSync(tmp, REVEAL_PATH); // atomic swap — a concurrent statusline never sees a half-written file
+  } catch {
+    /* the reveal is a bonus; a write failure must never affect the shadow */
+  }
+}
+
+// clearReveal() — retract a prior catch (the agent actually fixed it: a later proof re-run PASSED).
+function clearReveal() {
+  try {
+    rmSync(REVEAL_PATH, { force: true });
+  } catch {
+    /* stale reveal self-expires via the statusline's 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);
+      // MEASURABLE: one reveal_shown insight per fire → fire-rate + (later) retention, no fabricated data.
+      recordInsight({
+        kind: "reveal_shown",
+        display: buildRevealLine(row),
+        proof: row.proof_command,
+        session: row.session || null,
+      });
+    } else if (row.outcome === "PASS") {
+      clearReveal(); // resolved — don't wallpaper a catch the agent already fixed
+    }
+  } catch {
+    /* reveal surfacing is a bonus; never affect the shadow path */
+  }
+}
+
 // recordVerifyShadow({transcriptPath, session, cwd}) — the wired entry. On (claim + reconstructable
 // proof) it re-runs the proof and appends one shadow row. LOG ONLY. Never injects, never throws.
 export async function recordVerifyShadow({ transcriptPath, session, cwd }) {
@@ -676,7 +775,7 @@ export async function recordVerifyShadow({ transcriptPath, session, cwd }) {
     // the work) so it is NOT counted in the mismatch metric — only a GENUINE_FAIL is "the agent lied".
     const pass_fail =
       outcome === "PASS" ? "PASS" : outcome === "GENUINE_FAIL" ? "FAIL" : "HARNESS_ERROR";
-    appendShadowLog({
+    const row = {
       ts: new Date().toISOString(),
       session: session || null,
       claim_text: text,
@@ -685,7 +784,10 @@ export async function recordVerifyShadow({ transcriptPath, session, cwd }) {
       outcome,
       mismatch: claim && outcome === "GENUINE_FAIL", // THE money metric: claimed done, own test REALLY failed
       evidence: String(result.evidence || "").slice(0, 200),
-    });
+    };
+    appendShadowLog(row);
+    // SHADOW stays dark by default; this is the ONLY user-visible branch, gated on SKALPEL_VERIFY_REVEAL.
+    maybeSurfaceReveal(row);
   } catch {
     /* SHADOW: any failure is swallowed — this must never affect the hook or the turn */
   }