skalpel 3.2.2 → 3.2.4

package/INSTALL.md

@@ -37,23 +37,23 @@ All three paths produce identical binaries — same SHAs, same cosign signatures
 
 ## First-run flow
 
-Post-W4 (OAuth port): the first-run flow is a single browser-loopback Cognito sign-in. The historical `sk-skalpel-*` API-key paste path is gone — the daemon no longer persists or sends api_keys on any code path. The flow is:
+Post-W4 (OAuth port): first run is a guided TUI walkthrough plus browser-loopback Cognito sign-in. The historical `sk-skalpel-*` API-key paste path is gone — the daemon no longer persists or sends api_keys on any code path. The flow is:
 
-1. The user runs `npx skalpel login` (or `skalpel login` after a global install). The npm package is materialized; both binaries are present.
-2. `skalpel login` opens a browser to the Skalpel hosted-UI sign-in page (Cognito), waits on a loopback HTTP callback, and validates the signed envelope returned by the callback.
-3. On a verified envelope, the daemon writes `auth.json` to the per-OS configuration directory (per `SPEC.md` §7). The file is owned by the user with `0600` permissions and carries the Cognito JWT bundle (access_token, refresh_token, expires_at).
-4. The user runs `skalpel` (or `npx skalpel`). The TUI detects a usable `auth.json`, invokes `skalpeld` to start the daemon, and shows the `Starting skalpeld…` splash for up to three seconds (per spec §8.5).
-5. Once the daemon is reachable, the TUI lands the user on the Engines tab. The matrix renders for whatever agents the daemon has detected so far. If no agents have been opened since installation, the empty-state message from spec §3.2 is shown.
+1. The user installs (`npm install -g skalpel`) and runs `skalpel`.
+2. If `auth.json` is missing, `skalpel` renders a branded walkthrough in-terminal: daemon status, sign-in requirement, CA trust behavior, wrapper scope (new sessions only), and quick toggles (`skalpel off` / `skalpel on`).
+3. On Enter, `skalpel` opens a browser to the Skalpel hosted-UI sign-in page (Cognito), waits on a loopback HTTP callback, and validates the signed envelope returned by the callback.
+4. On a verified envelope, the daemon writes `auth.json` to the per-OS configuration directory (per `SPEC.md` §7). The file is owned by the user with `0600` permissions and carries the Cognito JWT bundle (access_token, refresh_token, expires_at).
+5. The TUI auto-launches into the Dashboard. Once the daemon is reachable, the app surfaces live status and tabs (Dashboard / Engines / Account) with the first-run intro banner.
 
 This flow corresponds to Journey 1 — First launch, fresh authentication — in `SPEC.md`. That narrative describes what the user feels at each step; this document describes what the install machinery actually does.
 
-If the user runs `skalpel` without first running `skalpel login`, the TUI exits per spec §8.4 with a stderr pointer at `skalpel login`. To sign out of an existing account on this machine, run `skalpel logout` from a shell — the CLI revokes the backend session (best-effort) and removes `auth.json` via `internal/auth.Delete`.
+If the user runs `skalpel` without first running `skalpel login`, the walkthrough prompts them to sign in inline (Enter), skip for now (`s`), turn interception off (`o`), or quit (`q`). To sign out of an existing account on this machine, run `skalpel logout` from a shell — the CLI revokes the backend session (best-effort) and removes `auth.json` via `internal/auth.Delete`.
 
 Historical note: prior versions of skalpel supported pasting a `sk-skalpel-*` API key copied from the web dashboard as an alternative to `skalpel login`. The W4 OAuth-port grep-delete removed both the api_key-paste wizard and the daemon-side api_key sending path. Users on stale auth.json files (api_key-only, no Cognito bundle) need to run `skalpel login` once to refresh.
 
 ## Daemon lifecycle on subsequent launches
 
-On every launch after the first, the TUI checks whether `skalpeld` is reachable. If it is, the TUI proceeds to the Engines tab without further interaction. If it is not, the TUI attempts to start it (per spec §8.5) and shows the `Starting skalpeld…` splash for up to three seconds. If the daemon does not come up in that window, the TUI proceeds with the daemon-unreachable banner and the user is offered a `[r]` retry affordance.
+On every launch after the first, the TUI checks whether `skalpeld` is reachable. If it is, the TUI proceeds to Dashboard without further interaction. If it is not, the TUI attempts to start it (per spec §8.5) and shows the `Starting skalpeld…` splash for up to three seconds. If the daemon does not come up in that window, the TUI proceeds with the daemon-unreachable banner and the user is offered a `[r]` retry affordance.
 
 The TUI is not a process supervisor. Per `SPEC.md` §01: the TUI tries to start the daemon at launch and surfaces the daemon's state via the banner, but there is no "stop daemon," "restart daemon," or "view daemon logs" control in the TUI; those are shell-level concerns. The install machinery makes both binaries available; the runtime relationship between them is the TUI's start-on-launch attempt and nothing more.
 
@@ -145,15 +145,24 @@ During `npm install -g skalpel` on macOS you will see a **one-time Touch ID / pa
 - Trusts only the daemon-minted local CA labelled `Skalpel Local Intercept CA`.
 - Used exclusively for `chatgpt.com` / `api.openai.com` traffic the daemon intercepts; every other host is blind-tunnelled untouched.
 
-**If you missed the prompt** or declined it, run `skalpel login` or invoke `codex` once — the postinstall step writes a deferred-install sentinel and the next entry point retries the keychain install.
+**If you missed the prompt** or declined it, run `skalpel login` or invoke `codex` once — the postinstall step writes a deferred-install sentinel and the next entry point retries the trust-store install.
 
