Keep browse daemons alive across separate CLI invocations on macOS

The browse CLI was starting a server that looked healthy during the first
command, but the daemon and its Chromium children were still tied to the
launching shell session. A follow-up invocation would miss the prior server,
start from about:blank, and lose all persisted browse state.

This switches the POSIX launcher to a detached Node child that starts Bun in a
separate session/process group, and adds explicit SIGHUP handling on the server
side so headless daemons stay alive when short-lived shells exit. It also adds a
small regression guard around the detached stdio contract.

Constraint: The fix must work with Bun-built CLI binaries on macOS without adding dependencies
Rejected: Keep using Bun.spawn(...).unref() | daemon and Chromium still died after the launching shell exited
Rejected: nohup wrapper only | shell hangup still dropped the launched browser session in practice
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Detached launch behavior is part of browse state persistence; do not revert to parent-attached spawn without re-testing separate invocations
Tested: bun test test/browse-cli-daemon.test.ts; bun run build; manual browse goto https://example.com then separate browse url reuse check
Not-tested: Full /qa and /canary flows on macOS after prolonged idle periods

Author: be-student

browse/src/cli.ts

@@ -94,6 +94,17 @@ interface ServerState {
   mode?: 'launched' | 'headed';
 }
 
+export function detachedServerSpawnStdio(isWindows: boolean = IS_WINDOWS): ['ignore', 'ignore', 'ignore'] {
+  // Keep detached server stdio disconnected from the parent shell on every
+  // platform. On macOS/Bun, piped stdio can take the daemon down when the
+  // short-lived CLI process exits between invocations.
+  return ['ignore', 'ignore', 'ignore'];
+}
+
+export function resolveBunExecutable(): string {
+  return process.env.BUN_BIN || Bun.which('bun') || 'bun';
+}
+
 // ─── State File ────────────────────────────────────────────────
 function readState(): ServerState | null {
   try {
@@ -231,12 +242,17 @@ async function startServer(extraEnv?: Record<string, string>): Promise<ServerSta
       `${extraEnvStr})}).unref()`;
     Bun.spawnSync(['node', '-e', launcherCode], { stdio: ['ignore', 'ignore', 'ignore'] });
   } else {
-    // macOS/Linux: Bun.spawn + unref works correctly
-    proc = Bun.spawn(['bun', 'run', SERVER_SCRIPT], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env, BROWSE_STATE_FILE: config.stateFile, BROWSE_PARENT_PID: parentPid, ...extraEnv },
-    });
-    proc.unref();
+    // POSIX: run the Bun server inside a detached Node child process so the
+    // daemon and its Chromium children live in a separate session/process
+    // group. Bun.spawn(...).unref() alone is not enough on macOS here.
+    const extraEnvStr = JSON.stringify({ BROWSE_STATE_FILE: config.stateFile, BROWSE_PARENT_PID: parentPid, ...(extraEnv || {}) });
+    const bunBin = JSON.stringify(resolveBunExecutable());
+    const launcherCode =
+      `const{spawn}=require('child_process');` +
+      `spawn(${bunBin},['run',${JSON.stringify(SERVER_SCRIPT)}],` +
+      `{detached:true,stdio:['ignore','ignore','ignore'],env:Object.assign({},process.env,` +
+      `${extraEnvStr})}).unref()`;
+    Bun.spawnSync(['node', '-e', launcherCode], { stdio: ['ignore', 'ignore', 'ignore'] });
   }
 
   // Wait for server to become healthy.
@@ -251,27 +267,16 @@ async function startServer(extraEnv?: Record<string, string>): Promise<ServerSta
     await Bun.sleep(100);
   }
 
-  // Server didn't start in time — try to get error details
-  if (proc?.stderr) {
-    // macOS/Linux: read stderr from the spawned process
-    const reader = proc.stderr.getReader();
-    const { value } = await reader.read();
-    if (value) {
-      const errText = new TextDecoder().decode(value);
-      throw new Error(`Server failed to start:\n${errText}`);
-    }
-  } else {
-    // Windows: check startup error log (server writes errors to disk since
-    // stderr is unavailable due to stdio: 'ignore' for detachment)
-    const errorLogPath = path.join(config.stateDir, 'browse-startup-error.log');
-    try {
-      const errorLog = fs.readFileSync(errorLogPath, 'utf-8').trim();
-      if (errorLog) {
-        throw new Error(`Server failed to start:\n${errorLog}`);
-      }
-    } catch (e: any) {
-      if (e.code !== 'ENOENT') throw e;
+  // Server didn't start in time — read the startup error log if the server
+  // wrote one. This works for detached launches on every platform.
+  const errorLogPath = path.join(config.stateDir, 'browse-startup-error.log');
+  try {
+    const errorLog = fs.readFileSync(errorLogPath, 'utf-8').trim();
+    if (errorLog) {
+      throw new Error(`Server failed to start:\n${errorLog}`);
     }
+  } catch (e: any) {
+    if (e.code !== 'ENOENT') throw e;
   }
   throw new Error(`Server failed to start within ${MAX_START_WAIT / 1000}s`);
 }

browse/src/server.ts

@@ -1489,6 +1489,24 @@ process.on('SIGTERM', () => {
     console.log('[browse] Received SIGTERM (ignoring — use /stop or Ctrl+C for intentional shutdown)');
   }
 });
+// Some shells send SIGHUP to background children when the launching shell exits.
+// Treat it like SIGTERM: keep headless daemons alive across CLI invocations, but
+// still allow headed/tunnel sessions to terminate with their controlling shell.
+if (process.platform !== 'win32') {
+  process.on('SIGHUP', () => {
+    if (hasActivePicker()) {
+      console.log('[browse] Received SIGHUP but cookie picker is active, ignoring to avoid stranding the picker UI');
+      return;
+    }
+    const headed = browserManager.getConnectionMode() === 'headed';
+    if (headed || tunnelActive) {
+      console.log(`[browse] Received SIGHUP in ${headed ? 'headed' : 'tunnel'} mode, shutting down`);
+      shutdown();
+    } else {
+      console.log('[browse] Received SIGHUP (ignoring — headless daemon stays alive across CLI invocations)');
+    }
+  });
+}
 // Windows: taskkill /F bypasses SIGTERM, but 'exit' fires for some shutdown paths.
 // Defense-in-depth — primary cleanup is the CLI's stale-state detection via health check.
 if (process.platform === 'win32') {

test/browse-cli-daemon.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, test } from 'bun:test';
+import { detachedServerSpawnStdio } from '../browse/src/cli';
+
+describe('browse CLI daemon lifecycle', () => {
+  test('detached server stdio is disconnected from the parent shell', () => {
+    expect(detachedServerSpawnStdio(false)).toEqual(['ignore', 'ignore', 'ignore']);
+    expect(detachedServerSpawnStdio(true)).toEqual(['ignore', 'ignore', 'ignore']);
+  });
+});