skalpel 4.0.1 → 4.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "description": "Behavioral graph for AI-assisted coding — learns how you work and steers Claude Code + Codex in real time.",
   "type": "module",
   "bin": {

package/skalpel-hook-session.mjs

@@ -121,6 +121,38 @@ const API = process.env.SKALPEL_API || CFG.api || "https://graph.skalpel.ai";
 // load with ~1s margin under the 8s backstop; warm it still returns in ~300ms, so no cost when hot.
 const DEADLINE_MS = 7000;
 
+// One-shot reveal: the detached background build drops ~/.skalpel/insights-ready.json when it
+// finishes. Surface it ONCE at the next session start, then clear it — so the user sees "your graph is
+// ready + here's what I learned" the moment it lands. This is the payoff of the async build.
+function graphReadyNote() {
+  const p = join(homedir(), ".skalpel", "insights-ready.json");
+  let m;
+  try {
+    m = JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null; // nothing pending
+  }
+  if (!m || !m.ready) return null;
+  try {
+    writeFileSync(p, JSON.stringify({ ready: false })); // one-shot — clear so it never repeats
+  } catch {
+    /* if we can't clear it we'd rather drop the reveal than repeat it, but proceed */
+  }
+  const h = (m.report && m.report.headline) || {};
+  const trap = m.report && (m.report.discriminative || [])[0] && m.report.discriminative[0].seq;
+  const n = m.n_sessions || h.sessions || 0;
+  const bits = [];
+  if (h.hours) bits.push(`~${h.hours}h with AI`);
+  if (h.rework_pct) bits.push(`~${h.rework_pct}% of it went to rework`);
+  if (trap) bits.push(`your signature trap is ${trap}`);
+  const learned = bits.length ? ` I learned: ${bits.join(", ")}.` : "";
+  return (
+    `[skalpel — the user's behavioral graph just FINISHED building in the background ` +
+    `(${n} session${n === 1 ? "" : "s"}). Open THIS reply with ONE natural line so they see it landed, ` +
+    `in skalpel's voice: "🔬 skalpel · your graph is ready —${learned}" Then continue normally.]`
+  );
+}
+
 async function main() {
   let payload = {};
   try {
@@ -169,9 +201,10 @@ async function main() {
     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");
+  // A just-finished background build leads (the async payoff — surface it the instant it's ready),
+  // then last session's recap, then the standing profile. Any can fire alone.
+  const readyNote = graphReadyNote();
+  const additionalContext = [readyNote, 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.

package/skalpel-setup.mjs

@@ -818,8 +818,12 @@ async function main() {
   //    so the user SEES skalpel already knows them before typing a prompt. Escape hatches:
   //    SKALPEL_SETUP_BACKGROUND=1 keeps the old fast "warming in the background" path; non-TTY (CI)
   //    always goes background/silent so a pipeline never blocks on the reveal.
+  // DEFAULT is now BACKGROUND: `skalpel` returns you to your terminal in seconds and the graph builds
+  // detached — the batches judge + fold server-side while you keep working, and a desktop notification
+  // + a "your graph is ready" line at your next Claude Code session surface the insights when it's done.
+  // Blocking in the foreground (watch all N batches) is opt-in for anyone who wants to see it live.
   const wantReveal =
-    (isTTY || process.env.SKALPEL_SETUP_WAIT_FOR_GRAPH === "1") &&
+    process.env.SKALPEL_SETUP_WAIT_FOR_GRAPH === "1" &&
     process.env.SKALPEL_SETUP_BACKGROUND !== "1";
 
   if (process.env.SKALPEL_DEMO) {
@@ -858,14 +862,20 @@ async function main() {
       );
     }
   } else if (files.length) {
-    // background/silent path (opt-out or CI): fast, no reveal
+    // DEFAULT async path: kick off the detached build and hand the terminal straight back.
     startBackgroundBuild();
     const capped = Math.min(
       files.length,
-      Math.max(1, Number.parseInt(process.env.SKALPEL_MAX_UPLOAD_SESSIONS || "20", 10)),
+      Math.max(1, Number.parseInt(process.env.SKALPEL_MAX_UPLOAD_SESSIONS || "40", 10)),
+    );
+    console.log(
+      `   ${G}✓${X} Building your graph from your newest ${capped} session${capped === 1 ? "" : "s"} — ${B}in the background${X}.`,
+    );
+    console.log(
+      `   ${D}Keep coding. I'll notify you and surface your insights the moment it's ready.${X}`,
     );
     await reportLiveAndLaunch(
-      `\n   ${B}${G}You're live.${X}  ${D}hooks are wired; your graph is warming from the newest ${capped} session${capped === 1 ? "" : "s"} in the background.${X}\n`,
+      `\n   ${B}${G}You're live.${X}  ${D}every prompt already pulls your history as it learns.${X}\n`,
     );
   } else {
     await reportLiveAndLaunch(
@@ -875,6 +885,8 @@ async function main() {
 }
 
 // The detached background build (spawned by main): does ONLY the upload+judge, no banner/hooks.
+// On success it stashes the fresh profile (for the next Claude Code SessionStart to reveal) and fires
+// a desktop notification, so the async build surfaces itself the moment it's ready.
 async function backgroundBuild() {
   const id = await identity();
   if (!id) return; // not signed in — nothing to build under
@@ -882,12 +894,54 @@ async function backgroundBuild() {
   if (!files.length) return;
   const sp = { text: () => {}, succeed: () => {} }; // silent — no TTY in the background
   try {
-    await buildGraph(sp, files, id);
+    const built = await buildGraph(sp, files, id);
+    if (!built) return;
+    let report = null;
+    try {
+      report = await fetchProfile(id);
+    } catch {
+      /* profile fetch is best-effort — the graph is still built */
+    }
+    try {
+      mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+      writeFileSync(
+        join(homedir(), ".skalpel", "insights-ready.json"),
+        JSON.stringify({ ready: true, ts: Date.now(), n_sessions: built, report }),
+      );
+    } catch {
+      /* the SessionStart reveal is a bonus; never block the build on it */
+    }
+    notifyDone(built);
   } catch {
     /* fail-open: a failed background build never surfaces; hooks fail open until it succeeds */
   }
 }
 
+// Desktop notification when the background build finishes — cross-platform, best-effort, never throws.
+function notifyDone(n) {
+  const title = "skalpel";
+  const msg = `Your graph is ready — learned from ${n} session${n === 1 ? "" : "s"}. Open Claude Code to see your insights.`;
+  try {
+    if (process.platform === "darwin") {
+      spawnSync(
+        "osascript",
+        ["-e", `display notification ${JSON.stringify(msg)} with title ${JSON.stringify(title)}`],
+        { stdio: "ignore" },
+      );
+    } else if (process.platform === "linux") {
+      spawnSync("notify-send", [title, msg], { stdio: "ignore" });
+    } else if (process.platform === "win32") {
+      spawnSync(
+        "powershell",
+        ["-NoProfile", "-Command", `New-BurntToastNotification -Text '${title}','${msg}'`],
+        { stdio: "ignore" },
+      );
+    }
+  } catch {
+    /* notifications are best-effort */
+  }
+}
+
 // `__build` = the detached background graph build spawned by setup; skips the banner/hooks entirely.
 if (isMain && sub === "__build") {
   backgroundBuild()