fix(browse): server runtime — restore off the boot path, shutdown that cannot hang, watchdog that still reaps tunnels

Four review findings on the wave's own new wiring: session restore ran
before Bun.serve with sequential 15s gotos while the CLI gives up at 8s
(one slow saved URL bricked every $B command) — restore now runs in the
background after bind; the shutdown snapshot gets a 2s deadline so a
wedged page.evaluate can't hold the port forever behind the new
ack-first stop; the persistence ticker gets in-flight + shutdown gates
and is cleared before the final snapshot; and the absorbed #2565
handoff fix no longer clears the whole parent watchdog — a suppress
flag keeps the tunnel-orphan reaper alive (handoff→resume→tunnel is no
longer an unreapable internet-exposed daemon). pair-agent with consent
off now names the real remedy instead of ngrok install instructions.
Lock-acquisition edge branches (garbage pidfile, vanish-race depth cap)
pinned.

browse/test/pair-agent-optin-gate.test.ts

@@ -95,6 +95,22 @@ describe('gate wiring — every tunnel activation point consults the guard', ()
     expect(CLI_SRC).toContain('const ngrokAvailable = pairEnabled && isNgrokAvailable();');
   });
 
+  test('CLI consent-off branch names the real remedy, never ngrok reinstall', () => {
+    // When pair_agent is off but ngrok is installed+authed, telling the user
+    // to `ngrok config add-authtoken` can never fix it — the gate is consent,
+    // not tooling. The consent branch must carry the same remedy wording as
+    // the /tunnel/start 403 body, and must not mention ngrok setup.
+    const branchAt = CLI_SRC.indexOf('} else if (!pairEnabled) {');
+    expect(branchAt).toBeGreaterThan(-1);
+    const branchEnd = CLI_SRC.indexOf('} else {', branchAt);
+    expect(branchEnd).toBeGreaterThan(branchAt);
+    const branch = CLI_SRC.slice(branchAt, branchEnd);
+    expect(branch).toContain('gstack-config set pair_agent on');
+    expect(branch).toContain('/pair-agent');
+    expect(branch).not.toContain('ngrok config add-authtoken');
+    expect(branch).not.toContain('install ngrok');
+  });
+
   test('/tunnel/start refuses with the enable hint when disabled', () => {
     const startIdx = SERVER_SRC.indexOf("url.pathname === '/tunnel/start'");
     const block = SERVER_SRC.slice(startIdx, startIdx + 1200);

browse/test/server-lock-errors.test.ts

@@ -15,6 +15,10 @@
 
 import { describe, test, expect, afterAll } from 'bun:test';
 import * as fs from 'fs';
+// Default (CJS) export — its properties are mutable in Bun, unlike the frozen
+// `* as fs` namespace, and mutations propagate to cli.ts's own fs import.
+// Used only for the depth-cap livelock simulations below (restored in finally).
+import fsMutable from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { acquireServerLock, ServerLockError } from '../src/cli';
@@ -77,4 +81,43 @@ describe('acquireServerLock (#1084 error honesty)', () => {
     expect(acquireServerLock(lockPath)).toBeNull();
     fs.unlinkSync(lockPath);
   });
+
+  test('EEXIST + garbage lockfile content: NaN pid is treated as stale, lock acquired', () => {
+    const lockPath = path.join(tmpRoot, 'garbage.lock');
+    fs.writeFileSync(lockPath, 'not-a-pid\n'); // parseInt → NaN → falsy → stale path
+    const release = acquireServerLock(lockPath);
+    expect(release).not.toBeNull();
+    // Our pid replaced the garbage — the stale lock was removed and re-acquired.
+    expect(fs.readFileSync(lockPath, 'utf8').trim()).toBe(String(process.pid));
+    release!();
+    expect(fs.existsSync(lockPath)).toBe(false);
+  });
+
+  // NOTE: the "stale lock that survives unlink" livelock variant is deliberately
+  // not simulated here — the source removes locks through safeUnlink's own fs
+  // binding, which a test-side fs monkey-patch cannot reliably intercept in Bun.
+  // The depth cap itself is exercised by the vanish-race test below.
+
+  test('depth cap: holder that vanishes between open and read returns null after 5 retries', () => {
+    // The EEXIST → readFileSync ENOENT race: the lock exists at openSync but
+    // is gone by the read (holder released in between). Repeated forever
+    // (open/release storm), the same depth cap must bound the retry loop.
+    const lockPath = path.join(tmpRoot, 'vanish.lock');
+    fs.writeFileSync(lockPath, `${process.pid}\n`);
+    const origRead = fsMutable.readFileSync;
+    try {
+      (fsMutable as any).readFileSync = (p: fs.PathLike | number, ...rest: unknown[]) => {
+        if (p === lockPath) {
+          const e: NodeJS.ErrnoException = new Error('mock: lock vanished before read');
+          e.code = 'ENOENT';
+          throw e;
+        }
+        return (origRead as any)(p, ...rest);
+      };
+      expect(acquireServerLock(lockPath)).toBeNull();
+    } finally {
+      (fsMutable as any).readFileSync = origRead;
+      fs.unlinkSync(lockPath);
+    }
+  });
 });

