skalpel 4.0.43 → 4.0.45

package/first-run.mjs

@@ -0,0 +1,722 @@
+#!/usr/bin/env node
+// first-run.mjs — THE FIRST CATCH: first-run magic for skalpel.
+//
+// THE MOMENT: the instant a user installs + consents (the #631 consent-arm flow), we scan their OWN
+// coding history and reveal ONE real catch from it — a past turn where their agent said "done" while its
+// own recorded test/build had ALREADY failed at claim time. Spotify-Wrapped-for-forensics: it collapses
+// time-to-first-aha from "keep coding until the live shadow catches something" to seconds, using history
+// the user already has on disk.
+//
+// HARD RED LINES (why this is safe + honest):
+//   • READ-ONLY over transcripts already on disk. It NEVER re-runs, spawns a proof, builds, or mutates.
+//     The pass/fail is the exit status the transcript ALREADY recorded — exactly like `skalpel catches`.
+//   • FAIL-OPEN. Any scan/render/IO error → skip SILENTLY to the normal setup ending. Never throws.
+//   • BYTE-IDENTICAL-OFF. Non-TTY / CI / declined-consent → returns before ANY transcript read or file
+//     write. The per-turn hook path is not touched at all.
+//   • PRECISION OVER RECALL. A false catch at the moment of maximum scrutiny is the worst failure this
+//     feature can have (magic → betrayal), so the first-run gate is STRICTER than `skalpel catches`:
+//     see passesFirstRunGate. If nothing qualifies we show an HONEST ZERO STATE — we never manufacture.
+//   • NO FABRICATED VALUES. Every rendered value traces to a real transcript field (verbatim claim, the
+//     recorded output tail, the recorded non-zero exit code, real timestamps). No invented minutes.
+//
+// REUSE: the detection + classification ENGINE is verify-shadow's / catches.mjs's, imported unedited —
+//   loadClaudeEntries / loadCodexEntries (catches.mjs) normalize both transcript shapes; detectCompletionClaim,
+//   reconstructProofEntry, classifyOutcome, extractFailCount (verify-shadow.mjs) do claim + proof + verdict.
+// We run a FIRST-RUN-specific loop over those primitives (rather than calling runScan) because the first-run
+// profile (newest ~150 sessions, HARD ~3s budget, a live progress line) and the strict precision gate need
+// per-catch metadata that runScan/scanSession deliberately drop: the ANCHORED first-line exit code (their
+// evidence is a clipped tail — the leading "Exit code N" line is gone), the claim↔proof turn-distance, and
+// the real per-entry timestamps. catches.mjs is imported, never edited (PR #634 owns its classifier).
+import {
+  appendFileSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+import { loadClaudeEntries, loadCodexEntries } from "./catches.mjs";
+import {
+  detectCompletionClaim,
+  reconstructProofEntry,
+  classifyOutcome,
+  extractFailCount,
+  VERIFY_LOG_PATH,
+} from "./verify-shadow.mjs";
+import { recordInsight, revealEnabled } from "./insights.mjs";
+import { renderMarkdownCard } from "./card.mjs";
+
+// ---------- first-run profile (the knobs that make this instant + safe) ----------
+const MAX_SESSIONS = 150; // newest sessions to consider (across Claude + Codex)
+const BUDGET_MS = 3000; // HARD wall-clock budget for the whole scan
+const MAX_CLAIM_PROOF_GAP = 25; // strict gate (c): max transcript-entry distance claim→failing proof
+const EVIDENCE_TAIL = 200; // verbatim recorded-output tail we surface / store
+const WITHIN_30D_MS = 30 * 24 * 60 * 60 * 1000;
+
+// ---------- (0) sanitize (transcript-derived text prints to a terminal — strip escape/control bytes) ----------
+function clean(s, n) {
+  const t = String(s == null ? "" : s)
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "") // ANSI CSI
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, " ") // other C0 controls → space
+    .replace(/\s+/g, " ")
+    .trim();
+  if (n && t.length > n) return t.slice(0, n - 1) + "…";
+  return t;
+}
+
+// ---------- (1) strict-gate vocab ----------
+// Gate (a): the claim must invoke a PROOF concept (test/build/typecheck/fix/done-over-a-proof), NOT a
+// vibe-only "lgtm / good to go / works now / all set / ready" (those match verify-shadow's CLAIM_RE but
+// are not a claim OVER a proof, so at first impression we do not indict on them).
+const PROOF_ADJACENT_RE =
+  /\b(tests?|passe?s|passing|passed|green|builds?|built|compiles?|compiled|compilation|fix(?:ed|es)?|suite|lint|typechecks?|done|complete[ds]?|finished|implemented|resolved|merged)\b/i;
+
+// Gate (b): a SAME-TURN acknowledgment that something is still failing/not passing. detectCompletionClaim
+// already rejects a negated claim LINE; this is the stricter full-message guard so a message that carries
+// one clean positive line AND "…but the suite still fails" is never surfaced.
+const FAILURE_ACK_RE = new RegExp(
+  [
+    "\\bstill\\s+(fail(s|ing)?|red|broken|not\\b|failing)",
+    "\\btests?\\s+(are\\s+)?(still\\s+)?(fail(s|ing)?|not\\s+pass|red|broken)\\b",
+    "\\bfail(s|ing|ed)?\\s+(still|again)\\b",
+    "\\bnot\\s+(yet\\s+)?pass(ing|es)?\\b",
+    "\\bdoes(n'?t| not)\\s+pass\\b",
+    "\\bdid(n'?t| not)\\s+pass\\b",
+    "\\bwon'?t\\s+pass\\b",
+    "\\bremaining\\s+failures?\\b",
+    "\\bthere\\s+(are|were)\\s+(still\\s+)?(\\d+\\s+)?(test\\s+)?failures?\\b",
+    "\\b(some|a\\s+few|several)\\s+(tests?\\s+)?(are\\s+)?fail",
+    "\\bknown\\s+(failure|issue|bug)\\b",
+  ].join("|"),
+  "i",
+);
+
+export function hasProofAdjacentTerm(claimText) {
+  return PROOF_ADJACENT_RE.test(String(claimText || ""));
+}
+export function hasFailureAck(messageText) {
+  return FAILURE_ACK_RE.test(String(messageText || ""));
+}
+
+// leadingExitCode(body) — the ANCHORED recorded exit code. Real Bash tool_results declare the genuine
+// outcome on the LEADING line ("Exit code 1\n…"); Codex on "Process exited with code N". We read ONLY the
+// first non-empty line so an unrelated "exit code 123" buried in a passing proof's body can NEVER be read
+// as a failure. Returns a finite integer or null.
+export function leadingExitCode(body) {
+  const s = String(body || "");
+  let first = "";
+  for (const line of s.split("\n")) {
+    if (line.trim()) {
+      first = line.trim();
+      break;
+    }
+  }
+  const m = first.match(/^(?:Exit code|Process exited with code)\s+(-?\d+)\b/i);
+  if (!m) return null;
+  const n = Number.parseInt(m[1], 10);
+  return Number.isInteger(n) ? n : null;
+}
+
+// ---------- (2) index a session's recorded results (full body + anchored exit + entry indices + ts) ----------
+function resultTextOf(block) {
+  const c = block?.content;
+  if (typeof c === "string") return c;
+  if (Array.isArray(c)) return c.map((x) => (typeof x === "string" ? x : x?.text || "")).join(" ");
+  return "";
+}
+
+function indexSession(entries) {
+  const results = new Map(); // tool_use_id -> { isError, body, structuredExit }
+  const toolUseIndex = new Map(); // tool_use_id -> entry index (for turn-distance)
+  const ts = new Array(entries.length).fill(null); // entry index -> ISO timestamp | null
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (typeof e?.timestamp === "string") ts[i] = e.timestamp;
+    const c = e?.message?.content;
+    if (!Array.isArray(c)) continue;
+    for (const b of c) {
+      if (b && b.type === "tool_use" && b.id && !toolUseIndex.has(b.id)) toolUseIndex.set(b.id, i);
+      if (b && b.type === "tool_result" && b.tool_use_id) {
+        results.set(b.tool_use_id, {
+          isError: b.is_error === true,
+          body: resultTextOf(b),
+          // Codex-normalized results carry a STRUCTURED numeric exit_code (parsed from Codex's own
+          // wrapper by loadCodexEntries) — a trustworthy, non-free-text signal.
+          structuredExit: typeof b.exit_code === "number" ? b.exit_code : null,
+        });
+      }
+    }
+  }
+  return { results, toolUseIndex, ts };
+}
+
+function assistantTextOf(entry) {
+  if (entry?.type !== "assistant" && entry?.message?.role !== "assistant") return "";
+  const c = entry?.message?.content;
+  if (typeof c === "string") return c;
+  if (Array.isArray(c))
+    return c
+      .filter((b) => b && b.type === "text")
+      .map((b) => b.text || "")
+      .join(" ")
+      .trim();
+  return "";
+}
+
+// ---------- (3) scan ONE session for strict first-run catches ----------
+// Returns [{ claim_text, proof_command, recorded_exit_code, fail_count, evidence_tail, claim_ts,
+//            proof_ts, seconds_before }]. Uses the SAME claim/proof primitives as scanSession, then
+// applies the strict gate (a)+(b)+(c)+(d) with an INDEPENDENT anchored exit-code check.
+export function scanEntriesForCatches(entries, meta = {}) {
+  const out = [];
+  if (!Array.isArray(entries) || !entries.length) return out;
+  const { results, toolUseIndex, ts } = indexSession(entries);
+  const seenProof = new Set();
+
+  for (let i = 0; i < entries.length; i++) {
+    const fullText = assistantTextOf(entries[i]);
+    if (!fullText) continue;
+
+    const { claim, text: claimText } = detectCompletionClaim(fullText);
+    if (!claim) continue;
+    // Gate (a): proof-adjacent claim, and (b): no same-turn failure acknowledgment.
+    if (!hasProofAdjacentTerm(claimText)) continue;
+    if (hasFailureAck(fullText)) continue;
+
+    // The most-recent proof the session actually ran up to and including this claim.
+    const found = reconstructProofEntry(entries.slice(0, i + 1), meta.cwd || null);
+    if (!found || !found.toolUseId) continue;
+    if (seenProof.has(found.toolUseId)) continue;
+
+    // Gate (c): the failing proof must be within a bounded turn-distance of the claim.
+    const proofIdx = toolUseIndex.get(found.toolUseId);
+    if (!Number.isInteger(proofIdx)) continue;
+    const gap = i - proofIdx;
+    if (gap < 0 || gap > MAX_CLAIM_PROOF_GAP) continue;
+
+    const res = results.get(found.toolUseId);
+    if (!res) continue;
+
+    // Gate (d): the recorded exit code is a LITERAL non-zero integer, read ANCHORED (never a body scan).
+    // Claude: leading "Exit code N" line + is_error corroboration. Codex: the structured wrapper code.
+    let exitCode = leadingExitCode(res.body);
+    if (exitCode == null && Number.isInteger(res.structuredExit)) exitCode = res.structuredExit;
+    if (!Number.isInteger(exitCode) || exitCode === 0) continue;
+    // Claude corroboration: a real command failure sets is_error. If a numeric exit came only from the
+    // body (no is_error and no structured code), refuse it — precision over recall.
+    if (!res.isError && !Number.isInteger(res.structuredExit)) continue;
+
+    // Reuse the verdict classifier so timeouts / 127 / 126 / missing-script noise are NEVER surfaced.
+    if (classifyOutcome({ code: exitCode }, res.body) !== "GENUINE_FAIL") continue;
+
+    seenProof.add(found.toolUseId);
+    const claimTs = ts[i] || null;
+    const proofTs = ts[proofIdx] || null;
+    let secondsBefore = null;
+    if (claimTs && proofTs) {
+      const d = (Date.parse(claimTs) - Date.parse(proofTs)) / 1000;
+      if (Number.isFinite(d) && d >= 0) secondsBefore = Math.round(d);
+    }
+    const evidenceTail = String(res.body || "")
+      .replace(/\s+$/, "")
+      .slice(-EVIDENCE_TAIL);
+    out.push({
+      tool: meta.tool || "claude",
+      session: meta.session || null,
+      claim_text: claimText,
+      proof_command: [found.proof.cmd, ...found.proof.args].join(" ").slice(0, 160),
+      recorded_exit_code: exitCode,
+      fail_count: extractFailCount(evidenceTail),
+      evidence_tail: evidenceTail,
+      claim_ts: claimTs,
+      proof_ts: proofTs,
+      seconds_before: secondsBefore,
+    });
+  }
+  return out;
+}
+
+// ---------- (4) discover newest sessions (read-only) ----------
+function walkJsonl(dir, pred, out) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    try {
+      if (e.isDirectory()) walkJsonl(p, pred, out);
+      else if (e.isFile() && pred(e.name)) out.push(p);
+    } catch {
+      /* one bad entry — skip */
+    }
+  }
+}
+
+function discoverSessions(home, maxSessions) {
+  const claudeRoot = path.join(home, ".claude", "projects");
+  const codexDirs = [
+    path.join(home, ".codex", "sessions"),
+    path.join(home, ".codex", "archived_sessions"),
+  ];
+  const files = [];
+  const claude = [];
+  walkJsonl(claudeRoot, (n) => n.endsWith(".jsonl"), claude);
+  for (const f of claude) files.push({ file: f, tool: "claude" });
+  const codex = [];
+  for (const d of codexDirs) walkJsonl(d, (n) => /^rollout-.*\.jsonl$/.test(n), codex);
+  for (const f of codex) files.push({ file: f, tool: "codex" });
+  const withMtime = [];
+  for (const f of files) {
+    try {
+      withMtime.push({ ...f, mtime: statSync(f.file).mtimeMs });
+    } catch {
+      /* vanished between readdir + stat — skip */
+    }
+  }
+  withMtime.sort((a, b) => b.mtime - a.mtime);
+  return withMtime.slice(0, maxSessions);
+}
+
+// ---------- (5) the first-run scan (budgeted, progress-reporting) ----------
+// Returns { scanned, candidates, best, moreWithin30d }. Fail-open: any error → whatever we had so far.
+export function firstRunScan({
+  home = homedir(),
+  maxSessions = MAX_SESSIONS,
+  budgetMs = BUDGET_MS,
+  onProgress = null,
+  now = Date.now(),
+} = {}) {
+  const started = Date.now();
+  let scanned = 0;
+  const candidates = [];
+  let sessions = [];
+  try {
+    sessions = discoverSessions(home, maxSessions);
+  } catch {
+    sessions = [];
+  }
+  for (const s of sessions) {
+    if (Date.now() - started > budgetMs) break; // HARD budget — stop cleanly (precision unaffected)
+    let entries;
+    try {
+      entries = s.tool === "codex" ? loadCodexEntries(s.file) : loadClaudeEntries(s.file);
+    } catch {
+      continue;
+    }
+    if (!entries.length) continue;
+    scanned++;
+    if (typeof onProgress === "function") {
+      try {
+        onProgress(scanned);
+      } catch {
+        /* progress is cosmetic */
+      }
+    }
+    const sessionId = path.basename(s.file, ".jsonl");
+    let found = [];
+    try {
+      found = scanEntriesForCatches(entries, { tool: s.tool, session: sessionId });
+    } catch {
+      continue; // one malformed session must never abort the scan
+    }
+    for (const c of found) {
+      c.session_mtime = s.mtime;
+      candidates.push(c);
+    }
+  }
+
+  // Rank: most recent first (real claim ts, else session mtime), then by extractable fail count.
+  const timeOf = (c) => (c.claim_ts ? Date.parse(c.claim_ts) : c.session_mtime) || 0;
+  candidates.sort((a, b) => timeOf(b) - timeOf(a) || (b.fail_count || 0) - (a.fail_count || 0));
+  const best = candidates[0] || null;
+  const moreWithin30d = best
+    ? candidates.filter((c) => c !== best && now - timeOf(c) <= WITHIN_30D_MS).length
+    : 0;
+  return { scanned, candidates, best, moreWithin30d };
+}
+
+// ---------- (6) the retro CARD row (append to the shared catch log the card reads) ----------
+// A retro row is a RECORDED catch (never a re-run). It carries recorded_exit_code (required by card.mjs's
+// isGenuineCatch for retro) and provenance markers. pass_fail:"RETRO" + mismatch:false keep it OUT of the
+// live test-proof instrument's re-run / mismatch counters (renderVerifyReport), so first-run never inflates
+// the live numbers; outcome:"GENUINE_FAIL" is what lets the card accept + render it.
+export function buildRetroRow(best) {
+  return {
+    ts: best.claim_ts || new Date().toISOString(),
+    session: best.session || null,
+    tool: best.tool || "claude",
+    category: "retro",
+    claim_text: best.claim_text,
+    proof_command: best.proof_command,
+    pass_fail: "RETRO",
+    outcome: "GENUINE_FAIL",
+    mismatch: false,
+    recorded_exit_code: best.recorded_exit_code,
+    recorded: true,
+    provenance: "recorded-in-transcript-at-claim-time",
+    fail_count: best.fail_count,
+    evidence: best.evidence_tail,
+  };
+}
+
+function appendRetroRow(row) {
+  try {
+    mkdirSync(path.dirname(VERIFY_LOG_PATH), { recursive: true });
+    appendFileSync(VERIFY_LOG_PATH, JSON.stringify(row) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------- (7) the staged reveal ----------
+const R = "\x1b[38;2;233;38;31m";
+const G = "\x1b[38;2;124;184;108m";
+const D = "\x1b[2m";
+const B = "\x1b[1m";
+const X = "\x1b[0m";
+
+// Real day + time from a REAL ISO timestamp (or a real session mtime fallback). Never fabricated.
+function whenPhrase(best) {
+  const ms = best.claim_ts ? Date.parse(best.claim_ts) : best.session_mtime;
+  if (!Number.isFinite(ms)) return null;
+  const d = new Date(ms);
+  try {
+    const day = d.toLocaleDateString("en-US", { weekday: "long", month: "short", day: "numeric" });
+    const time = d.toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit" });
+    return `${day} at ${time}`;
+  } catch {
+    return d.toISOString();
+  }
+}
+
+export function revealLines(best, moreWithin30d, color = true) {
+  const c = (code, s) => (color ? `${code}${s}${X}` : s);
+  const when = whenPhrase(best);
+  const claim = clean(best.claim_text, 160) || "it's done";
+  const evidence = clean(best.evidence_tail, 200);
+  const failN = best.fail_count;
+  const secs = best.seconds_before;
+  const L = [];
+  L.push("");
+  L.push(
+    `  ${c(B, "🔬 skalpel — your first catch")} ${c(D, "· from your own history, read-only")}`,
+  );
+  L.push(`  ${c(D, "─".repeat(70))}`);
+  L.push("");
+  L.push(
+    when
+      ? `  On ${c(B, when)}, your agent told you:`
+      : `  Earlier in your history, your agent told you:`,
+  );
+  L.push(`     ${c(B, `"${claim}"`)}`);
+  L.push("");
+  // Line 3 — every clause here is a real recorded field; anything absent is OMITTED, never invented.
+  const earlier = secs != null ? `, ${secs}s earlier,` : "";
+  const failsClause =
+    failN != null ? `recorded ${failN} failure${failN === 1 ? "" : "s"}` : "had already failed";
+  L.push(`  Its own test run${earlier} ${failsClause}. Here's the line:`);
+  if (evidence) L.push(`     ${c(R, evidence)}`);
+  L.push("");
+  const more = moreWithin30d > 0 ? `…and ${moreWithin30d} more in your last 30 days. ` : "";
+  L.push(`  ${c(D, `${more}From now on, skalpel catches these live.`)}`);
+  L.push("");
+  return L.join("\n");
+}
+
+function zeroStateLines(scanned, color = true) {
+  const c = (code, s) => (color ? `${code}${s}${X}` : s);
+  const L = [];
+  L.push("");
+  L.push(`  ${c(B, "🔬 skalpel — first-run scan")} ${c(D, "· your own history, read-only")}`);
+  L.push(`  ${c(D, "─".repeat(70))}`);
+  L.push("");
+  L.push(`  Scanned ${c(B, String(scanned))} of your recent sessions. Zero times your agent`);
+  L.push(`  said "done" over a failing test. ${c(G, "Clean")} — I'll watch from here.`);
+  L.push("");
+  return L.join("\n");
+}
+
+// copy the pre-rendered markdown card to the OS clipboard. Best-effort; returns true on success.
+// SKALPEL_NO_CLIPBOARD=1 disables the OS write (CI / tests must not touch the developer's clipboard).
+function copyToClipboard(text) {
+  if (String(process.env.SKALPEL_NO_CLIPBOARD || "") === "1") return false;
+  const tries =
+    process.platform === "darwin"
+      ? [["pbcopy", []]]
+      : process.platform === "win32"
+        ? [["clip", []]]
+        : [
+            ["wl-copy", []],
+            ["xclip", ["-selection", "clipboard"]],
+            ["xsel", ["--clipboard", "--input"]],
+          ];
+  for (const [cmd, args] of tries) {
+    try {
+      const r = spawnSync(cmd, args, { input: text, stdio: ["pipe", "ignore", "ignore"] });
+      if (r && r.status === 0) return true;
+    } catch {
+      /* try the next clipboard tool */
+    }
+  }
+  return false;
+}
+
+// Interactive exit keys: [c] copy the (pre-rendered) markdown card · [x] not right? · [enter] done.
+// Fail-open: no raw TTY → print the hint, do not block. `answer` forces a key for tests.
+function promptRevealExit({ out, stdin, interactive, answer, markdown, best, env }) {
+  const done = (key) => {
+    if (key === "c") {
+      const ok = copyToClipboard(markdown);
+      out.write(
+        ok
+          ? `   ${G}✓${X} ${D}card copied — paste it in Slack / a PR / X.${X}\n\n`
+          : `   ${D}(clipboard unavailable — run ${X}skalpel card --md${D} to copy it.)${X}\n\n`,
+      );
+      recordInsight({
+        kind: "first_run_card_copied",
+        display: "first-run: card copied to clipboard",
+        copied: ok,
+        session: best.session || null,
+      });
+    } else if (key === "x") {
+      out.write(`   ${D}Got it — flagged as disputed. I won't count this one.${X}\n\n`);
+      recordInsight({
+        kind: "first_run_disputed",
+        display: "first-run: user disputed the catch",
+        session: best.session || null,
+      });
+    } else {
+      out.write("\n");
+    }
+  };
+
+  const hint = `   ${D}[c]${X} copy card   ${D}[x]${X} not right?   ${D}[enter]${X} done  `;
+  // Non-interactive (tests / piped): honor a forced answer, else just print the hint and continue.
+  const canRaw =
+    interactive && stdin && stdin.isTTY && typeof stdin.setRawMode === "function" && !env.CI;
+  if (!canRaw) {
+    out.write(hint + "\n");
+    if (answer) done(String(answer).toLowerCase());
+    return Promise.resolve();
+  }
+
+  out.write(hint);
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (key) => {
+      if (settled) return;
+      settled = true;
+      try {
+        stdin.setRawMode(false);
+        stdin.pause();
+        stdin.removeListener("data", onData);
+      } catch {
+        /* teardown best-effort */
+      }
+      out.write("\n");
+      try {
+        done(key);
+      } catch {
+        /* never throw at the user */
+      }
+      resolve();
+    };
+    const onData = (buf) => {
+      const k = buf.toString("utf8").toLowerCase();
+      if (k === "") return finish("enter"); // Ctrl-C → just finish (don't kill setup)
+      if (k === "c") return finish("c");
+      if (k === "x") return finish("x");
+      return finish("enter"); // Enter / any other key → done
+    };
+    try {
+      stdin.setRawMode(true);
+      stdin.resume();
+      stdin.on("data", onData);
+    } catch {
+      finish("enter");
+    }
+  });
+}
+
+// ---------- (8) coin-flip variant + first-run state ----------
+function firstRunPath(home) {
+  return path.join(home, ".skalpel", "first-run.json");
+}
+function readState(home) {
+  try {
+    return JSON.parse(readFileSync(firstRunPath(home), "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+function writeState(home, state) {
+  try {
+    mkdirSync(path.join(home, ".skalpel"), { recursive: true });
+    writeFileSync(firstRunPath(home), JSON.stringify(state, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// assignVariant(home, env) — persist a coin-flip variant ONCE. Dev/test override: SKALPEL_FIRST_RUN_VARIANT.
+export function assignVariant(home, env = process.env) {
+  const state = readState(home);
+  const forced = String(env.SKALPEL_FIRST_RUN_VARIANT || "").toLowerCase();
+  if (forced === "reveal" || forced === "holdout") {
+    if (state.variant !== forced) {
+      state.variant = forced;
+      state.assigned_at = state.assigned_at || new Date().toISOString();
+      writeState(home, state);
+    }
+    return forced;
+  }
+  if (state.variant === "reveal" || state.variant === "holdout") return state.variant;
+  const variant = Math.random() < 0.5 ? "reveal" : "holdout";
+  state.variant = variant;
+  state.assigned_at = new Date().toISOString();
+  writeState(home, state);
+  return variant;
+}
+
+// ---------- (9) THE orchestrator (called from skalpel-setup.mjs right after consent) ----------
+// Contract: never throws, never blocks setup. Returns a small summary object for tests.
+export async function maybeFirstRunCatch({
+  isTTY = process.stdout.isTTY && !process.env.CI,
+  env = process.env,
+  home = homedir(),
+  out = process.stdout,
+  stdin = process.stdin,
+  interactive = true,
+  answer = null,
+  now = Date.now(),
+} = {}) {
+  try {
+    // BYTE-IDENTICAL-OFF: no TTY, or consent not accepted → return before ANY transcript read or write.
+    if (!isTTY) return { ran: false, reason: "no_tty" };
+    if (!revealEnabled(env)) return { ran: false, reason: "not_consented" };
+
+    // Once only (unless forced) — the first catch is a first-run moment, not a per-setup nag.
+    const state0 = readState(home);
+    if (state0.ran && env.SKALPEL_FIRST_RUN_FORCE !== "1") {
+      return { ran: false, reason: "already_ran", variant: state0.variant || null };
+    }
+
+    const variant = assignVariant(home, env);
+
+    // HOLDOUT arm = current flow, no scan, no reveal. Record the assignment for the D7 A/B and return.
+    if (variant === "holdout") {
+      recordInsight({
+        kind: "first_run",
+        display: "first-run holdout (no reveal)",
+        variant,
+        shown: false,
+      });
+      const st = readState(home);
+      writeState(home, { ...st, variant, ran: true, ran_at: new Date().toISOString() });
+      return { ran: true, variant, shown: false };
+    }
+
+    // REVEAL arm — scan with a live progress line, then reveal the single best catch (or the honest zero
+    // state). Progress writes to the same line; cleared before the reveal renders.
+    let lastLen = 0;
+    const onProgress = (nSessions) => {
+      const line = `   ${D}scanning your own history — read-only — ${nSessions} sessions…${X}`;
+      out.write("\r" + line);
+      lastLen = line.length;
+    };
+    const result = firstRunScan({ home, onProgress, now });
+    if (lastLen) out.write("\r" + " ".repeat(lastLen) + "\r"); // wipe the progress line
+
+    const shown = Boolean(result.best);
+    recordInsight({
+      kind: "first_run",
+      display: shown
+        ? `first-run reveal: caught 1 of ${result.candidates.length} across ${result.scanned} sessions`
+        : `first-run zero-state: 0 catches across ${result.scanned} sessions`,
+      variant,
+      sessions: result.scanned,
+      gate_catches: result.candidates.length,
+      shown,
+      session: result.best ? result.best.session : null,
+    });
+
+    if (!shown) {
+      out.write(zeroStateLines(result.scanned, Boolean(out.isTTY)) + "\n");
+      const st = readState(home);
+      writeState(home, {
+        ...st,
+        variant,
+        ran: true,
+        ran_at: new Date().toISOString(),
+        shown: false,
+      });
+      return { ran: true, variant, shown: false, scanned: result.scanned };
+    }
+
+    const best = result.best;
+    out.write(revealLines(best, result.moreWithin30d, Boolean(out.isTTY)) + "\n");
+
+    // Append the retro row so `skalpel card` can render it later, and pre-render the markdown for [c].
+    const row = buildRetroRow(best);
+    appendRetroRow(row);
+    const markdown = (() => {
+      try {
+        return renderMarkdownCard(row);
+      } catch {
+        return "";
+      }
+    })();
+
+    await promptRevealExit({ out, stdin, interactive, answer, markdown, best, env });
+
+    const st = readState(home);
+    writeState(home, {
+      ...st,
+      variant,
+      ran: true,
+      ran_at: new Date().toISOString(),
+      shown: true,
+      catch_session: best.session || null,
+    });
+    return { ran: true, variant, shown: true, scanned: result.scanned, best };
+  } catch {
+    // FAIL-OPEN: any failure → silently skip to the normal setup ending.
+    return { ran: false, reason: "error" };
+  }
+}
+
+// ---------- CLI: read-only dry run (prints what WOULD be revealed; writes nothing) ----------
+const isMain = (() => {
+  try {
+    return (
+      Boolean(process.argv[1]) &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  try {
+    const result = firstRunScan({});
+    if (result.best)
+      process.stdout.write(revealLines(result.best, result.moreWithin30d, true) + "\n");
+    else process.stdout.write(zeroStateLines(result.scanned, true) + "\n");
+  } catch {
+    process.stdout.write("\n  🔬 skalpel — first-run dry scan unavailable.\n\n");
+  }
+  process.exit(0);
+}