skalpel 3.4.5 → 3.4.7

package/prosumer-hooks/install.mjs

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+// install.mjs — wire the hosted skalpel behavior hook into Claude Code AND Codex. Pure Node,
+// idempotent, and non-clobbering:
+// preserves any existing hooks/settings, refreshes ours in place. Run: `node install.mjs` (or --uninstall).
+import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const uninstall = process.argv.includes("--uninstall");
+
+// Where this installer's own files live — the globally-installed package, a source checkout, OR the
+// transient `npx` cache. All three must produce ONE working command, so we can't rely on a bin being
+// on PATH (only `npm i -g` puts it there; `npx` and a source run don't). Instead we copy the three
+// self-contained hook files into a STABLE home and wire an absolute `node <path>` command that works
+// offline, survives npx cache GC, and needs no global install — so `npx @skalpelai/prosumer-hook` is
+// the single command that leaves genuinely-working hooks.
+const PKG_DIR = dirname(fileURLToPath(import.meta.url));
+const HOOKS_DIR = join(homedir(), ".skalpel", "hooks");
+// Keep the staged basenames == the historical bin names so the idempotency/uninstall MARKER is
+// unchanged: an older bare-bin install (command "skalpel-prosumer-hook") is still recognized and
+// gets healed to the absolute command on the next run.
+const HOOK_FILE = join(HOOKS_DIR, "skalpel-hook.mjs");
+const SESSION_FILE = join(HOOKS_DIR, "skalpel-hook-session.mjs");
+const STATUSLINE_FILE = join(HOOKS_DIR, "skalpel-statusline.mjs");
+
+// Copy the hook runtime (the two entrypoints + their shared auth.mjs) into ~/.skalpel/hooks so the
+// wired absolute path is always valid. Overwrites on every install so upgrades refresh the code.
+function stageHookRuntime() {
+  // `skalpel setup` invokes the already-staged copy. Avoid copying a file onto itself.
+  if (PKG_DIR === HOOKS_DIR) return;
+  mkdirSync(HOOKS_DIR, { recursive: true });
+  // insights.mjs is staged BEFORE the entrypoints that import it — a mid-copy ENOENT
+  // must not leave a wired hook missing its import (auth/metrics staging order predates
+  // this rule and is guarded by the all-or-nothing check below instead).
+  // a hook entrypoint staged without a module it imports — the exact 0.3.12–0.3.16 bug shape.
+  copyFileSync(join(PKG_DIR, "insights.mjs"), join(HOOKS_DIR, "insights.mjs")); // hooks import ./insights.mjs
+  copyFileSync(join(PKG_DIR, "skalpel-hook.mjs"), HOOK_FILE);
+  copyFileSync(join(PKG_DIR, "skalpel-hook-session.mjs"), SESSION_FILE);
+  copyFileSync(join(PKG_DIR, "skalpel-statusline.mjs"), STATUSLINE_FILE);
+  copyFileSync(join(PKG_DIR, "auth.mjs"), join(HOOKS_DIR, "auth.mjs")); // hooks import ./auth.mjs
+  copyFileSync(join(PKG_DIR, "metrics.mjs"), join(HOOKS_DIR, "metrics.mjs")); // hooks import ./metrics.mjs
+  copyFileSync(join(PKG_DIR, "stats.mjs"), join(HOOKS_DIR, "stats.mjs")); // `node ~/.skalpel/hooks/stats.mjs`
+}
+if (!uninstall && !process.env.SKALPEL_HOOK_BIN) {
+  try {
+    stageHookRuntime();
+  } catch (e) {
+    // Staging is all-or-nothing. A missing source file means the tarball is incomplete (a file this
+    // installer copies was left out of package.json "files"), and copyFileSync throws part-way
+    // through — so the *later* copies never run and the hooks are staged without the auth.mjs /
+    // metrics.mjs they import. Wiring absolute paths at that point yields hooks that crash on every
+    // prompt. Refuse to wire instead; a loud failure beats a silent no-op.
+    console.error(`skalpel: could not stage hook runtime: ${e.message}`);
+    console.error("skalpel: hooks were NOT wired.");
+    process.exit(1);
+  }
+}
+
+// The wired command. Defaults to the staged absolute `node <path>`; SKALPEL_HOOK_BIN /
+// SKALPEL_HOOK_SESSION_BIN still override (dev, or a deliberate global-bin install).
+const CMD = process.env.SKALPEL_HOOK_BIN || `node ${HOOK_FILE}`;
+const SESSION_CMD = process.env.SKALPEL_HOOK_SESSION_BIN || `node ${SESSION_FILE}`;
+const STATUSLINE_CMD = process.env.SKALPEL_STATUSLINE_BIN || `node ${STATUSLINE_FILE}`;
+const CLAUDE = join(homedir(), ".claude", "settings.json");
+const CODEX_DIR = join(homedir(), ".codex");
+const CODEX = join(CODEX_DIR, "hooks.json");
+const CODEX_TOML = join(CODEX_DIR, "config.toml"); // Codex reads hooks from config.toml [hooks]
+// The idempotency/uninstall marker is the command's basename — always matches exactly what this
+// installer wired, including bare-bin names and absolute `node <path>` commands.
+const markerOf = (cmd) =>
+  cmd
+    .split(/[/\\]/)
+    .pop()
+    .replace(/\.(mjs|js|exe)$/, "");
+const HOOKS = [
+  ["UserPromptSubmit", markerOf(CMD), CMD],
+  ["SessionStart", markerOf(SESSION_CMD), SESSION_CMD],
+];
+
+function readJson(p) {
+  let raw;
+  try {
+    raw = readFileSync(p, "utf8");
+  } catch {
+    return {}; // missing file — a fresh {} is correct
+  }
+  if (!raw.trim()) return {}; // empty file
+  try {
+    return JSON.parse(raw);
+  } catch {
+    // The file EXISTS but is corrupt JSON. Returning {} here would make writeJson OVERWRITE and
+    // wipe the user's real settings. Never do that: back the broken file up and skip touching it.
+    try {
+      copyFileSync(p, `${p}.skalpel-bak-${Date.now()}`);
+    } catch {
+      /* best-effort backup */
+    }
+    return null; // signal "do not write" to callers
+  }
+}
+function writeJson(p, o) {
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(o, null, 2));
+}
+function isOurs(c, marker) {
+  if (typeof c !== "string") return false;
+  const markers = [
+    marker,
+    "skalpel-hook",
+    "skalpel-hook-session",
+    "skalpel-statusline",
+    "skalpel-prosumer-hook",
+    "skalpel-prosumer-hook-session",
+    "skalpel-prosumer-statusline",
+  ];
+  return markers.some((candidate) => {
+    const escaped = candidate.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[/\\\\\\s])${escaped}(\\.mjs|\\.js|\\.exe)?($|\\s)`).test(c);
+  });
+}
+
+// Claude Code: hooks.<event>[] = [{matcher?, hooks:[{type:"command", command:"…"}]}]. Each array
+// entry MUST be a matcher-GROUP with a `hooks` array — a bare {type,command} is invalid and makes
+// Claude Code reject the whole settings file ("Expected array, but received undefined"). Install
+// REFRESHES our entry in place (strip any prior ours — whether it's a correct group OR a legacy
+// bare-command entry a past buggy install wrote — then append a proper group). Idempotent AND
+// self-healing: re-running repairs a file broken by the old writer.
+function claude() {
+  const d = existsSync(CLAUDE) ? readJson(CLAUDE) : {};
+  if (d === null) return "skipped-corrupt"; // corrupt settings backed up; never overwrite blindly
+  d.hooks ??= {};
+  let installed = 0;
+  let refreshed = 0;
+  let removed = 0;
+  for (const [event, marker, command] of HOOKS) {
+    d.hooks[event] ??= [];
+    const arr = d.hooks[event];
+    const isMine = (e) => {
+      if (isOurs(e?.command, marker)) return true; // legacy bare {type,command} entry
+      const inner = Array.isArray(e?.hooks) ? e.hooks : [];
+      return inner.some((h) => isOurs(h?.command, marker));
+    };
+    const had = arr.some(isMine);
+    const kept = arr.filter((e) => !isMine(e)); // drop ours (both shapes) AND repair
+    // 8s, not 5s: the hosted backend can cold-start after idle, and the hook's own internal
+    // DEADLINE_MS (4.5s) needs headroom under this outer harness timeout or it gets killed first.
+    const group = { hooks: [{ type: "command", command, timeout: 8 }] };
+    d.hooks[event] = uninstall ? kept : [...kept, group];
+    if (uninstall) {
+      if (had) removed += 1;
+    } else if (had) {
+      refreshed += 1;
+    } else {
+      installed += 1;
+    }
+  }
+  // statusLine: not a hooks.<event> array, a single top-level key — only touch it if it's unset or
+  // already ours, so we never clobber a genuinely custom statusline someone configured themselves.
+  const statuslineIsOurs = isOurs(d.statusLine?.command, markerOf(STATUSLINE_CMD));
+  if (uninstall) {
+    if (statuslineIsOurs) {
+      delete d.statusLine;
+      removed += 1;
+    }
+  } else if (!d.statusLine || statuslineIsOurs) {
+    if (statuslineIsOurs) refreshed += 1;
+    else installed += 1;
+    d.statusLine = { type: "command", command: STATUSLINE_CMD };
+  }
+  writeJson(CLAUDE, d);
+  if (uninstall) return removed ? "removed" : "absent";
+  return installed ? "installed" : refreshed ? "refreshed" : "absent";
+}
+
+// Codex (per developers.openai.com/codex/hooks) reads UserPromptSubmit hooks from config.toml
+// under [[hooks.UserPromptSubmit.hooks]] — TOML, same schema as hooks.json. This Codex ships a
+// config.toml and no hooks.json, so config.toml is the reliable target. We write BOTH (docs accept
+// either) but config.toml is what actually fires. Install strips any prior ours then appends fresh.
+const TOML_MARK = "# skalpel-hook (managed)";
+const TOML_MARKERS = [TOML_MARK, "# skalpel-prosumer-hook (managed)"];
+
+function tomlMark(event, marker) {
+  return `${TOML_MARK} ${event} ${marker}`;
+}
+
+function tomlBlock(event, marker, command) {
+  return `\n${tomlMark(event, marker)}\n[[hooks.${event}]]\n[[hooks.${event}.hooks]]\ntype = "command"\ncommand = "${command}"\ntimeout = 8\n`;
+}
+
+function stripManagedTomlBlocks(txt) {
+  const lines = txt.split("\n");
+  const out = [];
+  let removed = 0;
+
+  for (let i = 0; i < lines.length; ) {
+    if (TOML_MARKERS.some((marker) => lines[i].includes(marker))) {
+      i += 6;
+      removed += 1;
+      continue;
+    }
+
+    const section = lines[i].match(/^\[\[hooks\.(UserPromptSubmit|SessionStart)\]\]\s*$/);
+    if (!section) {
+      out.push(lines[i]);
+      i += 1;
+      continue;
+    }
+
+    const event = section[1];
+    const marker = HOOKS.find(([hookEvent]) => hookEvent === event)?.[1];
+    const block = [lines[i]];
+    let j = i + 1;
+    while (
+      j < lines.length &&
+      !/^\[\[hooks\.(UserPromptSubmit|SessionStart)\]\]\s*$/.test(lines[j])
+    ) {
+      j += 1;
+      block.push(lines[j - 1]);
+    }
+
+    const command = block
+      .map((line) => line.match(/^\s*command\s*=\s*"([^"]*)"\s*$/)?.[1])
+      .find(Boolean);
+    if (marker && isOurs(command, marker)) {
+      removed += 1;
+    } else {
+      out.push(...block);
+    }
+    i = j;
+  }
+
+  return { text: out.join("\n"), removed };
+}
+
+function codexToml() {
+  if (!existsSync(CODEX_DIR)) return "no-codex";
+  const txt = existsSync(CODEX_TOML) ? readFileSync(CODEX_TOML, "utf8") : "";
+  // Strip current managed blocks and older unmanaged skalpel blocks, so setup heals stale Codex
+  // configs that still point at bare PATH commands from pre-staged installs.
+  const stripped = stripManagedTomlBlocks(txt);
+  let next = stripped.text.replace(/\n{3,}/g, "\n\n").trimEnd();
+  if (uninstall) {
+    writeFileSync(CODEX_TOML, next + "\n");
+    return stripped.removed ? "removed" : "absent";
+  }
+  mkdirSync(CODEX_DIR, { recursive: true });
+  for (const [event, marker, command] of HOOKS) {
+    next += "\n" + tomlBlock(event, marker, command);
+  }
+  writeFileSync(CODEX_TOML, next + "\n");
+  return stripped.removed ? "refreshed" : "installed";
+}
+
+// Also write hooks.json (docs accept either; harmless belt-and-suspenders for Codex builds that read it)
+function codexJson() {
+  if (!existsSync(CODEX_DIR)) return "no-codex";
+  const d = existsSync(CODEX) ? readJson(CODEX) : {};
+  if (d === null) return "skipped-corrupt"; // corrupt file backed up; don't overwrite
+  d.hooks ??= {};
+  let installed = 0;
+  let refreshed = 0;
+  let removed = 0;
+  for (const [event, marker, command] of HOOKS) {
+    d.hooks[event] ??= [];
+    if (!d.hooks[event].length) d.hooks[event].push({ hooks: [] });
+    const grp = d.hooks[event][0];
+    grp.hooks ??= [];
+    const had = grp.hooks.some((h) => isOurs(h?.command, marker));
+    const kept = grp.hooks.filter((h) => !isOurs(h?.command, marker));
+    grp.hooks = uninstall ? kept : [...kept, { type: "command", command, timeout: 8 }];
+    if (uninstall) {
+      if (had) removed += 1;
+    } else if (had) {
+      refreshed += 1;
+    } else {
+      installed += 1;
+    }
+  }
+  writeJson(CODEX, d);
+  if (uninstall) return removed ? "removed" : "absent";
+  return installed ? "installed" : refreshed ? "refreshed" : "absent";
+}
+
+// Global CLAUDE.md — a STANDING attribution rule, on disk, loaded every session regardless of
+// whether the per-turn hook's network call succeeds. The per-turn hook injects the DATA (the
+// walked pattern + the number for THIS occurrence) but its own copy of the attribution rule only
+// exists in that one injected block — miss the fetch (cold backend, timeout) and the rule never
+// even reaches the model that turn. This block is the fallback that can't be dropped by a network
+// hiccup: it's read from disk at session start, same as any other CLAUDE.md instruction.
+const CLAUDE_MD = join(homedir(), ".claude", "CLAUDE.md");
+const CLAUDE_MD_MARK_START = "<!-- skalpel-hook:attribution (managed) -->";
+const CLAUDE_MD_MARK_END = "<!-- /skalpel-hook:attribution (managed) -->";
+const CLAUDE_MD_MARK_PAIRS = [
+  [CLAUDE_MD_MARK_START, CLAUDE_MD_MARK_END],
+  [
+    "<!-- skalpel-prosumer-hook:attribution (managed) -->",
+    "<!-- /skalpel-prosumer-hook:attribution (managed) -->",
+  ],
+];
+const CLAUDE_MD_BLOCK = `${CLAUDE_MD_MARK_START}
+## skalpel
+
+A \`skalpel\` behavioral-graph hook may inject a per-turn context block (starts \`[skalpel — signals
+for THIS turn ...]\`) with behavioral facts about how this user works. The block itself carries the
+surfacing rule for that turn — follow it. There are two tiers:
+
+- STRONG (a TELL or PLAN signal fired — a rare, high-confidence finding like "you're on a shape that
+  went bad 8× and never landed clean"): you MUST make the user feel it. Open with a \`🔬 skalpel ·\`
+  line that SPEAKS THE ACTUAL STAT (the shape, the count, the ~minutes) in plain words, name the loop
+  out loud, and you MAY briefly own your part ("I kept refining right there with you"). Then give the
+  genuinely-different answer the steer implies.
+- SOFT (only sink/funnel/trigger-type signals): earned-only. Surface a \`🔬 skalpel ·\` line ONLY if a
+  signal genuinely changes your answer; otherwise a QUIET closing \`🔬 skalpel · told the model to:
+  <terse verbs>\` for an invisible tune, or nothing at all. Silence is the default here.
+
+The 🔬 line is skalpel's FINDING from the signals, never your own advice. One 🔬 line per turn at most.
+Never theater, never explain the mechanism.
+${CLAUDE_MD_MARK_END}`;
+
+function claudeMd() {
+  const raw = existsSync(CLAUDE_MD) ? readFileSync(CLAUDE_MD, "utf8") : "";
+  let stripped = raw;
+  let had = false;
+  for (const [start, end] of CLAUDE_MD_MARK_PAIRS) {
+    const startIdx = stripped.indexOf(start);
+    const endIdx = stripped.indexOf(end);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx >= startIdx) {
+      stripped = (
+        stripped.slice(0, startIdx) + stripped.slice(endIdx + end.length)
+      ).replace(/\n{3,}/g, "\n\n");
+      had = true;
+    }
+  }
+  if (uninstall) {
+    if (!had) return "absent";
+    writeFileSync(CLAUDE_MD, stripped.trimEnd() + "\n");
+    return "removed";
+  }
+  const next = stripped.trimEnd()
+    ? `${stripped.trimEnd()}\n\n${CLAUDE_MD_BLOCK}\n`
+    : `${CLAUDE_MD_BLOCK}\n`;
+  mkdirSync(dirname(CLAUDE_MD), { recursive: true });
+  writeFileSync(CLAUDE_MD, next);
+  return had ? "refreshed" : "installed";
+}
+
+console.log(
+  `skalpel hook (${uninstall ? "uninstall" : CMD}) → claude: ${claude()} · claude.md: ${claudeMd()} · codex(config.toml): ${codexToml()} · codex(hooks.json): ${codexJson()}`,
+);
+console.log(
+  uninstall
+    ? "uninstalled."
+    : `installed. Hooks run from ${HOOKS_DIR} and use the canonical skalpel Cognito login.`,
+);

package/prosumer-hooks/metrics.mjs

@@ -0,0 +1,32 @@
+// metrics.mjs — injection telemetry, shared by both hooks. One NDJSON line per hook invocation.
+// Append is atomic on POSIX for small writes, so concurrent hook double-fires never race or corrupt
+// the file (a live-mutated counter file WOULD lose increments under that race). record() never throws
+// and never blocks — telemetry must not be able to break a fail-open hook.
+//
+// Read it back with:  node ~/.skalpel/hooks/stats.mjs
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DIR = join(homedir(), ".skalpel");
+export const METRICS_PATH = join(DIR, "metrics.ndjson");
+
+// outcome ∈ inject | silent | server_error | abort | fetch_error | skipped | budget_spent
+// `abort` == the fetch hit our deadline == a graph cold-start hit (the whole diagnosis).
+// ms == wall-clock of the network call (null for skipped / pre-network exits).
+export function record(event, outcome, ms) {
+  try {
+    mkdirSync(DIR, { recursive: true });
+    appendFileSync(
+      METRICS_PATH,
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        event, // "prompt" | "session"
+        outcome,
+        ms: ms == null ? null : Math.round(ms),
+      }) + "\n",
+    );
+  } catch {
+    /* never block a hook on telemetry */
+  }
+}