browse/test/watchdog.test.ts

@@ -1,8 +1,12 @@
-import { describe, test, expect, afterEach } from 'bun:test';
+import { describe, test, expect, afterEach, beforeEach, mock } from 'bun:test';
 import { spawn, type Subprocess } from 'bun';
 import * as path from 'path';
 import * as fs from 'fs';
 import * as os from 'os';
+import * as crypto from 'crypto';
+import { buildFetchHandler, __testInternals__, type ServerConfig } from '../src/server';
+import { __resetRegistry } from '../src/token-registry';
+import { resolveConfig } from '../src/config';
 
 // End-to-end regression tests for the parent-process watchdog in server.ts.
 // The watchdog has layered behavior since v0.18.1.0 (#1025) and v0.18.2.0
@@ -18,11 +22,9 @@ import * as os from 'os';
 //      eventual cleanup.
 //
 // Tunnel mode coverage (parent dies → shutdown because idle timeout doesn't
-// apply) is not covered by an automated test here — tunnelActive is a runtime
-// variable set by /pair-agent's tunnel-create flow, not an env var, so faking
-// it would require invasive test-only hooks. The mode check is documented
-// inline at the watchdog and SIGTERM handlers, and would regress visibly for
-// /pair-agent users (server lingers after disconnect).
+// apply) is covered behaviorally in the in-process suite at the bottom of this
+// file: the tick is exported via __testInternals__.parentWatchdogTick (same
+// seam as idleCheckTick) and tunnelActive is simulated via setTunnelActive.
 //
 // Each test spawns the real server.ts. Tests 1 and 2 verify behavior via
 // stdout log line (fast). Test 3 waits for the watchdog poll cycle to confirm