-**To revoke trust:**
+**macOS — revoke trust:**
 
 1. Open **Keychain Access**.
 2. Select the `login` keychain.
 3. Search for `Skalpel Local Intercept CA`.
 4. Right-click → Delete.
 
+**Linux — revoke trust:**
+
+```bash
+sudo rm /usr/local/share/ca-certificates/skalpel-local-intercept-ca.crt
+sudo update-ca-certificates --fresh
+```
+
+**Linux install requirements:** postinstall (and the deferred retry on first `skalpel login` / `codex` invocation) copies the daemon CA to `/usr/local/share/ca-certificates/skalpel-local-intercept-ca.crt` and runs `update-ca-certificates`. This needs **root** or **passwordless `sudo`**. If `sudo` is unavailable, postinstall prints the manual commands and does not fail the install.
+
 After deletion, Codex traffic falls back to bare TLS (daemon won't see it). Re-install the CA via `skalpel login` if you change your mind.
 
-**Linux / Windows status:** the trust-store install path is **not yet shipped** on Linux or Windows. Codex MITM works on macOS only in this release. On other platforms the postinstall step skips the keychain step with a printed notice; the user can configure trust manually if they need Codex visibility.
+**Windows status:** the trust-store install path is **not yet shipped** on Windows. Codex MITM on Windows still requires manual cert trust until a `certutil` path lands.

package/README.md

@@ -16,7 +16,21 @@ npx skalpel login
 npm install -g skalpel
 ```
 
-Both `skalpel` and `skalpeld` are placed on your `PATH`. For details on what gets installed where, per-OS service registration, updates, and uninstall, see [INSTALL.md](./INSTALL.md).
+Both `skalpel` and `skalpeld` are placed on your `PATH`. Then run:
+
+```
+skalpel
+```
+
+to open the guided first-run walkthrough (brand banner, step-by-step setup, sign-in handoff, and toggle tips).
+
+Note: npm may hide lifecycle-script output; if you want to see install wizard logs during `npm install`, use:
+
+```
+npm install -g skalpel --foreground-scripts
+```
+
+For details on what gets installed where, per-OS service registration, updates, and uninstall, see [INSTALL.md](./INSTALL.md).
 
 ## Subcommands
 

package/npm-bin/skalpel.bug-0039.test.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// BUG-0039 — Windows daemon missing → Defender-aware warning test.
+//
+// What we're testing: the sibling-check branch in resolveBinary. When
+// the user runs `skalpel <anything>` on Windows AND skalpeld.exe is
+// missing from the platform package's bin/, the CLI must:
+//   - emit a clear actionable warning to stderr
+//   - NOT exit (so --version / --help still work)
+//   - include the PowerShell Add-MpPreference command
+//   - use single-quoted path (neutralises NTFS-legal $ / backtick / ')
+//
+// Stdlib-only, no test framework. Builds a fake @skalpelai/skalpel-*
+// package layout in a tmpdir inside the repo's node_modules so Node's
+// resolver finds it, then patches Module._resolveLookupPaths to prefer
+// the sandbox.
+//
+// Run:  node npm-bin/skalpel.bug-0039.test.js
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+let pass = 0;
+let fail = 0;
+
+function t(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;
+  }
+}
+
+// Capture stderr + intercepted process.exit code.
+function captureStderr(fn) {
+  const original = process.stderr.write.bind(process.stderr);
+  let buf = '';
+  process.stderr.write = (chunk) => {
+    buf += String(chunk);
+    return true;
+  };
+  const origExit = process.exit;
+  let exitCode = null;
+  process.exit = (code) => {
+    exitCode = code;
+    throw new Error('__BUG0039_TEST_EXIT__');
+  };
+  try {
+    try { fn(); } catch (e) {
+      if (e && e.message !== '__BUG0039_TEST_EXIT__') throw e;
+    }
+  } finally {
+    process.stderr.write = original;
+    process.exit = origExit;
+  }
+  return { stderr: buf, exitCode };
+}
+
+function withFakeWin32Package(opts) {
+  // Use os.tmpdir() (NOT in-repo node_modules) so a test crash between
+  // mkdir and finally-cleanup can't leave a stub that shadows the real
+  // platform package on subsequent dev runs.
+  const sandboxRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'bug0039-'));
+  const platDir = path.join(sandboxRoot, 'node_modules', '@skalpelai', 'skalpel-win32-x64');
+  const binDir = path.join(platDir, 'bin');
+  fs.mkdirSync(binDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(platDir, 'package.json'),
+    JSON.stringify({ name: '@skalpelai/skalpel-win32-x64', version: '3.2.2-test' })
+  );
+  fs.writeFileSync(path.join(binDir, 'skalpel.exe'), 'stub');
+  if (opts.daemonPresent) fs.writeFileSync(path.join(binDir, 'skalpeld.exe'), 'stub');
+  return {
+    sandboxRoot,
+    cleanup: () => fs.rmSync(sandboxRoot, { recursive: true, force: true }),
+  };
+}
+
+function withResolveOverride(sandboxRoot, fn) {
+  const Module = require('module');
+  const orig = Module._resolveLookupPaths;
+  Module._resolveLookupPaths = function (request, parent) {
+    const base = orig.call(this, request, parent);
+    if (request && request.startsWith('@skalpelai/skalpel-')) {
+      const inject = path.join(sandboxRoot, 'node_modules');
+      return base && Array.isArray(base) ? [inject, ...base] : [inject];
+    }
+    return base;
+  };
+  try { return fn(); } finally { Module._resolveLookupPaths = orig; }
+}
+
+const skalpel = require('./skalpel.js');
+Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+Object.defineProperty(process, 'arch', { value: 'x64', configurable: true });
+
+// ── Test 1: skalpel-resolve + missing sibling daemon → warning, no exit
+t('resolveBinary(\'skalpel\') with missing skalpeld.exe emits warning and returns', () => {
+  const fake = withFakeWin32Package({ daemonPresent: false });
+  try {
+    let returned = null;
+    const { stderr, exitCode } = captureStderr(() => {
+      withResolveOverride(fake.sandboxRoot, () => {
+        returned = skalpel.resolveBinary('skalpel', []);
+      });
+    });
+    // MUST return the resolved skalpel.exe path (no exit)
+    assert.ok(returned, `expected non-null return, got ${returned}`);
+    assert.ok(returned.endsWith('skalpel.exe'), `expected skalpel.exe, got ${returned}`);
+    assert.strictEqual(exitCode, null, `expected NO process.exit, got code=${exitCode}`);
+    // MUST emit Defender-aware warning
+    assert.ok(stderr.includes('skalpel daemon missing'), `expected daemon-missing title:\n${stderr}`);
+    assert.ok(stderr.includes('Defender'), `expected Defender mention:\n${stderr}`);
+    assert.ok(stderr.includes('Add-MpPreference'), `expected PowerShell command:\n${stderr}`);
+    assert.ok(stderr.includes('Authenticode'), `expected code-sign mention:\n${stderr}`);
+    assert.ok(stderr.includes('Restore'), `expected restore path:\n${stderr}`);
+    // PowerShell path is single-quoted (the critical quoting fix)
+    const dirLine = stderr.split('\n').find((l) => l.includes('$dir ='));
+    assert.ok(dirLine, `expected $dir = line, got:\n${stderr}`);
+    assert.ok(/\$dir = '/.test(dirLine), `expected single-quoted path in $dir line: ${dirLine}`);
+    // The Add-MpPreference line should reference $dir (not embed the path)
+    const mpLine = stderr.split('\n').find((l) => l.includes('Add-MpPreference'));
+    assert.ok(mpLine, `expected Add-MpPreference line:\n${stderr}`);
+    assert.ok(/-ExclusionPath \$dir/.test(mpLine), `expected -ExclusionPath $dir: ${mpLine}`);
+  } finally { fake.cleanup(); }
+});
+
+// ── Test 2: happy path (daemon present) → returns path, NO warning
+t('resolveBinary(\'skalpel\') with daemon present: silent, returns path', () => {
+  const fake = withFakeWin32Package({ daemonPresent: true });
+  try {
+    let returned = null;
+    const { stderr, exitCode } = captureStderr(() => {
+      withResolveOverride(fake.sandboxRoot, () => {
+        returned = skalpel.resolveBinary('skalpel', []);
+      });
+    });
+    assert.ok(returned && returned.endsWith('skalpel.exe'), `expected skalpel.exe, got ${returned}`);
+    assert.strictEqual(exitCode, null);
+    assert.ok(!stderr.includes('Defender'), `expected no Defender warning on happy path, got:\n${stderr}`);
+    assert.ok(!stderr.includes('quarantine'), `expected no quarantine mention on happy path:\n${stderr}`);
+  } finally { fake.cleanup(); }
+});
+
+// ── Test 3: skalpel.exe itself missing → generic Binary missing error
+t('resolveBinary(\'skalpel\') with skalpel.exe missing: generic error, NOT Defender block', () => {
+  const fake = withFakeWin32Package({ daemonPresent: false });
+  // Also remove skalpel.exe
+  fs.unlinkSync(path.join(fake.sandboxRoot, 'node_modules', '@skalpelai', 'skalpel-win32-x64', 'bin', 'skalpel.exe'));
+  try {
+    const { stderr, exitCode } = captureStderr(() => {
+      withResolveOverride(fake.sandboxRoot, () => {
+        skalpel.resolveBinary('skalpel', []);
+      });
+    });
+    assert.strictEqual(exitCode, 1, 'expected exit 1 on missing CLI binary');
+    assert.ok(stderr.includes('Binary missing'), `expected generic title:\n${stderr}`);
+    // The Defender block is gated on a successful candidate-exists check,
+    // so it should NOT fire when skalpel.exe itself is missing.
+    assert.ok(!stderr.includes('Defender'), `Defender warning should NOT fire when CLI itself missing:\n${stderr}`);
+  } finally { fake.cleanup(); }
+});
+
+// ── Test 4: non-Windows platform → no sibling check fires
+t('resolveBinary(\'skalpel\') on linux: no sibling check, silent on success', () => {
+  // Temporarily flip to linux + reset PLATFORM_PACKAGES key check
+  Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
+  try {
+    const sandboxRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'bug0039-linux-'));
+    const platDir = path.join(sandboxRoot, 'node_modules', '@skalpelai', 'skalpel-linux-x64');
+    const binDir = path.join(platDir, 'bin');
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.writeFileSync(path.join(platDir, 'package.json'), JSON.stringify({ name: '@skalpelai/skalpel-linux-x64', version: '3.2.2-test' }));
+    fs.writeFileSync(path.join(binDir, 'skalpel'), 'stub');
+    // daemon intentionally missing
+    try {
+      const { stderr, exitCode } = captureStderr(() => {
+        withResolveOverride(sandboxRoot, () => {
+          skalpel.resolveBinary('skalpel', []);
+        });
+      });
+      assert.strictEqual(exitCode, null, 'expected no exit on linux happy path');
+      assert.ok(!stderr.includes('Defender'), `linux must NOT emit Defender warning:\n${stderr}`);
+    } finally { fs.rmSync(sandboxRoot, { recursive: true, force: true }); }
+  } finally {
+    Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+  }
+});
+
+// ── Test 5: PowerShell escape of literal apostrophe in path
+t("PowerShell '' escape activates when path contains a literal apostrophe", () => {
+  // Build a sandbox under a parent dir whose NAME contains an apostrophe.
+  // NTFS allows ' in filenames, and POSIX paths do too. The Defender
+  // exclusion path will be path.dirname(siblingDaemon) — which on this
+  // sandbox includes a "with'apos" segment. The PowerShell single-quote
+  // literal MUST escape the inner ' as '' to remain valid PS syntax.
+  const parent = fs.mkdtempSync(path.join(os.tmpdir(), "bug0039-apos-"));
+  const aposDir = path.join(parent, "with'apos");
+  const platDir = path.join(aposDir, 'node_modules', '@skalpelai', 'skalpel-win32-x64');
+  const binDir = path.join(platDir, 'bin');
+  fs.mkdirSync(binDir, { recursive: true });
+  fs.writeFileSync(path.join(platDir, 'package.json'), JSON.stringify({ name: '@skalpelai/skalpel-win32-x64', version: '3.2.2-test' }));
+  fs.writeFileSync(path.join(binDir, 'skalpel.exe'), 'stub');
+  // skalpeld.exe intentionally missing
+  try {
+    const { stderr } = captureStderr(() => {
+      withResolveOverride(aposDir, () => {
+        skalpel.resolveBinary('skalpel', []);
+      });
+    });
+    const dirLine = stderr.split('\n').find((l) => l.includes('$dir ='));
+    assert.ok(dirLine, `expected $dir = line, got:\n${stderr}`);
+    // The literal ' in the path must be DOUBLED inside the single-quoted PS literal
+    assert.ok(
+      dirLine.includes("with''apos"),
+      `expected '' escape for literal apostrophe, got: ${dirLine}`
+    );
+    // And the path must still be wrapped in single quotes
+    assert.ok(/\$dir = '.*'$/.test(dirLine.trim()), `expected single-quoted: ${dirLine}`);
+  } finally {
+    fs.rmSync(parent, { recursive: true, force: true });
+  }
+});
+
+// ── summary
+process.stdout.write(`\n  results: ${pass} passed, ${fail} failed\n`);
+if (fail > 0) process.exit(1);

package/npm-bin/skalpel.js

@@ -196,6 +196,73 @@ function resolveBinary(name, argv) {
     );
     process.exit(failExit);
   }
+  // BUG-0039 sibling check (Windows only). The CLI shim binary
+  // (skalpel.exe) survives Defender heuristics — it doesn't network
+  // or spawn — but the daemon (skalpeld.exe) trips them (unsigned +
+  // network-active + spawns processes) and gets silently quarantined
+  // within ~30s of `npm install`. The user then runs `skalpel login`,
+  // the Go binary's spawn-daemon call fails with an opaque error,
+  // and the user has no idea why. Emit a one-shot actionable warning
+  // here on the CLI-resolve path so the user sees the Defender
+  // explanation BEFORE the spawn failure. Doesn't exit — `skalpel
+  // --version` / `--help` continue to work; the Go binary surfaces
+  // its own error on commands that actually need the daemon.
+  if (process.platform === 'win32' && name === 'skalpel') {
+    const siblingDaemon = path.join(pkgRoot, 'bin', 'skalpeld.exe');
+    if (!fs.existsSync(siblingDaemon)) {
+      // Single-quoted PS path with '' escape neutralises backtick,
+      // $, and apostrophe (all NTFS-legal).
+      const psSafePath = path.dirname(siblingDaemon).replace(/'/g, "''");
+      // Custom layout: box contains ONLY the diagnostic explanation,
+      // hint text is emitted as plain stderr lines BELOW the box. This
+      // keeps long Windows install paths (which can exceed 80 cols)
+      // out of the box — cmd.exe's default 80-col width would
+      // otherwise wrap the box and shatter the copy-pasteable
+      // PowerShell command. Plain-text below the box wraps naturally
+      // and the user can still copy-paste a multi-line PS literal.
+      const body = [
+        'skalpel.exe is present and runnable, but skalpeld.exe is missing',
+        'from the install. Windows Defender (or another AV) almost',
+        'certainly quarantined the unsigned daemon binary shortly after',
+        'npm finished installing. `skalpel login` and the TUI need the',
+        'daemon and will fail with an opaque error until it is restored.',
+      ].join('\n');
+      const colored = process.stderr.isTTY && !process.env.NO_COLOR;
+      const titleText = colored
+        ? theme.bold(theme.red('✗ skalpel daemon missing (Defender quarantine likely)'))
+        : '✗ skalpel daemon missing (Defender quarantine likely)';
+      const bodyDim = colored ? theme.dim(theme.text(body)) : body;
+      const boxed = box([titleText, '', bodyDim].join('\n'), colored ? 'red' : null, { padding: 1 });
+      process.stderr.write(`${boxed}\n`);
+      // Plain-text hint — long path lives on its own line, no box to corrupt.
+      process.stderr.write([
+        '',
+        'FIX (pick one):',
+        '',
+        'A. Whitelist install dir in Defender, then reinstall:',
+        '   1) Open PowerShell as Administrator',
+        '   2) Run, with the path on its own line:',
+        '',
+        `        $dir = '${psSafePath}'`,
+        '        Add-MpPreference -ExclusionPath $dir',
+        '',
+        '   3) In any shell:  npm install -g skalpel',
+        '',
+        'B. Restore the quarantined binary:',
+        '     Windows Security → Virus & threat protection →',
+        '     Protection history → Allow → Restore (skalpeld.exe).',
+        '',
+        'Different AV? Add the directory to its own exclusion UI.',
+        'Add-MpPreference only configures Windows Defender.',
+        '',
+        'Permanent fix in progress: Authenticode code-signing of the',
+        'Windows binaries.',
+        '',
+      ].join('\n'));
+      // Intentionally no process.exit — the CLI must still run for
+      // --version / --help / diagnostic commands.
+    }
+  }
   return candidate;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "3.2.2",
+  "version": "3.2.4",
   "description": "Skalpel — local proxy and TUI for coding agents (skalpel + skalpeld bundle).",
   "license": "Apache-2.0",
   "homepage": "https://skalpel.ai",
@@ -31,10 +31,11 @@
     "preinstall": "node postinstall/preinstall.js",
     "postinstall": "node postinstall/index.js",
     "preuninstall": "node postinstall/uninstall.js",
-    "test": "node postinstall/lib/run-tests.js",
+    "test": "node postinstall/lib/run-tests.js && node npm-bin/skalpel.bug-0039.test.js",
     "test:rc-edit": "node postinstall/lib/rc-edit.test.js",
     "test:postinstall": "node --test postinstall/index.test.js",
-    "test:preinstall": "node --test postinstall/preinstall.test.js"
+    "test:preinstall": "node --test postinstall/preinstall.test.js",
+    "test:bug-0039": "node npm-bin/skalpel.bug-0039.test.js"
   },
   "files": [
     "npm-bin/",
@@ -57,10 +58,10 @@
     "x64"
   ],
   "optionalDependencies": {
-    "@skalpelai/skalpel-darwin-arm64": "3.2.2",
-    "@skalpelai/skalpel-darwin-x64": "3.2.2",
-    "@skalpelai/skalpel-linux-arm64": "3.2.2",
-    "@skalpelai/skalpel-linux-x64": "3.2.2",
-    "@skalpelai/skalpel-win32-x64": "3.2.2"
+    "@skalpelai/skalpel-darwin-arm64": "3.2.4",
+    "@skalpelai/skalpel-darwin-x64": "3.2.4",
+    "@skalpelai/skalpel-linux-arm64": "3.2.4",
+    "@skalpelai/skalpel-linux-x64": "3.2.4",
+    "@skalpelai/skalpel-win32-x64": "3.2.4"
   }
 }

