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 keeps the server fully Bun-native on POSIX by using a detached Bun spawn
instead of adding a new Node launch dependency, keeps headless daemons alive on
SIGHUP, and replaces the weak helper-only regression test with a real
multi-invocation lifecycle test against a local HTTP server.

Constraint: The fix must work with Bun-built CLI binaries on macOS without adding dependencies
Rejected: Keep using Bun.spawn(...).unref() without detached sessioning | daemon and Chromium still died after the launching shell exited
Rejected: POSIX Node launcher | fixed the symptom locally but added an unnecessary Node runtime dependency
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,13 @@ 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'];
+}
+
 // ─── State File ────────────────────────────────────────────────
 function readState(): ServerState | null {
   try {
@@ -231,9 +238,11 @@ 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
+    // POSIX: spawn the Bun server in its own detached session/process group so
+    // the daemon and Chromium survive the short-lived CLI shell.
     proc = Bun.spawn(['bun', 'run', SERVER_SCRIPT], {
-      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: true,
+      stdio: detachedServerSpawnStdio(),
       env: { ...process.env, BROWSE_STATE_FILE: config.stateFile, BROWSE_PARENT_PID: parentPid, ...extraEnv },
     });
     proc.unref();
@@ -251,27 +260,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,93 @@
+import { describe, expect, test } from 'bun:test';
+import { spawnSync } from 'child_process';
+import * as path from 'path';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const BROWSE_BIN = path.join(ROOT, 'browse', 'dist', 'browse');
+
+describe('browse CLI daemon lifecycle', () => {
+  test('reuses the same daemon across separate invocations', () => {
+    const script = `
+      set -euo pipefail
+      TMP=$(mktemp -d)
+      STATE="$TMP/browse.json"
+      PORTFILE="$TMP/port"
+      cleanup() {
+        if [ -f "$STATE" ]; then
+          PID=$(python3 - <<'PY' "$STATE"
+import json, sys
+print(json.load(open(sys.argv[1]))["pid"])
+PY
+)
+          kill "$PID" 2>/dev/null || true
+        fi
+        if [ -f "$TMP/http.pid" ]; then
+          kill "$(cat "$TMP/http.pid")" 2>/dev/null || true
+        fi
+        rm -rf "$TMP"
+      }
+      trap cleanup EXIT
+
+      python3 - <<'PY' "$PORTFILE" >/tmp/gstack-http-test.log 2>&1 &
+import http.server, socketserver, sys
+class H(http.server.BaseHTTPRequestHandler):
+    def do_GET(self):
+        self.send_response(200)
+        self.send_header('Content-Type', 'text/html; charset=utf-8')
+        self.end_headers()
+        self.wfile.write(b'<!doctype html><title>daemon test</title><h1>daemon test</h1>')
+    def log_message(self, *args):
+        pass
+with socketserver.TCPServer(('127.0.0.1', 0), H) as s:
+    open(sys.argv[1], 'w').write(str(s.server_address[1]))
+    s.serve_forever()
+PY
+      echo $! > "$TMP/http.pid"
+
+      while [ ! -f "$PORTFILE" ]; do sleep 0.1; done
+      PORT=$(cat "$PORTFILE")
+
+      cd "$TMP"
+      CI=1 BROWSE_STATE_FILE="$STATE" BROWSE_PORT=0 "${BROWSE_BIN}" goto "http://127.0.0.1:$PORT" >"$TMP/out1" 2>"$TMP/err1"
+      PID1=$(python3 - <<'PY' "$STATE"
+import json, sys
+print(json.load(open(sys.argv[1]))["pid"])
+PY
+)
+      CI=1 BROWSE_STATE_FILE="$STATE" BROWSE_PORT=0 "${BROWSE_BIN}" url >"$TMP/out2" 2>"$TMP/err2"
+      PID2=$(python3 - <<'PY' "$STATE"
+import json, sys
+print(json.load(open(sys.argv[1]))["pid"])
+PY
+)
+
+      printf 'PID1=%s\\n' "$PID1"
+      printf 'PID2=%s\\n' "$PID2"
+      printf 'ERR1=%s\\n' "$(cat "$TMP/err1")"
+      printf 'ERR2=%s\\n' "$(cat "$TMP/err2")"
+      printf 'OUT2=%s\\n' "$(cat "$TMP/out2")"
+    `;
+
+    const result = spawnSync('bash', ['-lc', script], {
+      cwd: ROOT,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 45000,
+    });
+
+    if (result.error) throw result.error;
+    expect(result.status).toBe(0);
+
+    const stdout = result.stdout;
+    expect(stdout).toContain('ERR1=[browse] Starting server...');
+    expect(stdout).toContain('ERR2=');
+    expect(stdout).not.toContain('ERR2=[browse] Starting server...');
+    expect(stdout).toMatch(/PID1=(\d+)/);
+    expect(stdout).toMatch(/PID2=(\d+)/);
+    expect(stdout).toContain('OUT2=http://127.0.0.1:');
+
+    const pid1 = stdout.match(/PID1=(\d+)/)?.[1];
+    const pid2 = stdout.match(/PID2=(\d+)/)?.[1];
+    expect(pid1).toBe(pid2);
+  }, 45_000);
+});