Function startServer

browse/src/cli.ts:295–373

(extraEnv?: Record<string, string>)

// ─── Server Lifecycle ──────────────────────────────────────────
async function startServer(extraEnv?: Record<string, string>): Promise<ServerState> {
  ensureStateDir(config);

  // Clean up stale state file and error log
  safeUnlink(config.stateFile);
  safeUnlink(path.join(config.stateDir, 'browse-startup-error.log'));

  // #1781: clear a stale Chromium profile lock (and kill the orphan still
  // holding it) before launch, so an auto-restart after an abrupt kill isn't
  // blocked by the previous Chromium's SingletonLock — the self-inflicted
  // crash-loop. Previously only the manual connect preamble did this.
  await killOrphanChromium();
  cleanChromiumProfileLocks();

  // Allow the caller to opt out of the parent-process watchdog by setting
  // BROWSE_PARENT_PID=0 in the environment. Useful for CI, non-interactive
  // shells, and short-lived Bash invocations that need the server to outlive
  // the spawning CLI. Defaults to the current process PID (watchdog active).
  // Parse as int so stray whitespace ("0\n") still opts out — matches the
  // server's own parseInt at server.ts:760.
  const parentPid = parseInt(process.env.BROWSE_PARENT_PID || '', 10) === 0 ? '0' : String(process.pid);

  if (IS_WINDOWS && NODE_SERVER_SCRIPT) {
    // Windows: Bun.spawn() + proc.unref() doesn't truly detach on Windows —
    // when the CLI exits, the server dies with it. Use Node's child_process.spawn
    // with { detached: true } instead, which is the gold standard for Windows
    // process independence. Credit: PR #191 by @fqueiro.
    const extraEnvStr = JSON.stringify({ BROWSE_STATE_FILE: config.stateFile, BROWSE_PARENT_PID: parentPid, ...(extraEnv || {}) });
    const launcherCode =
      `const{spawn}=require('child_process');` +
      `spawn(process.execPath,[${JSON.stringify(NODE_SERVER_SCRIPT)}],` +
      `{detached:true,stdio:['ignore','ignore','ignore'],env:Object.assign({},process.env,` +
      `${extraEnvStr})}).unref()`;
    Bun.spawnSync(['node', '-e', launcherCode], { stdio: ['ignore', 'ignore', 'ignore'] });
  } else {
    // macOS/Linux: Bun.spawn().unref() only removes the child from Bun's event
    // loop — it does NOT call setsid(), so the spawned server stays in the
    // parent's process session. When the CLI runs inside a session-managed
    // shell (e.g. Claude Code's per-command Bash sandbox, Conductor, CI
    // step runners), the session leader's exit sends SIGHUP to every PID in
    // the session, killing the bun server (and its Chromium grandchildren).
    // Even with BROWSE_PARENT_PID=0 disabling the watchdog, SIGHUP still
    // reaps the server. Use Node's child_process.spawn with detached:true,
    // which calls setsid() so the server becomes its own session leader
    // (PPID=1, STAT=Ss) and survives the spawning shell's exit. Mirrors
    // the Windows path's rationale — same root cause, different OS API.
    nodeSpawn('bun', ['run', SERVER_SCRIPT], {
      detached: true,
      stdio: ['ignore', 'ignore', 'ignore'],
      env: { ...process.env, BROWSE_STATE_FILE: config.stateFile, BROWSE_PARENT_PID: parentPid, ...extraEnv },
    }).unref();
  }

  // Wait for server to become healthy.
  // Use HTTP health check (not isProcessAlive) — it's fast (~instant ECONNREFUSED)
  // and works reliably on all platforms including Windows.
  const start = Date.now();
  while (Date.now() - start < MAX_START_WAIT) {