@monoes/monobrowse 1.0.16 → 1.0.19

package/src/browser/browser.ts

@@ -1,5 +1,5 @@
 import { execSync, spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { connect } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -128,9 +128,17 @@ const LAUNCH_PORT_SCAN_TRIES = 10;
 
 export async function launchBrowser(config: BrowserConfig = {}): Promise<number> {
   const rawPort = config.port ?? DEFAULT_PORT;
-  // Validate port is in a safe range for localhost CDP debugging
-  if (!Number.isInteger(rawPort) || rawPort < 1024 || rawPort > 65535) {
-    throw new Error(`Invalid port: ${rawPort}. Must be an integer between 1024 and 65535.`);
+  // Port 0 means "let Chrome bind a free port and tell us which" — see
+  // launchOnFreePort. Otherwise validate port is in a safe range for
+  // localhost CDP debugging.
+  if (rawPort === 0) {
+    if (!config.userDataDir) {
+      throw new Error(
+        'port 0 requires a dedicated userDataDir (Chrome reports the port it bound inside it).',
+      );
+    }
+  } else if (!Number.isInteger(rawPort) || rawPort < 1024 || rawPort > 65535) {
+    throw new Error(`Invalid port: ${rawPort}. Must be 0 or an integer between 1024 and 65535.`);
   }
 
   // Every launch/attach is this tool's only chance to notice that a previous
@@ -139,6 +147,8 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
   // instance on the port we are about to use is freed before we probe it.
   await reapIdleLaunchedBrowser();
 
+  if (rawPort === 0) return launchOnFreePort(config, 0);
+
   // strictPort: fail fast on the exact requested port, matching the old
   // behavior (Vite has the same escape hatch for the same reason) — for
   // callers that treat the error as a signal ("this port is taken by
@@ -158,19 +168,7 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
   for (let i = 0; i < LAUNCH_PORT_SCAN_TRIES && rawPort + i <= 65535; i++)
     candidates.push(rawPort + i);
 
-  // Attach-if-already-Chrome only applies to the EXACT requested port — the
-  // original, deliberate, single-port risk ("don't silently take over an
-  // unrelated real browser that happens to be on this port"). Scanning past
-  // an occupied default must not let that same shortcut attach to a
-  // DIFFERENT Chrome instance the caller never named; forward candidates are
-  // launch-only (skip if anything is there, Chrome or not).
-  if (await isTcpPortOpen(rawPort)) {
-    if (await isChromeIdentity(rawPort)) return rawPort;
-  } else {
-    return launchOnFreePort(config, rawPort);
-  }
-
-  for (const candidate of candidates.slice(1)) {
+  for (const candidate of candidates) {
     // TCP-level check for "is anything at all listening" — isPortOpen()
     // does a full CDP /json fetch, which returns false BOTH for a genuinely
     // free port and for one occupied by a non-CDP process (that ambiguity is
@@ -179,10 +177,39 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
     // socket first tells free and occupied apart up front, so the scan can
     // skip an occupied candidate instead of trying to spawn Chrome on top of
     // it and only discovering the conflict after a timeout.
-    if (!(await isTcpPortOpen(candidate))) return launchOnFreePort(config, candidate);
-    // Occupied (by anything — not just non-Chrome, per the note above) —
-    // try the next candidate instead of failing outright, same as a normal
-    // EADDRINUSE retry would.
+    if (await isTcpPortOpen(candidate)) {
+      // Attach-if-already-Chrome only applies to the EXACT requested port —
+      // the original, deliberate, single-port risk ("don't silently take
+      // over an unrelated real browser that happens to be on this port").
+      // Scanning past an occupied default must not let that same shortcut
+      // attach to a DIFFERENT Chrome instance the caller never named;
+      // forward candidates are launch-only (skip if anything is there,
+      // Chrome or not).
+      if (candidate === rawPort && (await isChromeIdentity(candidate))) return candidate;
+      // Occupied (by anything — not just non-Chrome, per the note above) —
+      // try the next candidate instead of failing outright, same as a
+      // normal EADDRINUSE retry would.
+      continue;
+    }
+    try {
+      return await launchOnFreePort(config, candidate);
+    } catch (err) {
+      const isLastCandidate = candidate === candidates[candidates.length - 1];
+      // isTcpPortOpen() above is a connect() probe, not an atomic claim: two
+      // concurrent launchBrowser() calls with no explicit --port can both
+      // observe the same candidate as free and both spawn Chrome on it
+      // before either binds. One wins; the other's Chrome exits before its
+      // CDP endpoint opens ("Chrome exited before the CDP endpoint opened
+      // ... code=21"). Something is listening on the candidate NOW that
+      // was not a moment ago — a losing race, not a broken Chrome install —
+      // so try the next candidate exactly like an already-occupied one,
+      // instead of failing the whole launch outright. A candidate that
+      // fails with nothing now listening (a real launch failure — bad
+      // executable, sandbox refusal, etc.) is not a race: retrying the
+      // next candidate would only fail the same way, so surface it as-is.
+      if (!isLastCandidate && (await isTcpPortOpen(candidate))) continue;
+      throw err;
+    }
   }
   throw new Error(
     `Ports ${candidates[0]}-${candidates[candidates.length - 1]} are all occupied and port ${candidates[0]} ` +
@@ -190,9 +217,50 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
   );
 }
 
+/** The port Chrome wrote to `<userDataDir>/DevToolsActivePort` once its
+ *  DevTools server was listening, or null if it has not (yet). */
+function readDevToolsActivePort(file: string): number | null {
+  try {
+    const port = Number.parseInt(readFileSync(file, 'utf8').split('\n')[0], 10);
+    return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Spawn Chrome and wait for its CDP endpoint.
+ *
+ * With a fixed `port`, "our Chrome is up" is inferred from *some* Chrome
+ * answering on 127.0.0.1:<port> — which is not necessarily ours. When the port
+ * is already bound on 127.0.0.1 (a concurrent launch picked the same "free"
+ * port between its probe and Chrome's bind), Chrome does not fail: it logs
+ * `bind() failed: Address already in use` and listens on [::1]:<port>
+ * instead. The poll then accepts the OTHER launcher's browser, both callers
+ * drive one Chrome, and whichever closes first kills the other's connections
+ * ("CDP connection closed") while this launch's own Chrome is orphaned.
+ *
+ * `port: 0` removes the race instead of narrowing it: Chrome asks the kernel
+ * for a free port at bind time — atomic, nothing to collide on — and writes
+ * the port it got to DevToolsActivePort in its own (caller-dedicated) profile
+ * directory, which is proof the endpoint is the process we spawned.
+ */
 async function launchOnFreePort(config: BrowserConfig, port: number): Promise<number> {
   const chromePath = findChrome(config.executablePath);
-  const userDataDir = config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}`);
+  // Suffixed with our own pid: two concurrent launches that both probe the
+  // same candidate port as free (the race this function exists to survive —
+  // see the retry-on-collision caller above) briefly run Chrome with
+  // *identical* --user-data-dir values if it were derived from the port
+  // alone, sharing a profile directory (lock files, preferences, the
+  // DevToolsActivePort file itself) between two unrelated Chrome processes
+  // for as long as the loser stays alive. Different processes always have
+  // different pids, so this can never collide even when the port does.
+  const userDataDir =
+    config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}-${process.pid}`);
+  const activePortFile = join(userDataDir, 'DevToolsActivePort');
+  // A reused profile dir may hold a previous run's file naming a port some
+  // other process now owns.
+  if (port === 0) rmSync(activePortFile, { force: true });
 
   const defaultArgs = [
     `--remote-debugging-port=${port}`,
@@ -264,10 +332,21 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   });
 
   child.unref();
-  if (child.pid) {
-    launchedPids.set(port, child.pid);
-    launchedUserDataDirs.set(port, userDataDir);
-  }
+  const track = (boundPort: number) => {
+    if (!child.pid) return;
+    launchedPids.set(boundPort, child.pid);
+    launchedUserDataDirs.set(boundPort, userDataDir);
+  };
+  // Tracked only once Chrome is CONFIRMED up on `boundPort`, not right after
+  // spawn(). For port !== 0 this used to track(port) unconditionally the
+  // moment the child was spawned, before knowing whether it would actually
+  // win the port — when a racing launchBrowser() call retries a candidate
+  // that a concurrent process also spawned Chrome on (see the retry loop in
+  // launchBrowser), BOTH child processes called track() for the SAME
+  // candidate, and whichever call's spawn happened to run last clobbered the
+  // map entry with its own pid — including the LOSING, about-to-exit
+  // process's pid overwriting the real winner's, corrupting the very map
+  // closeBrowser()'s kill fallback depends on.
 
   const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
   const deadline = Date.now() + launchTimeout;
@@ -275,17 +354,34 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
     if (earlyFailure) throw earlyFailure;
     await sleep(POLL_INTERVAL);
     if (earlyFailure) throw earlyFailure;
-    if (await isPortOpen(port)) {
-      if (await isChromeIdentity(port)) return port;
+    const boundPort = port === 0 ? readDevToolsActivePort(activePortFile) : port;
+    if (boundPort !== null && (await isPortOpen(boundPort))) {
+      if (await isChromeIdentity(boundPort)) {
+        track(boundPort);
+        return boundPort;
+      }
       throw new Error(
-        `Port ${port} is occupied by a CDP-speaking process that does not identify as Chrome/Chromium. ` +
-          `Refusing to attach — pass a different port or free port ${port}.`,
+        `Port ${boundPort} is occupied by a CDP-speaking process that does not identify as Chrome/Chromium. ` +
+          `Refusing to attach — pass a different port or free port ${boundPort}.`,
       );
     }
   }
 
   if (earlyFailure) throw earlyFailure;
 
+  if (port === 0) {
+    // Not tracked under any port yet, so no closeBrowser() could ever reach
+    // it — stop it here rather than leave it running.
+    try {
+      if (child.pid) process.kill(child.pid, 'SIGKILL');
+    } catch {
+      /* already gone */
+    }
+    throw new Error(
+      `Chrome did not report a CDP port in ${activePortFile} within ${launchTimeout}ms`,
+    );
+  }
+
   // 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.
@@ -363,20 +459,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);
@@ -501,22 +607,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, {

package/src/browser/types.ts

@@ -1,4 +1,6 @@
 export interface BrowserConfig {
+  /** CDP port. 0 lets Chrome bind a free one (requires `userDataDir`); the
+   *  port it bound is launchBrowser's return value. */
   port?: number;
   /** Fail fast if `port` is occupied by anything other than an attachable
    *  Chrome, instead of scanning forward to the next free port. Default false

package/src/cli/commands-report.ts

@@ -186,6 +186,34 @@ export const reportCommand: Command = {
       trendWindow: ctx.flags['trend-window'] as number | undefined,
     };
 
+    // Closing the browser is cleanup, not part of the verdict. It used to run
+    // in a `finally` sitting between "we have the result" and "we print it",
+    // which meant anything that wedged the teardown — a Chrome that never
+    // acknowledged `Browser.close`, a CDP socket that died silently — took the
+    // verdict down with it: no output at all, and exit 0 on a page that FAILED
+    // its budgets. That is exactly the signal CI, agents and `&&` chains gate
+    // on, so a hung teardown reported success on a broken page. The verdict is
+    // now printed and the exit code fixed BEFORE any of this runs.
+    const teardown = async (): Promise<void> => {
+      // A report is a one-shot command — CI should not be left with an
+      // orphan Chrome. Only close a browser THIS process launched: an
+      // attached one belongs to the user's own `open`/`connect` session.
+      if (ctx.flags['keep-open'] || browser.getLaunchedPid(session.port) === undefined) return;
+      browser.stopRequestCapture(sessionId);
+      browser.teardownConsoleCapture(sessionId);
+      try {
+        await browser.closeBrowser(client, session.port);
+      } catch {
+        /* best-effort */
+      }
+      session.client = null;
+      session.sessionId = '';
+      session.targetId = '';
+      session.refs = new Map();
+      await browser.clearActivePort();
+      await browser.clearRefCache();
+    };
+
     let result:
       | Awaited<ReturnType<typeof runReport>>
       | Awaited<ReturnType<typeof runReportRepeated>>;
@@ -193,25 +221,11 @@ export const reportCommand: Command = {
       result = repeat
         ? await runReportRepeated(client, sessionId, { ...runOptions, repeat })
         : await runReport(client, sessionId, runOptions);
-    } finally {
-      // A report is a one-shot command — CI should not be left with an
-      // orphan Chrome. Only close a browser THIS process launched: an
-      // attached one belongs to the user's own `open`/`connect` session.
-      if (!ctx.flags['keep-open'] && browser.getLaunchedPid(session.port) !== undefined) {
-        browser.stopRequestCapture(sessionId);
-        browser.teardownConsoleCapture(sessionId);
-        try {
-          await browser.closeBrowser(client, session.port);
-        } catch {
-          /* best-effort */
-        }
-        session.client = null;
-        session.sessionId = '';
-        session.targetId = '';
-        session.refs = new Map();
-        await browser.clearActivePort();
-        await browser.clearRefCache();
-      }
+    } catch (err) {
+      // No verdict to print on this path, so the old ordering still applies:
+      // clean up, then let the error propagate to the CLI's error handler.
+      await teardown();
+      throw err;
     }
 
     const { report, htmlPath, jsonPath, summary, historyDir } = result;
@@ -220,6 +234,15 @@ export const reportCommand: Command = {
     // runs must not exit 0 just because the last run happened to be green.
     const passed = flake ? flake.verdict === 'pass' : report.verdict === 'pass';
 
+    // Set the process-wide failure code up front, before printing and before
+    // teardown. Returning `exitCode` below is the normal channel, but it only
+    // reaches the CLI if this function returns; if teardown never settles,
+    // Node drains the event loop and exits on its own — and a natural exit
+    // uses process.exitCode. Setting it here means a failing page cannot exit
+    // 0 no matter what happens after this line. Only ever set on failure, so
+    // this never clears a non-zero code set elsewhere.
+    if (!passed) process.exitCode = 1;
+
     if (ctx.flags.json) {
       const { toJsonReport } = await import('../report/index.js');
       print(
@@ -265,6 +288,10 @@ export const reportCommand: Command = {
       if (historyDir) print(`History: ${historyDir}`);
     }
 
+    // Verdict is printed and the exit code is fixed — only now is it safe to
+    // close the browser.
+    await teardown();
+
     // Non-zero exit is the point of RIG-06 — CI and agents gate on it.
     return {
       success: passed,

package/src/report/util.ts

@@ -3,10 +3,13 @@
 /** Budget for one non-navigation collector (AX tree, screenshot, eval). */
 export const STEP_TIMEOUT_MS = 15_000;
 
+/** Not unref'd: callers `await sleep(...)` (e.g. the web-vitals settle
+ *  window), so this timer is on an actively-awaited path. An unref'd timer
+ *  does not keep the event loop alive, so once the CDP socket closes Node
+ *  would drain and exit mid-report instead of resuming after the sleep. */
 export function sleep(ms: number): Promise<void> {
   return new Promise((r) => {
-    const t = setTimeout(r, ms);
-    t.unref?.();
+    setTimeout(r, ms);
   });
 }
 
@@ -23,9 +26,12 @@ export async function withTimeout<T>(promise: Promise<T>, ms: number, label: str
   try {
     return await Promise.race([
       promise,
+      // Not unref'd: this timer is the only thing that settles the race when
+      // `promise` is waiting on a socket that quietly went away, and every
+      // caller awaits the result. The finally below clears it, so work that
+      // finishes in time never holds the event loop open.
       new Promise<never>((_, reject) => {
         timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
-        timer.unref?.();
       }),
     ]);
   } finally {