skalpel 3.4.6 → 3.4.7

package/prosumer-hooks/skalpel-hook.mjs

@@ -0,0 +1,699 @@
+#!/usr/bin/env node
+// skalpel thin client — the ENTIRE client. Reads the incoming prompt, asks the HOSTED graph for an
+// injection, relays it into Claude Code / Codex. No engine, no Python, no binary: just an HTTP call.
+// Cross-platform because Node is (Claude Code ships Node, so this Just Works on mac/linux/windows).
+// FAIL-OPEN: any error -> emit nothing, exit 0, never block the user's prompt.
+//
+// Wire it (Claude ~/.claude/settings.json):
+//   {"hooks":{"UserPromptSubmit":[{"type":"command","command":"node /path/to/skalpel-hook.mjs"}]}}
+// Config: SKALPEL_API (default https://graph.skalpel.ai). Identity comes from the Google sign-in
+// saved by `skalpel-prosumer login` (~/.skalpel/auth.json); SKALPEL_USER overrides for dev.
+import { readFileSync, writeFileSync, renameSync, appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { identity } from "./auth.mjs";
+import { record } from "./metrics.mjs";
+import { recordInsight } from "./insights.mjs";
+
+// Config precedence: env > ~/.skalpel/client.json (written by `skalpel-prosumer setup`) > default.
+function fileCfg() {
+  try {
+    return JSON.parse(readFileSync(join(homedir(), ".skalpel", "client.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+const CFG = fileCfg();
+const API = process.env.SKALPEL_API || CFG.api || "https://graph.skalpel.ai";
+// ONE shared wall-clock budget for the whole hook (auth-refresh + retrieve). Previously auth's 2s
+// refresh and the fetch timeout were independent and could STACK past the harness kill. A single
+// deadline caps total hook time so it always self-aborts (fail-open, silent) before the harness can
+// kill it → zero visible harness timeouts by construction. Warm /retrieve is ~1.8s; a coincident
+// token refresh (≤2s) can stack, so 4.5s fits both with margin (harness backstop is 8s). A genuine
+// graph cold-load (~5.5s) still aborts — that's the keep-warm layer's job to prevent, not the
+// client's to wait on. (Supersedes the earlier flat 6s TIMEOUT_MS cold-start fix from this branch.)
+const DEADLINE_MS = 4500;
+
+function lastUserPrompt(payload) {
+  if (payload.prompt) return String(payload.prompt);
+  try {
+    const lines = readFileSync(payload.transcript_path, "utf8").trim().split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const e = JSON.parse(lines[i]);
+      if (e.type === "user" || e.role === "user") {
+        const c = e.content ?? e.message?.content;
+        if (typeof c === "string") return c;
+        if (Array.isArray(c))
+          return c
+            .filter((b) => b?.type === "text")
+            .map((b) => b.text)
+            .join(" ");
+      }
+    }
+  } catch {
+    /* best-effort */
+  }
+  return "";
+}
+
+// Not a real prompt: IDE/system events (file opened, selection changed, command output) fire
+// UserPromptSubmit too, but their text is a synthetic tag or noise — never embed/match on those.
+function isRealPrompt(q) {
+  q = (q || "").trim();
+  if (q.length < 3) return false;
+  if (/^<(ide_|system-|command-)/.test(q)) return false; // IDE + harness tags
+  if (q.split(/\s+/).length === 1 && q.length < 8) return false; // bare filler ("the", "ok", "yes")
+  return true;
+}
+
+// TRAJECTORY: the pre-emptive human interrupt needs to see your RECENT turns, not just this one. The
+// server matches single-turn state; this reads the last few turns of the transcript for a SPIRAL —
+// interrupt markers + rapid corrections ("no", "still wrong", "that's not it"). The felt "you've cut
+// me off twice, let's reset" — the one steer you can't self-catch, and it's purely local + cheap.
+const _CORRECTION =
+  /^(no\b|nope|that'?s not|not what|still\b|again\b|wrong\b|i said|i meant|wtf|tf\b|why (is|are|does|isn|do)|ugh|c'?mon|cmon|bruh)/i;
+function detectCascade(payload) {
+  try {
+    if (!payload.transcript_path) return 0;
+    const lines = readFileSync(payload.transcript_path, "utf8").trim().split("\n");
+    let signals = 0;
+    let userTurns = 0;
+    for (let i = lines.length - 1; i >= 0 && userTurns < 6; i--) {
+      let e;
+      try {
+        e = JSON.parse(lines[i]);
+      } catch {
+        continue;
+      }
+      const raw = e.content ?? e.message?.content;
+      const text =
+        typeof raw === "string"
+          ? raw
+          : Array.isArray(raw)
+            ? raw
+                .filter((b) => b?.type === "text")
+                .map((b) => b.text)
+                .join(" ")
+            : "";
+      if (/\[Request interrupted by user\]/i.test(text)) signals++; // you cut it off
+      if (e.type === "user" || e.role === "user") {
+        userTurns++;
+        if (_CORRECTION.test(text.trim())) signals++; // you re-corrected
+      }
+    }
+    return signals;
+  } catch {
+    return 0;
+  }
+}
+
+// The running "rework flagged" counter — one JSON file, incremented every time a real recurring
+// pattern fires (server already gated it on recurs>=3, so this only counts real trends). The number
+// is the ESTIMATED downstream waste on the path we flagged — rework that USUALLY happens from here,
+// not time already saved (we can't prove the nudge changed anything). Per-session: SessionStart
+// zeroes it (see skalpel-hook-session.mjs). Read by the statusline, Brave-ad-block-counter style.
+const STATS_PATH = join(homedir(), ".skalpel", "stats.json");
+const EMPTY_STATS = {
+  session_hours: 0,
+  session_cost: 0,
+  session_events: 0,
+  total_hours: 0,
+  total_cost: 0,
+  total_events: 0,
+};
+function bumpStats(hours, cost) {
+  try {
+    let s = { ...EMPTY_STATS };
+    try {
+      s = { ...s, ...JSON.parse(readFileSync(STATS_PATH, "utf8")) };
+    } catch {
+      /* missing or corrupt -> start fresh, never block on it */
+    }
+    const r2 = (n) => Math.round(n * 100) / 100;
+    const h = hours || 0;
+    const c = cost || 0;
+    // increment BOTH: session (resets each session) and total (lifetime, never resets)
+    s.session_hours = r2(s.session_hours + h);
+    s.session_cost = r2(s.session_cost + c);
+    s.session_events += 1;
+    s.total_hours = r2(s.total_hours + h);
+    s.total_cost = r2(s.total_cost + c);
+    s.total_events += 1;
+    mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+    const tmp = `${STATS_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify(s));
+    renameSync(tmp, STATS_PATH); // atomic swap — a concurrent read never sees a half-written file
+  } catch {
+    /* stats are a bonus, never block emitting the injection */
+  }
+}
+
+// n+1 CONFIRMATION store — the honest, Brave-style counter. At turn N we PREDICT a rework path but
+// credit NOTHING yet; we stash the prediction here. At turn N+1 we check whether you actually broke
+// OUT of that predicted path — only THEN do we increment (a real avoided-loop event, not a guess).
+const PENDING_PATH = join(homedir(), ".skalpel", "pending.json");
+function readPending() {
+  try {
+    return JSON.parse(readFileSync(PENDING_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writePending(obj) {
+  try {
+    mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+    const tmp = `${PENDING_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify(obj || {}));
+    renameSync(tmp, PENDING_PATH);
+  } catch {
+    /* pending is best-effort; never block the hook */
+  }
+}
+
+// STEER label — the statusline reads this so the user SEES skalpel steering LIVE, every turn a steer
+// injects, INDEPENDENT of whether the model surfaces a 🔬 line (the deterministic awareness channel).
+// A one-glance 2-word label derived from the top injected steer type. Overwritten each turn.
+const STEER_PATH = join(homedir(), ".skalpel", "steer.json");
+function readSteer() {
+  try {
+    return JSON.parse(readFileSync(STEER_PATH, "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+function writeSteer(label, creditMins, type, wt, id) {
+  // label = server's plain-English "what skalpel's doing" (or null on a silent turn). credit = the
+  // +Xmin the n+1 check just credited THIS turn (or null) -> the statusline flashes "+Xmin ✓", the
+  // felt "just delivered" tick, on the exact turn a break-out lands. type/wt = the raw steer identity
+  // (e.g. "TELL"/"refine") so the NEXT turn's feedback phrase ("fewer like this") can target it.
+  // id = the steer's join key (minted once per steer turn, also on that steer's insight row) so the
+  // NEXT turn's adherence record can reference exactly this steer; null on a silent turn.
+  try {
+    mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+    const tmp = `${STEER_PATH}.tmp`;
+    writeFileSync(
+      tmp,
+      JSON.stringify({
+        label: label || null,
+        credit: creditMins || null,
+        type: type || null,
+        wt: wt || null,
+        id: id || null,
+        ts: Date.now(),
+      }),
+    );
+    renameSync(tmp, STEER_PATH);
+  } catch {
+    /* steer label is a bonus; never block the hook */
+  }
+}
+
+// PREFERENCES — the feedback loop (Grammarly's accept/reject, notification-UX's "fewer like this",
+// Eyal's investment): the user talks back to a steer in plain language and skalpel adapts. Persisted
+// across sessions EXCEPT `muted_session` (a session-scoped shush, cleared at SessionStart).
+//   muted_session : bool         — "mute skalpel"       -> shut up for the rest of THIS session
+//   suppress[key] : true         — "fewer like this"    -> stop firing this steer type/trap for me
+//   verbose[key]  : true         — "tell me more…"      -> expand this trap's steer when it fires
+//   score[type]   : {up,down}    — implicit + explicit usefulness, for future gating
+const PREFS_PATH = join(homedir(), ".skalpel", "prefs.json");
+function readPrefs() {
+  const base = { muted_session: false, suppress: {}, verbose: {}, score: {}, stats: {} };
+  try {
+    return { ...base, ...JSON.parse(readFileSync(PREFS_PATH, "utf8")) };
+  } catch {
+    return base;
+  }
+}
+
+// ADHERENCE — the implicit workhorse (Grammarly's accept/reject, not thumbs). Per steer TYPE we track,
+// from BEHAVIOR alone: shown (fired), acted (you moved off the work-type it pushed you off next turn),
+// paid (acting also produced an n+1 time-saved credit). This is revealed preference — which of your
+// patterns you actually act on — and it accretes across sessions into your personal steer model.
+function recordAdherence(prefs, prev, thisWt, paid) {
+  if (!prev || !prev.type || !thisWt) return null;
+  prefs.stats = prefs.stats || {};
+  const st = prefs.stats[prev.type] || { shown: 0, acted: 0, paid: 0 };
+  st.shown += 1;
+  const acted = prev.wt && thisWt !== prev.wt; // you left the work-type the steer pushed you off
+  if (acted) st.acted += 1;
+  if (acted && paid) st.paid += 1;
+  prefs.stats[prev.type] = st;
+  return { acted: !!acted }; // the same judgment the adherence insight row reuses (never re-derived)
+}
+
+// The GATE (de-prioritize what you ignore, like Grammarly demotes never-accepted rules): a steer TYPE
+// you've been shown enough times and consistently DON'T act on gets suppressed for you. Conservative
+// sample + threshold so a couple of ignores never kills a type; only a real pattern of ignoring does.
+function ignoredByAdherence(prefs, type) {
+  const st = prefs.stats && prefs.stats[type];
+  return !!(st && st.shown >= 6 && st.acted / st.shown < 0.2);
+}
+function writePrefs(p) {
+  try {
+    mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+    const tmp = `${PREFS_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify(p));
+    renameSync(tmp, PREFS_PATH);
+  } catch {
+    /* prefs are a bonus; never block the hook */
+  }
+}
+
+// Parse a control PHRASE aimed at skalpel out of the user's prompt — the explicit feedback channel,
+// captured natively through the prompt (no button UI needed; this IS the harness wrapping). Returns
+// {action} or null. Deliberately narrow so normal prose never trips it: the word "skalpel", or a
+// short standalone reaction right after a steer fired.
+function parseControl(q) {
+  const t = (q || "").trim().toLowerCase();
+  if (t.length > 60) return null; // a real coding prompt, not a reaction
+  const mentionsUs = /\bskalpel\b/.test(t);
+  // Explicit feedback is the LIGHT layer on top of the implicit adherence loop — natural-language
+  // control the user can type when they want to steer skalpel directly. Mute is the important one.
+  if (
+    /\b(mute|silence|shut ?up|turn off|disable|stop steering|quiet)\b/.test(t) &&
+    (mentionsUs || t.length < 24)
+  )
+    return { action: "mute" };
+  if (
+    /\bunmute|re-?enable|turn (it )?back on|resume steering\b/.test(t) &&
+    (mentionsUs || t.length < 24)
+  )
+    return { action: "unmute" };
+  if (
+    /\b(fewer|less|stop) (of )?(these|this|that|like this|steers?)\b/.test(t) ||
+    /\bfewer like this\b/.test(t)
+  )
+    return { action: "fewer" };
+  if (/\b(tell me more|more detail|expand|go deeper|more on this|explain the trap)\b/.test(t))
+    return { action: "more" };
+  if (
+    /\b(that('?s| was)? (helpful|useful|good|great)|nice catch|good (call|catch)|helped|love (this|that)|👍)\b/.test(
+      t,
+    )
+  )
+    return { action: "up" };
+  if (/\b(not (helpful|useful)|wrong|useless|👎|off base|missed)\b/.test(t) && mentionsUs)
+    return { action: "down" };
+  return null;
+}
+
+// SESSION EVENT LOG — the raw material for the end-of-session recap (peak-end rule). One row per turn
+// where a steer fired or a break-out was credited. SessionStart resets it; SessionEnd renders it.
+const SESSION_PATH = join(homedir(), ".skalpel", "session.json");
+function logSessionEvent(ev) {
+  try {
+    let s = { steers: [], caught: 0, mins: 0 };
+    try {
+      s = { ...s, ...JSON.parse(readFileSync(SESSION_PATH, "utf8")) };
+    } catch {
+      /* fresh session */
+    }
+    if (ev.type) s.steers.push({ type: ev.type, wt: ev.wt || null, ts: Date.now() });
+    if (ev.caughtMins) {
+      s.caught += 1;
+      s.mins += ev.caughtMins;
+    }
+    mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+    const tmp = `${SESSION_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify(s));
+    renameSync(tmp, SESSION_PATH);
+  } catch {
+    /* the recap is a bonus; never block the hook */
+  }
+}
+
+// Apply a control phrase to prefs, keyed to the LAST steer that fired (readSteer). Returns a short
+// ack note to inject so the model CONFIRMS the change in the user's own terms (that confirmation IS
+// the felt feedback loop), or null when no acknowledgement is needed.
+function applyControl(action, prefs) {
+  const last = readSteer();
+  const key = last.type ? (last.wt ? `${last.type}:${last.wt}` : last.type) : null;
+  const bump = (dir) => {
+    if (!last.type) return;
+    const sc = prefs.score[last.type] || { up: 0, down: 0 };
+    sc[dir] += 1;
+    prefs.score[last.type] = sc;
+  };
+  if (action === "mute") {
+    prefs.muted_session = true;
+    writePrefs(prefs);
+    return (
+      "[skalpel — the user asked to MUTE skalpel for this session. Acknowledge in ONE short line " +
+      "(“🔬 skalpel · muted for this session — I'll stay quiet”) and surface NO steers the rest of this session.]"
+    );
+  }
+  if (action === "unmute") {
+    prefs.muted_session = false;
+    writePrefs(prefs);
+    return "[skalpel — the user re-enabled skalpel. Acknowledge in one short line and continue.]";
+  }
+  if (action === "fewer") {
+    if (key) prefs.suppress[key] = true;
+    bump("down");
+    writePrefs(prefs);
+    return (
+      `[skalpel — the user wants FEWER steers like the last one${last.wt ? ` (${last.wt})` : ""}. ` +
+      "Acknowledge in one line (“🔬 skalpel · got it — easing off those”); skalpel will stop firing that trap for them.]"
+    );
+  }
+  if (action === "more") {
+    if (key) prefs.verbose[key] = true;
+    writePrefs(prefs);
+    return (
+      `[skalpel — the user wants MORE detail whenever they hit this${last.wt ? ` ${last.wt}` : ""} trap. ` +
+      "Acknowledge briefly, and from now on EXPAND that steer: name the shape, the count, and the way out.]"
+    );
+  }
+  if (action === "up") {
+    bump("up");
+    writePrefs(prefs);
+    return null; // positive signal — just record it; no need to make the model announce anything
+  }
+  if (action === "down") {
+    if (key) prefs.suppress[key] = true;
+    bump("down");
+    writePrefs(prefs);
+    return "[skalpel — the user found the last steer unhelpful. Acknowledge briefly; skalpel will ease off that one.]";
+  }
+  return null;
+}
+
+// Plain-English one-liners for the ack INSIGHT RECORD (the TUI row) — the user-visible restatement
+// of the control that fired, never the bracketed model directive applyControl returns. "up" is
+// absent on purpose: applyControl returns no ack note for it, so no record is written.
+const ACK_DISPLAY = {
+  mute: "muted for this session",
+  unmute: "back on",
+  fewer: "easing off those",
+  more: "expanding that steer from now on",
+  down: "easing off that one",
+};
+
+// TRAJECTORY of work-type classes this session — the last few states, sent to the server so it can
+// fire the discriminative TELL (a multi-turn shape that predicts a bad session). SessionStart clears it.
+const TRAJ_PATH = join(homedir(), ".skalpel", "traj.json");
+function readTraj() {
+  try {
+    return JSON.parse(readFileSync(TRAJ_PATH, "utf8")) || [];
+  } catch {
+    return [];
+  }
+}
+function pushTraj(cls) {
+  try {
+    const t = readTraj();
+    t.push(cls);
+    mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+    const tmp = `${TRAJ_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify(t.slice(-4))); // keep the last 4 turns
+    renameSync(tmp, TRAJ_PATH);
+  } catch {
+    /* trajectory is best-effort */
+  }
+}
+
+// local debug trail — proves the hook RAN (in any session), and what it decided. Fail-safe.
+function dbg(msg) {
+  if (process.env.SKALPEL_DEBUG === "0") return;
+  try {
+    const p = join(homedir(), ".skalpel");
+    mkdirSync(p, { recursive: true });
+    appendFileSync(join(p, "hook.log"), `${new Date().toISOString()} ${msg}\n`);
+  } catch {
+    /* never block on logging */
+  }
+}
+
+async function main() {
+  let payload = {};
+  try {
+    payload = JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return;
+  }
+  const query = lastUserPrompt(payload).trim();
+  dbg(`ran api=${API} q=${JSON.stringify(query.slice(0, 50))}`);
+
+  // Best-effort provenance for the local insight records: which harness fired us + the session id.
+  const sessionId = payload.session_id ?? null;
+  const fromClaude = payload.transcript_path?.includes(".claude") || payload.hook_event_name;
+  const fromCodex = process.env.CODEX_HOME || payload.transcript_path?.includes(".codex");
+  const harness = fromClaude ? "claude" : fromCodex ? "codex" : null;
+
+  if (!isRealPrompt(query)) {
+    dbg("  -> skipped (not a real prompt)");
+    record("prompt", "skipped", null);
+    return;
+  }
+
+  // FEEDBACK CHANNEL (explicit): the user talks back to the last steer in plain language — "mute",
+  // "fewer like this", "tell me more", "that helped". Captured natively out of the prompt (no button
+  // UI — this is the harness wrapping). Adjusts prefs; the ack note makes the model confirm it.
+  const prefs = readPrefs();
+  const control = parseControl(query);
+  let ackNote = null;
+  if (control) {
+    ackNote = applyControl(control.action, prefs);
+    dbg(`  -> control: ${control.action}`);
+  }
+
+  // TRAJECTORY (client-side, pre-server): are you spiraling RIGHT NOW? >=2 corrections/interrupts in
+  // the last few turns -> the felt "let's reset" human interrupt, independent of the server steer.
+  const cascade = detectCascade(payload);
+  let resetNote = null;
+  if (cascade >= 2) {
+    resetNote =
+      `[skalpel — the user has cut you off / re-corrected you ~${cascade} times in the last few turns. ` +
+      `You are NOT landing it, and retrying the same approach is their single biggest time sink. STOP. ` +
+      `Open with ONE line — "🔬 skalpel · we've gone back and forth a few times — stopping to reset rather ` +
+      `than push the same approach:" — then (1) restate in one sentence what they actually want, to confirm ` +
+      `you've got it, and (2) take a GENUINELY different tack, not a variation of what just failed.]`;
+    dbg(`  -> CASCADE ${cascade} -> reset interrupt`);
+  }
+
+  // Shared budget starts BEFORE auth so a token refresh is charged against the same deadline as the
+  // retrieve — the two can never stack past DEADLINE_MS.
+  const deadline = Date.now() + DEADLINE_MS;
+
+  // identity from the Google sign-in (refreshed if near expiry); the token authenticates the call so
+  // the server keys the graph by the VERIFIED uid. No token (dev/not signed in) -> server falls back.
+  const { uid, token } = await identity();
+  const user = uid || CFG.user || "anon";
+  const headers = { "content-type": "application/json" };
+  if (token) headers.authorization = `Bearer ${token}`;
+
+  const remaining = deadline - Date.now();
+  if (remaining <= 100) {
+    dbg("  -> budget spent by auth, skipping retrieve");
+    record("prompt", "budget_spent", DEADLINE_MS);
+    return;
+  }
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), remaining);
+  const t0 = Date.now();
+  let injection = null;
+  let winNote = null; // positive reinforcement: set when THIS turn confirms you broke out of a rut
+  let winMins = null; // the ~minutes the win note cites — reused verbatim by the insight record
+  let steerLabel = null; // "what skalpel's doing" for the statusline
+  let steerType = null; // raw top-steer type (TELL/SINK/…) — for the feedback loop + session log
+  let steerWt = null; // the work-type the steer is about (refine/debug/…)
+  let creditMins = null; // the +Xmin the n+1 check credited THIS turn -> statusline tick
+  let outcome = "fetch_error";
+  try {
+    const r = await fetch(`${API}/retrieve`, {
+      method: "POST",
+      headers,
+      // `recent` = the last few work-type classes THIS session (the trajectory) — lets the server fire
+      // the discriminative TELL ("you're on refine→refine→refine, the shape that goes bad 8×").
+      // `surface: "panel"` only for embedded TUI spawns (the TUI renders insights in its own panel,
+      // so the server keeps the steering but drops every "emit a 🔬 line" instruction). The key is
+      // omitted entirely otherwise — byte-stable body for non-embedded users.
+      body: JSON.stringify({
+        user_id: user,
+        query,
+        recent: readTraj(),
+        ...(process.env.SKALPEL_EMBEDDED === "1" ? { surface: "panel" } : {}),
+      }),
+      signal: ctrl.signal,
+    });
+    if (r.ok) {
+      const j = await r.json();
+      injection = j?.injection;
+      outcome = injection ? "inject" : "silent";
+      steerLabel = j?.steer_label; // surfaced on the statusline (written once below, with any credit)
+      steerType = j?.steer_type || null;
+      steerWt = j?.steer_wt || (j?.entry ? String(j.entry).split("/")[0] : null);
+      if (j?.entry) pushTraj(String(j.entry).split("/")[0]); // remember this turn's work-type
+      dbg(`  -> sim=${j?.top_sim ?? "?"} ${injection ? "INJECT" : "silent"}`);
+
+      // readSteer() still holds the PRIOR turn's steer (we overwrite it below) — used after the n+1
+      // credit resolves to record adherence (did you act on it, and did acting pay off).
+      const prevSteer = readSteer();
+      // HONOR prefs + adherence GATE: mute / per-trap "fewer" / a type you consistently ignore all
+      // suppress the steer; "more" expands it.
+      const key = steerType ? (steerWt ? `${steerType}:${steerWt}` : steerType) : null;
+      const ignored = steerType && ignoredByAdherence(prefs, steerType);
+      if (prefs.muted_session || (key && prefs.suppress[key]) || ignored) {
+        injection = null;
+        steerLabel = null;
+        dbg(
+          `  -> suppressed (${prefs.muted_session ? "muted" : ignored ? "ignored-type" : "fewer"}) ${key || ""}`,
+        );
+      } else if (key && prefs.verbose[key] && injection) {
+        injection +=
+          "\n\n[skalpel — the user asked for MORE on this trap; expand: name the shape, the count, and the way out in 2-3 sentences.]";
+      }
+
+      // --- n+1 CONFIRMATION: credit the DROP in expected waste-ahead (diff-from-worst) ---
+      // Turn N (a flagged high-waste moment) armed pending with V(N) = the DAG's expected waste ahead
+      // from where you were. THIS turn's waste-ahead is V(N+1) = j.state_hours. If it DROPPED, you
+      // moved toward resolved -> credit the drop (the real magnitude of time saved, now that the DAG
+      // state values discriminate stuck-vs-resolved; before they were flat so the drop was always 0).
+      const vNow = typeof j?.state_hours === "number" ? j.state_hours : null;
+      const vcNow = typeof j?.state_cost === "number" ? j.state_cost : 0;
+      const pending = readPending();
+      if (pending && typeof pending.v === "number" && vNow !== null) {
+        const savedH = Math.max(0, pending.v - vNow); // waste-ahead you shed since last turn
+        const savedC = Math.max(0, (pending.vc || 0) - vcNow);
+        // COHERENCE: a "catch" must be a REAL, visible >=1min drop. Everything downstream — the counter,
+        // the "+Xmin this turn" tick, the "N caught" tally, the recap minutes — is driven by the SAME
+        // number (cm), so caught can NEVER increment without the time moving by the same amount. (The old
+        // code credited sub-minute drops and forced caughtMins to 1 via Math.max, so caught ticked up
+        // while creditMins rounded to 0 and the visible time didn't budge — the incoherence.)
+        const cm = Math.round(savedH * 60);
+        if (cm >= 1) {
+          bumpStats(savedH, savedC);
+          creditMins = cm; // the felt "+Xmin ✓" tick — same value as the catch
+          logSessionEvent({ caughtMins: cm }); // caught++ and recap minutes, same number
+          dbg(`  -> n+1 CREDIT: waste-ahead ${pending.v}h -> ${vNow}h, +${cm}min saved`);
+          // REINFORCE GOOD MOVES (the carrot): on a MEANINGFUL break-out (not a trivial drop),
+          // hand the model a brief positive-acknowledgment note. Sparse by threshold so praise stays
+          // a signal, not noise — a coach that celebrates every micro-step becomes wallpaper too.
+          if (savedH >= 0.08) {
+            const mins = Math.max(1, Math.round(savedH * 60));
+            winMins = mins;
+            winNote =
+              `[skalpel — the user just broke OUT of a pattern that usually costs them ~${mins}min of rework. ` +
+              `If it feels natural (don't force it), briefly acknowledge the good move in one line — ` +
+              `e.g. "🔬 skalpel · nice — you skipped the loop you usually get stuck in there" — then continue. ` +
+              `Reinforce the behavior, don't lecture. Skip it if the moment doesn't fit.]`;
+          }
+        } else {
+          dbg(
+            `  -> n+1 no-credit: waste-ahead ${pending.v}h -> ${vNow}h (drop < 1min, not counted)`,
+          );
+        }
+        writePending({}); // this turn's confirmation is consumed
+      }
+      // Arm NEXT turn: when the injection fires (a flagged high-waste moment) AND we have a V for this
+      // turn, remember it so N+1 can measure how far your waste-ahead dropped.
+      if (injection && vNow !== null) {
+        writePending({ v: vNow, vc: vcNow });
+      } else if (!pending || vNow !== null) {
+        writePending({}); // clear only when we actually had data this turn (don't drop a stale carry)
+      }
+
+      // IMPLICIT ADHERENCE (the real Grammarly loop): now that the n+1 credit has resolved, record
+      // whether LAST turn's steer landed — did you act on it (moved off its work-type) and did acting
+      // pay off (a credit this turn). Accretes per steer-type; the gate above reads it next time.
+      const paid = creditMins != null && creditMins > 0;
+      const adh = recordAdherence(prefs, prevSteer, steerWt, paid);
+      writePrefs(prefs);
+      // ADHERENCE INSIGHT ROW (data, not display — no `display` field): the same judgment, exported
+      // for the TUI's rail, joined to the prior steer by its minted id. followed = the n+1 credit
+      // landed; ignored = you stayed on the very work-type the steer pushed you off AND no credit;
+      // anything else (no prior steer / indeterminate turn) writes nothing.
+      const adhOutcome = paid ? "followed" : adh && prevSteer.wt && !adh.acted ? "ignored" : null;
+      if (prevSteer?.id && adhOutcome)
+        recordInsight({
+          kind: "adherence",
+          ref: prevSteer.id,
+          outcome: adhOutcome,
+          harness,
+          session_id: sessionId,
+        });
+    } else {
+      outcome = "server_error";
+      dbg(`  -> server ${r.status}`);
+    }
+  } catch (e) {
+    outcome = e?.name === "AbortError" ? "abort" : "fetch_error";
+    dbg(`  -> fetch failed: ${String(e).slice(0, 60)}`);
+  } finally {
+    clearTimeout(timer);
+    record("prompt", outcome, Date.now() - t0);
+  }
+
+  // MUTE is absolute — a shushed session surfaces NOTHING (steer, reset, or win). The ack note (a
+  // one-time "muted" confirmation) still goes through, since that IS the mute turn's response.
+  if (prefs.muted_session) {
+    resetNote = null;
+    winNote = null;
+    injection = null;
+    steerLabel = null;
+  }
+
+  // A live cascade reset outranks the server steer for the statusline label (it's the acute one).
+  if (resetNote) steerLabel = "resetting a spiral";
+
+  // Statusline state, written ONCE per turn: what skalpel is doing now + the +Xmin the n+1 check just
+  // credited (the felt "just delivered" tick), plus the raw steer identity so NEXT turn's feedback
+  // phrase can target it. All null on a silent/no-credit turn -> bar shows just the running total.
+  // steerId = the join key minted once per STEER turn (a string), written to BOTH steer.json and the
+  // steer's insight row below, so next turn's adherence record can reference exactly this steer.
+  const steerId = injection ? String(Date.now()) : null;
+  writeSteer(steerLabel, creditMins, steerType, steerWt, steerId);
+  if (injection) logSessionEvent({ type: steerType, wt: steerWt }); // feed the end-of-session recap
+
+  // LOCAL INSIGHT RECORDS (~/.skalpel/insights.ndjson) — one plain-English row per note kind that
+  // fired this turn, post-suppression (a muted/suppressed steer writes nothing). recordInsight
+  // swallows everything, so these can never affect the hook output below.
+  if (injection)
+    recordInsight({
+      kind: "steer",
+      id: steerId,
+      display: steerLabel || "a steer for this spot",
+      label: steerLabel,
+      mins: creditMins > 0 ? creditMins : null,
+      harness,
+      session_id: sessionId,
+    });
+  if (winNote)
+    recordInsight({
+      kind: "win",
+      display: `nice — you broke out of a pattern that usually costs ~${winMins}min`,
+      mins: winMins,
+      harness,
+      session_id: sessionId,
+    });
+  if (resetNote)
+    recordInsight({
+      kind: "reset",
+      display: `we've gone back and forth ${cascade}× — resetting rather than pushing the same approach`,
+      harness,
+      session_id: sessionId,
+    });
+  if (ackNote)
+    recordInsight({
+      kind: "ack",
+      display: ACK_DISPLAY[control.action] || "preference updated",
+      harness,
+      session_id: sessionId,
+    });
+
+  // ackNote (feedback confirmation) leads, then the reset interrupt (most acute), the server steer,
+  // and the win note. Any can fire alone.
+  const additionalContext = [ackNote, resetNote, winNote, injection].filter(Boolean).join("\n\n");
+  if (additionalContext) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext },
+      }),
+    );
+  }
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch(() => process.exit(0));