skalpel 4.0.1 → 4.0.3

package/package.json

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

package/reveal.mjs

@@ -0,0 +1,61 @@
+// reveal.mjs — the one-shot "your graph is ready" reveal, shared by both hooks.
+//
+// The detached background build (skalpel-setup __build) drops ~/.skalpel/insights-ready.json when it
+// finishes. The FIRST hook to fire after that (the next per-turn prompt OR the next session start)
+// surfaces this reveal IN the Claude Code conversation — the native surface, no OS pop-up — then clears
+// the marker so it shows exactly once.
+//
+// Tone: this is the first time the user is seeing what skalpel learned about them, so the note directs
+// the model to TEACH them their own pattern in plain, warm English — never the internal notation, never
+// a stats dump.
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export 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, better to drop the reveal than repeat it — but proceed once */
+  }
+
+  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 facts = [];
+  if (h.hours)
+    facts.push(`they've spent about ${h.hours} hours working with AI across these sessions`);
+  if (h.rework_pct)
+    facts.push(
+      `roughly ${h.rework_pct}% of that time went into REWORK — going back to redo, re-explain, or ` +
+        `re-fix things they'd already worked on (that's the time skalpel is built to give back)`,
+    );
+  if (trap)
+    facts.push(
+      `the habit that most often kicks off that loop, in their own history, is the sequence "${trap}" ` +
+        `— TRANSLATE this into plain human language (e.g. "you ask me to explain something, then keep ` +
+        `refining the same thing in circles") and NEVER show the raw sequence or any arrow notation`,
+    );
+
+  return (
+    `[skalpel — the user's behavioral graph just finished building in the background, from ${n} of ` +
+    `their recent coding sessions. This is the FIRST time they're seeing what it learned about them, so ` +
+    `explain it like they've never seen their own patterns before: warm, plain, concrete — NO jargon, ` +
+    `NO internal notation, NO stats dump. Open your reply with ONE short line — ` +
+    `"🔬 skalpel · your graph's ready — here's what I noticed about how you work:" — then, in 2-3 ` +
+    `friendly plain-English sentences, tell them what it found` +
+    (facts.length ? `: ${facts.join("; ")}` : "") +
+    `. Close by reassuring them this is exactly the loop skalpel now quietly watches for and steers them ` +
+    `out of, live, while they code — they don't have to track it themselves. Then continue with whatever ` +
+    `they actually asked. Keep the whole thing short and human.]`
+  );
+}

package/skalpel-hook-session.mjs

@@ -12,6 +12,7 @@ import { join } from "node:path";
 import { identity } from "./auth.mjs";
 import { record } from "./metrics.mjs";
 import { recordInsight } from "./insights.mjs";
+import { graphReadyNote } from "./reveal.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
@@ -169,9 +170,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-hook.mjs

@@ -14,6 +14,7 @@ import { join } from "node:path";
 import { identity } from "./auth.mjs";
 import { record } from "./metrics.mjs";
 import { recordInsight } from "./insights.mjs";
+import { graphReadyNote } from "./reveal.mjs";
 
 // Config precedence: env > ~/.skalpel/client.json (written by `skalpel-prosumer setup`) > default.
 function fileCfg() {
@@ -682,9 +683,13 @@ async function main() {
       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");
+  // A just-finished background build leads (one-shot: surface "your graph's ready" the instant the next
+  // prompt fires, so the user doesn't have to restart a session to see it), then ackNote (feedback
+  // confirmation), the reset interrupt (most acute), the server steer, and the win note. Any can fire alone.
+  const readyNote = graphReadyNote();
+  const additionalContext = [readyNote, ackNote, resetNote, winNote, injection]
+    .filter(Boolean)
+    .join("\n\n");
   if (additionalContext) {
     process.stdout.write(
       JSON.stringify({

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,7 +894,26 @@ 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 */
+    }
+    // The reveal surfaces NATIVELY inside Claude Code — the next prompt's hook (or the next session)
+    // opens with "🔬 your graph's ready — here's what I noticed about how you work" from this marker.
+    // No OS pop-up: skalpel's whole surface is the conversation + the status line.
+    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 reveal is a bonus; never block the build on it */
+    }
   } catch {
     /* fail-open: a failed background build never surfaces; hooks fail open until it succeeds */
   }