skalpel 3.4.18 → 4.0.0

package/skalpel-setup.mjs

@@ -0,0 +1,896 @@
+#!/usr/bin/env node
+// setup — the automatic install flow (`skalpel-prosumer setup`, also npm postinstall). Prints the
+// banner, signs you in with Google (once), reads your last 30 days of Claude Code / Codex history,
+// UPLOADS it to the hosted graph (the server judges + builds — the client stays engine-free), wires
+// the two hooks into Claude Code + Codex, and reports "you're live". Skips in CI / non-TTY (override:
+// SKALPEL_FORCE_BANNER=1). Demo timing: SKALPEL_DEMO=1.
+import {
+  createReadStream,
+  readdirSync,
+  accessSync,
+  statSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  realpathSync,
+  constants,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, delimiter, sep as pathSep } from "node:path";
+import { createInterface, emitKeypressEvents } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+import { identity as authIdentity } from "./auth.mjs";
+
+// CLI (the `skalpel-prosumer` bin): `skalpel-prosumer setup [--api https://graph.skalpel.ai]
+// [--user <id>]`, plus `skalpel-prosumer uninstall` and `skalpel-prosumer login`. A bare invocation
+// (npm postinstall) keeps the TTY-gated flow below.
+const argv = process.argv.slice(2);
+const sub = argv[0] && !argv[0].startsWith("-") ? argv[0] : null;
+const flagOf = (name) => {
+  const i = argv.indexOf(name);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : null;
+};
+const apiFlag = flagOf("--api");
+const userFlag = flagOf("--user");
+const explicitCli = sub !== null || apiFlag !== null || userFlag !== null;
+const __filename = fileURLToPath(import.meta.url);
+const __dir = dirname(__filename);
+const isMain =
+  Boolean(process.argv[1]) &&
+  (() => {
+    try {
+      return realpathSync(process.argv[1]) === realpathSync(__filename);
+    } catch {
+      return false;
+    }
+  })();
+
+// Argument validation. `sub` above is null for ANY dash-prefixed token, so before this existed
+// `npx @skalpelai/prosumer-hook --version` fell straight through to the full install flow: it signed
+// you in and wired hooks into Claude Code and Codex, having been asked only to print a version.
+// Unknown input must never install. Guarded on isMain so importing this module (install.test.mjs
+// pulls in userTurnCount) can never exit the test runner.
+const KNOWN_SUBS = new Set(["setup", "login", "logout", "uninstall", "__build"]);
+const VALUE_FLAGS = new Set(["--api", "--user"]);
+const USAGE = `skalpel-prosumer — connect your coding history to your behavioral graph
+
+usage:
+  skalpel-prosumer [setup] [--api <url>] [--user <id>]   sign in, learn your history, wire the hooks
+  skalpel-prosumer login                                 (re-)run the Google sign-in
+  skalpel-prosumer logout                                clear the saved session
+  skalpel-prosumer uninstall                             remove the hooks from Claude Code + Codex
+
+options:
+  --api <url>    point at a different graph server
+  --user <id>    dev-only identity override
+  -v, --version  print the version and exit
+  -h, --help     print this help and exit`;
+
+function pkgVersion() {
+  try {
+    return JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+function validateArgv() {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (VALUE_FLAGS.has(a)) {
+      i++; // its value is not a token to validate
+      continue;
+    }
+    if (a === "-v" || a === "--version") {
+      console.log(pkgVersion());
+      process.exit(0);
+    }
+    if (a === "-h" || a === "--help") {
+      console.log(USAGE);
+      process.exit(0);
+    }
+    if (a.startsWith("-")) {
+      console.error(`skalpel: unknown option \`${a}\`\n\n${USAGE}`);
+      process.exit(2);
+    }
+    if (i === 0 && !KNOWN_SUBS.has(a)) {
+      console.error(`skalpel: unknown command \`${a}\`\n\n${USAGE}`);
+      process.exit(2);
+    }
+  }
+}
+if (isMain) validateArgv();
+
+const isTTY = process.stdout.isTTY && !process.env.CI;
+if (isMain && !isTTY && !process.env.SKALPEL_FORCE_BANNER && !explicitCli) process.exit(0);
+
+const R = "\x1b[38;2;233;38;31m",
+  G = "\x1b[38;2;124;184;108m";
+const D = "\x1b[2m",
+  B = "\x1b[1m",
+  X = "\x1b[0m";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// The hosted graph. env > ~/.skalpel/client.json > the public host default. The `--api` flag
+// (persisted to client.json) points a dev/self-host build at a different server.
+const DEFAULT_API = "https://graph.skalpel.ai";
+function fileCfg() {
+  try {
+    return JSON.parse(readFileSync(join(homedir(), ".skalpel", "client.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+const API = process.env.SKALPEL_API || apiFlag || fileCfg().api || DEFAULT_API;
+
+// who's signed in — the session saved by the login flow (~/.skalpel/auth.json). Its `uid` keys the
+// hosted graph; `access_token` authenticates the upload. SKALPEL_USER overrides for dev (no token).
+// Uses auth.mjs's REFRESH-CAPABLE identity() so a token that expired since login (Supabase tokens
+// live ~1h) is silently refreshed before the upload — otherwise a build long after login hits a 401
+// and silently produces no graph. name/email come from auth.json (auth.mjs surfaces only uid+token).
+async function identity() {
+  if (process.env.SKALPEL_USER) return { uid: process.env.SKALPEL_USER, access_token: null };
+  let email = null;
+  let name = null;
+  try {
+    const a = JSON.parse(readFileSync(join(homedir(), ".skalpel", "auth.json"), "utf8"));
+    email = a?.email ?? null;
+    name = a?.name ?? null;
+  } catch {
+    /* no file yet */
+  }
+  const { uid, token } = await authIdentity(); // refreshes if near/past expiry
+  return uid ? { uid, access_token: token, email, name } : null;
+}
+
+function banner() {
+  console.log(`
+${R}   ███████╗██╗  ██╗ █████╗ ██╗     ██████╗ ███████╗██╗
+   ██╔════╝██║ ██╔╝██╔══██╗██║     ██╔══██╗██╔════╝██║
+   ███████╗█████╔╝ ███████║██║     ██████╔╝█████╗  ██║
+   ╚════██║██╔═██╗ ██╔══██║██║     ██╔═══╝ ██╔══╝  ██║
+   ███████║██║  ██╗██║  ██║███████╗██║     ███████╗███████╗
+   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚══════╝╚══════╝${X}`);
+  console.log(`\n   ${D}your AI coding sessions, learned — and steered in real time${X}\n`);
+}
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+function spinner(label) {
+  const S = { label };
+  if (!isTTY) {
+    // non-TTY: just print the step, no animation
+    process.stdout.write(`   ${D}·${X} ${label}\n`);
+    S.text = () => {};
+    S.succeed = (m) => process.stdout.write(`   ${G}✓${X} ${m || S.label}\n`);
+    S.fail = (m) => process.stdout.write(`   ${R}✗${X} ${m || S.label}\n`);
+    return S;
+  }
+  let i = 0;
+  process.stdout.write("\x1b[?25l"); // hide cursor
+  const id = setInterval(() => {
+    process.stdout.write(`\r\x1b[2K   ${R}${FRAMES[i++ % FRAMES.length]}${X} ${S.label}`);
+  }, 80);
+  S.text = (t) => {
+    S.label = t;
+  };
+  S.succeed = (m) => {
+    clearInterval(id);
+    process.stdout.write(`\r\x1b[2K   ${G}✓${X} ${m || S.label}\n\x1b[?25h`);
+  };
+  S.fail = (m) => {
+    clearInterval(id);
+    process.stdout.write(`\r\x1b[2K   ${R}✗${X} ${m || S.label}\n\x1b[?25h`);
+  };
+  return S;
+}
+
+function walk(dir) {
+  let out = [];
+  let ents;
+  try {
+    ents = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of ents) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out = out.concat(walk(p));
+    else if (p.endsWith(".jsonl")) out.push(p);
+  }
+  return out;
+}
+
+const LOOKBACK_DAYS = Math.max(1, Number.parseInt(process.env.SKALPEL_LOOKBACK_DAYS || "30", 10));
+
+const HAS_WINDOWS = process.platform === "win32";
+const DEFAULT_EXTS = HAS_WINDOWS ? [".com", ".exe", ".bat", ".cmd"] : [""];
+
+function isExecutable(p) {
+  try {
+    accessSync(p, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveExecutable(cmd) {
+  if (!cmd) return null;
+
+  const hasPath = cmd.includes(pathSep) || cmd.includes("/") || cmd.includes("\\");
+  if (hasPath) {
+    return isExecutable(cmd) ? cmd : null;
+  }
+
+  const extList = HAS_WINDOWS
+    ? [
+        ...new Set(
+          (process.env.PATHEXT || DEFAULT_EXTS.join(";")).split(";").map((ext) => {
+            const e = ext.trim();
+            return e ? (e.startsWith(".") ? e : `.${e}`) : "";
+          }),
+        ),
+      ]
+    : [""];
+
+  const hasExplicitExt = cmd.includes(".");
+  const candidates = hasExplicitExt ? [cmd] : [cmd];
+  const seen = new Set(candidates.map((c) => c.toLowerCase()));
+  if (!hasExplicitExt) {
+    for (const ext of extList) {
+      if (!ext) continue;
+      const candidate = `${cmd}${ext}`;
+      if (!seen.has(candidate.toLowerCase())) {
+        seen.add(candidate.toLowerCase());
+        candidates.push(candidate);
+      }
+    }
+  }
+
+  const paths = (process.env.PATH || "").split(delimiter).filter(Boolean);
+  for (const dir of paths) {
+    for (const candidate of candidates) {
+      const p = join(dir, candidate);
+      if (isExecutable(p)) return p;
+    }
+  }
+  return null;
+}
+
+function detectLaunchers() {
+  const candidates = [
+    { key: "claude", label: "Claude Code", command: "claude" },
+    { key: "codex", label: "Codex", command: "codex" },
+  ];
+
+  return candidates
+    .map((entry) => {
+      const command = resolveExecutable(entry.command);
+      return command ? { ...entry, command } : null;
+    })
+    .filter(Boolean);
+}
+
+function renderLaunchMenu(options, selected) {
+  return [
+    `   ${B}Launch your first session${X}`,
+    `   ${D}Use arrow keys or j/k to move. Press Enter to launch, Esc to skip.${X}`,
+    "",
+    ...options.map((entry, i) => {
+      const active = i === selected;
+      const pointer = active ? `${G}>${X}` : `${D} ${X}`;
+      const label = active ? `${B}${entry.label}${X}` : entry.label;
+      return `   ${pointer} ${label}  ${D}${entry.command}${X}`;
+    }),
+  ];
+}
+
+function promptLaunchFallback(options) {
+  console.log("\n   Pick your first session:");
+  console.log("   0) Skip for now");
+  options.forEach((entry, i) => {
+    const n = i + 1;
+    console.log(`   ${n}) ${entry.label} (${entry.command})`);
+  });
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    const ask = () => {
+      rl.question("   Selection [0=skip]: ", (ans) => {
+        const trimmed = String(ans ?? "").trim();
+        const n = trimmed === "" ? 0 : Number.parseInt(trimmed, 10);
+        if (!Number.isInteger(n) || n < 0 || n > options.length) {
+          console.log(`   ${R}Please enter a number between 0 and ${options.length}.${X}`);
+          ask();
+          return;
+        }
+        rl.close();
+        resolve(n === 0 ? null : options[n - 1]);
+      });
+    };
+    ask();
+  });
+}
+
+function promptLaunch(targets) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY || process.env.CI) return Promise.resolve();
+  if (process.env.SKALPEL_SKIP_LAUNCH_PROMPT === "1") return Promise.resolve();
+
+  const launchers = (targets || []).filter((entry) => !!entry?.command);
+  if (!launchers.length) {
+    console.log(`
+   ${D}No AI launcher was found on PATH. Re-run ${X}skalpel-prosumer setup${D} after installing Claude Code or Codex.${X}
+`);
+    return Promise.resolve();
+  }
+
+  const options = [
+    ...launchers,
+    { key: "skip", label: "Skip for now", command: "Return to shell" },
+  ];
+  const interactive = typeof process.stdin.setRawMode === "function";
+
+  return new Promise((resolve) => {
+    const launch = (picked) => {
+      if (!picked || picked.key === "skip") {
+        console.log(`   ${D}Skipped launch. Start your session anytime from the shell.${X}`);
+        resolve();
+        return;
+      }
+      console.log(`   ${B}Launching ${picked.label}...${X}`);
+      const child = spawnSync(picked.command, { stdio: "inherit", shell: HAS_WINDOWS });
+      if (child.error) {
+        console.log(`   ${R}Failed to launch ${picked.label}: ${child.error.message}${X}`);
+      } else if (child.status !== 0) {
+        console.log(`   ${R}Session ended with status ${child.status}${X}`);
+      }
+      resolve();
+    };
+
+    if (!interactive) {
+      promptLaunchFallback(launchers).then(launch);
+      return;
+    }
+
+    let selected = 0;
+    let renderedLines = 0;
+
+    const redraw = () => {
+      if (renderedLines) process.stdout.write(`\x1b[${renderedLines}F`);
+      const lines = renderLaunchMenu(options, selected);
+      renderedLines = lines.length + 1;
+      process.stdout.write(`\n${lines.join("\n")}\n`);
+    };
+
+    const cleanup = () => {
+      process.stdin.off("keypress", onKeypress);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write("\x1b[?25h");
+    };
+
+    const move = (delta) => {
+      selected = (selected + delta + options.length) % options.length;
+      redraw();
+    };
+
+    const finish = (picked) => {
+      cleanup();
+      launch(picked);
+    };
+
+    const onKeypress = (_, key = {}) => {
+      if (key.ctrl && key.name === "c") {
+        cleanup();
+        process.kill(process.pid, "SIGINT");
+        return;
+      }
+      if (key.name === "up" || key.name === "k") {
+        move(-1);
+        return;
+      }
+      if (key.name === "down" || key.name === "j") {
+        move(1);
+        return;
+      }
+      if (key.name === "return") {
+        finish(options[selected]);
+        return;
+      }
+      if (key.name === "escape" || key.name === "q") {
+        finish(null);
+      }
+    };
+
+    emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdout.write("\x1b[?25l");
+    process.stdin.on("keypress", onKeypress);
+    redraw();
+  });
+}
+
+async function reportLiveAndLaunch(message) {
+  console.log(message);
+  await promptLaunch(detectLaunchers());
+}
+
+// A REAL coding session, not one of the ~16k .jsonl fragment files the walk finds. Mirrors the
+// server's filter_real_sessions (engine.py) so we upload the ~15 genuine sessions, not 100 raw noise
+// files: (1) not agent-*.jsonl (spawned sub-agents = the AI talking to itself), (2) >= MIN_USER_TURNS
+// real human turns (a back-and-forth, not a 1-2 line fragment). This is the natural bound — no
+// arbitrary "cap to 100" that could upload fragments and MISS the real sessions.
+const MIN_USER_TURNS = Math.max(1, Number.parseInt(process.env.SKALPEL_MIN_USER_TURNS || "5", 10));
+
+export async function userTurnCount(path, cap = 5) {
+  let n = 0;
+  const input = createReadStream(path, { encoding: "utf8" });
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  try {
+    for await (const line of rl) {
+      if (!line.includes('"user"')) continue;
+      let e;
+      try {
+        e = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (e?.type === "user" || e?.role === "user") {
+        n++;
+        if (n >= cap) {
+          rl.close();
+          input.destroy();
+          return n;
+        }
+      }
+    }
+  } catch {
+    return 0;
+  }
+  return n;
+}
+
+export async function scanHistory(days = LOOKBACK_DAYS) {
+  const cutoff = Date.now() - days * 864e5;
+  const files = walk(join(homedir(), ".claude", "projects"))
+    .concat(walk(join(homedir(), ".codex", "sessions")))
+    .filter((f) => {
+      if (f.split("/").pop().startsWith("agent-")) return false; // sub-agent transcripts, not the user
+      try {
+        return statSync(f).mtimeMs >= cutoff;
+      } catch {
+        return false;
+      }
+    });
+  const out = [];
+  const workers = Math.max(1, Number.parseInt(process.env.SKALPEL_SCAN_WORKERS || "16", 10));
+  let i = 0;
+  async function worker() {
+    while (i < files.length) {
+      const f = files[i++];
+      if ((await userTurnCount(f, MIN_USER_TURNS)) >= MIN_USER_TURNS) out.push(f);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(workers, files.length || 1) }, worker));
+  return out;
+}
+
+// HOSTED model: the client is thin — it just UPLOADS the raw transcripts; the SERVER filters
+// (real-session detection) + judges (Gemini) + builds the Amplitude dash + aggregate DAG into the
+// hosted store under the user's uid. No Python, no engine, no graph-building on the user's machine.
+async function buildGraph(sp, files, id) {
+  if (process.env.SKALPEL_DEMO || !files.length) {
+    const n = files.length || (process.env.SKALPEL_DEMO ? 9 : 0);
+    for (let k = 1; k <= n; k++) {
+      sp.text(`Judging session ${k}/${n} → ⟨intent · trajectory · resolution⟩`);
+      await sleep(180);
+    }
+    sp.text("Assembling causal DAG + your insight layer…");
+    await sleep(600);
+    return n;
+  }
+  // Read the raw transcript files and upload them (the server filters + judges + builds). The upload
+  // must fit the server's single-call capacity — a TOTAL body-size cap and a session-count cap — so a
+  // heavy user with hundreds of sessions / hundreds of MB doesn't 413 and end up with no graph. Only
+  // the TOTAL is bounded (never per-file: big sessions are the richest data). Newest-first, so if the
+  // total cap is ever hit we keep the freshest history. Caps overridable for tuning.
+  const MAX_SESSIONS = Math.max(
+    1,
+    Number.parseInt(process.env.SKALPEL_MAX_UPLOAD_SESSIONS || "20", 10),
+  );
+  const MAX_BYTES =
+    Math.max(1, Number.parseInt(process.env.SKALPEL_MAX_UPLOAD_MB || "90", 10)) * 1024 * 1024;
+  // newest first, so when a cap is hit we keep the freshest history
+  const ranked = files
+    .map((f) => {
+      try {
+        const s = statSync(f);
+        return { f, m: s.mtimeMs, size: s.size };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.m - a.m);
+  const raw = {};
+  let bytes = 0;
+  let dropped = 0;
+  for (const { f, size } of ranked) {
+    // Do NOT drop a session for being large — big sessions are the RICHEST data (the long ones
+    // where the real thrash happens). The only real limit is the total request body (413), so we
+    // only stop once the WHOLE upload would exceed MAX_BYTES / MAX_SESSIONS — never per-file.
+    if (Object.keys(raw).length >= MAX_SESSIONS || bytes + size > MAX_BYTES) {
+      dropped++;
+      continue;
+    }
+    try {
+      raw[f.split("/").pop()] = readFileSync(f, "utf8");
+      bytes += size;
+    } catch {
+      /* skip unreadable */
+    }
+  }
+  // Final guard: JSON escaping inflates the body slightly, so trim the oldest kept sessions until the
+  // GZIP the body — transcripts are JSON text and compress ~3-4x, so 100MB+ of real sessions fits
+  // under the server cap without dropping ANY of them (big sessions are the richest data). The trim
+  // loop only fires if even the COMPRESSED payload exceeds the cap — for a normal user, never.
+  const { gzipSync } = await import("node:zlib");
+  let body = gzipSync(JSON.stringify({ user_id: id.uid, raw_transcripts: raw }));
+  const HARD_CAP = 90 * 1024 * 1024; // matches the server body cap; compressed size
+  while (body.length > HARD_CAP && Object.keys(raw).length > 1) {
+    const keys = Object.keys(raw); // insertion order = newest first → drop the oldest kept
+    delete raw[keys[keys.length - 1]];
+    dropped++;
+    body = gzipSync(JSON.stringify({ user_id: id.uid, raw_transcripts: raw }));
+  }
+  const kept = Object.keys(raw).length;
+  const plain = JSON.stringify({ user_id: id.uid, raw_transcripts: raw });
+  sp.text(`Building your graph from ${kept} session${kept === 1 ? "" : "s"}…`);
+  const post = (token, gzip) =>
+    fetch(`${API}/ingest`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...(gzip ? { "content-encoding": "gzip" } : {}),
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+      body: gzip ? body : plain,
+    });
+
+  let r = await post(id.access_token, true);
+  // SELF-HEAL on 401: token was stale AND refresh didn't recover it (refresh_token also expired).
+  // Re-run the Google login ONCE for a fresh session, then retry — instead of dead-ending the user.
+  if (r.status === 401 && !process.env.SKALPEL_USER) {
+    sp.text("Session expired — re-opening sign-in…");
+    spawnSync("node", [join(__dir, "login.mjs")], { stdio: "inherit" });
+    const fresh = await identity();
+    if (fresh?.access_token) r = await post(fresh.access_token, true);
+  }
+  // COMPAT: if a server that predates gzip decompression 5xx's on the gzipped body, retry it plain
+  // (uncompressed). Only when the plain body still fits the cap; otherwise gzip was load-bearing.
+  if (r.status >= 500 && plain.length < HARD_CAP) {
+    r = await post(id.access_token, false);
+  }
+  if (!r.ok) {
+    const hint =
+      r.status === 401
+        ? " — sign-in failed; run `skalpel-prosumer login` and retry"
+        : r.status === 413
+          ? " — history too large even after trimming"
+          : "";
+    throw new Error(`ingest ${r.status}${hint}`);
+  }
+  // ASYNC: /ingest now returns 202 {job_id} and judges in the BACKGROUND (so a monster 50MB session
+  // can take minutes without any request timeout). Poll /ingest/status and drive the spinner with the
+  // server's REAL progress ("Judging 8/15…"); resolve only when the job reaches state=done. A server
+  // that predates async returns 200 with n_sessions inline — handle that too (back-compat).
+  const res = await r.json().catch(() => ({}));
+  if (res && typeof res.n_sessions === "number") return res.n_sessions; // legacy synchronous server
+  const jobId = res && res.job_id;
+  if (!jobId) return res && typeof res.n_sessions === "number" ? res.n_sessions : 0;
+
+  const statusUrl = `${API}/ingest/status?job_id=${encodeURIComponent(jobId)}`;
+  const POLL_MS = 1500;
+  const MAX_POLLS = 800; // ~20 min ceiling — a monster history, never hit by a normal user
+  for (let i = 0; i < MAX_POLLS; i++) {
+    await sleep(POLL_MS);
+    let s;
+    try {
+      const sr = await fetch(statusUrl, {
+        headers: { authorization: `Bearer ${id.access_token}` },
+      });
+      s = await sr.json();
+    } catch {
+      continue; // transient network blip — keep polling, the job runs server-side regardless
+    }
+    if (s.state === "done") return s.n_sessions ?? 0;
+    if (s.state === "error") throw new Error("build failed");
+    if (s.state === "judging" && s.total) {
+      sp.text(`Judging your sessions… ${s.done}/${s.total}`);
+    }
+  }
+  throw new Error("build timed out");
+}
+
+function startBackgroundBuild() {
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), "__build"], {
+    detached: true,
+    stdio: "ignore",
+    env: {
+      ...process.env,
+      SKALPEL_FORCE_BANNER: "0",
+    },
+  });
+  child.unref();
+}
+
+// The causal Profile (mine.build_profile) as a structured report — so the FIRST RUN can reveal, in
+// natural language, what skalpel just learned (the waste number + the top patterns). This is the
+// trust moment: the user SEES it knows them before they've typed a single prompt.
+async function fetchProfile(id) {
+  try {
+    const r = await fetch(`${API}/profile?user_id=${encodeURIComponent(id.uid)}`, {
+      headers: id.access_token ? { authorization: `Bearer ${id.access_token}` } : {},
+    });
+    if (!r.ok) return null;
+    return await r.json();
+  } catch {
+    return null;
+  }
+}
+
+// A short "mining" flourish after the judging completes — names the suite as it assembles, so the wait
+// reads as work being done ON their data, not a dead spinner. (The 12-lens causal suite, in plain terms.)
+async function miningFlourish(sp) {
+  for (const p of [
+    "Assembling your causal DAG…",
+    "Mining behavioral patterns — bottlenecks, triggers, spirals, resolvers…",
+    "Ranking where your time actually goes…",
+  ]) {
+    sp.text(p);
+    await sleep(process.env.SKALPEL_DEMO ? 700 : 500);
+  }
+}
+
+// Realistic sample profile so `SKALPEL_DEMO=1` shows the full reveal (for demos / screenshots).
+const DEMO_REPORT = {
+  headline: { sessions: 18, intents: 240, hours: 42.5, rework_pct: 45 },
+  morphology: [{ archetype: "over-polish", sessions: 7, hours_wasted: 12.1 }],
+  discriminative: [{ seq: "refine→refine→refine", high: 8, clean: 0 }],
+  bottleneck: [{ type: "debug", pct_time: 31, pct_wasted: 60 }],
+  survival: [{ depth: 5, escape_pct: 96, n: 40 }],
+};
+
+// THE REVEAL — natural-language readout of what skalpel learned, led by the WASTE NUMBER. Every line
+// is a real finding from the causal suite; degrades gracefully when a lens is empty (a light history).
+async function revealInsights(report) {
+  if (!report || !report.headline) return;
+  const h = report.headline;
+  const line = async (s, d = 380) => {
+    console.log(s);
+    await sleep(process.env.SKALPEL_DEMO ? d + 220 : d);
+  };
+  console.log("");
+  await line(`   ${B}Here's what I learned about how you work:${X}\n`, 480);
+
+  const rw = h.rework_pct || 0;
+  await line(
+    `   ${R}▸${X} You've spent ${B}${h.hours}h${X} with AI across ${h.sessions} sessions — and about ${B}${R}${rw}%${X} of it went to ${B}rework${X}:`,
+  );
+  await line(
+    `     ${D}circling back, re-explaining, re-fixing the same thing. That's the time skalpel goes after.${X}\n`,
+    520,
+  );
+
+  const morph = (report.morphology || [])
+    .slice()
+    .sort((a, b) => (b.hours_wasted || 0) - (a.hours_wasted || 0))[0];
+  if (morph)
+    await line(
+      `   ${R}▸${X} Your waste is mostly ${B}${morph.archetype}${X} ${D}(~${morph.hours_wasted}h of it).${X}`,
+    );
+
+  const d0 = (report.discriminative || [])[0];
+  if (d0)
+    await line(
+      `   ${R}▸${X} Your signature trap: ${B}${d0.seq}${X} ${D}— shows up in your worst sessions, never your clean ones.${X}`,
+    );
+
+  const bn = (report.bottleneck || [])[0];
+  if (bn)
+    await line(
+      `   ${R}▸${X} Biggest time sink: ${B}${bn.type}${X} ${D}— ${bn.pct_time}% of your wall-clock.${X}`,
+    );
+
+  const surv = report.survival || [];
+  const deep = surv[surv.length - 1];
+  if (deep) {
+    const s =
+      deep.escape_pct >= 80
+        ? `you ${B}grind out${X} ${D}(${deep.escape_pct}% escape even deep spirals) — for you waste is time, not failure${X}`
+        : `you tend to ${B}bail${X} ${D}(only ${deep.escape_pct}% escape a deep spiral)${X}`;
+    await line(`   ${R}▸${X} When you spiral, ${s}.`, 480);
+  }
+
+  console.log("");
+  await line(
+    `   ${G}skalpel now watches for these every session and steers you off them in real time.${X}`,
+    260,
+  );
+  await line(
+    `   ${D}No dashboard to check — you'll feel it mid-session, right when it matters.${X}\n`,
+    180,
+  );
+}
+
+async function main() {
+  if (sub === "uninstall") {
+    spawnSync("node", [join(__dir, "install.mjs"), "--uninstall"], { stdio: "inherit" });
+    return;
+  }
+  // `skalpel-prosumer login` — just run the sign-in flow (also invoked automatically by setup).
+  if (sub === "login") {
+    spawnSync("node", [join(__dir, "login.mjs")], { stdio: "inherit" });
+    return;
+  }
+  // `skalpel-prosumer logout` — clear the saved Google session so the next run signs in fresh.
+  // (Setup skips the sign-in when a valid ~/.skalpel/auth.json exists — this is how you force a new
+  // account / a real Google popup.)
+  if (sub === "logout") {
+    try {
+      const { rmSync } = await import("node:fs");
+      rmSync(join(homedir(), ".skalpel", "auth.json"), { force: true });
+      console.log(`   ${G}✓${X} Signed out. Next run will prompt for Google sign-in.\n`);
+    } catch (e) {
+      console.log(`   Could not sign out: ${String(e.message || e)}\n`);
+    }
+    return;
+  }
+  // Persist --api/--user to ~/.skalpel/client.json so the hooks can read them without shell-env
+  // plumbing (env vars SKALPEL_API / SKALPEL_USER still win at hook runtime).
+  if (apiFlag || userFlag) {
+    const cfgDir = join(homedir(), ".skalpel");
+    const cfgPath = join(cfgDir, "client.json");
+    let cfg = {};
+    try {
+      cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+    } catch {
+      /* fresh config */
+    }
+    if (apiFlag) cfg.api = apiFlag;
+    if (userFlag) cfg.user = userFlag;
+    mkdirSync(cfgDir, { recursive: true });
+    writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
+  }
+  banner();
+
+  // 1) SIGN IN with Google (once). SKALPEL_USER (dev) or an existing ~/.skalpel/auth.json skips it.
+  //    identity() refreshes a stale token first, so a build long after login still authenticates.
+  let id = await identity();
+  if (!id && !process.env.SKALPEL_DEMO) {
+    console.log(`   ${D}First, sign in with Google to create your account…${X}\n`);
+    spawnSync("node", [join(__dir, "login.mjs")], { stdio: "inherit" });
+    id = await identity();
+    if (!id) {
+      console.log(
+        `\n   ${D}Not signed in — run ${X}skalpel-prosumer login${D} then re-run to build your graph.${X}\n`,
+      );
+      return;
+    }
+  }
+  if (id)
+    console.log(
+      `   ${G}✓${X} Signed in as ${D}${id.name ? `${id.name} · ${id.email}` : id.email || id.uid}${X}\n`,
+    );
+
+  // 2) find the real coding sessions in the last 30 days (the client reads; the server builds)
+  const s1 = spinner(`Looking through your last ${LOOKBACK_DAYS} days of Claude Code + Codex…`);
+  await sleep(500);
+  const files = await scanHistory();
+  const n = files.length;
+  s1.succeed(
+    n
+      ? `Found ${n} coding session${n === 1 ? "" : "s"} to learn from`
+      : "No sessions yet — your graph will grow as you work",
+  );
+
+  // 3) wire the hooks (instant). Never claim success we didn't verify: install.mjs exits non-zero if
+  //    it could not stage the hook runtime, and swallowing that here is what let a broken install
+  //    print a green checkmark while every hook crashed on import.
+  const s3 = spinner("Wiring Claude Code + Codex…");
+  const wired = spawnSync("node", [join(__dir, "install.mjs")], {
+    stdio: ["ignore", "ignore", "pipe"],
+    encoding: "utf8",
+  });
+  if (wired.status !== 0) {
+    s3.fail("Could not wire Claude Code + Codex");
+    if (wired.stderr) process.stderr.write(wired.stderr);
+    process.exit(1);
+  }
+  s3.succeed("Hooks wired into Claude Code + Codex");
+
+  // 4) build the graph + REVEAL the insights. First-run trust is won here: we mine in the foreground
+  //    with a narrated animation, then read back the waste number + the top patterns in plain language,
+  //    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.
+  const wantReveal =
+    (isTTY || process.env.SKALPEL_SETUP_WAIT_FOR_GRAPH === "1") &&
+    process.env.SKALPEL_SETUP_BACKGROUND !== "1";
+
+  if (process.env.SKALPEL_DEMO) {
+    const s4 = spinner(`⛏  Mining your last ${LOOKBACK_DAYS} days of Claude Code + Codex…`);
+    await buildGraph(s4, files, id);
+    await miningFlourish(s4);
+    s4.succeed("Learned from your history");
+    await revealInsights(DEMO_REPORT);
+    await reportLiveAndLaunch(
+      `\n   ${B}${G}You're live.${X}  ${D}every prompt now pulls your history.${X}\n`,
+    );
+  } else if (files.length && wantReveal) {
+    const s4 = spinner(
+      `⛏  Mining ${files.length} session${files.length === 1 ? "" : "s"} — judging intent · trajectory · resolution…`,
+    );
+    let built = 0;
+    let err = null;
+    try {
+      built = await buildGraph(s4, files, id);
+      if (built) await miningFlourish(s4);
+    } catch (e) {
+      err = e;
+    }
+    if (built) {
+      s4.succeed(`Learned from ${built} session${built === 1 ? "" : "s"}`);
+      await revealInsights(await fetchProfile(id));
+      await reportLiveAndLaunch(
+        `\n   ${B}${G}You're live.${X}  ${D}every prompt now pulls your history.${X}\n`,
+      );
+    } else {
+      s4.fail(
+        `Couldn't build your graph${err ? ` (${String(err.message || err).slice(0, 40)})` : ""}`,
+      );
+      console.log(
+        `\n   ${D}Hooks are wired and fail open. Re-run ${X}skalpel-prosumer setup${D} to try building again.${X}\n`,
+      );
+    }
+  } else if (files.length) {
+    // background/silent path (opt-out or CI): fast, no reveal
+    startBackgroundBuild();
+    const capped = Math.min(
+      files.length,
+      Math.max(1, Number.parseInt(process.env.SKALPEL_MAX_UPLOAD_SESSIONS || "20", 10)),
+    );
+    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`,
+    );
+  } else {
+    await reportLiveAndLaunch(
+      `\n   ${B}${G}You're live.${X}  ${D}your graph grows as you work.${X}\n`,
+    );
+  }
+}
+
+// The detached background build (spawned by main): does ONLY the upload+judge, no banner/hooks.
+async function backgroundBuild() {
+  const id = await identity();
+  if (!id) return; // not signed in — nothing to build under
+  const files = await scanHistory();
+  if (!files.length) return;
+  const sp = { text: () => {}, succeed: () => {} }; // silent — no TTY in the background
+  try {
+    await buildGraph(sp, files, id);
+  } catch {
+    /* fail-open: a failed background build never surfaces; hooks fail open until it succeeds */
+  }
+}
+
+// `__build` = the detached background graph build spawned by setup; skips the banner/hooks entirely.
+if (isMain && sub === "__build") {
+  backgroundBuild()
+    .then(() => process.exit(0))
+    .catch(() => process.exit(0));
+} else if (isMain) {
+  main().catch(() => process.exit(0));
+}