skalpel 4.0.41 → 4.0.42

package/_test-home.mjs

@@ -0,0 +1,18 @@
+// _test-home.mjs — TEST-ONLY isolation shim. Imported FIRST (before any client module) by every test
+// that touches ~/.skalpel, so os.homedir() resolves to a throwaway temp dir and the suite can never read
+// or clobber the developer's real ~/.skalpel. ESM evaluates imports depth-first in source order, so a test
+// that does `import "./_test-home.mjs"` before `import "./insights.mjs"` guarantees HOME is redirected
+// BEFORE insights.mjs binds its DIR = join(homedir(), ".skalpel") at module load. Not a test file itself.
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const home = mkdtempSync(join(tmpdir(), "skalpel-verify-test-"));
+process.env.HOME = home;
+process.env.USERPROFILE = home; // Windows
+// Never let a stray dev env var arm/disarm the resolver mid-test — each test sets these explicitly.
+delete process.env.SKALPEL_VERIFY_REVEAL;
+delete process.env.SKALPEL_VERIFY_SHADOW;
+
+export const TEST_HOME = home;
+export const SKALPEL_DIR = join(home, ".skalpel");

package/insights.mjs

@@ -17,6 +17,9 @@ import { join } from "node:path";
 
 const DIR = join(homedir(), ".skalpel");
 export const INSIGHTS_PATH = join(DIR, "insights.ndjson");
+// The persisted client config `skalpel setup` writes (api/user/verify). Read HERE too so the ONE arming
+// resolver can consult the consented `verify` key without any writer/reader plumbing.
+export const CLIENT_JSON_PATH = join(DIR, "client.json");
 
 // ---- 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
@@ -30,10 +33,188 @@ export const REVEAL_PATH = join(DIR, "verify-reveal.json");
 // 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.
