@monoes/monobrowse 1.0.15 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monobrowse",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Native browser automation via Chrome DevTools Protocol — the engine powering monomind browse",
   "type": "module",
   "bin": {

package/src/__tests__/launch-close-settle.test.ts

@@ -0,0 +1,175 @@
+/**
+ * #314: launchMonobrowseBrowser() returned a promise that never settled on a
+ * CI runner — node:test reported `cancelledByParent` / "Promise resolution is
+ * still pending but the event loop has already resolved". Two distinct bugs
+ * in browser.ts, both fixed here, both reproduced below without a real
+ * Chrome:
+ *
+ *   1. launchOnFreePort() spawned Chrome with no 'error' listener on the
+ *      child. A spawn failure (EACCES/ENOENT — the executable existed when
+ *      findChrome()'s existsSync() checked it, then failed to actually exec)
+ *      fires Node's 'error' event asynchronously; with nothing listening,
+ *      Node throws it as an uncaught exception and the whole process goes
+ *      down, stranding launchBrowser()'s promise forever pending rather than
+ *      rejecting it. A process that execs but dies immediately (missing
+ *      shared libraries, a sandboxed container refusing it) hit the same
+ *      "poll forever, then possibly crash" shape via 'exit' instead.
+ *
+ *   2. closeBrowser()'s waitForProcessExit() polled with a deliberately
+ *      unref'd setTimeout. unref'd means the timer does not count toward
+ *      "does the event loop have anything left to do" — so once nothing else
+ *      is pinning the loop (as soon as the CDP websocket closes, which
+ *      happens right around here as Chrome shuts down), Node considers the
+ *      loop drained and exits WITHOUT ever firing that timer's callback,
+ *      leaving closeBrowser()'s promise (and its caller's) pending forever.
+ *      This is real and 100% reproducible locally with a genuine launched
+ *      Chrome and nothing else running — see the PR description for the
+ *      manual repro. vi.useFakeTimers() (used throughout close-browser.test.ts)
+ *      cannot catch this class of bug, because fake timers do not model real
+ *      event-loop-drain semantics — hence a dedicated, real-timer test here.
+ */
+
+import { spawn } from 'node:child_process';
+import { chmodSync, writeFileSync } from 'node:fs';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Minimal fake CDP websocket — enough for closeBrowser()'s Browser.close
+// round trip, without needing a real Chrome or CDP endpoint. Deliberately
+// NOT paired with vi.useFakeTimers(): the bug under test only manifests
+// against the real event loop.
+let lastSocket: FakeWs | null = null;
+
+class FakeWs {
+  handlers = new Map<string, Array<(...a: unknown[]) => void>>();
+  constructor(public url: string) {
+    lastSocket = this;
+  }
+  on(event: string, fn: (...a: unknown[]) => void): void {
+    if (!this.handlers.has(event)) this.handlers.set(event, []);
+    this.handlers.get(event)!.push(fn);
+  }
+  emit(event: string, ...args: unknown[]): void {
+    for (const fn of [...(this.handlers.get(event) ?? [])]) fn(...args);
+  }
+  send(data: string): void {
+    const { id } = JSON.parse(data) as { id: number };
+    queueMicrotask(() => this.deliver({ id, result: {} }));
+  }
+  close(): void {}
+  deliver(msg: unknown): void {
+    this.emit('message', Buffer.from(JSON.stringify(msg)));
+  }
+}
+
+vi.mock('ws', () => ({ WebSocket: FakeWs }));
+
+let tempDir: string;
+const children: Array<ReturnType<typeof spawn>> = [];
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'monobrowse-launch-close-'));
+  vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  for (const child of children.splice(0)) {
+    if (child.pid && !child.killed) {
+      try {
+        process.kill(child.pid, 'SIGKILL');
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+async function writePersistedPort(port: number, pid: number, savedAt: number): Promise<void> {
+  const dir = join(tempDir, '.monomind', 'monobrowse');
+  await mkdir(dir, { recursive: true });
+  await writeFile(
+    join(dir, 'active-port.json'),
+    JSON.stringify({ port, pid, launched: true, savedAt }),
+    'utf-8',
+  );
+}
+
+async function connectedClient() {
+  vi.resetModules();
+  const { CdpClient } = await import('../browser/cdp.js');
+  const client = new CdpClient();
+  const p = client.connect('ws://127.0.0.1:9333/devtools/page/ABC');
+  lastSocket!.emit('open');
+  await p;
+  return client;
+}
+
+describe('#314: launchBrowser settles instead of hanging when Chrome fails to start', () => {
+  it('rejects promptly (does not hang or crash the process) when the executable cannot be spawned', async () => {
+    vi.resetModules();
+    const { launchBrowser } = await import('../browser/browser.js');
+    const fake = join(tempDir, 'chrome');
+    // Exists (passes findChrome()'s existsSync check) but is not a valid
+    // executable — a real EACCES/ENOEXEC from spawn(), not a synchronous
+    // "file not found" that launchBrowser would reject before ever exec'ing.
+    writeFileSync(fake, 'not an executable\n');
+    chmodSync(fake, 0o644);
+
+    const start = Date.now();
+    await expect(
+      launchBrowser({ executablePath: fake, port: 23495, launchTimeoutMs: 3000 }),
+    ).rejects.toThrow(/Chrome failed to start on port 23495/);
+    // Without a child 'error' listener, this used to depend entirely on
+    // whether something outside this function happened to intercept the
+    // resulting uncaught exception (a bare node:test process has nothing
+    // that does — see the module doc comment); where it happened not to
+    // crash the process outright, the promise still only ever settled by
+    // burning the full launchTimeoutMs. The fix rejects as soon as the
+    // spawn error fires, so this must land in well under a second, not
+    // ride the 3000ms timeout out.
+    expect(Date.now() - start).toBeLessThan(1000);
+  }, 8000);
+
+  it('rejects with a clear message when Chrome exits immediately instead of opening its CDP port', async () => {
+    vi.resetModules();
+    const { launchBrowser } = await import('../browser/browser.js');
+    const fake = join(tempDir, 'chrome.sh');
+    writeFileSync(fake, '#!/bin/sh\nexit 1\n');
+    chmodSync(fake, 0o755);
+
+    await expect(
+      launchBrowser({ executablePath: fake, port: 23496, launchTimeoutMs: 3000 }),
+    ).rejects.toThrow(/Chrome exited before the CDP endpoint opened on port 23496/);
+  }, 8000);
+});
+
+describe('#314: closeBrowser settles under the real event loop, not fake timers', () => {
+  it('resolves promptly when nothing else is pinning the event loop', async () => {
+    vi.resetModules();
+    const { closeBrowser } = await import('../browser/browser.js');
+    const port = 23497;
+
+    // A real, short-lived child — not Chrome, just something with a genuine,
+    // observable exit so process.kill(pid, 0) behaves for real and there is
+    // no other handle (socket, ref'd timer) left to accidentally keep the
+    // event loop alive on this bug's behalf.
+    const child = spawn(process.execPath, ['-e', 'setTimeout(() => {}, 150)'], {
+      stdio: 'ignore',
+    });
+    children.push(child);
+    await writePersistedPort(port, child.pid!, Date.now());
+
+    const client = await connectedClient();
+
+    const outcome = await Promise.race([
+      closeBrowser(client, port).then(() => 'settled' as const),
+      new Promise<'timeout'>((resolve) => setTimeout(() => resolve('timeout'), 4000)),
+    ]);
+
+    expect(outcome).toBe('settled');
+  }, 8000);
+});

package/src/__tests__/report-exit-code.test.ts

@@ -0,0 +1,207 @@
+/**
+ * `monobrowse report` exited 0, and printed nothing at all, on a page that
+ * FAILED its budgets — while the report JSON it had already written on disk
+ * said `"verdict": "fail"`. Anything gating on exit status (CI, an agent, a
+ * shell `&&` chain) saw green on a broken page, which defeats the entire
+ * point of the budgets feature.
+ *
+ * Two things combined to cause it:
+ *
+ *   1. closeBrowser() could hang. Its timers were unref'd, so once Chrome's
+ *      CDP socket went away nothing was left holding the event loop open and
+ *      Node exited before those timers ever fired. (browser.ts; the poll-loop
+ *      half of this is #314's launch-close-settle.test.ts.)
+ *
+ *   2. commands-report.ts awaited that teardown in a `finally` positioned
+ *      BETWEEN producing the result and printing it. So a hung teardown took
+ *      the verdict down with it: the print never ran, `exitCode: 1` was never
+ *      returned, and Node drained the loop and exited 0.
+ *
+ * (1) alone is not enough to make this safe — any future teardown hang would
+ * silently reintroduce it. (2) is the ordering fix: print the verdict and fix
+ * process.exitCode BEFORE teardown, so a teardown that never settles can no
+ * longer turn a failing page green.
+ *
+ * WHY THIS IS A SUBPROCESS TEST. The bug only exists in the semantics of a
+ * real process exit — "the event loop drained while a promise was still
+ * pending, so Node exited with the code it had". An in-process test cannot
+ * observe that: vitest's own runner pins the event loop, so the hang simply
+ * becomes a pending promise and the exit code is never consulted. (#314's
+ * test says the same thing about fake timers.) So this spawns a real `node`
+ * and asserts the code the OS sees.
+ *
+ * WHY IT NEEDS NO CHROME. The suite is deliberately browser-free (see the
+ * monobrowse note in .github/workflows/tests.yml) and this keeps it that way.
+ * The child imports the REAL built commands-report.js, but next to stub
+ * `session.js` / `report/index.js` modules in a temp sandbox — commands-report
+ * has only those two static imports, and output.js has none, so copying three
+ * files reproduces its module graph exactly with no loader hooks and no
+ * Node-version-specific API. The stub's closeBrowser() is the hang, modelled
+ * as a promise that never settles — which is precisely what an unref'd timer
+ * on a dead socket degrades into.
+ *
+ * Requires `npm run build` (CI's monobrowse job builds before `npm test`).
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const distCli = join(here, '..', '..', 'dist', 'src', 'cli');
+const hasBuild = existsSync(join(distCli, 'commands-report.js'));
+
+let sandbox: string;
+
+beforeEach(async () => {
+  sandbox = await mkdtemp(join(tmpdir(), 'monobrowse-report-exit-'));
+});
+
+afterEach(async () => {
+  await rm(sandbox, { recursive: true, force: true });
+});
+
+/** Stub `cli/session.js`. `closeBrowser` is the failure under test. */
+function sessionStub(mode: 'hang' | 'clean'): string {
+  const close =
+    mode === 'hang'
+      ? // Never settles — a teardown that is wedged forever. An unref'd timer
+        // racing a dead socket degrades into exactly this.
+        'closeBrowser: () => new Promise(() => {}),'
+      : 'closeBrowser: async () => {},';
+  return `
+export const session = {
+  client: null, sessionId: '', targetId: '', port: 9222,
+  refs: new Map(), parentSessionId: '',
+};
+export async function ensureConnected(port) {
+  session.client = {}; session.sessionId = 'stub-session';
+  return { client: session.client, sessionId: session.sessionId };
+}
+export function print(line) { console.log(line); }
+export async function getBrowser() {
+  return {
+    // Non-undefined so the teardown branch actually runs (it is skipped for
+    // a browser this process did not launch).
+    getLaunchedPid: () => 4242,
+    stopRequestCapture: () => {},
+    teardownConsoleCapture: () => {},
+    ${close}
+    clearActivePort: async () => {},
+    clearRefCache: async () => {},
+  };
+}
+export function ensureSignalCleanupHandlers() {}
+`;
+}
+
+/** Stub `report/index.js` — a run that FAILED its budgets. */
+const reportStub = `
+const report = {
+  verdict: 'fail',
+  failures: [{ budget: 'maxConsoleErrors', expected: '<= 0', actual: 3, detail: 'boom' }],
+  notes: [],
+  trend: undefined,
+  diff: undefined,
+};
+export async function runReport() {
+  return {
+    report,
+    htmlPath: '/stub/r.html',
+    jsonPath: '/stub/r.json',
+    summary: '✗ FAIL — 1 budget failure(s)',
+    historyDir: undefined,
+    flake: undefined,
+  };
+}
+export const runReportRepeated = runReport;
+export async function readHistory() { return { dir: '/stub', runs: [] }; }
+export function toJsonReport(r) { return r; }
+`;
+
+/** Harness: mirrors cli.ts's real shape — `main().then(() => process.exit(...))`,
+ *  NOT a top-level await. That distinction is the whole bug: with a top-level
+ *  await Node notices the unsettled promise and exits 13, but cli.ts's promise
+ *  chain simply never runs its `.then`, so the loop drains and the process
+ *  exits with whatever process.exitCode holds — 0, unless someone set it. */
+const harness = `
+import { reportCommand } from './cli/commands-report.js';
+
+async function main() {
+  const result = await reportCommand.action({
+    args: ['http://127.0.0.1:1/broken.html'],
+    flags: { out: '/stub/r.html' },
+    cwd: process.cwd(),
+    interactive: false,
+  });
+  // Only reached when teardown settles. cli.ts does exactly this.
+  if (result && !result.success) process.exitCode = result.exitCode ?? 1;
+}
+
+main()
+  .then(() => { process.exit(process.exitCode ?? 0); })
+  .catch((err) => { console.error(err?.message ?? String(err)); process.exit(1); });
+`;
+
+async function runChild(mode: 'hang' | 'clean'): Promise<{
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}> {
+  await mkdir(join(sandbox, 'cli'), { recursive: true });
+  await mkdir(join(sandbox, 'report'), { recursive: true });
+  await cp(join(distCli, 'commands-report.js'), join(sandbox, 'cli', 'commands-report.js'));
+  await cp(join(distCli, 'output.js'), join(sandbox, 'cli', 'output.js'));
+  await writeFile(join(sandbox, 'cli', 'session.js'), sessionStub(mode), 'utf-8');
+  await writeFile(join(sandbox, 'report', 'index.js'), reportStub, 'utf-8');
+  await writeFile(join(sandbox, 'run.mjs'), harness, 'utf-8');
+
+  return await new Promise((resolve) => {
+    const child = spawn(process.execPath, [join(sandbox, 'run.mjs')], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: sandbox,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => (stdout += String(d)));
+    child.stderr.on('data', (d) => (stderr += String(d)));
+    // A hung teardown must still let the process EXIT (by draining), so if
+    // the child is genuinely still alive here the test should fail loudly
+    // rather than hang the suite.
+    const kill = setTimeout(() => child.kill('SIGKILL'), 15_000);
+    child.on('close', (code) => {
+      clearTimeout(kill);
+      resolve({ code, stdout, stderr });
+    });
+  });
+}
+
+describe.skipIf(!hasBuild)('report exit code survives a hung browser teardown', () => {
+  it('exits non-zero and prints the verdict even when closeBrowser never settles', async () => {
+    const { code, stdout, stderr } = await runChild('hang');
+
+    // THE BUG: this was 0 — a failing page reported as success, with the
+    // process exiting cleanly because the loop drained mid-teardown.
+    expect(code).toBe(1);
+    // ...and the verdict was never printed at all.
+    expect(stderr + stdout).toContain('FAIL');
+    expect(stdout).toContain('maxConsoleErrors');
+  }, 30_000);
+
+  it('still exits non-zero on the normal path where teardown completes', async () => {
+    const { code, stdout, stderr } = await runChild('clean');
+
+    expect(code).toBe(1);
+    expect(stderr + stdout).toContain('FAIL');
+  }, 30_000);
+});
+
+describe.skipIf(hasBuild)('report exit code subprocess test', () => {
+  it('is skipped because dist/ is not built (run `npm run build`)', () => {
+    expect(hasBuild).toBe(false);
+  });
+});

package/src/browser/actions.ts

@@ -680,18 +680,27 @@ export async function evaluateJs(
     sessionId,
   );
 
-  const result = await (timeoutMs > 0
-    ? Promise.race([
-        evalPromise,
-        new Promise<never>((_, reject) => {
-          const t = setTimeout(
-            () => reject(new Error(`JS evaluation timed out after ${timeoutMs}ms`)),
-            timeoutMs,
-          );
-          t.unref?.();
-        }),
-      ])
-    : evalPromise);
+  // Not unref'd (same rule as CdpClient.send): this timer settles the awaited
+  // race, so it has to hold the event loop open while the evaluation is in
+  // flight. Cleared in the finally so a fast evaluation does not keep the
+  // process alive for the rest of timeoutMs.
+  let evalTimer: ReturnType<typeof setTimeout> | undefined;
+  let result: Awaited<typeof evalPromise>;
+  try {
+    result = await (timeoutMs > 0
+      ? Promise.race([
+          evalPromise,
+          new Promise<never>((_, reject) => {
+            evalTimer = setTimeout(
+              () => reject(new Error(`JS evaluation timed out after ${timeoutMs}ms`)),
+              timeoutMs,
+            );
+          }),
+        ])
+      : evalPromise);
+  } finally {
+    clearTimeout(evalTimer);
+  }
 
   if (result.exceptionDetails) {
     throw new Error(

package/src/browser/bridge.ts

@@ -237,13 +237,16 @@ export class BridgeTransport implements CdpTransport {
     const envelope: BridgeEnvelope = { id, type, params };
     if (this.tabId) envelope.tabId = this.tabId;
     return new Promise<BridgeReply>((resolve, reject) => {
+      // Not unref'd (same rule as CdpClient.send): this timer settles a
+      // promise the caller awaits, so it must count toward keeping the event
+      // loop alive — otherwise a dead bridge socket lets Node exit 0 rather
+      // than surfacing the timeout. Cleared on every settle path below.
       let timer: ReturnType<typeof setTimeout> | undefined;
       if (timeoutMs > 0) {
         timer = setTimeout(() => {
           this.pending.delete(id);
           reject(new Error(`bridge ${type} timed out after ${timeoutMs}ms`));
         }, timeoutMs);
-        timer.unref?.();
       }
       this.pending.set(id, (reply) => {
         if (timer) clearTimeout(timer);

package/src/browser/browser.ts

@@ -237,6 +237,32 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
     detached: true,
     stdio: 'ignore',
   });
+
+  // Without this, a spawn failure (e.g. EACCES/ENOENT — chromePath exists per
+  // findChrome()'s existsSync check but isn't actually executable, or is
+  // removed between the check and exec) fires Node's 'error' event on the
+  // next tick. With no listener, Node throws it as an uncaught exception and
+  // the whole process goes down — which strands this function's promise
+  // forever pending rather than rejecting it (issue #314: node:test reports
+  // that as "cancelledByParent" / "still pending" because nothing here ever
+  // got the chance to settle it). Recording the failure and having the poll
+  // loop below notice it turns that crash into a normal rejection. 'exit'
+  // covers the twin case: Chrome execs fine but the process itself dies
+  // immediately (missing shared libraries, a container's sandbox refusing
+  // it, etc.) — that fires 'exit', not 'error', and without this the poll
+  // loop would just burn its whole timeout probing a port nothing will ever
+  // open on.
+  let earlyFailure: Error | null = null;
+  child.on('error', (err) => {
+    earlyFailure ??= new Error(`Chrome failed to start on port ${port}: ${err.message}`);
+  });
+  child.on('exit', (code, signal) => {
+    earlyFailure ??= new Error(
+      `Chrome exited before the CDP endpoint opened on port ${port} ` +
+        `(code=${code ?? 'null'}, signal=${signal ?? 'null'})`,
+    );
+  });
+
   child.unref();
   if (child.pid) {
     launchedPids.set(port, child.pid);
@@ -246,7 +272,9 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
   const deadline = Date.now() + launchTimeout;
   while (Date.now() < deadline) {
+    if (earlyFailure) throw earlyFailure;
     await sleep(POLL_INTERVAL);
+    if (earlyFailure) throw earlyFailure;
     if (await isPortOpen(port)) {
       if (await isChromeIdentity(port)) return port;
       throw new Error(
@@ -256,6 +284,8 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
     }
   }
 
+  if (earlyFailure) throw earlyFailure;
+
   // Timed out waiting for our Chrome to come up on the port. Distinguish
   // "nothing is listening" (real launch failure) from "something non-CDP is
   // squatting the port" (confusing generic timeout otherwise) via a raw TCP probe.
@@ -333,20 +363,30 @@ export async function connectToTarget(
  */
 export async function closeBrowser(client: CdpClient, port: number): Promise<void> {
   let gracefullyClosed = false;
+  let closeTimer: ReturnType<typeof setTimeout> | undefined;
   try {
     await Promise.race([
       client.send('Browser.close', {}),
+      // Deliberately NOT unref'd, for the same reason waitForProcessExit()'s
+      // poll below is not. This timer is the only thing that settles the race
+      // when Chrome's socket dies without ever acknowledging the close, and
+      // closeBrowser() is actively awaited by callers. An unref'd timer does
+      // not hold the event loop open, so Node would consider the loop drained
+      // and exit — status 0, before the caller's verdict was ever printed.
+      // Cleared in the finally so a close that IS acknowledged does not pin
+      // the loop for the rest of BROWSER_CLOSE_TIMEOUT_MS.
       new Promise<never>((_, reject) => {
-        const t = setTimeout(
+        closeTimer = setTimeout(
           () => reject(new Error('Browser.close timed out')),
           BROWSER_CLOSE_TIMEOUT_MS,
         );
-        t.unref?.();
       }),
     ]);
     gracefullyClosed = true;
   } catch {
     // fall through to PID-kill fallback below
+  } finally {
+    clearTimeout(closeTimer);
   }
 
   let pid = launchedPids.get(port);
@@ -403,7 +443,19 @@ export async function closeBrowser(client: CdpClient, port: number): Promise<voi
 
 /** Poll until `pid` is gone or PROCESS_EXIT_TIMEOUT_MS elapses. Returns
  *  whether it exited. `process.kill(pid, 0)` throws once the process is no
- *  longer there, on Windows as well as POSIX. */
+ *  longer there, on Windows as well as POSIX.
+ *
+ *  This timer is deliberately NOT unref'd. closeBrowser() awaits this poll
+ *  as part of its own return value — a caller that awaits closeBrowser() is
+ *  actively blocked on it, not doing other work in the background. Once
+ *  Chrome's CDP websocket closes (which happens right around here, as part
+ *  of it shutting down), nothing else may be left holding the event loop
+ *  open; an unref'd timer at that point never fires because Node considers
+ *  the loop drained and exits without running it, leaving this promise (and
+ *  closeBrowser()'s) pending forever — reproduced locally by closing a real
+ *  launched browser with nothing else scheduled. Bounded by
+ *  PROCESS_EXIT_TIMEOUT_MS (5s) either way, so keeping it ref'd only ever
+ *  costs a caller a few seconds, never a hang. */
 async function waitForProcessExit(pid: number): Promise<boolean> {
   const deadline = Date.now() + PROCESS_EXIT_TIMEOUT_MS;
   for (;;) {
@@ -414,8 +466,7 @@ async function waitForProcessExit(pid: number): Promise<boolean> {
     }
     if (Date.now() >= deadline) return false;
     await new Promise((resolve) => {
-      const t = setTimeout(resolve, PROCESS_EXIT_POLL_MS);
-      t.unref?.();
+      setTimeout(resolve, PROCESS_EXIT_POLL_MS);
     });
   }
 }
@@ -460,22 +511,27 @@ export async function reapIdleLaunchedBrowser(): Promise<number | null> {
     if ((await fetchTargets(session.port)).length > 0) return null;
 
     const client = new CdpClient();
+    let reapTimer: ReturnType<typeof setTimeout> | undefined;
     try {
       // CdpClient.connect() has no timeout of its own — a socket that never
       // opens (and never errors) would hang the launch this reap is running
       // inside of, which is strictly worse than leaving the port squatted.
+      // Not unref'd (see closeBrowser): a socket that never opens and never
+      // errors leaves this timer as the only thing that can settle the race,
+      // and the reap is awaited inside launch/attach. Cleared in the finally
+      // below so a connect that succeeds does not pin the event loop.
       await Promise.race([
         client.connect(wsUrl),
         new Promise<never>((_, reject) => {
-          const t = setTimeout(
+          reapTimer = setTimeout(
             () => reject(new Error('Reap: CDP connect timed out')),
             REAP_CONNECT_TIMEOUT_MS,
           );
-          t.unref?.();
         }),
       ]);
       await closeBrowser(client, session.port);
     } finally {
+      clearTimeout(reapTimer);
       try {
         client.close();
       } catch {

package/src/browser/cdp.ts

@@ -125,13 +125,20 @@ export class CdpClient {
       const cmd: CdpCommand = { id, method, params };
       if (sessionId) cmd.sessionId = sessionId;
 
+      // This timer is deliberately NOT unref'd. It is the backstop for the
+      // exact case described at the top of this file — a socket that dies
+      // without ever firing 'close'/'error', so flushPending() never runs.
+      // send()'s promise is awaited by essentially every caller; an unref'd
+      // timer cannot hold the event loop open, so Node would drain and exit
+      // (status 0, no output) instead of rejecting with a timeout the caller
+      // can report. Every settle path below clears it, so a command that gets
+      // its response never keeps the loop alive.
       let timer: ReturnType<typeof setTimeout> | undefined;
       if (timeoutMs > 0) {
         timer = setTimeout(() => {
           this.pendingCommands.delete(id);
           reject(new Error(`CDP command "${method}" timed out after ${timeoutMs}ms`));
         }, timeoutMs);
-        timer.unref?.();
       }
 
       this.pendingCommands.set(id, {