package/postinstall/index.js

@@ -112,14 +112,14 @@ async function runCAInstallStep(opts) {
     // ignored — fall through to deferred-no-ca branch
   }
   if (!caPath) {
-    log.warn('ca-install: could not resolve `skalpel ca-path`; deferring keychain trust to first login');
+    log.warn('ca-install: could not resolve `skalpel ca-path`; deferring trust-store install to first login');
     return { ok: false, reason: 'no-binary' };
   }
   if (opts.dryRun) {
-    log.info(`ca-install: dry-run; would install ${caPath} into login keychain`);
+    log.info(`ca-install: dry-run; would install ${caPath} into OS trust store`);
     return { ok: true, skipped: true, reason: 'dry-run' };
   }
-  return caInstall.installMacOSCA(caPath);
+  return caInstall.installDaemonCA(caPath);
 }
 
 async function main(argv) {
@@ -184,12 +184,10 @@ async function main(argv) {
       allWarnings.push(...sr.warnings);
     }
 
-    log.step(4, total, 'ca-install', `keychain trust on ${process.platform}`);
-    // ca-install is NON-CRITICAL: a declined Touch ID prompt must NOT
+    log.step(4, total, 'ca-install', `trust store on ${process.platform}`);
+    // ca-install is NON-CRITICAL: declined prompts or missing sudo must NOT
     // fail postinstall. The deferred-install sentinel ensures first
-    // `skalpel login` / `codex` invocation retries the trust. On
-    // non-darwin we log + skip; Linux/Windows trust-store install is
-    // deferred to a later bundle.
+    // `skalpel login` / `codex` invocation retries the trust install.
     try {
       const caRes = await runCAInstallStep(opts);
       if (caRes && !caRes.ok && caRes.reason) {

package/postinstall/lib/ca-install.js

@@ -1,24 +1,16 @@
 'use strict';
 
-// macOS keychain CA install for the daemon's MITM CA.
+// Platform trust-store install for the daemon's MITM CA.
 //
-// Codex CLI is Rust and consults the OS keychain (Security Framework on
-// macOS) for trust. To make `skalpel codex-exec` work end-to-end on a
-// fresh `npm install -g skalpel`, the postinstall flow trusts the
-// daemon's local CA in the user's login keychain. This module owns that
-// step.
+// macOS: login keychain via `security add-trusted-cert`.
+// Linux: /usr/local/share/ca-certificates + `update-ca-certificates`.
 //
-// Contract:
-//   installMacOSCA(caPath, opts) returns
-//     { ok: true }                                — installed (or already trusted)
-//     { ok: true, skipped: true, reason: '...' } — non-darwin or idempotent skip
-//     { ok: false, reason: '...' }                — user declined / timeout /
-//                                                   deferred (CA not yet on disk)
+// Contract (installDaemonCA / installMacOSCA):
+//   { ok: true }                                — installed (or already trusted)
+//   { ok: true, skipped: true, reason: '...' } — idempotent skip / unsupported OS
+//   { ok: false, reason: '...' }                — deferred / declined / failed
 //
-// Failure is NEVER fatal to postinstall. The user falls back to a
-// printed-instruction path and the next `skalpel codex-exec` /
-// `skalpel login` retries via the Go-side `internal/cainstall`
-// RetrySentinel helper.
+// Failure is NEVER fatal to postinstall.
 
 const fs = require('fs');
 const os = require('os');
@@ -29,80 +21,167 @@ const KEYCHAIN_LABEL = 'Skalpel Local Intercept CA';
 const DEFAULT_TIMEOUT_MS = 60_000;
 const SENTINEL_BASENAME = '.ca-install-pending';
 
-// loginKeychainPath returns the path to the user's login keychain on
-// macOS. macOS Catalina+ uses .keychain-db.
+const LINUX_CA_DIR = '/usr/local/share/ca-certificates';
+const LINUX_CA_BASENAME = 'skalpel-local-intercept-ca.crt';
+
 function loginKeychainPath(homedir) {
   return path.join(homedir, 'Library', 'Keychains', 'login.keychain-db');
 }
 
+function linuxTargetPath() {
+  return path.join(LINUX_CA_DIR, LINUX_CA_BASENAME);
+}
+
 function logMsg(stream, msg) {
   if (stream && typeof stream.write === 'function') {
     stream.write(`${msg}\n`);
   }
 }
 
-// installMacOSCA installs the daemon's MITM CA into the user's login
-// keychain, prompting the user for Touch ID / password. Idempotent —
-// re-running after a successful install is a no-op.
-//
-// opts:
-//   spawn:         optional injected child_process.spawn for tests
-//   stderr:        optional Writable for status messages (defaults to process.stderr)
-//   homedir:       optional homedir for tests (defaults to os.homedir())
-//   timeoutMs:     optional timeout override (defaults to 60s)
-//   sentinelDir:   optional dir where the deferred-install sentinel is written
-//                  when caPath does not exist (defaults to dirname(caPath))
-async function installMacOSCA(caPath, opts) {
+function caFilesMatch(leftPath, rightPath) {
+  try {
+    const a = fs.readFileSync(leftPath);
+    const b = fs.readFileSync(rightPath);
+    return a.length === b.length && a.equals(b);
+  } catch (_) {
+    return false;
+  }
+}
+
+function writeDeferredSentinel(caPath, opts, stderr) {
+  const sentinelDir = opts.sentinelDir || path.dirname(caPath);
+  const sentinelPath = path.join(sentinelDir, SENTINEL_BASENAME);
+  try {
+    fs.mkdirSync(sentinelDir, { recursive: true });
+    fs.writeFileSync(sentinelPath, '');
+  } catch (err) {
+    logMsg(stderr, `Skalpel: could not write ca-install sentinel at ${sentinelPath}: ${err.message}`);
+  }
+  logMsg(
+    stderr,
+    'Skalpel: daemon CA not yet generated — will install on first `skalpel login` or `codex` invocation.'
+  );
+  return { ok: false, reason: 'deferred-no-ca', sentinelPath };
+}
+
+function isRootUser() {
+  return typeof process.getuid === 'function' && process.getuid() === 0;
+}
+
+function runPrivileged(spawnSync, bin, args) {
+  const fn = spawnSync || childProcess.spawnSync;
+  if (isRootUser()) {
+    return fn(bin, args, { encoding: 'utf8' });
+  }
+  return fn('sudo', ['-n', bin, ...args], { encoding: 'utf8' });
+}
+
+function sudoAvailable(spawnSync) {
+  const fn = spawnSync || childProcess.spawnSync;
+  const probe = fn('sudo', ['-n', 'true'], { encoding: 'utf8' });
+  return probe.status === 0;
+}
+
+// installDaemonCA is the postinstall entrypoint for all platforms.
+async function installDaemonCA(caPath, opts) {
+  const platform = (opts && opts.platform) || process.platform;
+  if (platform === 'darwin') {
+    return installMacOSCA(caPath, { ...opts, platform: 'darwin' });
+  }
+  if (platform === 'linux') {
+    return installLinuxCA(caPath, opts);
+  }
+  const stderr = (opts && opts.stderr) || process.stderr;
+  logMsg(
+    stderr,
+    `Skalpel: Codex MITM CA install skipped on ${platform}; trust-store install ` +
+      'not yet implemented for this OS.'
+  );
+  return { ok: true, skipped: true, reason: 'platform' };
+}
+
+// installLinuxCA copies the daemon CA into the distro trust bundle and
+// refreshes the system store.
+async function installLinuxCA(caPath, opts) {
   const o = opts || {};
-  const spawn = o.spawn || childProcess.spawn;
   const stderr = o.stderr || process.stderr;
-  const homedir = o.homedir || os.homedir();
-  const timeoutMs = o.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spawnSync = o.spawnSync || childProcess.spawnSync;
   const platform = o.platform || process.platform;
 
-  if (platform !== 'darwin') {
+  if (platform !== 'linux') {
+    return { ok: true, skipped: true, reason: 'platform' };
+  }
+
+  if (!fs.existsSync(caPath)) {
+    return writeDeferredSentinel(caPath, o, stderr);
+  }
+
+  const dest = o.linuxTargetPath || linuxTargetPath();
+  if (fs.existsSync(dest) && caFilesMatch(caPath, dest)) {
+    return { ok: true, skipped: true, reason: 'already-installed' };
+  }
+
+  if (!isRootUser() && !sudoAvailable(spawnSync)) {
     logMsg(
       stderr,
-      `Skalpel: Codex MITM CA install skipped on ${platform}; Linux/Windows ` +
-        `trust-store install not yet implemented. Codex will fall back to bare ` +
-        `TLS — daemon won't see Codex traffic until trust is configured manually.`
+      'Skalpel: Linux CA trust install needs root or passwordless sudo. Run:\n' +
+        `  sudo install -m 0644 ${caPath} ${dest}\n` +
+        '  sudo update-ca-certificates'
     );
-    return { ok: true, skipped: true, reason: 'platform' };
+    return { ok: false, reason: 'no-sudo' };
   }
 
-  if (!fs.existsSync(caPath)) {
-    // Daemon hasn't generated the CA yet. Drop a sentinel and let the
-    // Go-side retry path pick it up on next `skalpel login` /
-    // `skalpel codex-exec`.
-    const sentinelDir = o.sentinelDir || path.dirname(caPath);
-    const sentinelPath = path.join(sentinelDir, SENTINEL_BASENAME);
-    try {
-      fs.mkdirSync(sentinelDir, { recursive: true });
-      fs.writeFileSync(sentinelPath, '');
-    } catch (err) {
-      logMsg(stderr, `Skalpel: could not write ca-install sentinel at ${sentinelPath}: ${err.message}`);
-    }
+  const installRes = runPrivileged(spawnSync, 'install', ['-m', '0644', caPath, dest]);
+  if (installRes.status !== 0) {
+    const detail = (installRes.stderr || installRes.stdout || '').trim();
     logMsg(
       stderr,
-      'Skalpel: daemon CA not yet generated — will install on first `skalpel login` or `codex` invocation.'
+      `Skalpel: failed to copy CA to ${dest}${detail ? `: ${detail}` : ''}. ` +
+        'Codex may bypass skalpel until trust is configured.'
     );
-    return { ok: false, reason: 'deferred-no-ca', sentinelPath };
+    return { ok: false, reason: 'install-failed', exitCode: installRes.status, detail };
+  }
+
+  const updateRes = runPrivileged(spawnSync, 'update-ca-certificates', []);
+  if (updateRes.status !== 0) {
+    const detail = (updateRes.stderr || updateRes.stdout || '').trim();
+    logMsg(
+      stderr,
+      `Skalpel: update-ca-certificates failed${detail ? `: ${detail}` : ''}.`
+    );
+    return { ok: false, reason: 'update-failed', exitCode: updateRes.status, detail };
+  }
+
+  logMsg(stderr, 'Skalpel: daemon CA trusted in Linux system store.');
+  return { ok: true };
+}
+
+// installMacOSCA installs into the login keychain (darwin only).
+async function installMacOSCA(caPath, opts) {
+  const o = opts || {};
+  const spawn = o.spawn || childProcess.spawn;
+  const stderr = o.stderr || process.stderr;
+  const homedir = o.homedir || os.homedir();
+  const timeoutMs = o.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const platform = o.platform || process.platform;
+
+  if (platform !== 'darwin') {
+    return installDaemonCA(caPath, opts);
+  }
+
+  if (!fs.existsSync(caPath)) {
+    return writeDeferredSentinel(caPath, o, stderr);
   }
 
   const loginKC = loginKeychainPath(homedir);
 
-  // Idempotency: probe first via `security find-certificate -c <label>
-  // <keychain>`. Exit 0 → already trusted; nothing to do.
   if (await findCertificate(spawn, loginKC, timeoutMs)) {
     return { ok: true, skipped: true, reason: 'already-installed' };
   }
 
-  return await runAddTrustedCert(spawn, stderr, caPath, loginKC, timeoutMs);
+  return runAddTrustedCert(spawn, stderr, caPath, loginKC, timeoutMs);
 }
 
-// findCertificate runs `security find-certificate -c <label> <kc>` and
-// resolves to true iff the certificate is already trusted in the user's
-// login keychain.
 function findCertificate(spawn, loginKC, timeoutMs) {
   return new Promise((resolve) => {
     const child = spawn('security', ['find-certificate', '-c', KEYCHAIN_LABEL, loginKC], {
@@ -130,11 +209,6 @@ function findCertificate(spawn, loginKC, timeoutMs) {
   });
 }
 
-// runAddTrustedCert spawns the install command, branching on its
-// outcome:
-//   exit 0  → installed
-//   exit !=0 within timeout → user declined or system rejected
-//   timeout → kill child and report timeout
 function runAddTrustedCert(spawn, stderr, caPath, loginKC, timeoutMs) {
   return new Promise((resolve) => {
     const child = spawn(
@@ -180,9 +254,15 @@ function runAddTrustedCert(spawn, stderr, caPath, loginKC, timeoutMs) {
 }
 
 module.exports = {
+  installDaemonCA,
   installMacOSCA,
+  installLinuxCA,
   KEYCHAIN_LABEL,
   SENTINEL_BASENAME,
-  // Exported for tests:
+  LINUX_CA_DIR,
+  LINUX_CA_BASENAME,
+  linuxTargetPath,
   loginKeychainPath,
+  caFilesMatch,
+  runPrivileged,
 };

package/postinstall/lib/ca-install.test.js

@@ -95,19 +95,118 @@ function tmpdir() {
 async function run() {
   process.stdout.write('ca-install tests:\n');
 
-  await test('non-darwin skip', async () => {
+  await test('win32 platform skip via installDaemonCA', async () => {
     const stderr = captureStderr();
-    const spawn = makeSpawn([]);
-    const result = await ca.installMacOSCA('/anything', {
-      spawn,
+    const result = await ca.installDaemonCA('/anything', {
       stderr,
-      platform: 'linux',
+      platform: 'win32',
     });
     assert.strictEqual(result.ok, true);
     assert.strictEqual(result.skipped, true);
     assert.strictEqual(result.reason, 'platform');
-    assert.strictEqual(spawn.calls.length, 0, 'must not invoke security on non-darwin');
-    assert.ok(/linux/.test(stderr.text()), 'should mention current platform');
+    assert.ok(/win32/.test(stderr.text()), 'should mention current platform');
+  });
+
+  await test('linux deferred writes sentinel', async () => {
+    const stderr = captureStderr();
+    const dir = tmpdir();
+    const caPath = path.join(dir, 'mitm-ca.pem');
+    const result = await ca.installLinuxCA(caPath, {
+      stderr,
+      platform: 'linux',
+      sentinelDir: dir,
+      spawnSync: () => ({ status: 0 }),
+    });
+    assert.strictEqual(result.ok, false);
+    assert.strictEqual(result.reason, 'deferred-no-ca');
+    const sentinel = path.join(dir, ca.SENTINEL_BASENAME);
+    assert.ok(fs.existsSync(sentinel));
+  });
+
+  await test('linux already-installed idempotency', async () => {
+    const stderr = captureStderr();
+    const dir = tmpdir();
+    const caPath = path.join(dir, 'mitm-ca.pem');
+    const dest = path.join(dir, 'skalpel-local-intercept-ca.crt');
+    const body = 'test-pem';
+    fs.writeFileSync(caPath, body);
+    fs.writeFileSync(dest, body);
+    const spawnSync = () => {
+      throw new Error('spawnSync should not run when already installed');
+    };
+    const result = await ca.installLinuxCA(caPath, {
+      stderr,
+      platform: 'linux',
+      linuxTargetPath: dest,
+      spawnSync,
+    });
+    assert.strictEqual(result.ok, true);
+    assert.strictEqual(result.skipped, true);
+    assert.strictEqual(result.reason, 'already-installed');
+  });
+
+  await test('linux success path', async () => {
+    const stderr = captureStderr();
+    const dir = tmpdir();
+    const caPath = path.join(dir, 'mitm-ca.pem');
+    const dest = path.join(dir, 'skalpel-local-intercept-ca.crt');
+    fs.writeFileSync(caPath, 'pem');
+    const calls = [];
+    const spawnSync = (bin, args) => {
+      if (bin === 'sudo') {
+        calls.push({ bin: args[1], args: args.slice(2) });
+      } else {
+        calls.push({ bin, args });
+      }
+      if (calls[calls.length - 1].bin === 'install') {
+        fs.copyFileSync(caPath, dest);
+      }
+      return { status: 0, stdout: '', stderr: '' };
+    };
+    const origGetuid = process.getuid;
+    process.getuid = () => 1000;
+    try {
+      const result = await ca.installLinuxCA(caPath, {
+        stderr,
+        platform: 'linux',
+        linuxTargetPath: dest,
+        spawnSync,
+      });
+      assert.strictEqual(result.ok, true);
+      assert.ok(fs.existsSync(dest));
+      const bins = calls.map((c) => c.bin);
+      assert.ok(bins.includes('install'), `expected install in ${bins}`);
+      assert.ok(bins.includes('update-ca-certificates'), `expected update-ca-certificates in ${bins}`);
+    } finally {
+      process.getuid = origGetuid;
+    }
+  });
+
+  await test('linux no-sudo soft failure', async () => {
+    const stderr = captureStderr();
+    const dir = tmpdir();
+    const caPath = path.join(dir, 'mitm-ca.pem');
+    const dest = path.join(dir, 'skalpel-local-intercept-ca.crt');
+    fs.writeFileSync(caPath, 'pem');
+    const spawnSync = (bin) => {
+      if (bin === 'sudo') return { status: 1, stdout: '', stderr: 'sorry' };
+      return { status: 0, stdout: '', stderr: '' };
+    };
+    const origGetuid = process.getuid;
+    process.getuid = () => 1000;
+    try {
+      const result = await ca.installLinuxCA(caPath, {
+        stderr,
+        platform: 'linux',
+        linuxTargetPath: dest,
+        spawnSync,
+      });
+      assert.strictEqual(result.ok, false);
+      assert.strictEqual(result.reason, 'no-sudo');
+      assert.ok(/passwordless sudo|sudo install/.test(stderr.text()));
+    } finally {
+      process.getuid = origGetuid;
+    }
   });
 
   await test('already-installed idempotency', async () => {

package/postinstall/lib/launch.js

@@ -16,12 +16,14 @@ const path = require('path');
 const log = require('./log');
 
 function run({ dryRun }) {
-  const hint = 'all set — run `skalpel` to open the TUI';
+  const hint =
+    'all set — run `skalpel` to open the guided TUI walkthrough (sign-in, daemon status, toggle tips)';
   if (dryRun) {
     log.dryRun(`step 5 launch: would print: ${hint}`);
     return { launched: false, dryRun: true };
   }
   log.info(hint);
+  log.info('npm may hide lifecycle output by default; use `npm install -g skalpel --foreground-scripts` if you want to see wizard logs.');
   return { launched: false, deferred: true };
 }