Function buildFetchHandler

browse/src/server.ts:1469–2857

(cfg: ServerConfig)

 * responsibility — embedders may fd-pass; CLI uses Bun.serve normally.
 */
export function buildFetchHandler(cfg: ServerConfig): ServerHandle {
  if (!cfg.authToken || cfg.authToken.length < 16) {
    throw new Error('buildFetchHandler: cfg.authToken must be a non-empty string >= 16 chars');
  }
  if (!cfg.browserManager) {
    throw new Error('buildFetchHandler: cfg.browserManager is required');
  }

  // Re-run init with cfg-provided values. ensureStateDir is idempotent
  // (mkdir -p); initAuditLog is idempotent (sets a module string);
  // initRegistry is idempotent for same-token, throws for different-token.
  // Owning init here (instead of at module load) means cfg.authToken is the
  // single source of truth for the registry root token.
  ensureStateDir(cfg.config);
  initAuditLog(cfg.config.auditLog);
  initRegistry(cfg.authToken);

  const { authToken, browserManager: cfgBrowserManager, startTime, beforeRoute, browsePort } = cfg;
  // Strict opt-out: only explicit `false` flips the gate. Any other value
  // (undefined, truthy non-bool from a JS caller bypassing TS, etc.) defaults
  // to gstack-owns. Matches the "default-true preserves CLI bit-for-bit"
  // premise even under malformed cfg.
  const ownsTerminalAgent = cfg.ownsTerminalAgent === false ? false : true;

  // ─── Terminal-Agent Watchdog (v1.44+) ─────────────────────────────
  //
  // The terminal-agent process can die independently of the server: SIGKILL
  // from the OS OOM killer, an uncaught exception under load, an external
  // `pkill` from a sibling debugging session. Pre-v1.44 the sidebar would
  // see the broken connection and stay broken until the user reloaded.
  // Now: 60s ticker checks the recorded agent PID, respawns via the shared
  // spawnTerminalAgent helper if dead.
  //
  // Identity-based — uses readAgentRecord + isProcessAlive, NOT a process
  // name probe. Critical: prevents respawning around a slow-but-alive agent
  // (which would create split-brain — two agents writing the port file,
  // tokens diverging between them, mystery PTY upgrade failures).
  //
  // Crash-loop guard: 3 respawn attempts inside 60s → stop trying and emit
  // a one-line error. Manual `forceRestart` from the sidebar clears the
  // history (the user is the explicit signal to retry).
  //
  // Only active when ownsTerminalAgent === true. Embedders that pre-launch
  // their own PTY server (gbrowser phoenix overlay) must not be auto-respawned
  // by us — their lifecycle is their concern.
  let agentWatchdogInterval: ReturnType<typeof setInterval> | null = null;
  const respawnHistory: number[] = [];
  const AGENT_WATCHDOG_TICK_MS = parseInt(
    process.env.GSTACK_AGENT_WATCHDOG_TICK_MS || '60000',
    10,
  );
  const RESPAWN_GUARD_WINDOW_MS = 60_000;
  const RESPAWN_GUARD_MAX = 3;
  let agentRespawnGuardTripped = false;

  if (ownsTerminalAgent) {
    agentWatchdogInterval = setInterval(() => {
      if (isShuttingDown) return;