skalpel 4.0.29 → 4.0.31

package/anchor-shadow.mjs

@@ -0,0 +1,627 @@
+#!/usr/bin/env node
+// anchor-shadow.mjs — ship-status "Auto-Run-the-Anchor", SHADOW mode, READ-ONLY.
+//
+// WHAT: when the user falls into the cycle-12 signature (>=2 consecutive terse re-verify/doubt turns
+// about the SAME claim — "did it merge?", "you sure it's live?", "did that actually push?") AND that
+// doubt is about SHIP STATUS (merged / pushed / live / deployed / price / trial / CI / passing /
+// released), reconstruct the concrete anchor from recent session + repo context (a PR number, a URL,
+// a commit sha, a Stripe price), run ONE read-only allowlisted probe to resolve the doubt, and LOG
+// what we WOULD have injected. It NEVER injects into the live model and NEVER mutates anything.
+//
+// RED LINES honored by construction:
+//   - LOCAL-ONLY: the only side effect is appending to ~/.skalpel/anchor-shadow.log. No network exfil.
+//   - FAIL-OPEN: the per-turn wiring only spawns a DETACHED, unref'd child to run the probe, so the
+//     hook returns immediately — a probe can never block or slow a turn. Every probe has a hard 5s cap.
+//   - REVERSIBLE / SHADOW: log only, never inject, never throw out to the caller.
+//   - PRECISION OVER RECALL: fire only on a tight, consecutive doubt streak about a ship-status claim.
+//   - NO FABRICATED NUMBERS: probe evidence is the REAL stdout of a read-only command (execFile arg
+//     arrays, never a shell string), or an honest "unknown" on error/timeout.
+//
+// INJECTION SAFETY: every probe is `execFile(bin, [args...])` — arguments are an array, so there is NO
+// shell and NO string interpolation. On top of that (defense in depth) every reconstructed value is
+// re-validated against a strict whitelist before it is ever passed as an argument: PR = integer, sha =
+// /^[0-9a-f]{7,40}$/, url = parseable http(s) URL with no whitespace/control chars, repo dir = an
+// existing absolute directory. A crafted target such as url = "; rm -rf x" fails `new URL()` and is
+// rejected; even if it weren't, execFile would hand it to curl as one literal argv, not to a shell.
+
+import {
+  appendFileSync,
+  mkdirSync,
+  existsSync,
+  statSync,
+  writeFileSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFile, spawn } from "node:child_process";
+import { tailLines } from "./transcript.mjs";
+
+const SKALPEL_DIR = join(homedir(), ".skalpel");
+const LOG_PATH = join(SKALPEL_DIR, "anchor-shadow.log");
+const PENDING_PATH = join(SKALPEL_DIR, "anchor-pending.json");
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+const PROBE_TIMEOUT_MS = 5000;
+
+// The claim classifier: the doubt only counts as SHIP-STATUS if one of these tokens is present.
+// Word-boundary matched, case-insensitive. Kept tight (precision over recall).
+const SHIP_LEXICON =
+  /\b(merged?|push(?:ed)?|live|deployed?|deploy|prod(?:uction)?|price|pricing|trial|ci|passing|pass(?:ed)?|released?|release|shipp?ed|ship)\b/i;
+
+// The re-verify / doubt signature: a TERSE turn that questions a prior claim without taking a new
+// action. Either it hits one of these doubt phrases, or it is a short bare question ("live?", "did it?").
+const DOUBT_LEXICON =
+  /\b(did (?:it|that|you|they|we)|are you sure|you sure|is it (?:really|actually|live|up|merged|deployed|passing)|are they|has it|have you|really|actually|for real|for sure|double[- ]?check|recheck|re-?verify|verify|confirm|check again|wait\b|hmm+|sure\?)\b/i;
+
+// A NEW ACTION (imperative work) disqualifies a turn from being a pure re-verify. If a "doubt" turn
+// also issues fresh work, it isn't the passive cycle-12 loop we target.
+const NEW_ACTION =
+  /\b(add|fix|change|write|implement|refactor|make|create|update|remove|delete|build|run|try|use|set|rename)\b/i;
+
+// ---------------------------------------------------------------------------------------------------
+// Transcript helpers (bounded tail read — reuses the same helper the hook uses, so no unbounded slurp).
+// ---------------------------------------------------------------------------------------------------
+function entryText(e) {
+  const raw = e?.content ?? e?.message?.content;
+  if (typeof raw === "string") return raw;
+  if (Array.isArray(raw))
+    return raw
+      .map((b) => {
+        if (typeof b === "string") return b;
+        if (b?.type === "text") return b.text || "";
+        // tool_result content can be a string or nested blocks — flatten best-effort for anchor mining.
+        if (b?.type === "tool_result") {
+          const c = b.content;
+          if (typeof c === "string") return c;
+          if (Array.isArray(c)) return c.map((x) => x?.text || "").join(" ");
+        }
+        return "";
+      })
+      .join(" ");
+  return "";
+}
+
+// The last `n` USER turns, newest first, as trimmed strings. Bounded tail read; never throws.
+export function recentUserTurns(payload, n = 5) {
+  const out = [];
+  try {
+    if (payload?.prompt) out.push(String(payload.prompt).trim());
+    if (!payload?.transcript_path) return out.slice(0, n);
+    const lines = tailLines(payload.transcript_path, TRANSCRIPT_TAIL_BYTES);
+    for (let i = lines.length - 1; i >= 0 && out.length < n; i--) {
+      let e;
+      try {
+        e = JSON.parse(lines[i]);
+      } catch {
+        continue;
+      }
+      if (e.type === "user" || e.role === "user") {
+        const t = entryText(e).trim();
+        if (t) out.push(t);
+      }
+    }
+  } catch {
+    /* fail-open */
+  }
+  return out.slice(0, n);
+}
+
+// A broad recent-context string (user + assistant + tool text) for anchor mining — this is where a PR
+// number, URL, or sha most often lives (in the assistant's prior `gh`/`git` output, not the user turn).
+export function recentContextText(payload, entries = 60) {
+  try {
+    if (!payload?.transcript_path) return String(payload?.prompt || "");
+    const lines = tailLines(payload.transcript_path, TRANSCRIPT_TAIL_BYTES);
+    const slice = lines.slice(-entries);
+    const parts = [];
+    for (const ln of slice) {
+      try {
+        parts.push(entryText(JSON.parse(ln)));
+      } catch {
+        /* skip */
+      }
+    }
+    if (payload?.prompt) parts.push(String(payload.prompt));
+    return parts.join("\n");
+  } catch {
+    return "";
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------
+// (1) detectShipStatusSpiral — the cycle-12 re-verify signature + ship-status classification.
+// `turns` = user turns newest-first (as returned by recentUserTurns). Returns {fire, claim}.
+// ---------------------------------------------------------------------------------------------------
+function isTerse(t) {
+  return t.split(/\s+/).filter(Boolean).length <= 10;
+}
+function isDoubtTurn(t) {
+  if (!isTerse(t)) return false;
+  if (NEW_ACTION.test(t)) return false; // a fresh instruction is not a passive re-verify
+  return DOUBT_LEXICON.test(t) || /\?\s*$/.test(t); // doubt phrase OR a short bare question
+}
+function shipToken(t) {
+  const m = SHIP_LEXICON.exec(t);
+  return m ? m[1].toLowerCase() : null;
+}
+// Normalize surface variants to a canonical claim keyword for stable grouping/probing.
+function canonicalClaim(tok) {
+  if (!tok) return null;
+  if (/^merg/.test(tok)) return "merged";
+  if (/^push/.test(tok)) return "pushed";
+  if (/^deploy/.test(tok)) return "deployed";
+  if (/^prod/.test(tok)) return "deployed";
+  if (tok === "live") return "live";
+  if (/^releas/.test(tok)) return "released";
+  if (/^ship/.test(tok)) return "released";
+  if (/^pric/.test(tok)) return "price";
+  if (tok === "trial") return "trial";
+  if (tok === "ci" || /^pass/.test(tok)) return "ci";
+  return tok;
+}
+
+export function detectShipStatusSpiral(turns) {
+  const none = { fire: false, claim: null };
+  if (!Array.isArray(turns) || turns.length < 2) return none;
+  // Walk consecutive doubt turns from the newest. Stop at the first non-doubt turn.
+  const streak = [];
+  for (const t of turns) {
+    if (isDoubtTurn(t)) streak.push(t);
+    else break;
+  }
+  if (streak.length < 2) return none; // need >=2 consecutive terse re-verify/doubt turns
+  // The doubt must classify as SHIP-STATUS: a ship-status token present across the streak. "SAME claim"
+  // = the streak shares one canonical ship claim (no conflicting ship subject dominates the streak).
+  const claims = streak.map((t) => canonicalClaim(shipToken(t))).filter(Boolean);
+  if (claims.length === 0) return none; // doubt, but not about ship status → do not fire
+  // pick the most-recent ship claim; require the streak not to mix two different ship subjects.
+  const claim = claims[0];
+  const distinct = new Set(claims);
+  if (distinct.size > 1) return none; // ambiguous — different claims → precision guard, do not fire
+  return { fire: true, claim };
+}
+
+// ---------------------------------------------------------------------------------------------------
+// (2) reconstructTarget — pull the concrete anchor from recent turns + repo context. Returns a STRUCTURED
+// target or null (null = "not confidently reconstructable" → the caller logs a miss and does NOT fire).
+// ---------------------------------------------------------------------------------------------------
+function findPr(text) {
+  // "#123", "PR 123", "PR#123", "pull/123", "pull request 123"
+  const m = /(?:\bpr\s*#?\s*|\bpull(?:\s*request)?\s*#?\s*|\/pull\/|#)(\d{1,6})\b/i.exec(text);
+  if (!m) return null;
+  const n = Number(m[1]);
+  return Number.isInteger(n) && n > 0 && n < 1e7 ? n : null;
+}
+function findUrl(text) {
+  const m = /\bhttps?:\/\/[^\s'")<>`]+/i.exec(text);
+  if (!m) return null;
+  let url = m[0].replace(/[.,);]+$/, ""); // trim trailing punctuation from prose
+  return isSafeUrl(url) ? url : null;
+}
+function findSha(text) {
+  // Prefer a sha that appears near commit-ish words; otherwise the longest lone hex token in [7,40].
+  const near = /\b(?:commit|sha|rev(?:ision)?|HEAD|at)\s+([0-9a-f]{7,40})\b/i.exec(text);
+  if (near && /^[0-9a-f]{7,40}$/.test(near[1])) return near[1].toLowerCase();
+  let best = null;
+  const re = /\b([0-9a-f]{7,40})\b/gi;
+  let m;
+  while ((m = re.exec(text))) {
+    const tok = m[1].toLowerCase();
+    if (/^\d+$/.test(tok)) continue; // pure decimal → not a sha (avoids matching long numbers)
+    if (!best || tok.length > best.length) best = tok;
+  }
+  return best;
+}
+function repoDirOf(payload) {
+  const cwd = payload?.cwd && isAbsolute(payload.cwd) ? payload.cwd : process.cwd();
+  try {
+    return existsSync(cwd) && statSync(cwd).isDirectory() ? cwd : null;
+  } catch {
+    return null;
+  }
+}
+
+export function reconstructTarget(claim, contextText, payload) {
+  const text = String(contextText || "");
+  const repoDir = repoDirOf(payload);
+  const pr = findPr(text);
+  const url = findUrl(text);
+  const sha = findSha(text);
+
+  // Claim-driven preference, each with fallbacks. Return the first that reconstructs; null otherwise.
+  const tryPr = () => (pr != null ? { kind: "pr", n: pr, repoDir } : null);
+  const tryUrl = () => (url ? { kind: "url", url } : null);
+  const tryGit = () => (sha && repoDir ? { kind: "git", sha, repoDir } : null);
+  const tryStripe = () => ({ kind: "stripe-price" });
+
+  let order;
+  switch (claim) {
+    case "merged":
+    case "pushed":
+    case "ci":
+    case "released":
+      order = [tryPr, tryGit, tryUrl];
+      break;
+    case "live":
+    case "deployed":
+      order = [tryUrl, tryPr, tryGit];
+      break;
+    case "price":
+    case "trial":
+      // Only claim a stripe-price target if the context actually talks price/product — otherwise a
+      // bare "stripe prices list" is not a confident reconstruction of THIS doubt.
+      order = /\b(price|pricing|trial|checkout|stripe|plan|subscription|\$\d)/i.test(text)
+        ? [tryStripe, tryUrl]
+        : [tryUrl];
+      break;
+    default:
+      order = [tryPr, tryUrl, tryGit];
+  }
+  for (const f of order) {
+    const t = f();
+    if (t) return t;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Strict validators (defense in depth — execFile already means no shell).
+// ---------------------------------------------------------------------------------------------------
+function isSafeUrl(u) {
+  if (typeof u !== "string" || u.length === 0 || u.length > 2048) return false;
+  if (/[\s-<>`"'\\]/.test(u)) return false; // no whitespace/control/quote/backtick/backslash
+  try {
+    const p = new URL(u);
+    return p.protocol === "http:" || p.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function validateTarget(t) {
+  if (!t || typeof t !== "object") return null;
+  switch (t.kind) {
+    case "pr": {
+      const n = Number(t.n);
+      if (!Number.isInteger(n) || n <= 0 || n >= 1e7) return null;
+      const repoDir = validDir(t.repoDir);
+      return { kind: "pr", n, repoDir };
+    }
+    case "url":
+      return isSafeUrl(t.url) ? { kind: "url", url: t.url } : null;
+    case "git": {
+      if (!/^[0-9a-f]{7,40}$/.test(String(t.sha || ""))) return null;
+      const repoDir = validDir(t.repoDir);
+      if (!repoDir) return null;
+      return { kind: "git", sha: String(t.sha).toLowerCase(), repoDir };
+    }
+    case "stripe-price":
+      return { kind: "stripe-price" };
+    default:
+      return null;
+  }
+}
+function validDir(d) {
+  try {
+    return d && isAbsolute(d) && existsSync(d) && statSync(d).isDirectory() ? d : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------
+// (3) runProbe — ONE read-only allowlisted command via execFile (arg ARRAYS, never a shell string),
+// hard 5s timeout, catch-all. Returns {pass, evidence}. pass ∈ {true,false,null(unknown)}.
+// ---------------------------------------------------------------------------------------------------
+function run(bin, args, opts = {}) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => {
+      if (!done) {
+        done = true;
+        resolve(v);
+      }
+    };
+    try {
+      const child = execFile(
+        bin,
+        args,
+        { timeout: PROBE_TIMEOUT_MS, killSignal: "SIGKILL", maxBuffer: 1 << 20, ...opts },
+        (err, stdout, stderr) => {
+          finish({ err, stdout: String(stdout || ""), stderr: String(stderr || "") });
+        },
+      );
+      child.on("error", (err) => finish({ err, stdout: "", stderr: String(err) }));
+    } catch (err) {
+      finish({ err, stdout: "", stderr: String(err) });
+    }
+  });
+}
+const clip = (s) =>
+  String(s || "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 200);
+
+export async function runProbe(rawTarget) {
+  const t = validateTarget(rawTarget);
+  if (!t) return { pass: null, evidence: "rejected: target failed validation" };
+  try {
+    if (t.kind === "pr") {
+      // gh pr view <n> --json state,mergedAt   (READ-ONLY)
+      const opts = t.repoDir ? { cwd: t.repoDir } : {};
+      const { err, stdout } = await run(
+        "gh",
+        ["pr", "view", String(t.n), "--json", "state,mergedAt"],
+        opts,
+      );
+      if (err)
+        return { pass: null, evidence: clip(`gh error: ${err.killed ? "timeout" : err.message}`) };
+      let j;
+      try {
+        j = JSON.parse(stdout);
+      } catch {
+        return { pass: null, evidence: clip(`gh non-json: ${stdout}`) };
+      }
+      const merged = j.state === "MERGED" || !!j.mergedAt;
+      return { pass: merged, evidence: clip(`state=${j.state} mergedAt=${j.mergedAt || "null"}`) };
+    }
+    if (t.kind === "url") {
+      // curl -sS -m 5 -o /dev/null -w "%{http_code}" <url>   (READ-ONLY reachability)
+      const { err, stdout } = await run("curl", [
+        "-sS",
+        "-m",
+        "5",
+        "-o",
+        "/dev/null",
+        "-w",
+        "%{http_code}",
+        t.url,
+      ]);
+      if (err)
+        return {
+          pass: null,
+          evidence: clip(`curl error: ${err.killed ? "timeout" : err.message}`),
+        };
+      const code = parseInt(stdout, 10);
+      if (!Number.isFinite(code) || code === 0)
+        return { pass: null, evidence: clip(`no http code: ${stdout}`) };
+      return { pass: code >= 200 && code < 400, evidence: `http_code=${code}` };
+    }
+    if (t.kind === "git") {
+      // git -C <repo> branch --contains <sha> -a   (READ-ONLY: is the commit on main?)
+      const { err, stdout } = await run("git", [
+        "-C",
+        t.repoDir,
+        "branch",
+        "--contains",
+        t.sha,
+        "-a",
+        "--format=%(refname:short)",
+      ]);
+      if (err)
+        return { pass: null, evidence: clip(`git error: ${err.killed ? "timeout" : err.message}`) };
+      const branches = stdout
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      const onMain = branches.some((b) => /(^|\/)main$|(^|\/)master$/.test(b));
+      return { pass: onMain, evidence: clip(`contains: ${branches.join(",") || "(none)"}`) };
+    }
+    if (t.kind === "stripe-price") {
+      // stripe prices list --limit 3   (READ-ONLY)
+      const { err, stdout } = await run("stripe", ["prices", "list", "--limit", "3"]);
+      if (err)
+        return {
+          pass: null,
+          evidence: clip(`stripe error: ${err.killed ? "timeout" : err.message}`),
+        };
+      const has = /"id"\s*:/.test(stdout) || /price_/.test(stdout);
+      return { pass: has, evidence: clip(has ? "prices listed" : `no prices: ${stdout}`) };
+    }
+  } catch (e) {
+    return { pass: null, evidence: clip(`probe threw: ${e}`) };
+  }
+  return { pass: null, evidence: "unknown target kind" };
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Logging — the ONLY side effect. Append-only NDJSON at ~/.skalpel/anchor-shadow.log. Never throws.
+// ---------------------------------------------------------------------------------------------------
+function logRow(row) {
+  try {
+    mkdirSync(SKALPEL_DIR, { recursive: true });
+    appendFileSync(LOG_PATH, JSON.stringify(row) + "\n");
+  } catch {
+    /* logging is best-effort; never block or throw */
+  }
+}
+function readPending() {
+  try {
+    return JSON.parse(readFileSync(PENDING_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writePending(obj) {
+  try {
+    mkdirSync(SKALPEL_DIR, { recursive: true });
+    writeFileSync(PENDING_PATH, JSON.stringify(obj || {}));
+  } catch {
+    /* best-effort */
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------
+// (4) recordAnchorShadow — the per-turn wiring. SHADOW: log only, never inject, never throw. Cheap on
+// the common path (no spiral → returns after a bounded tail read). On a fire with a reconstructable
+// target it spawns a DETACHED, unref'd child to run the probe so the hook is NEVER slowed by it.
+// ---------------------------------------------------------------------------------------------------
+export function recordAnchorShadow(payload) {
+  try {
+    const session = payload?.session_id ?? null;
+    const turns = recentUserTurns(payload, 5);
+
+    // n+1 instrument (3): resolve the PREVIOUS fire against THIS turn — did the spiral end? (the user's
+    // newest turn no longer doubts the same claim). Race-free: uses only doubt-cessation, not the probe.
+    const pending = readPending();
+    if (pending && pending.claim) {
+      const newest = turns[0] || "";
+      const stillDoubting =
+        isDoubtTurn(newest) && canonicalClaim(shipToken(newest)) === pending.claim;
+      logRow({
+        ts: new Date().toISOString(),
+        session,
+        event: "resolve",
+        ref_ts: pending.ts,
+        claim: pending.claim,
+        spiral_ended: !stillDoubting,
+      });
+      writePending({});
+    }
+
+    const { fire, claim } = detectShipStatusSpiral(turns);
+    if (!fire) return;
+
+    const target = reconstructTarget(claim, recentContextText(payload), payload);
+    if (!target) {
+      // Fire but no concrete anchor → DO NOT fire the probe; log a miss (instrument 2 denominator).
+      logRow({ ts: new Date().toISOString(), session, event: "miss", claim, reason: "no-target" });
+      return;
+    }
+
+    // Arm the n+1 resolution for next turn, then hand the read-only probe to a detached child.
+    writePending({ ts: new Date().toISOString(), claim });
+    spawnProbeChild({ session, claim, target });
+  } catch {
+    /* SHADOW: swallow everything — this can NEVER affect the hook or its injected output. */
+  }
+}
+
+// Spawn a detached, unref'd child that runs ONE read-only probe and appends the fire row, then exits.
+// The parent returns immediately → zero added per-turn latency. Job passed via env as JSON (no shell,
+// no argv interpolation); the child re-validates every field before executing anything.
+function spawnProbeChild(job) {
+  try {
+    const self = fileURLToPath(import.meta.url);
+    const child = spawn(process.execPath, [self, "--run-probe"], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, SKALPEL_ANCHOR_JOB: JSON.stringify(job) },
+    });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    /* if we can't spawn, log a miss so the fire is still accounted for */
+    logRow({
+      ts: new Date().toISOString(),
+      session: job?.session ?? null,
+      event: "miss",
+      claim: job?.claim ?? null,
+      reason: "spawn-failed",
+    });
+  }
+}
+
+async function runDetachedProbe() {
+  let job;
+  try {
+    job = JSON.parse(process.env.SKALPEL_ANCHOR_JOB || "{}");
+  } catch {
+    return;
+  }
+  const { pass, evidence } = await runProbe(job.target);
+  logRow({
+    ts: new Date().toISOString(),
+    session: job.session ?? null,
+    event: "probe",
+    claim: job.claim ?? null,
+    target: safeTarget(job.target),
+    would_inject_pass_fail: pass === null ? "UNKNOWN" : pass ? "PASS" : "FAIL",
+    evidence: clip(evidence),
+  });
+}
+// A compact, non-sensitive view of the target for the log.
+function safeTarget(t) {
+  if (!t || typeof t !== "object") return null;
+  if (t.kind === "pr") return { kind: "pr", n: t.n };
+  if (t.kind === "url") return { kind: "url", url: clip(t.url) };
+  if (t.kind === "git") return { kind: "git", sha: t.sha };
+  if (t.kind === "stripe-price") return { kind: "stripe-price" };
+  return null;
+}
+
+// ---------------------------------------------------------------------------------------------------
+// The tiny analyzer — `skalpel __anchor-report`. Prints the three instrument numbers from the log.
+// ---------------------------------------------------------------------------------------------------
+export function report() {
+  let lines = [];
+  try {
+    lines = readFileSync(LOG_PATH, "utf8").trim().split("\n").filter(Boolean);
+  } catch {
+    console.log(`no anchor-shadow log yet (${LOG_PATH})`);
+    return;
+  }
+  const rows = [];
+  for (const ln of lines) {
+    try {
+      rows.push(JSON.parse(ln));
+    } catch {
+      /* skip */
+    }
+  }
+  const fires = rows.filter((r) => r.event === "probe" || r.event === "miss");
+  const probes = rows.filter((r) => r.event === "probe");
+  const resolves = rows.filter((r) => r.event === "resolve");
+
+  const withTarget = probes.length;
+  const decisive = probes.filter((r) => r.would_inject_pass_fail !== "UNKNOWN").length;
+  const spiralEnded = resolves.filter((r) => r.spiral_ended).length;
+
+  const pct = (a, b) => (b > 0 ? `${((100 * a) / b).toFixed(0)}%` : "n/a");
+
+  console.log(`\nskalpel anchor-shadow report — ${rows.length} rows — ${LOG_PATH}\n`);
+  console.log(`  1. fires (detected ship-status spirals):        ${fires.length}`);
+  console.log(
+    `  2. target-reconstruction success rate:           ${pct(withTarget, fires.length)}  (${withTarget}/${fires.length})`,
+  );
+  console.log(
+    `  3. probe would-resolve the doubt (decisive):     ${pct(decisive, withTarget)}  (${decisive}/${withTarget})`,
+  );
+  console.log(
+    `     └ spiral ended on the next human turn:        ${pct(spiralEnded, resolves.length)}  (${spiralEnded}/${resolves.length})`,
+  );
+  // Pass/fail split of what we WOULD have surfaced — real command output, never fabricated.
+  const p = probes.filter((r) => r.would_inject_pass_fail === "PASS").length;
+  const f = probes.filter((r) => r.would_inject_pass_fail === "FAIL").length;
+  const u = probes.filter((r) => r.would_inject_pass_fail === "UNKNOWN").length;
+  console.log(`\n  would-inject verdicts:  PASS ${p} · FAIL ${f} · UNKNOWN ${u}\n`);
+}
+
+// ---------------------------------------------------------------------------------------------------
+// CLI entry (only when run directly). `--run-probe` = the detached child; `--report` = the analyzer.
+// When imported (from the hook or tests) none of this runs — only the exports above are used.
+// ---------------------------------------------------------------------------------------------------
+const isMain = (() => {
+  try {
+    if (!process.argv[1]) return false;
+    const self = fileURLToPath(import.meta.url);
+    if (self === process.argv[1]) return true;
+    // Tolerate symlinked staging paths (~/.skalpel/hooks may be reached via a symlink).
+    return realpathSync(self) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  if (process.argv.includes("--run-probe")) {
+    runDetachedProbe().finally(() => process.exit(0));
+  } else if (process.argv.includes("--report")) {
+    report();
+    process.exit(0);
+  } else {
+    console.log("anchor-shadow.mjs — internal skalpel module. Use `skalpel __anchor-report`.");
+    process.exit(0);
+  }
+}