@monoes/monobrowse 1.0.26 → 1.0.28

package/src/browser/browser.ts

@@ -1,917 +1,21 @@
-import { execSync, spawn } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
-import { existsSync, readFileSync, rmSync } from 'node:fs';
-import { connect } from 'node:net';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { CdpClient, fetchNewTarget, fetchTargets } from './cdp.js';
-import { enableConsoleCapture, setupConsoleCapture } from './console-log.js';
-import { setupDialogAutoHandling } from './dialog.js';
-import {
-  listSessionRecords,
-  loadSessionRecord,
-  removeSessionRecord,
-  type SessionRecord,
-} from './ref-cache.js';
-import type { BrowserConfig, CdpTarget } from './types.js';
-import { CHROME_EXECUTABLES } from './types.js';
-
-const DEFAULT_PORT = 9222;
-const LAUNCH_TIMEOUT = 10_000;
-const POLL_INTERVAL = 200;
-const BROWSER_CLOSE_TIMEOUT_MS = 3000;
-// How long closeBrowser() waits for the process to actually disappear before
-// forcing it, and again after forcing. Bounded so a wedged Chrome cannot hang
-// a caller indefinitely.
-const PROCESS_EXIT_TIMEOUT_MS = 5000;
-const PROCESS_EXIT_POLL_MS = 50;
-// A cross-process persisted PID older than this is not trusted for the
-// SIGKILL fallback in closeBrowser() — see the call site for why.
-const PERSISTED_PID_MAX_AGE_MS = 24 * 60 * 60 * 1000;
-// A browser WE launched that has had no targets for longer than this is
-// reaped at the next launch/attach — see reapIdleLaunchedBrowser().
-const IDLE_REAP_AFTER_MS = 30 * 60 * 1000;
-const REAP_CONNECT_TIMEOUT_MS = 3000;
-
-// Tracks the PID of Chrome instances *we* spawned, keyed by CDP port, so
-// closeBrowser() has a kill fallback when the graceful `Browser.close` CDP
-// command fails or times out (e.g. a hung renderer). Ports we merely attached
-// to (already-running browser) are never recorded here — we only ever kill
-// processes we launched ourselves.
-const launchedPids = new Map<number, number>();
-// userDataDir per launched port — informational, persisted alongside the pid
-// so a later process could clean up the temp profile dir too if ever needed.
-const launchedUserDataDirs = new Map<number, string>();
-
-/** PID of the Chrome instance *this process* launched on `port`, if any. */
-export function getLaunchedPid(port: number): number | undefined {
-  return launchedPids.get(port);
-}
-
-/** userDataDir of the Chrome instance *this process* launched on `port`, if any. */
-export function getLaunchedUserDataDir(port: number): string | undefined {
-  return launchedUserDataDirs.get(port);
-}
-
-function findChrome(executablePath?: string): string {
-  if (executablePath) {
-    if (existsSync(executablePath)) return executablePath;
-    throw new Error(`Chrome executable not found: ${executablePath}`);
-  }
-  for (const candidate of CHROME_EXECUTABLES) {
-    if (existsSync(candidate)) return candidate;
-  }
-  // Try PATH
-  try {
-    const result = execSync(
-      'which google-chrome chromium-browser chromium microsoft-edge microsoft-edge-stable 2>/dev/null',
-      { encoding: 'utf8' },
-    ).trim();
-    const first = result.split('\n')[0];
-    if (first) return first;
-  } catch {
-    // ignore
-  }
-  throw new Error(
-    'No supported browser found. Install Google Chrome, Microsoft Edge, or Chromium — or pass executablePath in BrowserConfig.',
-  );
-}
-
-export async function isPortOpen(port: number): Promise<boolean> {
-  try {
-    await fetchTargets(port);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Confirm the CDP endpoint on `port` actually identifies as Chrome/Chromium
- * via `/json/version`'s `Browser` field, rather than assuming any CDP-speaking
- * responder is "ours". Reduces (does not eliminate) the risk of silently
- * attaching to an unrelated real browser that happens to be listening there.
- */
-async function isChromeIdentity(port: number): Promise<boolean> {
-  return (await chromeIdentity(port)) === 'chrome';
-}
-
-/** isChromeIdentity, telling "answered as something else" apart from "did
- *  not answer in time" ('unknown': a timeout, a refused or reset connection,
- *  a non-OK status or an unparseable body). */
-async function chromeIdentity(port: number): Promise<'chrome' | 'other' | 'unknown'> {
-  try {
-    const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
-      signal: AbortSignal.timeout(1000),
-    });
-    if (!res.ok) return 'unknown';
-    const info = (await res.json()) as { Browser?: string };
-    // Edge's Browser field is "Edg/<version>" with no "chrome"/"chromium"
-    // substring, even though it's Chromium-based and CDP-compatible —
-    // accept it alongside Chrome/Chromium rather than rejecting a valid target.
-    return typeof info.Browser === 'string' && /chrom(e|ium)|edg/i.test(info.Browser)
-      ? 'chrome'
-      : 'other';
-  } catch {
-    return 'unknown';
-  }
-}
-
-/** Raw TCP connect probe — distinguishes "nothing listening" from "something listening that isn't CDP". */
-function isTcpPortOpen(port: number, timeoutMs = 1000): Promise<boolean> {
-  return new Promise((resolve) => {
-    const socket = connect({ host: '127.0.0.1', port, timeout: timeoutMs });
-    const done = (result: boolean) => {
-      socket.removeAllListeners();
-      socket.destroy();
-      resolve(result);
-    };
-    socket.once('connect', () => done(true));
-    socket.once('timeout', () => done(false));
-    socket.once('error', () => done(false));
-  });
-}
-
-/** Ports scanned when the requested one is occupied by a non-Chrome process
- *  (e.g. another local tool that happens to reuse Chrome's conventional CDP
- *  default, 9222 — mirrors the auto-increment convention this monorepo's own
- *  dashboard server uses in bindServer/server.mjs). Only occupied-by-a-
- *  DIFFERENT-process is worked around; an already-attachable Chrome on the
- *  requested port is still returned as-is (existing "attach, don't relaunch"
- *  behavior). */
-const LAUNCH_PORT_SCAN_TRIES = 10;
-
-export async function launchBrowser(config: BrowserConfig = {}): Promise<number> {
-  const rawPort = config.port ?? DEFAULT_PORT;
-  // 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
-  // session abandoned a browser on a CDP port and never gave it back — there
-  // is no daemon to do it on a timer. Bounded and non-throwing; a stale
-  // 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
-  // something else, bail") rather than consuming the returned port.
-  if (config.strictPort) {
-    if (await isTcpPortOpen(rawPort)) {
-      if (await isChromeIdentity(rawPort)) return rawPort;
-      throw new Error(
-        `Port ${rawPort} is occupied by a process that does not identify as Chrome/Chromium. ` +
-          `Refusing to attach — pass a different port or free port ${rawPort}.`,
-      );
-    }
-    return launchOnFreePort(config, rawPort);
-  }
-
-  const candidates: number[] = [];
-  for (let i = 0; i < LAUNCH_PORT_SCAN_TRIES && rawPort + i <= 65535; i++)
-    candidates.push(rawPort + i);
-
-  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
-    // exactly what the post-spawn isTcpPortOpen fallback below exists to
-    // resolve, the hard way, after a 10s launch timeout). Checking the raw
-    // 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)) {
-      // 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]} ` +
-      `isn't a Chrome/Chromium instance to attach to. Pass a different --port.`,
-  );
-}
-
-/** 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.
- *
- * A fixed port needs its own proof, since Chrome writes DevToolsActivePort
- * only for port 0. Once listening, Chrome prints `DevTools listening on
- * ws://…/devtools/browser/<id>` to stderr, and `<id>` is unique to that
- * browser process, the same one `/json/version` reports. An endpoint is
- * adopted only when it reports the id our own child printed. Without that
- * check, a launch whose Chrome was still booting found a concurrent
- * launch's Chrome on the shared port and returned it, recording its own
- * doomed pid there. It also covers Chrome's [::1] fallback described above.
- */
-async function launchOnFreePort(config: BrowserConfig, port: number): Promise<number> {
-  const chromePath = findChrome(config.executablePath);
-  // Unique per launch, not just per port and 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) would
-  // otherwise share one profile directory (lock files, preferences, the
-  // DevToolsActivePort file itself) — including two launches from the same
-  // process, where a pid suffix alone is identical.
-  const userDataDir =
-    config.userDataDir ??
-    join(tmpdir(), `monomind-browser-${port}-${process.pid}-${randomUUID().slice(0, 8)}`);
-  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}`,
-    `--user-data-dir=${userDataDir}`,
-    '--no-first-run',
-    '--no-default-browser-check',
-    '--disable-background-networking',
-    '--disable-client-side-phishing-detection',
-    '--disable-default-apps',
-    '--disable-extensions',
-    '--disable-hang-monitor',
-    '--disable-popup-blocking',
-    '--disable-prompt-on-repost',
-    '--disable-sync',
-    '--disable-translate',
-    '--metrics-recording-only',
-    '--safebrowsing-disable-auto-update',
-    '--password-store=basic',
-    '--use-mock-keychain',
-  ];
-
-  if (config.headless !== false) {
-    defaultArgs.push('--headless=new');
-  }
-
-  // Chrome's setuid sandbox cannot initialise on most CI runners and
-  // containers, so the process dies during startup and the CDP endpoint never
-  // opens. The launch below then burns its whole timeout before reporting a
-  // generic failure, which reads as a hang rather than "Chrome could not
-  // start". Disabling the sandbox is the standard remedy and is scoped to CI
-  // so a real user's browser keeps it. --disable-dev-shm-usage goes with it:
-  // a container's default /dev/shm is 64MB, which Chrome exhausts and then
-  // crashes the same way.
-  if (process.env.CI) {
-    defaultArgs.push('--no-sandbox', '--disable-dev-shm-usage');
-  }
-
-  // Cap caller-supplied args to prevent memory exhaustion via huge argument arrays
-  const callerArgs = (config.args ?? []).slice(0, 50);
-  const args = [...defaultArgs, ...callerArgs];
-  const child = spawn(chromePath, args, {
-    detached: true,
-    // stderr carries the fixed-port ownership proof (see above). The pipe is
-    // closed as soon as this launch settles, so a Chrome that outlives us
-    // never blocks writing to it.
-    stdio: port === 0 ? 'ignore' : ['ignore', 'ignore', 'pipe'],
-  });
-  let announcedBrowserId: string | null = null;
-  if (child.stderr) {
-    let stderrTail = '';
-    child.stderr.setEncoding('utf8');
-    child.stderr.on('data', (chunk: string) => {
-      if (announcedBrowserId) return;
-      stderrTail = (stderrTail + chunk).slice(-4096);
-      announcedBrowserId = browserIdOf(
-        /DevTools listening on (ws:\/\/\S+)\r?\n/.exec(stderrTail)?.[1],
-      );
-    });
-    child.stderr.on('error', () => {
-      /* closed under us — nothing to read */
-    });
-  }
-
-  // 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();
-  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.
-
-  // A refused or timed-out launch is not tracked under any port, so no
-  // closeBrowser() could ever reach it — stop it rather than leave it
-  // running.
-  const killUntracked = () => {
-    try {
-      if (child.pid) process.kill(child.pid, 'SIGKILL');
-    } catch {
-      /* already gone */
-    }
-  };
-
-  // Our own Chrome, not just some Chrome, is serving `boundPort`. For port 0
-  // the port came from our own profile's DevToolsActivePort, so it is.
-  const isOwnEndpoint = async (boundPort: number): Promise<boolean> => {
-    if (port === 0) return true;
-    if (!announcedBrowserId) return false;
-    const wsUrl = await fetchBrowserWebSocketUrl(boundPort).catch(() => null);
-    return browserIdOf(wsUrl ?? undefined) === announcedBrowserId;
-  };
-
-  const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
-  const deadline = Date.now() + launchTimeout;
-  try {
-    while (Date.now() < deadline) {
-      if (earlyFailure) throw earlyFailure;
-      await sleep(POLL_INTERVAL);
-      if (earlyFailure) throw earlyFailure;
-      const boundPort = port === 0 ? readDevToolsActivePort(activePortFile) : port;
-      if (boundPort !== null && (await isPortOpen(boundPort))) {
-        const identity = await chromeIdentity(boundPort);
-        if (identity === 'chrome') {
-          if (await isOwnEndpoint(boundPort)) {
-            track(boundPort);
-            return boundPort;
-          }
-          // Some Chrome answers on the port, but not the one we started: a
-          // concurrent launch's, or ours before its stderr line arrived. Our
-          // child exiting (it lost the bind) or the deadline decides.
-          continue;
-        }
-        // A Chrome that has only just opened its endpoint, on a loaded
-        // machine, can answer /json/list (no timeout) yet miss the identity
-        // check's 1 s timeout on /json/version. That says nothing about who is
-        // listening — keep polling rather than refuse our own Chrome.
-        if (identity === 'unknown') continue;
-        killUntracked();
-        throw new Error(
-          `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;
-    killUntracked();
-
-    if (port === 0) {
-      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
-    // "another Chrome holds it", "nothing is listening" (real launch failure)
-    // and "something non-CDP is squatting the port" (confusing generic
-    // timeout otherwise).
-    if (await isChromeIdentity(port)) {
-      throw new Error(
-        `Port ${port} is held by a Chrome/Chromium this launch did not start (a concurrent launch took it).`,
-      );
-    }
-    if (await isTcpPortOpen(port)) {
-      throw new Error(
-        `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${launchTimeout}ms). ` +
-          `Free the port or pass a different one.`,
-      );
-    }
-
-    throw new Error(`Chrome failed to start on port ${port} within ${launchTimeout}ms`);
-  } finally {
-    child.stderr?.destroy();
-  }
-}
-
-/** The per-process id in a browser-level CDP websocket URL
- *  (`ws://host:port/devtools/browser/<id>`), or null. */
-function browserIdOf(wsUrl: string | undefined): string | null {
-  return wsUrl?.match(/\/devtools\/browser\/([^/?#\s]+)/)?.[1] ?? null;
-}
-
-export async function enableSessionDomains(client: CdpClient, sessionId: string): Promise<void> {
-  await Promise.all([
-    client.send('Page.enable', {}, sessionId),
-    client.send('Runtime.enable', {}, sessionId),
-    client.send('Network.enable', {}, sessionId),
-    client.send('DOM.enable', {}, sessionId),
-    client.send('Accessibility.enable', {}, sessionId),
-  ]);
-  setupConsoleCapture(client, sessionId);
-  await enableConsoleCapture(client, sessionId);
-  setupDialogAutoHandling(client, sessionId);
-}
-
-export async function connectToTarget(
-  port: number,
-  targetId?: string,
-): Promise<{ client: CdpClient; target: CdpTarget; sessionId: string }> {
-  const targets = await fetchTargets(port);
-  const pageTargets = targets.filter((t) => t.type === 'page');
-
-  let target: CdpTarget;
-  if (targetId) {
-    const found = pageTargets.find((t) => t.id === targetId);
-    if (!found) throw new Error(`Target ${targetId} not found`);
-    target = found;
-  } else if (pageTargets.length > 0) {
-    target = pageTargets[0];
-  } else {
-    target = await fetchNewTarget(port, 'about:blank');
-  }
-
-  const wsUrl = target.webSocketDebuggerUrl ?? `ws://127.0.0.1:${port}/devtools/page/${target.id}`;
-  const client = new CdpClient();
-  await client.connect(wsUrl);
-
-  const { sessionId } = await client.send<{ sessionId: string }>('Target.attachToTarget', {
-    targetId: target.id,
-    flatten: true,
-  });
-
-  await enableSessionDomains(client, sessionId);
-  return { client, target, sessionId };
-}
-
-/**
- * Cleanly terminate a Chrome/Chromium instance we launched on `port`.
- * Sends the `Browser.close` CDP command (the correct graceful shutdown —
- * closes all tabs and exits the process cleanly) over `client`'s connection.
- * If that command fails, times out, or the connection is already gone,
- * falls back to killing the tracked PID directly so a headed/interactive
- * browser window (e.g. one spawned for a login/CAPTCHA flow) never lingers
- * as a visible, authenticated, still-debuggable orphan process.
- *
- * On the graceful path this resolves only once the process is actually gone,
- * or after force-killing it when it outlasts PROCESS_EXIT_TIMEOUT_MS. Chrome
- * acknowledges `Browser.close` well before it exits, and this used to return
- * on the ack with an unref'd 1s timer as the only force-kill — so it resolved
- * while Chrome was still running and holding its port and its profile's
- * singleton lock, and if the caller's process exited first the kill never
- * happened at all. Callers reasonably read a resolved close() as "that
- * browser is gone"; on the graceful path it now means that.
- */
-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) => {
-        closeTimer = setTimeout(
-          () => reject(new Error('Browser.close timed out')),
-          BROWSER_CLOSE_TIMEOUT_MS,
-        );
-      }),
-    ]);
-    gracefullyClosed = true;
-  } catch {
-    // fall through to PID-kill fallback below
-  } finally {
-    clearTimeout(closeTimer);
-  }
-
-  let pid = launchedPids.get(port);
-  if (pid === undefined) {
-    // Fresh process (each CLI invocation is its own node process — see
-    // module header) — launchedPids is per-process and empty here even
-    // though a prior `open` in a DIFFERENT process launched this Chrome.
-    // Fall back to the PID that process persisted via saveSessionRecord().
-    try {
-      const persisted = await loadSessionRecord(port);
-      if (persisted?.launched && persisted.pid) {
-        // Bound how far we trust a cross-process PID: if the Chrome we
-        // launched died outside this flow (OOM-killed, host slept, etc.)
-        // without its session record ever being cleared, the OS can recycle
-        // that PID for an unrelated process. There is no cmdline/start-time
-        // check available portably, so a coarse age bound is the practical
-        // guard — a PID persisted more than a day ago is far more likely to
-        // be stale/reused than to still be the same live Chrome.
-        const age = persisted.savedAt !== undefined ? Date.now() - persisted.savedAt : undefined;
-        if (age === undefined || age <= PERSISTED_PID_MAX_AGE_MS) {
-          pid = persisted.pid;
-        }
-      }
-    } catch {
-      // best-effort — fall through to "nothing to kill" below
-    }
-  }
-  if (pid === undefined) return; // not a process we launched, or too stale to trust — nothing to kill
-  launchedPids.delete(port);
-
-  // Liveness-check before every SIGKILL (not just the safety-net path below)
-  // — process.kill(pid, 0) throws ESRCH if the PID is no longer running,
-  // which also catches the case where the PID has already been recycled by
-  // an unrelated process that happens to have exited too.
-  if (!gracefullyClosed) {
-    try {
-      process.kill(pid, 0);
-      process.kill(pid, 'SIGKILL');
-    } catch {
-      /* already exited, or never was — nothing to do */
-    }
-    return;
-  }
-
-  // Browser.close was acknowledged — wait for the process to actually go away,
-  // then force-kill as a safety net in case it hung.
-  if (await waitForProcessExit(pid)) return;
-  try {
-    process.kill(pid, 'SIGKILL');
-  } catch {
-    /* raced us to exit — expected */
-  }
-}
-
-/** 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.
- *
- *  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 (;;) {
-    try {
-      process.kill(pid, 0);
-    } catch {
-      return true;
-    }
-    if (Date.now() >= deadline) return false;
-    await new Promise((resolve) => {
-      setTimeout(resolve, PROCESS_EXIT_POLL_MS);
-    });
-  }
-}
-
-/**
- * Give back the CDP port of a browser we launched that nothing is using any
- * more. A launched Chrome is deliberately detached and unref'd so it outlives
- * the command that spawned it and later commands can reattach — but nothing
- * reaped it afterwards, so an abandoned session kept listening on its port
- * (9222 by convention, which other local tools want) indefinitely. A foreign
- * CDP server *answers* there rather than refusing the connection, so those
- * tools retry the wrong port and report misleading errors instead of moving on.
- *
- * Nothing long-lived exists to run this on a timer — every CLI command is its
- * own short-lived process — so it runs at the next launch/attach instead
- * (see launchBrowser). A browser is reaped only when ALL of these hold:
- *   - the persisted session says WE launched it — `connect` records
- *     launched:false for a browser that belongs to the user, never touched;
- *   - that session is older than IDLE_REAP_AFTER_MS;
- *   - the CDP endpoint still answers and reports ZERO targets. An open tab,
- *     or a client attached to one (Chrome drops webSocketDebuggerUrl from an
- *     attached target but still lists it), means the session is live and
- *     reattach-across-commands must keep working.
- *
- * Shutdown goes through closeBrowser() on the browser-level websocket — the
- * only connection left once every target is gone — so a recycled PID can
- * never be signaled by mistake: graceful `Browser.close` reaches whatever is
- * actually listening on that port, at any age, and the persisted PID is only
- * ever used for closeBrowser's own age-bounded force-kill.
- *
- * Never throws: a failed reap must not stop a launch. Returns the reaped
- * port, or null when there was nothing to reap. Sessions are per-port
- * (#318), so every recorded one is considered, not just the newest.
- */
-export async function reapIdleLaunchedBrowser(): Promise<number | null> {
-  let reaped: number | null = null;
-  for (const session of await listSessionRecords().catch(() => [])) {
-    const port = await reapSession(session);
-    reaped ??= port;
-  }
-  return reaped;
-}
-
-async function reapSession(session: SessionRecord): Promise<number | null> {
-  try {
-    if (!session.launched || session.savedAt === undefined) return null;
-    if (Date.now() - session.savedAt < IDLE_REAP_AFTER_MS) return null;
-
-    const wsUrl = await fetchBrowserWebSocketUrl(session.port);
-    if (!wsUrl) return 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) => {
-          reapTimer = setTimeout(
-            () => reject(new Error('Reap: CDP connect timed out')),
-            REAP_CONNECT_TIMEOUT_MS,
-          );
-        }),
-      ]);
-      await closeBrowser(client, session.port);
-    } finally {
-      clearTimeout(reapTimer);
-      try {
-        client.close();
-      } catch {
-        /* already gone */
-      }
-    }
-    launchedPids.delete(session.port);
-    launchedUserDataDirs.delete(session.port);
-    await removeSessionRecord(session.port);
-    return session.port;
-  } catch {
-    return null;
-  }
-}
-
-/** Chrome's browser-level debugger endpoint, from /json/version — the
- *  connection `Browser.close` belongs on. Null if the port isn't answering as
- *  a Chrome/Chromium CDP endpoint (same identity check as isChromeIdentity). */
-async function fetchBrowserWebSocketUrl(port: number): Promise<string | null> {
-  const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
-    signal: AbortSignal.timeout(1000),
-  });
-  if (!res.ok) return null;
-  const info = (await res.json()) as { Browser?: string; webSocketDebuggerUrl?: string };
-  if (typeof info.Browser !== 'string' || !/chrom(e|ium)|edg/i.test(info.Browser)) return null;
-  return typeof info.webSocketDebuggerUrl === 'string' ? info.webSocketDebuggerUrl : null;
-}
-
-export async function openUrl(client: CdpClient, sessionId: string, url: string): Promise<void> {
-  // Cap to 2 MB to prevent OOM in CDP message serializer (e.g. data: URI attacks)
-  if (url.length > 2_097_152) throw new Error('URL exceeds 2 MB limit');
-  // Page.navigate reports a protocol-level failure (e.g. a refused connection)
-  // via errorText in its own response, before Chrome ever settles on the
-  // chrome-error://chromewebdata/ page — without this check a refused
-  // connection previously reported success against that error page.
-  const nav = await client.send<{ errorText?: string }>('Page.navigate', { url }, sessionId);
-  if (nav.errorText) throw new Error(`Navigation to ${url} failed: ${nav.errorText}`);
-  await waitForNetworkIdle(client, sessionId, 500, 30_000);
-}
-
-export async function waitForLoad(
-  client: CdpClient,
-  sessionId: string,
-  condition: 'load' | 'networkidle' | 'domcontentloaded' = 'load',
-  timeout = 30_000,
-): Promise<void> {
-  if (condition === 'load' || condition === 'domcontentloaded') {
-    // Guard against race where the page loads before the listener is registered
-    const readyExpr =
-      condition === 'load'
-        ? 'document.readyState === "complete"'
-        : 'document.readyState !== "loading"';
-    const readyCheck = await client
-      .send<{ result: { value?: boolean } }>(
-        'Runtime.evaluate',
-        {
-          expression: readyExpr,
-          returnByValue: true,
-        },
-        sessionId,
-      )
-      .catch(() => ({ result: { value: false } }));
-    if (readyCheck.result?.value) return;
-
-    const event = condition === 'load' ? 'Page.loadEventFired' : 'Page.domContentEventFired';
-    const [eventPromise, cancelOnce] = client.onceWithOff(event, sessionId);
-    let timedOut = false;
-    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
-    const timeoutPromise = new Promise<void>((resolve) => {
-      timeoutHandle = setTimeout(() => {
-        timedOut = true;
-        resolve();
-      }, timeout);
-    });
-    try {
-      await Promise.race([eventPromise, timeoutPromise]);
-      if (timedOut) throw new Error(`Timeout waiting for ${condition}`);
-    } finally {
-      cancelOnce();
-      clearTimeout(timeoutHandle);
-    }
-    return;
-  }
-
-  // networkidle: no network requests for 500ms
-  await waitForNetworkIdle(client, sessionId, 500, timeout);
-}
-
-async function waitForNetworkIdle(
-  client: CdpClient,
-  sessionId: string,
-  idleMs: number,
-  timeout: number,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    let pending = 0;
-    const inflight = new Set<string>();
-    let idleTimer: ReturnType<typeof setTimeout> | null = null;
-    const killTimer = setTimeout(() => {
-      cleanup();
-      reject(new Error('Timeout waiting for networkidle'));
-    }, timeout);
-
-    const cleanup = () => {
-      if (idleTimer) {
-        clearTimeout(idleTimer);
-        idleTimer = null;
-      }
-      clearTimeout(killTimer);
-      offReq();
-      offResp();
-      offFail();
-      offCache();
-      offResp2();
-    };
-
-    const settle = () => {
-      cleanup();
-      resolve();
-    };
-
-    const check = () => {
-      if (pending === 0) {
-        if (idleTimer) clearTimeout(idleTimer);
-        idleTimer = setTimeout(settle, idleMs);
-      } else {
-        if (idleTimer) {
-          clearTimeout(idleTimer);
-          idleTimer = null;
-        }
-      }
-    };
-
-    const offReq = client.on('Network.requestWillBeSent', (params, sid) => {
-      if (sid !== sessionId) return;
-      const id = params.requestId as string;
-      if (!inflight.has(id)) {
-        inflight.add(id);
-        pending++;
-        check();
-      }
-    });
-
-    const decrement = (params: Record<string, unknown>, sid?: string) => {
-      if (sid !== sessionId) return;
-      const id = params.requestId as string;
-      if (inflight.delete(id)) {
-        pending = Math.max(0, pending - 1);
-        check();
-      }
-    };
-
-    const offResp = client.on('Network.loadingFinished', decrement);
-    const offFail = client.on('Network.loadingFailed', decrement);
-    const offCache = client.on('Network.requestServedFromCache', decrement);
-    // Guard against requests that never fire loadingFinished/loadingFailed (e.g. data: URLs)
-    // Skip 3xx redirect responses — the request continues under the same requestId
-    const offResp2 = client.on('Network.responseReceived', (params, sid) => {
-      const p = params as { requestId: string; response: { status: number } };
-      if (p.response.status >= 300 && p.response.status < 400) return;
-      decrement(params, sid);
-    });
-
-    check();
-  });
-}
-
-export async function getCurrentUrl(client: CdpClient, sessionId: string): Promise<string> {
-  const result = await client.send<{ result: { value: string } }>(
-    'Runtime.evaluate',
-    {
-      expression: 'location.href',
-      returnByValue: true,
-    },
-    sessionId,
-  );
-  return result.result?.value ?? '';
-}
-
-export async function getCurrentTitle(client: CdpClient, sessionId: string): Promise<string> {
-  const result = await client.send<{ result: { value: string } }>(
-    'Runtime.evaluate',
-    {
-      expression: 'document.title',
-      returnByValue: true,
-    },
-    sessionId,
-  );
-  return result.result?.value ?? '';
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((r) => setTimeout(r, ms));
-}
+// File-size sweep: split into sibling modules (browser-state, browser-discovery,
+// browser-launch, browser-lifecycle, browser-page). Pure move — this file now
+// re-exports everything it used to define, so every existing import path
+// keeps working.
+
+export { isPortOpen } from './browser-discovery.js';
+export { launchBrowser } from './browser-launch.js';
+export { closeBrowser, reapIdleLaunchedBrowser } from './browser-lifecycle.js';
+export {
+  connectToTarget,
+  enableSessionDomains,
+  getCurrentTitle,
+  getCurrentUrl,
+  openUrl,
+  waitForLoad,
+} from './browser-page.js';
+export {
+  getLaunchedPid,
+  getLaunchedUserDataDir,
+  ownsLaunchedUserDataDir,
+} from './browser-state.js';