skalpel 3.4.10 → 3.4.12

package/INSTALL.md

@@ -65,6 +65,11 @@ The shell wrappers — and the `skalpel active` / `skalpel inactive` indicator e
 
 A user who independently runs `npm install -g skalpel` is still supported: `postinstall` prints a best-effort pointer to `https://skalpel.ai/signup`, and the first `skalpel` run repeats that pointer where output is guaranteed.
 
+When Claude Code is already present, the persistent install also registers Skalpel's local,
+read-only `statusLine` command. It is visible immediately as `~0.0h saved` and grows only from
+confirmed savings. This does **not** opt the user into prompt/session hooks: those remain disabled
+until the explicit `skalpel setup` flow below. An existing custom Claude status line is preserved.
+
 ### `skalpel setup` — detect and wrap coding agents
 
 Harness setup runs automatically at the tail of `login --activation` (see above), and is also available as a standalone command for re-running later or for `npm install -g` users. `skalpel setup` detects which coding-agent harnesses are installed (cross-platform on Linux, Windows, and macOS) via PATH and per-user config probes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "3.4.10",
+  "version": "3.4.12",
   "description": "Skalpel — local proxy and TUI for coding agents (skalpel + skalpeld bundle).",
   "license": "Apache-2.0",
   "homepage": "https://skalpel.ai",
@@ -59,10 +59,10 @@
     "x64"
   ],
   "optionalDependencies": {
-    "@skalpelai/skalpel-darwin-arm64": "3.4.10",
-    "@skalpelai/skalpel-darwin-x64": "3.4.10",
-    "@skalpelai/skalpel-linux-arm64": "3.4.10",
-    "@skalpelai/skalpel-linux-x64": "3.4.10",
-    "@skalpelai/skalpel-win32-x64": "3.4.10"
+    "@skalpelai/skalpel-darwin-arm64": "3.4.12",
+    "@skalpelai/skalpel-darwin-x64": "3.4.12",
+    "@skalpelai/skalpel-linux-arm64": "3.4.12",
+    "@skalpelai/skalpel-linux-x64": "3.4.12",
+    "@skalpelai/skalpel-win32-x64": "3.4.12"
   }
 }

package/postinstall/index.js

