Function ensureServer

browse/src/cli.ts:404–502

(flags?: GlobalFlags)

}

async function ensureServer(flags?: GlobalFlags): Promise<ServerState> {
  const state = readState();
  const desiredHash = flags?.configHash;
  const extraEnv: Record<string, string> = {};
  if (flags?.proxyUrl) extraEnv.BROWSE_PROXY_URL = flags.proxyUrl;
  if (flags?.headed) extraEnv.BROWSE_HEADED = '1';
  if (desiredHash) extraEnv.BROWSE_CONFIG_HASH = desiredHash;

  // Health-check-first: HTTP is definitive proof the server is alive and responsive.
  // This replaces the PID-gated approach which breaks on Windows (Bun's process.kill
  // always throws ESRCH for Windows PIDs in compiled binaries).
  if (state && await isServerHealthy(state.port)) {
    // D2 daemon-mismatch check: existing daemon's configHash must match the
    // CLI's resolved hash. If --proxy or --headed are passed and the existing
    // daemon was started with different config, refuse with a `disconnect`
    // hint. No silent restart — that would drop tab state, cookies, and
    // logged-in sessions without warning.
    if (desiredHash && state.configHash && state.configHash !== desiredHash) {
      console.error(`[browse] existing daemon has different config (proxy/headed mismatch).`);
      console.error(`[browse] run 'browse disconnect' first to apply --proxy/--headed.`);
      process.exit(1);
    }
    // Same path: existing daemon is plain (no flags) but caller passes
    // --proxy/--headed. Refuse for the same reason — apply explicitly via
    // disconnect+reconnect.
    if (desiredHash && !state.configHash && (flags?.proxyUrl || flags?.headed)) {
      console.error(`[browse] existing daemon was started without --proxy/--headed.`);
      console.error(`[browse] run 'browse disconnect' first to apply new flags.`);
      process.exit(1);
    }

    // Check for binary version mismatch (auto-restart on update)
    const currentVersion = readVersionHash();
    if (currentVersion && state.binaryVersion && currentVersion !== state.binaryVersion) {
      console.error('[browse] Binary updated, restarting server...');
      await killServer(state.pid);
      return startServer(extraEnv);
    }
    return state;
  }

  // BROWSE_NO_AUTOSTART: sidebar agent sets this so the child claude never
  // spawns an invisible headless browser. If the headed server is down,
  // fail fast with a clear error instead of silently starting a new one.
  if (process.env.BROWSE_NO_AUTOSTART === '1') {
    console.error('[browse] Server not available and BROWSE_NO_AUTOSTART is set.');
    console.error('[browse] The headed browser may have been closed. Run /open-gstack-browser to restart.');
    process.exit(1);
  }

  // Guard: never silently replace a headed server with a headless one.
  // Headed mode means a user-visible Chrome window is (or was) controlled.
  // Silently replacing it would be confusing — tell the user to reconnect.
  if (state && state.mode === 'headed' && isProcessAlive(state.pid)) {
    console.error(`[browse] Headed server running (PID ${state.pid}) but not responding.`);
    console.error(`[browse] Run '/open-gstack-browser' to restart.`);
    process.exit(1);
  }