@monoes/monobrowse 1.0.25 → 1.0.27

package/dist/src/browser/browser-launch.js

@@ -0,0 +1,324 @@
+// Split out of browser.ts (file-size sweep). Pure move: no behaviour change.
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { browserIdOf, chromeIdentity, fetchBrowserWebSocketUrl, findChrome, isChromeIdentity, isPortOpen, isTcpPortOpen, readDevToolsActivePort, } from './browser-discovery.js';
+import { reapIdleLaunchedBrowser } from './browser-lifecycle.js';
+import { launchedPids, launchedUserDataDirs } from './browser-state.js';
+const DEFAULT_PORT = 9222;
+const LAUNCH_TIMEOUT = 10_000;
+const POLL_INTERVAL = 200;
+/** 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 = {}) {
+    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 = [];
+    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.`);
+}
+/**
+ * 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, port) {
+    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 = null;
+    if (child.stderr) {
+        let stderrTail = '';
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            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 = 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) => {
+        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) => {
+        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();
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=browser-launch.js.map

package/dist/src/browser/browser-launch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-launch.js","sourceRoot":"","sources":["../../../src/browser/browser-launch.ts"],"names":[],"mappings":"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"}

package/dist/src/browser/browser-lifecycle.d.ts

@@ -0,0 +1,52 @@
+import { CdpClient } from './cdp.js';
+/**
+ * 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 declare function closeBrowser(client: CdpClient, port: number): Promise<void>;
+/**
+ * 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 declare function reapIdleLaunchedBrowser(): Promise<number | null>;
+//# sourceMappingURL=browser-lifecycle.d.ts.map

package/dist/src/browser/browser-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/browser/browser-lifecycle.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAgB,MAAM,UAAU,CAAC;AAsBnD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8EjF;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOtE"}

package/dist/src/browser/browser-lifecycle.js

@@ -0,0 +1,233 @@
+// Split out of browser.ts (file-size sweep). Pure move: no behaviour change.
+import { fetchBrowserWebSocketUrl } from './browser-discovery.js';
+import { launchedPids, launchedUserDataDirs } from './browser-state.js';
+import { CdpClient, fetchTargets } from './cdp.js';
+import { listSessionRecords, loadSessionRecord, removeSessionRecord, } from './ref-cache.js';
+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;
+/**
+ * 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, port) {
+    let gracefullyClosed = false;
+    let closeTimer;
+    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((_, 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) {
+    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() {
+    let reaped = null;
+    for (const session of await listSessionRecords().catch(() => [])) {
+        const port = await reapSession(session);
+        reaped ??= port;
+    }
+    return reaped;
+}
+async function reapSession(session) {
+    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;
+        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((_, 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;
+    }
+}
+//# sourceMappingURL=browser-lifecycle.js.map

package/dist/src/browser/browser-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-lifecycle.js","sourceRoot":"","sources":["../../../src/browser/browser-lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/src/browser/browser-page.d.ts

@@ -0,0 +1,13 @@
+import { CdpClient } from './cdp.js';
+import type { CdpTarget } from './types.js';
+export declare function enableSessionDomains(client: CdpClient, sessionId: string): Promise<void>;
+export declare function connectToTarget(port: number, targetId?: string): Promise<{
+    client: CdpClient;
+    target: CdpTarget;
+    sessionId: string;
+}>;
+export declare function openUrl(client: CdpClient, sessionId: string, url: string): Promise<void>;
+export declare function waitForLoad(client: CdpClient, sessionId: string, condition?: 'load' | 'networkidle' | 'domcontentloaded', timeout?: number): Promise<void>;
+export declare function getCurrentUrl(client: CdpClient, sessionId: string): Promise<string>;
+export declare function getCurrentTitle(client: CdpClient, sessionId: string): Promise<string>;
+//# sourceMappingURL=browser-page.d.ts.map