@@ -171,6 +171,11 @@ async function main(argv) {
       const hooks = prosumerHooks.stageAndHeal({ dryRun: opts.dryRun });
       if (hooks.healed) {
         log.info('behavior-hooks: refreshed an existing skalpel hook installation');
+      } else if (hooks.statuslineManaged) {
+        log.info(
+          'behavior-hooks: runtime staged; Claude status line enabled at 0.0h; ' +
+          'prompt hooks remain opt-in via `skalpel setup`'
+        );
       } else {
         log.info('behavior-hooks: runtime staged; activation remains opt-in via `skalpel setup`');
       }

package/postinstall/lib/prosumer-hooks.js

@@ -17,7 +17,12 @@ const RUNTIME_FILES = [
   'install.mjs',
 ];
 
-const MANAGED_COMMAND = /skalpel-(?:prosumer-)?(?:hook(?:-session)?|statusline)/;
+// Match managed command basenames/markers, not arbitrary parent-directory text. A path such as
+// /tmp/skalpel-prosumer-hooks-test/... must never be misread as consent to activate prompt hooks.
+const MANAGED_BEHAVIOR_COMMAND =
+  /(^|[/\\\s"'])skalpel-(?:prosumer-)?hook(?:-session)?(?:\.(?:mjs|js|exe))?(?=$|[:\s"'])/m;
+const MANAGED_STATUSLINE_COMMAND =
+  /(^|[/\\\s"'])skalpel-(?:prosumer-)?statusline(?:\.(?:mjs|js|exe))?(?=$|[\s"'])/m;
 
 function runtimeDir() {
   return path.join(os.homedir(), '.skalpel', 'hooks');
@@ -35,14 +40,24 @@ function readText(file) {
   }
 }
 
-function hasManagedInstall() {
+function hasManagedBehaviorInstall() {
   const home = os.homedir();
   return [
     path.join(home, '.claude', 'settings.json'),
     path.join(home, '.claude', 'CLAUDE.md'),
     path.join(home, '.codex', 'config.toml'),
     path.join(home, '.codex', 'hooks.json'),
-  ].some((file) => MANAGED_COMMAND.test(readText(file)));
+  ].some((file) => MANAGED_BEHAVIOR_COMMAND.test(readText(file)));
+}
+
+function hasManagedStatusline() {
+  return MANAGED_STATUSLINE_COMMAND.test(
+    readText(path.join(os.homedir(), '.claude', 'settings.json'))
+  );
+}
+
+function hasClaudeConfig() {
+  return fs.existsSync(path.join(os.homedir(), '.claude'));
 }
 
 function copyRuntime() {
@@ -77,11 +92,29 @@ function runInstaller(args, stdio = 'inherit') {
 }
 
 function stageAndHeal({ dryRun = false } = {}) {
-  const heal = hasManagedInstall();
-  if (dryRun) return { staged: false, healed: false, wouldHeal: heal };
+  const healBehavior = hasManagedBehaviorInstall();
+  const configureStatusline = hasClaudeConfig();
+  if (dryRun) {
+    return {
+      staged: false,
+      healed: false,
+      wouldHeal: healBehavior,
+      wouldConfigureStatusline: configureStatusline,
+    };
+  }
   copyRuntime();
-  if (heal) runInstaller([]);
-  return { staged: true, healed: heal };
+  if (healBehavior) {
+    runInstaller([]);
+  } else if (configureStatusline) {
+    // Keep prompt/session hooks consent-based, but make the read-only zero-state indicator visible
+    // immediately. Crucially, a later upgrade must not mistake this statusline for hook opt-in.
+    runInstaller(['--statusline-only']);
+  }
+  return {
+    staged: true,
+    healed: healBehavior,
+    statuslineManaged: hasManagedStatusline(),
+  };
 }
 
 function uninstall({ removeRuntime = true } = {}) {

package/postinstall/lib/prosumer-hooks.test.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// CLI-owned behavior-hook packaging and status-line tests. Stdlib only; each case runs against an
+// isolated HOME so npm-install behavior cannot touch the developer's real Claude/Codex settings.
+
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const hooksLib = path.join(__dirname, 'prosumer-hooks.js');
+const statusline = path.resolve(__dirname, '..', '..', 'prosumer-hooks', 'skalpel-statusline.mjs');
+const packageJson = path.resolve(__dirname, '..', '..', 'package.json');
+
+let pass = 0;
+let fail = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    process.stdout.write(`  PASS ${name}\n`);
+    pass += 1;
+  } catch (err) {
+    process.stderr.write(`  FAIL ${name}\n    ${err && err.stack ? err.stack : err}\n`);
+    fail += 1;
+  }
+}
+
+function tempHome({ claude = false } = {}) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'skalpel-prosumer-hooks-test-'));
+  if (claude) fs.mkdirSync(path.join(home, '.claude'), { recursive: true });
+  return home;
+}
+
+function childEnv(home) {
+  return {
+    ...process.env,
+    HOME: home,
+    USERPROFILE: home,
+    NO_COLOR: '1',
+  };
+}
+
+function stage(home) {
+  return spawnSync(
+    process.execPath,
+    ['-e', `require(${JSON.stringify(hooksLib)}).stageAndHeal()`],
+    { env: childEnv(home), encoding: 'utf8', timeout: 10_000 },
+  );
+}
+
+function render(home) {
+  const result = spawnSync(process.execPath, [statusline], {
+    env: childEnv(home),
+    encoding: 'utf8',
+    timeout: 5_000,
+  });
+  assert.strictEqual(result.status, 0, result.stderr);
+  return result.stdout.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function settings(home) {
+  return JSON.parse(fs.readFileSync(path.join(home, '.claude', 'settings.json'), 'utf8'));
+}
+
+function run() {
+  process.stdout.write('prosumer-hooks tests:\n');
+
+  test('status line renders an always-visible honest zero without stats', () => {
+    const home = tempHome();
+    try {
+      assert.strictEqual(render(home), 'skalpel · ~0.0h saved · 0 steers');
+    } finally {
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test('status line still renders accumulated confirmed savings', () => {
+    const home = tempHome();
+    try {
+      fs.mkdirSync(path.join(home, '.skalpel'), { recursive: true });
+      fs.writeFileSync(
+        path.join(home, '.skalpel', 'stats.json'),
+        JSON.stringify({ session_hours: 0.5, total_hours: 2.25, total_events: 3 }),
+      );
+      assert.strictEqual(render(home), 'skalpel · ~2.3h saved · 3 steers');
+    } finally {
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test('npm package includes the complete status-line runtime directory', () => {
+    const pkg = JSON.parse(fs.readFileSync(packageJson, 'utf8'));
+    assert.ok(
+      pkg.files.includes('prosumer-hooks/'),
+      'npm package files must include the CLI-owned hook/status-line runtime',
+    );
+    assert.ok(fs.existsSync(statusline), 'status-line source is missing from the packaged directory');
+  });
+
+  test('fresh npm-style staging registers only the Claude status line', () => {
+    const home = tempHome({ claude: true });
+    try {
+      const result = stage(home);
+      assert.strictEqual(result.status, 0, result.stderr);
+      const cfg = settings(home);
+      assert.deepStrictEqual(cfg.statusLine, {
+        type: 'command',
+        command: `node ${path.join(home, '.skalpel', 'hooks', 'skalpel-statusline.mjs')}`,
+      });
+      assert.strictEqual(cfg.hooks, undefined, 'postinstall must not opt users into prompt hooks');
+      assert.strictEqual(
+        fs.existsSync(path.join(home, '.claude', 'CLAUDE.md')),
+        false,
+        'postinstall must not add behavior-hook instructions',
+      );
+    } finally {
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test('status-line-only install stays status-line-only across upgrades', () => {
+    const home = tempHome({ claude: true });
+    try {
+      assert.strictEqual(stage(home).status, 0);
+      assert.strictEqual(stage(home).status, 0);
+      const cfg = settings(home);
+      assert.strictEqual(cfg.hooks, undefined, 'an existing status line is not behavior-hook consent');
+      assert.strictEqual(fs.existsSync(path.join(home, '.claude', 'CLAUDE.md')), false);
+      assert.strictEqual(fs.existsSync(path.join(home, '.codex', 'config.toml')), false);
+    } finally {
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test('an existing behavior-hook opt-in is fully healed on upgrade', () => {
+    const home = tempHome({ claude: true });
+    try {
+      fs.writeFileSync(
+        path.join(home, '.claude', 'settings.json'),
+        JSON.stringify({
+          hooks: {
+            UserPromptSubmit: [
+              {
+                hooks: [
+                  { type: 'command', command: 'node /old/.skalpel/hooks/skalpel-hook.mjs' },
+                ],
+              },
+            ],
+          },
+        }),
+      );
+      const result = stage(home);
+      assert.strictEqual(result.status, 0, result.stderr);
+      const cfg = settings(home);
+      assert.ok(cfg.hooks.UserPromptSubmit.length > 0);
+      assert.ok(cfg.hooks.SessionStart.length > 0);
+      assert.match(cfg.statusLine.command, /skalpel-statusline\.mjs$/);
+      assert.strictEqual(fs.existsSync(path.join(home, '.claude', 'CLAUDE.md')), true);
+    } finally {
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test('fresh staging preserves a custom Claude status line', () => {
+    const home = tempHome({ claude: true });
+    try {
+      const file = path.join(home, '.claude', 'settings.json');
+      const custom = { type: 'command', command: 'my-custom-status' };
+      fs.writeFileSync(file, JSON.stringify({ statusLine: custom, theme: 'dark' }));
+      const result = stage(home);
+      assert.strictEqual(result.status, 0, result.stderr);
+      assert.deepStrictEqual(settings(home), { statusLine: custom, theme: 'dark' });
+    } finally {
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  process.stdout.write(`\n  pass=${pass} fail=${fail}\n`);
+  return fail === 0 ? 0 : 1;
+}
+
+if (require.main === module) process.exit(run());
+
+module.exports = { run };

package/prosumer-hooks/install.mjs

@@ -8,6 +8,9 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const uninstall = process.argv.includes("--uninstall");
+// npm postinstall uses this mode to make the local, read-only status indicator visible without
+// opting the user into prompt/session hooks. `skalpel setup` still runs the full installer.
+const statuslineOnly = !uninstall && process.argv.includes("--statusline-only");
 
 // 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
@@ -129,30 +132,32 @@ function isOurs(c, marker) {
 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;
+  if (!statuslineOnly) {
+    d.hooks ??= {};
+    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
@@ -167,6 +172,8 @@ function claude() {
     if (statuslineIsOurs) refreshed += 1;
     else installed += 1;
     d.statusLine = { type: "command", command: STATUSLINE_CMD };
+  } else if (statuslineOnly) {
+    return "preserved"; // a custom status line wins; do not rewrite unrelated Claude settings
   }
   writeJson(CLAUDE, d);
   if (uninstall) return removed ? "removed" : "absent";
@@ -345,11 +352,21 @@ function claudeMd() {
   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.`,
-);
+const claudeResult = claude();
+if (statuslineOnly) {
+  console.log(`skalpel statusline (${STATUSLINE_CMD}) → claude: ${claudeResult}`);
+  console.log(
+    claudeResult === "preserved"
+      ? "custom Claude status line preserved."
+      : "installed. Behavior hooks remain opt-in via `skalpel setup`.",
+  );
+} else {
+  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.`,
+  );
+}

package/prosumer-hooks/skalpel-statusline.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // skalpel statusline — reads the running "time saved" counter (bumped by skalpel-hook.mjs every time
 // a real recurring pattern fires) and prints one line for Claude Code's status bar. Brave's
-// ads-blocked-counter, but for AI-coding thrash. Fail-open: no stats yet -> print nothing.
+// ads-blocked-counter, but for AI-coding thrash. The zero state stays visible so a fresh install
+// advertises that skalpel is present before the first confirmed save lands.
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -18,15 +19,18 @@ const DIM = "\x1b[2m";
 const RESET = "\x1b[0m";
 
 function main() {
-  let s;
+  let s = {};
   try {
-    s = JSON.parse(readFileSync(STATS_PATH, "utf8"));
+    const parsed = JSON.parse(readFileSync(STATS_PATH, "utf8"));
+    if (parsed && typeof parsed === "object") s = parsed;
   } catch {
-    return; // no stats yet — print nothing rather than a misleading "0 saved"
+    // Missing/corrupt first-run state is an honest zero, not a reason to hide the status line.
   }
-  const sess = (s.session_hours || 0).toFixed(1);
-  const total = (s.total_hours || 0).toFixed(1);
-  const steers = s.total_events || 0;
+  const finiteOrZero = (value) =>
+    typeof value === "number" && Number.isFinite(value) ? value : 0;
+  const sess = finiteOrZero(s.session_hours).toFixed(1);
+  const total = finiteOrZero(s.total_hours).toFixed(1);
+  const steers = finiteOrZero(s.total_events);
 
   // The LIVE steer (written by skalpel-hook.mjs each turn) — the deterministic awareness channel: the
   // user SEES skalpel steering right now, even when the model doesn't surface a 🔬 line in the answer.