@@ -165,11 +167,18 @@ describe('parent-process watchdog (v0.18.1.0)', () => {
 // so the next poll shut the daemon down and discarded whatever the user had been
 // handed off to do — observed as repeated session loss mid-login.
 //
+// The fix must NOT clear the interval, though: the same tick is the
+// tunnel-orphan reaper (idle timeout is disabled in tunnel mode, so parent
+// death is the ONLY thing that reaps an internet-exposed daemon). Promotion
+// sets a suppress flag the tick re-reads each pass — "being headed" no longer
+// kills the daemon on parent death, but an active tunnel still does.
+//
 // Driving a real `handoff` needs a headed Chromium, which does not belong in the
 // free tier, so this pins the WIRING instead — the same static-tripwire approach
 // used by cdp-session-cleanup.test.ts and server-auth.test.ts. If either half of
-// the contract is dropped, the crash returns silently and these fail.
-describe('watchdog is cancelled on runtime promotion to headed', () => {
+// the contract is dropped, the crash returns silently and these fail. The
+// behavioral halves (suppression + tunnel reaping) run in-process below.
+describe('headed parent-death shutdown is suppressed on runtime promotion', () => {
   const read = (rel: string) => fs.readFileSync(path.join(ROOT, rel), 'utf-8');
 
   test('handoff() notifies the server that it promoted the daemon', () => {
@@ -181,17 +190,130 @@ describe('watchdog is cancelled on runtime promotion to headed', () => {
     expect(src.slice(promote, promote + 800)).toContain('this.onHeadedPromotion?.()');
   });
 
-  test('the server binds that callback to the watchdog canceller', () => {
+  test('the server binds that callback to the suppress-flag setter', () => {
     const src = read('src/server.ts');
-    // The timer must be reachable — `setInterval(` with its return value dropped
-    // cannot be cleared, which was the original defect.
-    expect(src).toContain('parentWatchdogTimer = setInterval(');
-    expect(src).toContain('function clearParentWatchdog()');
-    expect(src).toContain('clearInterval(parentWatchdogTimer)');
+    expect(src).toContain('function suppressHeadedParentShutdown()');
     // Bound on BOTH the module-level manager and any embedder-supplied one; the
     // watchdog reads activeBrowserManager, so binding only the default instance
     // leaves embedders (e.g. gbrowser) promoting silently.
-    expect(src).toContain('browserManager.onHeadedPromotion = clearParentWatchdog');
-    expect(src).toContain('cfgBrowserManager.onHeadedPromotion = clearParentWatchdog');
+    expect(src).toContain('browserManager.onHeadedPromotion = suppressHeadedParentShutdown');
+    expect(src).toContain('cfgBrowserManager.onHeadedPromotion = suppressHeadedParentShutdown');
+  });
+
+  test('promotion must NOT clear the interval — the tick doubles as the tunnel-orphan reaper', () => {
+    const src = read('src/server.ts');
+    // The original #2565 absorption cleared the ENTIRE interval on promotion.
+    // Sequence handoff → resume → /pair-agent tunnel then left an
+    // internet-exposed daemon that nothing reaps. The tick must stay
+    // registered and re-check the suppress flag + tunnelActive every pass.
+    expect(src).not.toContain('clearInterval(parentWatchdogTimer)');
+    expect(src).toContain('setInterval(parentWatchdogTick');
+    const tickStart = src.indexOf('function parentWatchdogTick(');
+    expect(tickStart).toBeGreaterThan(-1);
+    const tick = src.slice(tickStart, src.indexOf('\n}', tickStart));
+    expect(tick).toContain('headedParentShutdownSuppressed');
+    expect(tick).toContain('tunnelActive');
+  });
+});
+
+// ─── Behavioral: suppressed watchdog still reaps tunnel orphans ────────────
+//
+// In-process, via the same __testInternals__ seam server-factory.test.ts uses
+// for idleCheckTick. parentWatchdogTick(deadPid) simulates the 15s poll
+// discovering a dead parent; setTunnelActive simulates /pair-agent's
+// tunnel-create flow; suppressHeadedParentShutdown is exactly what the
+// handoff promotion callback invokes.
+function makeMinimalConfig(mode: 'launched' | 'headed', tmpDir: string): ServerConfig {
+  const base = resolveConfig();
+  return {
+    authToken: 'watchdog-test-' + crypto.randomBytes(16).toString('hex'),
+    browsePort: 34567,
+    idleTimeoutMs: 1_800_000,
+    // State paths pointed at a scratch dir so shutdown()'s cleanup can never
+    // touch a real daemon's files on the machine running the tests.
+    config: { ...base, stateFile: path.join(tmpDir, 'browse-state.json'), stateDir: tmpDir },
+    browserManager: {
+      getConnectionMode: () => mode,
+      isWatching: () => false,
+      stopWatch: () => {},
+      close: async () => {},
+      onDisconnect: null,
+    } as any,
+    startTime: Date.now(),
+    // Skip terminal-agent teardown: identity files live under the REAL state
+    // dir conventions and this suite must stay hermetic.
+    ownsTerminalAgent: false,
+  };
+}
+
+describe('suppressed watchdog still reaps tunnel orphans (behavioral)', () => {
+  // A PID above darwin/linux default pid_max: process.kill(pid, 0) throws
+  // ESRCH, which the tick reads as "parent exited".
+  const DEAD_PID = 999_999;
+  let scratch: string;
+  const savedChromiumProfile = process.env.CHROMIUM_PROFILE;
+
+  beforeEach(() => {
+    scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'watchdog-tick-'));
+    // shutdown() runs cleanSingletonLocks(resolveChromiumProfile()); point it
+    // at scratch so the operator's real profile is never inspected.
+    process.env.CHROMIUM_PROFILE = path.join(scratch, 'chromium-profile');
+    __resetRegistry();
+    __testInternals__.setTunnelActive(false);
+    __testInternals__.setLastActivity(Date.now());
+    __testInternals__.resetShutdownState();
+    __testInternals__.resetParentWatchdogState();
+  });
+
+  afterEach(() => {
+    if (savedChromiumProfile === undefined) delete process.env.CHROMIUM_PROFILE;
+    else process.env.CHROMIUM_PROFILE = savedChromiumProfile;
+    __testInternals__.setTunnelActive(false);
+    __testInternals__.resetShutdownState();
+    __testInternals__.resetParentWatchdogState();
+    try { fs.rmSync(scratch, { recursive: true, force: true }); } catch {}
+  });
+
+  // Drain the fire-and-forget shutdown promise chain (flushBuffers + close)
+  // the same way server-factory.test.ts does before asserting on exit.
+  async function drainShutdown(): Promise<void> {
+    await Promise.resolve();
+    await Promise.resolve();
+    await new Promise<void>((r) => setImmediate(r));
+    await new Promise<void>((r) => setImmediate(r));
+  }
+
+  test('after promotion suppression, parent death does NOT shut down a headed daemon (#2565)', async () => {
+    const exitMock = mock((_code?: number) => {});
+    const originalExit = process.exit;
+    (process as any).exit = exitMock;
+    try {
+      buildFetchHandler(makeMinimalConfig('headed', scratch));
+      __testInternals__.suppressHeadedParentShutdown(); // what handoff promotion triggers
+      __testInternals__.parentWatchdogTick(DEAD_PID);
+      await drainShutdown();
+      expect(exitMock).not.toHaveBeenCalled();
+    } finally {
+      (process as any).exit = originalExit;
+    }
+  });
+
+  test('CRITICAL: suppression active + tunnel live — parent death still shuts down', async () => {
+    const exitMock = mock((_code?: number) => {});
+    const originalExit = process.exit;
+    (process as any).exit = exitMock;
+    try {
+      buildFetchHandler(makeMinimalConfig('headed', scratch));
+      __testInternals__.suppressHeadedParentShutdown();
+      __testInternals__.setTunnelActive(true); // handoff → resume → /pair-agent tunnel
+      __testInternals__.parentWatchdogTick(DEAD_PID);
+      await drainShutdown();
+      // The tick is the ONLY reaper for tunnel orphans (idle timeout is
+      // disabled in tunnel mode). If this fails, an internet-exposed daemon
+      // outlives its parent forever.
+      expect(exitMock).toHaveBeenCalled();
+    } finally {
+      (process as any).exit = originalExit;
+    }
   });
 });