skalpel 3.2.1 → 3.2.3

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/package.json

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

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 };
 }