skalpel 4.0.12 → 4.0.14

package/auth.mjs

@@ -15,7 +15,11 @@ const COGNITO_TOKEN_URL =
 const COGNITO_CLIENT_ID = process.env.SKALPEL_COGNITO_CLIENT_ID || "2gfil041fv9u58jemc7l5u2pht";
 const GRAPH_API = process.env.SKALPEL_API || "https://graph.skalpel.ai";
 
-function cliAuthPath() {
+// Exported so `skalpel logout` / `skalpel uninstall --purge` remove the session from the SAME
+// platform path this module reads it from (macOS Application Support, XDG on Linux, APPDATA on
+// Windows) — never a divergent guess. This is only a path resolver: it touches no token-exchange
+// or verification logic.
+export function cliAuthPath() {
   if (process.env.SKALPEL_CONFIG_DIR) return join(process.env.SKALPEL_CONFIG_DIR, "auth.json");
   if (process.platform === "win32") {
     const appData = process.env.APPDATA || join(homedir(), "AppData", "Roaming");

package/bootstrap.mjs

@@ -368,7 +368,9 @@ function recordProfile(profile, sessions) {
   if (headline) {
     recordInsight({
       kind: "profile",
-      display: `learned ${headline.hours ?? 0}h across ${headline.sessions ?? sessions} sessions; ${headline.rework_pct ?? 0}% was rework`,
+      // RED LINE 1: hours/rework_pct are the server's LLM-derived ESTIMATES, not a stopwatch and not
+      // locally reproducible — label them as estimates and point to the `skalpel autopsy` receipt.
+      display: `estimated ~${headline.hours ?? 0}h active with AI across ${headline.sessions ?? sessions} sessions; est. ~${headline.rework_pct ?? 0}% rework (run 'skalpel autopsy' for the exact receipt)`,
     });
   } else {
     recordInsight({ kind: "profile", display: `standing profile built from ${sessions} sessions` });

package/install.mjs

@@ -2,12 +2,25 @@
 // 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 {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  copyFileSync,
+  rmSync,
+  readdirSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { cliAuthPath } from "./auth.mjs";
 
 const uninstall = process.argv.includes("--uninstall");
+// `--purge` (only meaningful with --uninstall): additionally delete the saved session + ALL local
+// skalpel data so an uninstalled machine has nothing left — important because skalpel uploads
+// transcripts and a user must be able to verify no residue remains.
+const purge = process.argv.includes("--purge");
 // npm postinstall uses this mode to make the local, read-only status indicator visible without
 // opting the user into prompt/session hooks. A successful `skalpel login` runs the full installer;
 // `skalpel setup` remains an explicit repair path.
@@ -141,7 +154,11 @@ function isOurs(c, marker) {
   ];
   return markers.some((candidate) => {
     const escaped = candidate.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return new RegExp(`(^|[/\\\\\\s])${escaped}(\\.mjs|\\.js|\\.exe)?($|\\s)`).test(c);
+    // Boundaries must accept a QUOTE too: the installer writes the Windows-safe quoted form
+    // `node "<path>/skalpel-hook.mjs"`, so the marker is bounded by `/` before and `"` after. The
+    // old class only allowed path-sep/whitespace/end, so it NEVER matched a quoted command — uninstall
+    // left the hooks wired and re-install appended duplicate groups. Allow `"` and `'` on both sides.
+    return new RegExp(`(^|[/\\\\"'\\s])${escaped}(\\.mjs|\\.js|\\.exe)?($|["'\\s])`).test(c);
   });
 }
 
@@ -380,6 +397,75 @@ function claudeMd() {
   return had ? "refreshed" : "installed";
 }
 
+// After the hooks are UNWIRED (settings.json / CLAUDE.md / Codex — handled above), remove the local
+// data skalpel staged and accumulated so an uninstall leaves the machine clean. Plain uninstall keeps
+// the saved auth (so `--purge` is the deliberate "forget me entirely" step); --purge removes auth +
+// the whole ~/.skalpel tree. Returns a short human summary of what was cleaned.
+function cleanupLocalData() {
+  const SKALPEL_DIR = join(homedir(), ".skalpel");
+  const cleaned = [];
+  const rm = (target, label) => {
+    // Never delete a directory that contains the currently-running installer (defensive — install.mjs
+    // is never staged into ~/.skalpel, but guard anyway so a self-hosted layout can't self-destruct).
+    if (
+      PKG_DIR === target ||
+      PKG_DIR.startsWith(target + "/") ||
+      PKG_DIR.startsWith(target + "\\")
+    ) {
+      return;
+    }
+    if (!existsSync(target)) return;
+    try {
+      rmSync(target, { recursive: true, force: true });
+      cleaned.push(label);
+    } catch {
+      /* best-effort — a locked/again-absent path never fails the uninstall */
+    }
+  };
+
+  if (purge) {
+    // Forget-me-entirely: the saved session at the PLATFORM path (macOS Application Support / XDG /
+    // APPDATA — resolved by auth.mjs so it matches exactly where login wrote it) + the whole tree.
+    rm(cliAuthPath(), "auth (session token)");
+    rm(SKALPEL_DIR, "~/.skalpel (all local data)");
+    return cleaned;
+  }
+
+  // Plain uninstall: remove staged hooks + the raw transcript snapshots + all local state/logs, but
+  // KEEP the saved auth (that's what `--purge` is for). List every file skalpel writes under ~/.skalpel
+  // so nothing is silently left behind; auth.json (legacy local location) is deliberately preserved.
+  rm(join(SKALPEL_DIR, "hooks"), "staged hooks");
+  rm(join(SKALPEL_DIR, "ingest-outbox"), "raw transcript snapshots (ingest-outbox)");
+  for (const f of [
+    "session.json",
+    "steer.json",
+    "traj.json",
+    "pending.json",
+    "prefs.json",
+    "insights.ndjson",
+    "insights-ready.json",
+    "metrics.ndjson",
+    "bootstrap.json",
+    "bootstrap.lock",
+    "client.json",
+    "doctor.log",
+    "hook.log",
+  ]) {
+    rm(join(SKALPEL_DIR, f), f);
+  }
+  if (cleaned.length)
+    cleaned.push("(auth kept — run `skalpel uninstall --purge` to remove it too)");
+  // Tidy: if nothing but an empty shell remains, drop the directory. Preserve it if auth.json is still
+  // there (legacy local session) so the kept-auth promise holds.
+  try {
+    if (existsSync(SKALPEL_DIR) && readdirSync(SKALPEL_DIR).length === 0)
+      rmSync(SKALPEL_DIR, { force: true, recursive: true });
+  } catch {
+    /* leave the dir if we can't inspect it */
+  }
+  return cleaned;
+}
+
 const claudeResult = claude();
 if (statuslineOnly) {
   console.log(`skalpel statusline (${STATUSLINE_CMD}) → claude: ${claudeResult}`);
@@ -392,9 +478,20 @@ if (statuslineOnly) {
   console.log(
     `skalpel hook (${uninstall ? "uninstall" : CMD}) → claude: ${claudeResult} · 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.`,
-  );
+  if (uninstall) {
+    const cleaned = cleanupLocalData();
+    if (cleaned.length) console.log(`removed: ${cleaned.join(", ")}.`);
+    if (purge) {
+      // Honest note: there is no server-side data-deletion endpoint yet. Don't imply we called one.
+      console.log(
+        "note: local data removed. skalpel has no self-serve server-side deletion endpoint yet — " +
+          "to delete the transcripts already uploaded to the graph, email privacy@skalpel.ai.",
+      );
+    }
+    console.log("uninstalled.");
+  } else {
+    console.log(
+      `installed. Hooks run from ${HOOKS_DIR} and use the canonical skalpel Cognito login.`,
+    );
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "4.0.12",
+  "version": "4.0.14",
   "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

@@ -31,13 +31,25 @@ export function graphReadyNote() {
   const trap = m.report && (m.report.discriminative || [])[0] && m.report.discriminative[0].seq;
   const n = m.n_sessions || h.sessions || 0;
 
+  // PROVENANCE / HONESTY (RED LINE 1): both `hours` and `rework_pct` come from the hosted graph
+  // server's profile, which is built from an LLM judge's per-intent classification (intent_class +
+  // resolution) over the ingested transcripts. `hours` = summed, banded human read/dwell time on
+  // non-`other` intents (NOT raw session wall-clock); `rework_pct` = share of that time whose
+  // LLM-judged resolution is a "waste" class. Neither is a stopwatch measurement and neither
+  // re-derives locally the way `skalpel autopsy` does — so they must be surfaced as ESTIMATES, never
+  // as measured fact. The reproducible receipt is `skalpel autopsy`.
   const facts = [];
   if (h.hours)
-    facts.push(`they've spent about ${h.hours} hours working with AI across these sessions`);
+    facts.push(
+      `skalpel ESTIMATES they've spent about ${h.hours} hours of active time working with AI across ` +
+        `these sessions (inferred from their history — an estimate, not an exact clock)`,
+    );
   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)`,
+      `and it estimates roughly ${h.rework_pct}% of that went into REWORK-type patterns — going back ` +
+        `to redo, re-explain, or re-fix things they'd already worked on (this % is skalpel's ESTIMATE ` +
+        `from reading their sessions, NOT a stopwatch figure — it's the kind of loop skalpel is built ` +
+        `to help with)`,
     );
   if (trap)
     facts.push(
@@ -54,8 +66,12 @@ export function graphReadyNote() {
     `"🔬 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.]`
+    `. HONESTY RULE: present every number as skalpel's ESTIMATE inferred from their history — hedge ` +
+    `naturally ("about", "roughly", "skalpel estimates") and NEVER state a figure as an exact ` +
+    `measurement. If they want the exact, locally-verified receipt that re-derives from the coding ` +
+    `logs already on their own machine, tell them they can run \`skalpel autopsy\` anytime. 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-setup.mjs

@@ -20,7 +20,7 @@ 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";
+import { identity as authIdentity, cliAuthPath } 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
@@ -53,6 +53,8 @@ const isMain =
 // pulls in userTurnCount) can never exit the test runner.
 const KNOWN_SUBS = new Set(["setup", "login", "logout", "uninstall", "autopsy", "__build"]);
 const VALUE_FLAGS = new Set(["--api", "--user"]);
+// Boolean flags that take no value. `--purge` on `uninstall` also removes auth + all local data.
+const BOOL_FLAGS = new Set(["--purge"]);
 const USAGE = `skalpel-prosumer — connect your coding history to your behavioral graph
 
 usage:
@@ -60,11 +62,12 @@ usage:
   skalpel-prosumer login                                 (re-)run the Google sign-in
   skalpel-prosumer logout                                clear the saved session
   skalpel-prosumer autopsy                               local, read-only receipt of your verified patterns
-  skalpel-prosumer uninstall                             remove the hooks from Claude Code + Codex
+  skalpel-prosumer uninstall [--purge]                   remove the hooks + local data from this machine
 
 options:
   --api <url>    point at a different graph server
   --user <id>    dev-only identity override
+  --purge        on uninstall, also delete the saved session + ALL local skalpel data (~/.skalpel)
   -v, --version  print the version and exit
   -h, --help     print this help and exit`;
 
@@ -91,6 +94,7 @@ function validateArgv() {
       console.log(USAGE);
       process.exit(0);
     }
+    if (BOOL_FLAGS.has(a)) continue; // valueless flag (e.g. `uninstall --purge`)
     if (a.startsWith("-")) {
       console.error(`skalpel: unknown option \`${a}\`\n\n${USAGE}`);
       process.exit(2);
@@ -698,12 +702,15 @@ async function revealInsights(report) {
   console.log("");
   await line(`   ${B}Here's what I learned about how you work:${X}\n`, 480);
 
+  // RED LINE 1: h.hours / h.rework_pct are the hosted graph server's ESTIMATES, built from an LLM
+  // judge's per-intent classification — not a stopwatch, and not locally reproducible. Surface them
+  // as estimates and point to `skalpel autopsy` (the zero-network receipt that re-derives from disk).
   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}:`,
+    `   ${R}▸${X} skalpel estimates about ${B}${h.hours}h${X} of active time with AI across ${h.sessions} sessions — and that 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`,
+    `     ${D}circling back, re-explaining, re-fixing the same thing — the loop skalpel goes after.${X}\n`,
     520,
   );
 
@@ -738,6 +745,13 @@ async function revealInsights(report) {
   }
 
   console.log("");
+  // RED LINE 1: everything above (hours, rework %, archetype waste-hours, time-sink %, escape %) is
+  // the hosted graph's ESTIMATE from an LLM read of your sessions — not a stopwatch. State that once,
+  // plainly, and point to the zero-network receipt that re-derives from the logs on THIS machine.
+  await line(
+    `   ${D}These are skalpel's estimates from your recent sessions — run ${X}${B}skalpel autopsy${X}${D} for the exact receipt that re-derives from the logs on this machine.${X}`,
+    260,
+  );
   await line(
     `   ${G}skalpel now watches for these every session and steers you off them in real time.${X}`,
     260,
@@ -792,7 +806,8 @@ function preflight() {
 
 async function main() {
   if (sub === "uninstall") {
-    spawnSync("node", [join(__dir, "install.mjs"), "--uninstall"], { stdio: "inherit" });
+    const passthrough = argv.includes("--purge") ? ["--uninstall", "--purge"] : ["--uninstall"];
+    spawnSync("node", [join(__dir, "install.mjs"), ...passthrough], { stdio: "inherit" });
     return;
   }
   // `skalpel-prosumer login` — just run the sign-in flow (also invoked automatically by setup).
@@ -806,7 +821,30 @@ async function main() {
   if (sub === "logout") {
     try {
       const { rmSync } = await import("node:fs");
-      rmSync(join(homedir(), ".skalpel", "auth.json"), { force: true });
+      // The real session written by `skalpel login` / read by auth.mjs lives at the PLATFORM path
+      // (macOS Application Support, XDG on Linux, APPDATA on Windows) — NOT ~/.skalpel/auth.json.
+      // Delete it via auth.mjs's own resolver so we hit exactly where the session lives; the old
+      // code only unlinked the legacy ~/.skalpel/auth.json, so the next run silently re-authed.
+      const platformAuth = cliAuthPath();
+      rmSync(platformAuth, { force: true });
+      rmSync(join(homedir(), ".skalpel", "auth.json"), { force: true }); // legacy location, if present
+      // Clear the live per-session steering state + first-run bootstrap state so a subsequent login
+      // (possibly a different account) starts clean. Historical telemetry (metrics/insights ndjson)
+      // and config/prefs are left alone — `skalpel uninstall` owns those.
+      const skalpelDir = join(homedir(), ".skalpel");
+      for (const f of [
+        "session.json",
+        "steer.json",
+        "traj.json",
+        "pending.json",
+        "bootstrap.json",
+        "bootstrap.lock",
+        "insights-ready.json",
+      ]) {
+        rmSync(join(skalpelDir, f), { force: true });
+      }
+      // No persistent local proxy/daemon ships with this client (the legacy Go `skalpeld` is retired
+      // by postinstall.mjs). Clearing bootstrap.lock above releases any stuck first-run build lock.
       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`);