+// ---- THE ONE ARMING RESOLVER (single source of truth) --------------------------------------------
+// The "aha catch" is OPT-IN and OFF BY DEFAULT. Arming is resolved by ONE function everyone reads —
+// the hook spawn gate, the statusline reveal, verify-shadow's surfacing, and reveal.mjs's agent note —
+// so writer, reader, and gate can never drift. PRECEDENCE:
+//   1. ENV OVERRIDE (dev/CI): SKALPEL_VERIFY_REVEAL, explicit on OR off, always wins.
+//   2. CONSENTED CONFIG: ~/.skalpel/client.json "verify" key ("on"/"off"), written by `skalpel setup`.
+//   3. DEFAULT OFF — an absent config + unset env is DARK, byte-identical to the shadow-only baseline.
+// Only an explicit consented "on" (or a dev env override) arms it; existing installs stay dark.
+const ARM_TRUTHY = /^(1|true|on|yes)$/i;
+const ARM_FALSY = /^(0|false|off|no)$/i;
+// parseArmToken(v) → true (armed) | false (disarmed) | null (no opinion — unset/blank/unrecognized).
+export function parseArmToken(v) {
+  const s = String(v ?? "").trim();
+  if (ARM_TRUTHY.test(s)) return true;
+  if (ARM_FALSY.test(s)) return false;
+  return null;
+}
+// verifyConfigArmed() → the persisted consent from client.json's "verify" key, or null if unset/unreadable.
+// Fail-open: any read/parse error → null (no opinion → falls through to DEFAULT OFF). Never throws.
+export function verifyConfigArmed() {
+  try {
+    return parseArmToken(JSON.parse(readFileSync(CLIENT_JSON_PATH, "utf8"))?.verify);
+  } catch {
+    return null;
+  }
+}
+// revealEnabled(env) — is the USER-VISIBLE reveal armed? env override > consented config > default off.
+// SKALPEL_VERIFY_SHADOW is deliberately NOT consulted here: it arms only the DARK log-only shadow (no
+// reveal); the spawn gate ORs it in separately (verifySpawnArmed). Wrapped so it can never throw.
 export function revealEnabled(env) {
-  return /^(1|true|on|yes)$/i.test(String((env || {}).SKALPEL_VERIFY_REVEAL || "").trim());
+  try {
+    const envOverride = parseArmToken((env || {}).SKALPEL_VERIFY_REVEAL);
+    if (envOverride !== null) return envOverride; // 1) dev/CI env override wins
+    const cfg = verifyConfigArmed();
+    if (cfg !== null) return cfg; // 2) consented config
+  } catch {
+    /* fall through to default */
+  }
+  return false; // 3) DEFAULT OFF
+}
+// verifySpawnArmed(env) — should the per-turn hook SPAWN the detached shadow worker at all? True when the
+// reveal is armed OR the dev log-only shadow (SKALPEL_VERIFY_SHADOW=1) is set. This is the single gate the
+// hook reads; it stays byte-identical to the prior inline `SHADOW==="1" || revealEnabled(env)` when the
+// config is absent, so no existing install starts spawning.
+export function verifySpawnArmed(env) {
+  try {
+    if (String((env || {}).SKALPEL_VERIFY_SHADOW || "").trim() === "1") return true;
+    return revealEnabled(env);
+  } catch {
+    return false;
+  }
+}
+
+// ---- FALSE-ACCUSATION SAFEGUARDS: adjudication ledger + derived auto-darken -----------------------
+// A "was this right?" flight recorder. `skalpel yes|no` appends ONE row here keyed to the most-recent
+// reveal; precision = right/(right+wrong) is derived from these rows, never a stored number that can lie.
+export const ADJUDICATIONS_PATH = join(DIR, "verify-adjudications.ndjson");
+// Every reveal actually SURFACED to the user is logged here (append-only) so `skalpel yes|no` can key an
+// adjudication to the real reveal it saw, and the field-proof report can count real fires.
+export const REVEALS_LOG_PATH = join(DIR, "verify-reveals.ndjson");
+// Session-scoped suppression: a `skalpel no` writes the (session, proof) here so that proof never
+// re-accuses for the rest of THAT session (matched by session id → a new session is never suppressed).
+export const SUPPRESS_PATH = join(DIR, "verify-suppressed.ndjson");
+
+// Auto-darken thresholds. If adjudicated precision < 90% over >= 10 adjudications, the LIVE red reveal
+// self-darkens (derived from these rows every read — NOT a stored flag) and falls back to `skalpel catches`.
+export const AUTO_DARKEN_MIN_ADJ = 10;
+export const AUTO_DARKEN_MIN_PRECISION = 0.9;
+
+// proofSig(s) — normalize a proof command for stable suppression matching (collapse whitespace, bound).
+export function proofSig(s) {
+  return String(s ?? "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 200);
+}
+
+function readNdjson(path, cap = 5000) {
+  try {
+    const rows = readFileSync(path, "utf8").trim().split("\n").filter(Boolean);
+    const out = [];
+    for (const l of rows.slice(-cap)) {
+      try {
+        out.push(JSON.parse(l));
+      } catch {
+        /* skip a partial/garbage line */
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+// adjudicationStats() → { right, wrong, total, precision } from the REAL adjudication rows. precision is
+// right/(right+wrong) or null when there are none. Only "yes"/"no" verdicts count. Never throws.
+export function adjudicationStats() {
+  let right = 0;
+  let wrong = 0;
+  for (const r of readNdjson(ADJUDICATIONS_PATH)) {
+    if (r && r.verdict === "yes") right++;
+    else if (r && r.verdict === "no") wrong++;
+  }
+  const total = right + wrong;
+  return { right, wrong, total, precision: total > 0 ? right / total : null };
+}
+
+// autoDarkened() → is the live red reveal auto-paused? DERIVED from the adjudication rows every call (never
+// a stored boolean): true only once there are >= AUTO_DARKEN_MIN_ADJ adjudications AND precision < 90%.
+// Fail-open: any error → false (stay live — a broken read must never silently darken the catch).
+export function autoDarkened() {
+  try {
+    const { total, precision } = adjudicationStats();
+    return (
+      total >= AUTO_DARKEN_MIN_ADJ && precision !== null && precision < AUTO_DARKEN_MIN_PRECISION
+    );
+  } catch {
+    return false;
+  }
+}
+
+function appendNdjson(path, row) {
+  try {
+    mkdirSync(DIR, { recursive: true });
+    appendFileSync(path, JSON.stringify(row) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// appendAdjudication(row) — ONE flight-recorder row (verdict yes/no, keyed to a reveal). Never throws.
+export function appendAdjudication(row) {
+  return appendNdjson(ADJUDICATIONS_PATH, { ts: new Date().toISOString(), ...row });
+}
+
+// appendRevealLog(row) — record a reveal that was actually SHOWN to the user (append-only, bounded).
+export function appendRevealLog(row) {
+  return appendNdjson(REVEALS_LOG_PATH, { ts: new Date().toISOString(), ...row });
+}
+
+// lastReveal() — the most-recent reveal actually shown (the row `skalpel yes|no` adjudicates). Null if none.
+export function lastReveal() {
+  const rows = readNdjson(REVEALS_LOG_PATH);
+  return rows.length ? rows[rows.length - 1] : null;
+}
+
+// suppressProof(session, proof) — after a `skalpel no`, stop this proof re-accusing for the rest of the
+// session. Requires a real session id (a null-session suppression would over-suppress). Never throws.
+export function suppressProof(session, proof) {
+  const sid = session ? String(session) : "";
+  const sig = proofSig(proof);
+  if (!sid || !sig) return false;
+  return appendNdjson(SUPPRESS_PATH, { ts: new Date().toISOString(), session: sid, proof: sig });
+}
+
+// isProofSuppressed(session, proof) — has this (session, proof) been marked "no" this session? Both sides
+// must have a real session id and they must match, plus the normalized proof must match. Fail-open → false.
+export function isProofSuppressed(session, proof) {
+  try {
+    const sid = session ? String(session) : "";
+    const sig = proofSig(proof);
+    if (!sid || !sig) return false;
+    for (const r of readNdjson(SUPPRESS_PATH)) {
+      if (r && String(r.session || "") === sid && proofSig(r.proof) === sig) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// verifyArmedAt() — the real ISO timestamp `verify` was last turned ON (recorded in client.json at consent
+// time), as a Date, or null. Used only for the honest "armed N days" line — a recorded fact, not a metric.
+export function verifyArmedAt() {
+  try {
+    const t = JSON.parse(readFileSync(CLIENT_JSON_PATH, "utf8"))?.verify_armed_at;
+    const d = t ? new Date(t) : null;
+    return d && Number.isFinite(d.getTime()) ? d : null;
+  } catch {
+    return null;
+  }
 }
 
 // Unlike metrics.ndjson (write-only telemetry, uncapped), this file is READ by a TUI every render —

package/mutation-check.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// mutation-check.mjs — mutation testing for the CRITICAL LOGIC: detectCompletionClaim (incl. the negation
+// guard), classifyOutcome, classifyConfirm, plus the false-accusation safeguards shipUrlPass (URL
+// reachability) and hasMutatingFlag (non-idempotent re-run guard). For each mutation we flip ONE key
+// predicate/branch in verify-shadow.mjs and re-run the pure-function suite (verify-core.test.mjs) against
+// the mutated copy. A mutation the suite still PASSES is a SURVIVOR (a test gap). Gate: survivors must be
+// 0. Run: `node mutation-check.mjs`.
+import { cpSync, mkdtempSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TARGET = "verify-shadow.mjs";
+const SUITE = "verify-core.test.mjs";
+
+// Each mutation: a UNIQUE substring in verify-shadow.mjs and the flipped version. Every one MUST be caught
+// by at least one assertion in verify-core.test.mjs.
+const MUTATIONS = [
+  // ---- detectCompletionClaim (incl. the negation/hedge guard, Fix 2) ----
+  {
+    fn: "detectCompletionClaim",
+    find: 'if (!CLAIM_RE.test(s)) return { claim: false, text: "" };',
+    replace: 'if (CLAIM_RE.test(s)) return { claim: false, text: "" };',
+  },
+  {
+    fn: "detectCompletionClaim",
+    find: "if (!l || !CLAIM_RE.test(l)) continue;",
+    replace: "if (!l || CLAIM_RE.test(l)) continue;",
+  },
+  {
+    fn: "detectCompletionClaim",
+    find: "if (NEGATION_RE.test(l)) continue; // negated/hedged → not a completion claim",
+    replace: "if (!NEGATION_RE.test(l)) continue; // negated/hedged → not a completion claim",
+  },
+  {
+    fn: "detectCompletionClaim",
+    find: 'if (NEGATION_RE.test(s)) return { claim: false, text: "" };',
+    replace: 'if (!NEGATION_RE.test(s)) return { claim: false, text: "" };',
+  },
+  // ---- shipUrlPass (Fix 1: URL false-red safeguard) ----
+  {
+    fn: "shipUrlPass",
+    find: "if (urlResponded(ev1)) return true;",
+    replace: "if (urlResponded(ev1)) return false;",
+  },
+  {
+    fn: "shipUrlPass",
+    find: "  if (urlResponded(ev2)) return true;\n  return false;",
+    replace: "  if (urlResponded(ev2)) return true;\n  return true;",
+  },
+  // ---- hasMutatingFlag (Fix 3: non-idempotent re-run guard) ----
+  {
+    fn: "hasMutatingFlag",
+    find: "if (a.some((x) => MUTATING_FLAG.test(String(x)))) return true;",
+    replace: "if (a.some((x) => MUTATING_FLAG.test(String(x)))) return false;",
+  },
+  // ---- classifyOutcome ----
+  {
+    fn: "classifyOutcome",
+    find: 'if (!err) return "PASS";',
+    replace: 'if (err) return "PASS";',
+  },
+  {
+    fn: "classifyOutcome",
+    find: 'if (err.killed || err.signal === "SIGTERM") return "HARNESS_ERROR"; // hit the timeout',
+    replace: 'if (err.killed && err.signal === "SIGTERM") return "PASS"; // hit the timeout',
+  },
+  {
+    fn: "classifyOutcome",
+    find: 'if (exit === 127 || exit === 126) return "HARNESS_ERROR"; // command not found / not executable',
+    replace:
+      'if (exit === 127 && exit === 126) return "HARNESS_ERROR"; // command not found / not executable',
+  },
+  {
+    fn: "classifyOutcome",
+    find: 'return "GENUINE_FAIL"; // a real non-zero exit from the test/build/lint itself',
+    replace: 'return "HARNESS_ERROR"; // a real non-zero exit from the test/build/lint itself',
+  },
+  // ---- classifyConfirm (the flake-confirm state machine) ----
+  {
+    fn: "classifyConfirm",
+    find: 'const needsConfirm = firstOutcome === "GENUINE_FAIL";',
+    replace: 'const needsConfirm = firstOutcome !== "GENUINE_FAIL";',
+  },
+  {
+    fn: "classifyConfirm",
+    find: 'const confirmedFail = needsConfirm && confirmOutcome === "GENUINE_FAIL";',
+    replace: 'const confirmedFail = needsConfirm || confirmOutcome === "GENUINE_FAIL";',
+  },
+  {
+    fn: "classifyConfirm",
+    find: 'const confirmedFail = needsConfirm && confirmOutcome === "GENUINE_FAIL";',
+    replace: 'const confirmedFail = needsConfirm && confirmOutcome !== "GENUINE_FAIL";',
+  },
+  {
+    fn: "classifyConfirm",
+    find: "const unconfirmedFail = needsConfirm && !confirmedFail;",
+    replace: "const unconfirmedFail = needsConfirm && confirmedFail;",
+  },
+];
+
+const workRoot = mkdtempSync(join(tmpdir(), "skalpel-mutants-"));
+cpSync(HERE, join(workRoot, "src"), {
+  recursive: true,
+  filter: (s) => !s.includes("node_modules"),
+});
+const dir = join(workRoot, "src");
+const targetPath = join(dir, TARGET);
+const pristine = readFileSync(targetPath, "utf8");
+
+function runSuite() {
+  const r = spawnSync("node", ["--test", SUITE], { cwd: dir, encoding: "utf8" });
+  return r.status; // 0 = suite passed (mutant SURVIVED); non-zero = suite failed (mutant KILLED)
+}
+
+// Baseline: the pristine copy must pass, else the harness itself is broken.
+if (runSuite() !== 0) {
+  console.error(
+    "BASELINE FAIL: verify-core.test.mjs does not pass on the pristine copy — aborting.",
+  );
+  process.exit(2);
+}
+
+let survivors = 0;
+let missing = 0;
+const results = [];
+for (const m of MUTATIONS) {
+  const count = pristine.split(m.find).length - 1;
+  if (count !== 1) {
+    missing++;
+    results.push(`  ✗ MUTATION TARGET NOT UNIQUE (${count}×) [${m.fn}] ${m.find.slice(0, 50)}…`);
+    continue;
+  }
+  writeFileSync(targetPath, pristine.replace(m.find, m.replace));
+  const killed = runSuite() !== 0;
+  writeFileSync(targetPath, pristine); // restore
+  if (killed) {
+    results.push(`  ✓ killed   [${m.fn}] ${m.find.slice(0, 52)}…`);
+  } else {
+    survivors++;
+    results.push(`  ☠ SURVIVED [${m.fn}] ${m.find.slice(0, 52)}…`);
+  }
+}
+
+rmSync(workRoot, { recursive: true, force: true });
+console.log(results.join("\n"));
+console.log(
+  `\nmutants: ${MUTATIONS.length}   killed: ${MUTATIONS.length - survivors - missing}   survivors: ${survivors}   target-errors: ${missing}`,
+);
+if (survivors === 0 && missing === 0) {
+  console.log(
+    "MUTATION GATE: survivors = 0 on the critical + false-accusation-safeguard functions ✓",
+  );
+  process.exit(0);
+}
+process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "4.0.41",
+  "version": "4.0.42",
   "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, revealEnabled } from "./insights.mjs";
+import { recordInsight, cleanText, verifySpawnArmed } from "./insights.mjs";
 import { graphReadyNote, verifyCatchNote } from "./reveal.mjs";
 import { tailLines } from "./transcript.mjs";
 
@@ -510,13 +510,11 @@ 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.
-  // 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
-  ) {
+  // ARMING is resolved by the ONE shared resolver (verifySpawnArmed): the consented `verify:"on"` in
+  // client.json OR a dev env override (SKALPEL_VERIFY_SHADOW=1 / SKALPEL_VERIFY_REVEAL). When arming
+  // resolves OFF (the default for every existing install — env unset + config off/absent) this branch is
+  // skipped and the hook's stdout is byte-identical to before; the spawn is detached with stdio ignored.
+  if (verifySpawnArmed(process.env) && payload.transcript_path) {
     try {
       const { spawn } = await import("node:child_process");
       const { fileURLToPath } = await import("node:url");

package/skalpel-setup.mjs

@@ -22,6 +22,7 @@ import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import { identity as authIdentity, cliAuthPath } from "./auth.mjs";
 import { isGenuineUserTurn } from "./session-turns.mjs";
+import { appendAdjudication, suppressProof, lastReveal, parseArmToken } from "./insights.mjs";
 
 // CLI (the `skalpel` bin): `skalpel setup [--api https://graph.skalpel.ai]
 // [--user <id>]`, plus `skalpel uninstall` and `skalpel login`. A bare invocation
@@ -65,6 +66,9 @@ const KNOWN_SUBS = new Set([
   "card",
   "ledger",
   "analytics",
+  "verify",
+  "yes",
+  "no",
   "__build",
   "__verify-report",
 ]);
@@ -83,6 +87,8 @@ usage:
   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 verify on|off|status                  arm/disarm the live catch (re-runs your own proof on a "done" claim)
+  skalpel yes | skalpel no                      was the last catch right? (feeds precision; "no" stops that proof this session)
   skalpel uninstall [--purge]                   remove the hooks + local data from this machine
 
 options:
@@ -157,6 +163,84 @@ function fileCfg() {
 }
 const API = process.env.SKALPEL_API || apiFlag || fileCfg().api || DEFAULT_API;
 
+// writeVerifyConfig(state) — persist the CONSENTED arming for the live catch to ~/.skalpel/client.json.
+// state ∈ { "on", "off" }. On "on" we stamp verify_armed_at (a REAL timestamp) only if not already armed,
+// so re-confirming never resets the honest "armed N days" clock; on "off" we clear it. This is the ONLY
+// writer of the `verify` key; insights.mjs's resolver is the only reader — one key, no drift. Never throws.
+function writeVerifyConfig(state) {
+  const cfgDir = join(homedir(), ".skalpel");
+  const cfgPath = join(cfgDir, "client.json");
+  let cfg = {};
+  try {
+    cfg = JSON.parse(readFileSync(cfgPath, "utf8")) || {};
+  } catch {
+    /* fresh config */
+  }
+  const wasOn = parseArmToken(cfg.verify) === true;
+  cfg.verify = state === "on" ? "on" : "off";
+  if (state === "on") {
+    if (!wasOn || !cfg.verify_armed_at) cfg.verify_armed_at = new Date().toISOString();
+  } else {
+    delete cfg.verify_armed_at;
+  }
+  mkdirSync(cfgDir, { recursive: true });
+  writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
+}
+
+// promptVerifyConsent() — the ONE honest consent line at setup. The prompt DEFAULTS TO THE EXISTING
+// SETTING so a setup re-run never silently flips a deliberate choice: a user who ran `skalpel verify off`
+// and re-runs setup + Enter STAYS OFF; unset/on defaults to on (the activation intent). Non-interactive /
+// CI must NOT hang: no TTY → leave the config untouched and return. The copy is accurate, not hype: the
+// re-run is only the session's OWN already-executed command (reconstructed from its Bash tool calls) —
+// never a new class of side effect. Best-effort: never breaks setup.
+// resolveConsentChoice(current, answerRaw) → "on" | "off". The prompt DEFAULTS TO THE EXISTING SETTING so
+// an empty Enter never silently flips a deliberate choice: current "off" → stays off unless explicitly
+// re-enabled (y/yes/on); current "on"/unset → the activation default, on unless declined (n/no/off).
+export function resolveConsentChoice(current, answerRaw) {
+  const defaultOn = parseArmToken(current) !== false; // off → default off; on/unset → default on
+  const t = String(answerRaw || "")
+    .trim()
+    .toLowerCase();
+  if (defaultOn) return t === "n" || t === "no" || t === "off" ? "off" : "on";
+  return t === "y" || t === "yes" || t === "on" ? "on" : "off"; // stays off unless explicitly turned on
+}
+
+async function promptVerifyConsent() {
+  try {
+    const interactive = process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;
+    if (!interactive || process.env.SKALPEL_DEMO || process.env.SKALPEL_SKIP_VERIFY_CONSENT === "1")
+      return; // CI / piped / demo → leave config untouched, never block
+    // Default the prompt to the EXISTING setting: off → Enter keeps off; on/unset → Enter accepts.
+    const current = fileCfg().verify; // "on" | "off" | undefined
+    const defaultOn = parseArmToken(current) !== false;
+    console.log(
+      `   ${B}The live catch${X}\n` +
+        `   ${D}When your agent says "done / tests pass", skalpel re-runs the SAME test/build command\n` +
+        `   it just ran, in the same directory, and shows you the real result. It only ever re-runs\n` +
+        `   your session's own command — never anything new.${X}`,
+    );
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const promptLine = defaultOn ? `[Enter = on · n = off]` : `[Enter = keep off · y = on]`;
+    const ans = await new Promise((res) =>
+      rl.question(`   ${B}${promptLine}${X} `, (a) => {
+        rl.close();
+        res(a);
+      }),
+    );
+    // Resolve against the existing setting so an empty Enter preserves the current choice.
+    const choice = resolveConsentChoice(current, ans);
+    const on = choice === "on";
+    writeVerifyConfig(choice);
+    console.log(
+      on
+        ? `   ${G}✓${X} ${D}Live catch on — it'll re-run your own proof and flag a false "done". ${X}skalpel verify off${D} anytime.${X}\n`
+        : `   ${D}Live catch off. Turn it on anytime with ${X}skalpel verify on${D}.${X}\n`,
+    );
+  } catch {
+    /* consent is best-effort — never break setup */
+  }
+}
+
 // who's signed in — the session saved by the login flow (~/.skalpel/auth.json). Its `uid` keys the
 // hosted graph; `access_token` authenticates the upload. SKALPEL_USER overrides for dev (no token).
 // Uses auth.mjs's REFRESH-CAPABLE identity() so a token that expired since login (Supabase tokens
@@ -933,6 +1017,66 @@ async function main() {
     spawnSync("node", [join(__dir, "verify-shadow.mjs"), "--xray"], { stdio: "inherit" });
     return;
   }
+  // `skalpel verify on|off|status` — the one-command reverse for the live catch. Local, no network, no
+  // sign-in. `on`/`off` persist the consented arming to client.json (the single writer); `status` (and a
+  // bare `skalpel verify`) render the arming + FIELD-PROOF (real fires, adjudicated precision, armed-days,
+  // auto-darken state) — all from real local rows.
+  if (sub === "verify") {
+    const action = (argv[1] || "status").toLowerCase();
+    if (action === "on" || action === "off") {
+      writeVerifyConfig(action);
+      if (action === "on") {
+        console.log(
+          `\n   ${G}✓${X} Live catch ${B}armed${X}. On a "done" claim, skalpel re-runs your session's own\n` +
+            `   test/build once (twice to confirm before any red) and shows the real result.\n` +
+            `   ${D}Reverse anytime: ${X}skalpel verify off${D}  ·  see the field proof: ${X}skalpel verify status\n`,
+        );
+      } else {
+        console.log(
+          `\n   ${G}✓${X} Live catch ${B}off${X}. ${D}Re-arm anytime: ${X}skalpel verify on\n`,
+        );
+      }
+    } else if (action === "status") {
+      spawnSync("node", [join(__dir, "verify-shadow.mjs"), "--status"], { stdio: "inherit" });
+    } else {
+      console.error(`skalpel verify: unknown action \`${argv[1]}\` (use: on | off | status)`);
+      process.exitCode = 2;
+    }
+    return;
+  }
+  // `skalpel yes` / `skalpel no` — ONE-KEY ADJUDICATION of the most-recent catch (the flight recorder).
+  // Local, no network, no sign-in. Appends one NDJSON row keyed to the reveal you just saw; a "no" also
+  // suppresses that exact proof for the rest of THAT session and counts against precision (feeding the
+  // auto-darken kill-switch). Fail-open: nothing to adjudicate → an honest note, never an error.
+  if (sub === "yes" || sub === "no") {
+    const r = lastReveal();
+    if (!r || !r.proof_command) {
+      console.log(
+        `\n   ${D}No recent skalpel catch to adjudicate — nothing has surfaced yet.${X}\n` +
+          `   ${D}When skalpel flags a false "done", it'll say: was this right? ${X}skalpel yes / skalpel no\n`,
+      );
+      return;
+    }
+    const proofShort = String(r.proof_command).slice(0, 60);
+    appendAdjudication({
+      verdict: sub, // "yes" | "no"
+      reveal_ts: r.ts || null,
+      session: r.session || null,
+      proof: r.proof_command,
+    });
+    if (sub === "no") {
+      suppressProof(r.session || null, r.proof_command);
+      console.log(
+        `\n   ${G}✓${X} Marked ${B}not a real catch${X}. ${D}skalpel won't re-accuse ${X}\`${proofShort}\`${D}\n` +
+          `   for the rest of this session, and it counts against precision.${X}\n`,
+      );
+    } else {
+      console.log(
+        `\n   ${G}✓${X} Marked ${B}a real catch${X}. ${D}Thanks — this counts toward precision.${X}\n`,
+      );
+    }
+    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) {
@@ -971,6 +1115,10 @@ async function main() {
       `   ${G}✓${X} Signed in as ${D}${id.name ? `${id.name} · ${id.email}` : id.email || id.uid}${X}\n`,
     );
 
+  // CONSENT for the live catch (default-accept). One honest line; persisted to client.json. Non-TTY/CI
+  // never blocks (stays default OFF). Reversible anytime with `skalpel verify off`.
+  await promptVerifyConsent();
+
   // 2) find the real coding sessions in the last 30 days (the client reads; the server builds)
   const s1 = spinner(`Looking through your last ${LOOKBACK_DAYS} days of Claude Code + Codex…`);
   await sleep(500);

package/skalpel-statusline.mjs

@@ -30,7 +30,7 @@ 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, VERDICT_PATH, revealEnabled } from "./insights.mjs";
+import { cleanText, REVEAL_PATH, VERDICT_PATH, revealEnabled, autoDarkened } from "./insights.mjs";
 
 const CYAN = "\x1b[36m";
 const GREEN = "\x1b[32m";
@@ -368,9 +368,23 @@ function main() {
   // SKALPEL_VERIFY_REVEAL — when off (the default) this branch never runs and the bar is byte-identical to
   // the always-on baseline below.
   if (revealEnabled(process.env)) {
+    // AUTO-DARKEN kill-switch: once adjudicated precision drops below 90% over >= 10 `skalpel yes|no`
+    // rows, the LIVE red reveal self-pauses and the bar points at the retro `skalpel catches`
+    // (transcript-grounded — it can't flake) until the user re-arms. autoDarkened() is DERIVED from the
+    // real adjudication rows on every render (never a stored flag), so writer + reader can't drift.
+    if (autoDarkened()) {
+      process.stdout.write(
+        `${BOLD}skalpel${RESET} · ${DIM}live catch paused (precision <90%) · run: skalpel catches${RESET}`,
+      );
+      return;
+    }
     const reveal = revealNote(payload.session_id);
     if (reveal) {
-      process.stdout.write(`${BOLD}${reveal}${RESET}`);
+      // The red carries its one-key adjudication pointer — the flight recorder that feeds precision +
+      // the auto-darken kill-switch. A `skalpel no` also suppresses this exact proof for the session.
+      process.stdout.write(
+        `${BOLD}${reveal}${RESET} ${DIM}· was this right? skalpel yes / skalpel no${RESET}`,
+      );
       return;
     }
     const verdict = verdictNote();