package/prosumer-hooks/skalpel-hook-session.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// skalpel SessionStart hook — fires ONCE when a Claude Code / Codex session opens. Injects the
+// user's standing Amplitude profile (recurring patterns, outcome rates, response habits) so the
+// model starts the session already knowing how they work. The per-turn UserPromptSubmit hook
+// handles the specific query (the graph-walk fork); this handles the standing context. Fail-open.
+//
+// Wire it (Claude ~/.claude/settings.json):
+//   {"hooks":{"SessionStart":[{"hooks":[{"type":"command","command":"node …/skalpel-hook-session.mjs"}]}]}}
+import { readFileSync, writeFileSync, renameSync, 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";
+
+// The statusline counter is PER-SESSION: it shows the estimated rework skalpel flagged during THIS
+// session, not a forever-accumulating lifetime total (which reads as a bragging trophy and is
+// unprovable). SessionStart zeroes it so each new session starts the count fresh. Fail-open — a
+// stats reset must never block the profile injection.
+// RECAP — the felt wins, surfaced at a break point (peak-end rule). Two break points:
+//   • "compact"  → mid-session, right AFTER compaction (a natural chapter break, user present). The
+//                  recap is CUMULATIVE ("so far this session") and the tally is NOT reset — work goes on.
+//   • else       → a fresh session start; recap the PREVIOUS session's tally (re-engagement), then reset.
+// PreCompact/SessionEnd stdout are silent in Claude Code; the post-compact SessionStart CAN inject, so
+// that's where the compaction recap rides. Read BEFORE resetStats wipes it.
+const SESSION_PATH = join(homedir(), ".skalpel", "session.json");
+// Returns { note, mins } — the injected directive AND the minutes it cites, so the local insight
+// record (below) can reuse the exact same number instead of re-deriving it.
+function buildRecap(source) {
+  try {
+    const s = JSON.parse(readFileSync(SESSION_PATH, "utf8"));
+    const mins = Math.round(s.mins || 0);
+    const steers = Array.isArray(s.steers) ? s.steers : [];
+    // Recap only when there's real saved time to report — the honest, felt number. No "caught" count.
+    if (mins < 1) return { note: null, mins: 0 };
+    const byWt = {};
+    for (const st of steers) if (st.wt) byWt[st.wt] = (byWt[st.wt] || 0) + 1;
+    const top = Object.entries(byWt).sort((a, b) => b[1] - a[1])[0];
+    const trapTail = top ? ` — ${top[0]} kept coming up` : "";
+    const compact = source === "compact";
+    const when = compact ? "in the stretch before this compaction" : "last session";
+    const line = compact
+      ? `“🔬 skalpel · in that last stretch I saved you ~${mins}min${trapTail} — fresh context now.”`
+      : `“🔬 skalpel · last session I saved you ~${mins}min${trapTail}.”`;
+    const note =
+      `[skalpel — RECAP (${when}): saved ~${mins}min` +
+      (top ? `; the recurring trap was ${top[0]} (${top[1]}×)` : "") +
+      `. Open THIS message with ONE natural line so they see it landed — ${line} ` +
+      "Then continue normally. Skip it only if it doesn't fit.]";
+    return { note, mins };
+  } catch {
+    return { note: null, mins: 0 }; // no prior session / fresh install
+  }
+}
+
+function resetStats() {
+  try {
+    const dir = join(homedir(), ".skalpel");
+    mkdirSync(dir, { recursive: true });
+    const p = join(dir, "stats.json");
+    // Reset the SESSION counters to zero but PRESERVE the lifetime total across sessions — so the
+    // statusline can show both "saved this session" and "total saved". Read current first.
+    let s = {
+      session_hours: 0,
+      session_cost: 0,
+      session_events: 0,
+      total_hours: 0,
+      total_cost: 0,
+      total_events: 0,
+    };
+    try {
+      s = { ...s, ...JSON.parse(readFileSync(p, "utf8")) };
+    } catch {
+      /* fresh */
+    }
+    s.session_hours = 0;
+    s.session_cost = 0;
+    s.session_events = 0;
+    const tmp = `${p}.tmp`;
+    writeFileSync(tmp, JSON.stringify(s));
+    renameSync(tmp, p);
+    // also clear any pending n+1 prediction from the prior session — a stale prediction must never
+    // false-credit an avoided detour across a session boundary.
+    writeFileSync(join(dir, "pending.json"), "{}");
+    writeFileSync(join(dir, "steer.json"), "{}"); // no live steer until the first prompt this session
+    writeFileSync(join(dir, "traj.json"), "[]"); // fresh work-type trajectory each session
+    writeFileSync(join(dir, "session.json"), JSON.stringify({ steers: [], caught: 0, mins: 0 })); // recap tally
+    // clear the SESSION-scoped mute (a shush lasts one session), but PRESERVE persistent prefs
+    // (per-trap "fewer"/"more", usefulness scores) — those are the learned personalization.
+    try {
+      const pp = join(dir, "prefs.json");
+      const pr = JSON.parse(readFileSync(pp, "utf8"));
+      if (pr.muted_session) {
+        pr.muted_session = false;
+        writeFileSync(pp, JSON.stringify(pr));
+      }
+    } catch {
+      /* no prefs yet */
+    }
+  } catch {
+    /* never block on stats */
+  }
+}
+
+// Config precedence: env > ~/.skalpel/client.json (written by `skalpel-prosumer setup`) > default.
+// Identity: the uid from the Google sign-in (~/.skalpel/auth.json); SKALPEL_USER overrides for dev.
+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";
+// Shared wall-clock budget for the whole hook (auth-refresh + insights fetch): cap total time so it
+// self-aborts before the harness kill (settings timeout is 8s), and record every outcome. This is
+// MORE generous than the per-turn hook's 4.5s on purpose: /retrieve is kept warm (~1.8s) but /insights
+// is NOT, and its cold-start loads the full graph (corpus + index + agg_dag). At 4.5s a cold /insights
+// aborted -> the whole SessionStart profile silently vanished (no error, no injection). 7s fits a cold
+// load with ~1s margin under the 8s backstop; warm it still returns in ~300ms, so no cost when hot.
+const DEADLINE_MS = 7000;
+
+async function main() {
+  let payload = {};
+  try {
+    payload = JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    /* drain stdin, ignore */
+  }
+  // source distinguishes a real new session (startup/resume/clear) from a mid-session compaction.
+  const source = payload.source || payload.hookSpecificOutput?.source || "startup";
+  const { note: recapNote, mins: recapMins } = buildRecap(source); // read the tally BEFORE resetStats wipes it
+  // Compaction CONTINUES the session — keep the counter + tally running; only a real start zeroes them.
+  if (source !== "compact") resetStats();
+  // identity from the Google sign-in (refreshed if near expiry); the token authenticates the read so
+  // the server keys the profile by the VERIFIED uid. No token (dev/not signed in) -> server fallback.
+  const deadline = Date.now() + DEADLINE_MS;
+  const { uid, token } = await identity();
+  const user = uid || CFG.user || "anon";
+  const remaining = deadline - Date.now();
+  if (remaining <= 100) {
+    record("session", "budget_spent", DEADLINE_MS);
+    return;
+  }
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), remaining);
+  const t0 = Date.now();
+  let context = null;
+  let nSessions = null; // sessions of history behind the standing profile — for the insight record
+  let outcome = "fetch_error";
+  try {
+    const r = await fetch(`${API}/insights?user_id=${encodeURIComponent(user)}`, {
+      headers: token ? { authorization: `Bearer ${token}` } : {},
+      signal: ctrl.signal,
+    });
+    if (r.ok) {
+      const j = await r.json();
+      context = j?.context;
+      nSessions = typeof j?.n_sessions === "number" ? j.n_sessions : null;
+      outcome = context ? "inject" : "silent";
+    } else {
+      outcome = "server_error";
+    }
+  } catch (e) {
+    outcome = e?.name === "AbortError" ? "abort" : "fetch_error";
+  } finally {
+    clearTimeout(timer);
+    record("session", outcome, Date.now() - t0);
+  }
+
+  // Recap (last session's felt wins) leads, then the standing profile. Either can fire alone — a first
+  // session has no recap; a session with no graph yet has no profile but can still recap.
+  const additionalContext = [recapNote, context].filter(Boolean).join("\n\n");
+
+  // LOCAL INSIGHT RECORDS (~/.skalpel/insights.ndjson) — plain-English rows for the TUI, one per
+  // note that fired. recordInsight swallows everything, so these never affect the hook output.
+  if (recapNote)
+    recordInsight({
+      kind: "recap",
+      display: `last session skalpel saved you ~${recapMins}min`,
+      mins: recapMins,
+    });
+  if (context)
+    recordInsight({
+      kind: "profile",
+      display:
+        nSessions != null
+          ? `standing profile loaded — ${nSessions} sessions of history`
+          : "standing profile loaded",
+    });
+
+  if (additionalContext) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: "SessionStart", additionalContext },
+      }),
+    );
+  }
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch(() => process.exit(0));