@ultimat3/testing 23.0.0 → 25.0.0

package/src/cdp-launch-attempt.ts

@@ -0,0 +1,224 @@
+// One responsibility: ONE start of a Chrome process — spawn it on a throwaway profile, wait for its
+// first DevTools answer, and on no answer reap it (killed, awaited, profile removed) and say why.
+// Which binary, which flags and how many starts is `cdp-launch.ts`.
+
+import { renderThrowable } from '@ultimat3/core';
+import type { CdpConnection } from './cdp-connection';
+import type { CdpLaunchAttempt } from './cdp-errors';
+import { CdpTimeoutError } from './cdp-errors';
+import { throwawayProfile } from './cdp-launch-profile';
+import { CLOSE_GRACE_MS, killTree } from './cdp-launch-reap';
+import type { CdpWire } from './cdp-launch-wire';
+import { pipeConnection, portConnection, wireStdio } from './cdp-launch-wire';
+
+export { CLOSE_GRACE_MS } from './cdp-launch-reap';
+
+/**
+ * The longest `LaunchedBrowser.close()` is DESIGNED to take: SIGTERM's grace, SIGKILL's, the group
+ * reap, then the profile's removal — four `CLOSE_GRACE_MS`, each step bounded by its own. A hook
+ * that closes a browser and gives it less is killed by Bun mid-close, and when that hook is the
+ * run's last the process exits with the profile half-removed: the `Default/Cache` tree the leaked
+ * `x-e2e-chrome-*` directories held.
+ */
+export const LAUNCHED_CLOSE_MS = 4 * CLOSE_GRACE_MS;
+
+export interface LaunchedBrowser {
+  /** The browser's own CDP connection, over its debugging pipe or port. Already answering. */
+  readonly connection: CdpConnection;
+  /**
+   * THE close, idempotent, and awaited by every caller: the connection closed, SIGTERM, SIGKILL
+   * after `CLOSE_GRACE_MS`, then the browser's whole process group killed and, only then, the
+   * profile removed — bounded at `LAUNCHED_CLOSE_MS`. On Windows, which has no SIGTERM to grant grace to, the process TREE
+   * is killed outright (`killTree`) and awaited. A promise because a Chrome still shutting down competes with the next
+   * launch on a 4-CPU runner, and its children re-create a profile removed before they are gone.
+   */
+  close(): Promise<void>;
+}
+
+export interface LaunchAttemptOptions {
+  readonly executable: string;
+  /** What the process is started with, given the profile directory this attempt made for it. */
+  readonly flags: (profileDir: string) => readonly string[];
+  /** Which wire the flags opened — `cdp-launch-wire.ts`. */
+  readonly wire: CdpWire;
+  /** Whose process rules the reap follows. Defaults to this process's platform. */
+  readonly platform?: string | undefined;
+  /** Every call's deadline AFTER the first. */
+  readonly timeoutMs: number;
+  /** The first call's deadline: how long a cold start may take. */
+  readonly launchTimeoutMs: number;
+}
+
+export type LaunchAttemptResult =
+  | { readonly ok: true; readonly browser: LaunchedBrowser }
+  /** `reaped: false` is a process that outlived SIGKILL's grace — never start another beside it. */
+  | { readonly ok: false; readonly failure: CdpLaunchAttempt; readonly reaped: boolean };
+
+const STDERR_TAIL_CHARS = 4_000;
+/** How much of the tail one attempt hands a cause: the last lines, each cut to a readable width. */
+const TAIL_LINES = 3;
+const TAIL_LINE_CHARS = 160;
+
+/**
+ * Read stderr to its end for the life of the process, keeping only a bounded tail. A pipe nobody
+ * reads fills, and Chrome's next stderr write then blocks the thread making it — a browser that
+ * stops answering mid-run for a reason no log shows. The tail is the launch-failure diagnostics:
+ * a missing library, a sandbox refusal and a bad flag are all named there and nowhere else.
+ */
+function stderrTail(stream: ReadableStream<Uint8Array>): {
+  readonly lastLines: () => string;
+  /** Settles once the stream has ended — every byte the process wrote has been read. */
+  readonly drained: Promise<void>;
+} {
+  let text = '';
+  const drained = (async () => {
+    const decoder = new TextDecoder();
+    for await (const chunk of stream) {
+      text = (text + decoder.decode(chunk, { stream: true })).slice(-STDERR_TAIL_CHARS);
+    }
+  })().catch(() => undefined);
+  const lastLines = (): string =>
+    text
+      .trim()
+      .split('\n')
+      .slice(-TAIL_LINES)
+      .map((line) => line.slice(0, TAIL_LINE_CHARS))
+      .join(' | ');
+  return { lastLines, drained };
+}
+
+/**
+ * How long a browser that CLOSED ITS PIPE gets to finish dying, and any browser's stderr to finish
+ * draining, before the tail is read. The pipe ending and the stderr reader reaching the last line
+ * are two unordered events; read at the first, the reason a browser died was reported as "printed
+ * nothing". Bounded, because a WEDGED browser neither exits nor closes stderr.
+ */
+const FAILURE_DRAIN_MS = 1_000;
+
+/**
+ * The longest a FAILED attempt spends after its deadline before the next can start: the drain a
+ * browser that hung up gets, the bounded close (`LAUNCHED_CLOSE_MS`), then the stderr drain. A
+ * caller's hook deadline adds this per attempt.
+ */
+export const LAUNCH_REAP_MS = FAILURE_DRAIN_MS + LAUNCHED_CLOSE_MS + FAILURE_DRAIN_MS;
+
+const within = (ms: number, work: Promise<unknown>): Promise<unknown> =>
+  Promise.race([work, Bun.sleep(ms)]);
+
+/**
+ * Start the browser once and answer when it has answered one CDP call. With a pipe there is no
+ * "DevTools listening" line to wait for — the first reply IS the readiness signal.
+ */
+export async function launchAttempt(options: LaunchAttemptOptions): Promise<LaunchAttemptResult> {
+  const platform = options.platform ?? process.platform;
+  const profile = throwawayProfile();
+  const profileDir = profile.path;
+  const began = performance.now();
+  let child: ReturnType<typeof spawnBrowser>;
+  try {
+    child = spawnBrowser(options, profileDir, platform);
+  } catch (error) {
+    // A binary that cannot be started at all — not there, not executable, not an executable FORMAT
+    // this OS runs (a `#!` script on Windows). Bun throws from `spawn`, synchronously, and that
+    // throw escaped as a bare ENOENT where every other way a launch fails is X_CDP_LAUNCH_FAILED.
+    await profile.remove(undefined, CLOSE_GRACE_MS);
+    return {
+      ok: false,
+      failure: {
+        why: 'spawn',
+        waitedMs: 0,
+        exitCode: null,
+        stderr: '',
+        detail: renderThrowable(error),
+      },
+      reaped: true,
+    };
+  }
+  const tail = stderrTail(child.stderr as ReadableStream<Uint8Array>);
+  let connection: CdpConnection | undefined =
+    options.wire === 'pipe' ? pipeConnection(child.stdio, options.timeoutMs) : undefined;
+  let exiting: Promise<void> | undefined;
+  const close = (): Promise<void> => {
+    exiting ??= (async () => {
+      // Read while the browser still runs: a clean exit unlinks it, a killed one never does.
+      const singleton = profile.singletonDir();
+      connection?.close();
+      if (platform === 'win32') {
+        // No SIGTERM to grant grace to: a kill on Windows is TerminateProcess, and taking the
+        // browser alone would orphan the children that hold the profile's files open.
+        await killTree(child.pid, platform);
+        await within(CLOSE_GRACE_MS, child.exited);
+      } else {
+        child.kill();
+        const exited =
+          (await within(
+            CLOSE_GRACE_MS,
+            child.exited.then(() => true),
+          )) === true;
+        if (!exited) {
+          child.kill('SIGKILL');
+          await within(CLOSE_GRACE_MS, child.exited);
+        }
+        await killTree(child.pid, platform);
+      }
+      // Only now, with the tree gone: removed under a live browser, the profile is re-created by
+      // its shutdown — the network process flushes its cache, the browser writes its prefs — and
+      // a close cut short there leaves exactly that tree. Measured on Chrome 150, 30 launches
+      // each: left behind 6 and 12 times without the group reap, 0 with.
+      await profile.remove(singleton, CLOSE_GRACE_MS);
+    })();
+    return exiting;
+  };
+  try {
+    // The pipe needs no wait to exist; the port is not known until the browser writes it down, and
+    // finding it spends the same launch deadline the first answer does.
+    connection ??= await portConnection({
+      profileDir,
+      exited: () => child.exitCode !== null || child.signalCode !== null,
+      deadlineMs: options.launchTimeoutMs,
+      timeoutMs: options.timeoutMs,
+    });
+    const left = Math.max(1, options.launchTimeoutMs - (performance.now() - began));
+    await connection.send('Browser.getVersion', {}, undefined, left);
+    return { ok: true, browser: { connection, close } };
+  } catch (error) {
+    const why = error instanceof CdpTimeoutError ? 'deadline' : 'closed';
+    // The deadline itself when that is what ended it: the number the reader can raise.
+    const waitedMs =
+      why === 'deadline' ? options.launchTimeoutMs : Math.round(performance.now() - began);
+    // Only a browser that hung up may be on its way out with the reason still unwritten. One that
+    // was silent for the whole deadline has had its time.
+    if (why === 'closed') await within(FAILURE_DRAIN_MS, child.exited);
+    // Read BEFORE the kill: after it, an exit code is ours and says nothing about the browser.
+    const exitCode = child.exitCode;
+    await close();
+    await within(FAILURE_DRAIN_MS, tail.drained);
+    return {
+      ok: false,
+      // `detail`: the error itself. Without it a refused dial after "DevTools listening" read as a
+      // browser that hung up (seen on windows), and nothing said which step had failed.
+      failure: {
+        why,
+        waitedMs,
+        exitCode,
+        stderr: tail.lastLines(),
+        detail: renderThrowable(error),
+      },
+      reaped: child.exitCode !== null || child.signalCode !== null,
+    };
+  }
+}
+
+/**
+ * The process, on its own process GROUP on POSIX so the zygote, GPU and network processes are
+ * reaped with it (`killTree`). It still ends with this process on the pipe wire: Chrome exits when
+ * its fd 3 closes. Windows has no group to make — `detached` there is a console flag — so not.
+ */
+function spawnBrowser(options: LaunchAttemptOptions, profileDir: string, platform: string) {
+  // Spread into a fresh tuple: Bun's `stdio` type takes a mutable tuple, never a readonly one.
+  const [stdin, stdout, stderr, ...extra] = wireStdio(options.wire);
+  return Bun.spawn([options.executable, ...options.flags(profileDir)], {
+    stdio: [stdin, stdout, stderr, ...extra],
+    detached: platform !== 'win32',
+  });
+}

package/src/cdp-launch-candidates.ts

@@ -0,0 +1,62 @@
+// One responsibility: WHERE a Chrome is installed, per platform — the ordered list `findChrome`
+// probes when `CHROME_PATH` names none. Which binary wins and how it starts is `cdp-launch.ts`.
+
+// why: a Windows candidate is spelled with `\` whatever OS computes the list (a test, or the
+// Linux runner asserting it), and only node:path's win32 half joins that way. Bun has no path API.
+import { win32 } from 'node:path';
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/** What GitHub-hosted `ubuntu-latest` ships, which lets CI run the browser suite with no download. */
+const LINUX: readonly string[] = [
+  '/usr/bin/google-chrome',
+  '/usr/bin/google-chrome-stable',
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+];
+
+const set = (value: string | undefined): string | undefined =>
+  value === undefined || value === '' ? undefined : value;
+
+/**
+ * Chrome under each root an installer uses — machine-wide 64- and 32-bit, then per-user — then
+ * Edge, which is Chromium, speaks the same DevTools protocol and is on every Windows 10 and 11. A
+ * root the environment does not name falls back to its fixed default; a per-user root has none, so
+ * it is not guessed at.
+ */
+const windows = (env: Env): readonly string[] => {
+  const programFiles = set(env['ProgramFiles']) ?? 'C:\\Program Files';
+  const programFilesX86 = set(env['ProgramFiles(x86)']) ?? 'C:\\Program Files (x86)';
+  const localAppData = set(env['LOCALAPPDATA']);
+  const chromeRoots = [programFiles, programFilesX86, ...(localAppData ? [localAppData] : [])];
+  return [
+    ...chromeRoots.map((root) => win32.join(root, 'Google', 'Chrome', 'Application', 'chrome.exe')),
+    // x86 first for Edge: it is where the Windows image installs it, 64-bit or not.
+    ...[programFilesX86, programFiles].map((root) =>
+      win32.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+    ),
+  ];
+};
+
+const MAC_CHROME = 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+
+/** The app bundles' executables: system-wide, then the per-user `~/Applications` an admin-less install uses. */
+const mac = (env: Env): readonly string[] => {
+  const home = set(env['HOME']);
+  return [
+    `/${MAC_CHROME}`,
+    ...(home ? [`${home}/${MAC_CHROME}`] : []),
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  ];
+};
+
+/**
+ * Where a Chrome is on `platform`, in the order worth trying. Any platform that is neither Windows
+ * nor macOS gets the Linux paths — the BSDs install to the same names when they install at all.
+ */
+export function chromeCandidates(platform: string, env: Env): readonly string[] {
+  if (platform === 'win32') return windows(env);
+  if (platform === 'darwin') return mac(env);
+  return LINUX;
+}

package/src/cdp-launch-profile.ts

@@ -0,0 +1,106 @@
+// One responsibility: the throwaway profile a launch hands Chrome, and its removal — after every
+// process of the browser is gone, retried while something re-creates it, bounded — together with
+// the singleton-socket directory Chrome makes BESIDE it in the temp root.
+
+// why: Bun exposes no temp-root, recursive-remove or readlink primitive; the profile needs all three.
+import { existsSync, mkdtempSync, readdirSync, readlinkSync, rmdirSync, rmSync } from 'node:fs';
+// why: Bun exposes no tmpdir(), so only node:os answers the platform temp root.
+import { tmpdir } from 'node:os';
+// why: Bun exposes no path-join primitive.
+import { basename, dirname, join } from 'node:path';
+
+/**
+ * How long a removed profile is watched for coming back before it counts as gone. Chrome's late
+ * writers are the network service flushing its disk cache and the browser's atomic preference
+ * write (`Default/.com.google.Chrome.XXXXXX`) — the exact tree the leaked profiles held. Removal
+ * waits for the process tree first, so the look is for what the tree kill cannot see: a process
+ * outside the group (Chrome's crashpad handler calls `setsid`), and on Windows a child `taskkill`
+ * has not finished ending when it returns.
+ */
+export const PROFILE_SETTLE_MS = 50;
+
+/**
+ * What Chrome's ProcessSingleton puts in its socket directory, and nothing else. The directory is
+ * `<temp>/com.google.Chrome.XXXXXX` (Chromium: `org.chromium.Chromium.…`), linked from the profile's
+ * `SingletonSocket`, and a browser that does not shut down cleanly never removes it: measured, one
+ * left in the temp root per launch — 444 of them beside 146 leaked profiles.
+ */
+const SINGLETON_FILES: ReadonlySet<string> = new Set([
+  'SingletonSocket',
+  'SingletonCookie',
+  'SingletonLock',
+]);
+
+export interface ThrowawayProfile {
+  readonly path: string;
+  /**
+   * Where the browser's singleton socket lives, read off the profile's own link. Asked BEFORE the
+   * browser is signalled: a browser that exits cleanly removes the link first, and one killed
+   * leaves the directory with nothing in the profile pointing at it.
+   */
+  singletonDir(): string | undefined;
+  /**
+   * Remove the profile — and `singleton`, when it holds Chrome's singleton files and nothing else —
+   * and answer once neither has come back for `PROFILE_SETTLE_MS`, or at `deadlineMs`. Never throws:
+   * a directory that will not go is litter, never the close's verdict.
+   */
+  remove(singleton: string | undefined, deadlineMs: number): Promise<void>;
+}
+
+const quietly = (work: () => void): void => {
+  try {
+    work();
+  } catch {
+    // Already gone, or held open past the deadline: the loop's next look decides which.
+  }
+};
+
+/**
+ * Only a directory whose every entry is a singleton file is Chrome's to have made: a link that
+ * points anywhere else is somebody's directory, and is left alone.
+ */
+function isSingletonDir(dir: string): boolean {
+  try {
+    return readdirSync(dir).every((entry) => SINGLETON_FILES.has(entry));
+  } catch {
+    return false;
+  }
+}
+
+/** File by file, then a plain `rmdir` — never a recursive remove of a path read off a link. */
+function removeSingleton(dir: string): void {
+  for (const entry of SINGLETON_FILES) quietly(() => rmSync(join(dir, entry), { force: true }));
+  quietly(() => rmdirSync(dir));
+}
+
+/** A fresh profile directory under the temp root, named so a leak is recognisable as ours. */
+export function throwawayProfile(root: string = tmpdir()): ThrowawayProfile {
+  const path = mkdtempSync(join(root, 'x-e2e-chrome-'));
+  return {
+    path,
+    singletonDir() {
+      try {
+        const target = readlinkSync(join(path, 'SingletonSocket'));
+        return basename(target) === 'SingletonSocket' ? dirname(target) : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    async remove(singleton, deadlineMs) {
+      const until = performance.now() + deadlineMs;
+      const owned = singleton !== undefined && isSingletonDir(singleton) ? singleton : undefined;
+      const present = (): boolean => existsSync(path) || (owned !== undefined && existsSync(owned));
+      do {
+        quietly(() => rmSync(path, { recursive: true, force: true }));
+        if (owned !== undefined) removeSingleton(owned);
+        if (present()) {
+          await Bun.sleep(PROFILE_SETTLE_MS / 5);
+          continue;
+        }
+        // Gone NOW is not gone: the look after the settle is what a late writer fails.
+        await Bun.sleep(PROFILE_SETTLE_MS);
+        if (!present()) return;
+      } while (performance.now() < until);
+    },
+  };
+}

package/src/cdp-launch-reap.ts

@@ -0,0 +1,68 @@
+// One responsibility: nothing of a launched browser outlives its close — on POSIX its process GROUP,
+// on Windows its process TREE — and the close waits until that is so, bounded.
+
+/** How long a closed Chrome gets to exit on SIGTERM before it is killed outright. */
+export const CLOSE_GRACE_MS = 5_000;
+
+const GROUP_POLL_MS = 10;
+
+/** Runs a command to its exit; the seam the Windows branch is asserted through on any runner. */
+export type RunCommand = (argv: readonly string[]) => Promise<number>;
+
+const runQuiet: RunCommand = (argv) =>
+  // Bounded: taskkill ends a tree in well under a second; a stuck one must not stall `close()`.
+  Bun.spawn([...argv], { stdio: ['ignore', 'ignore', 'ignore'], timeout: 10_000 }).exited;
+
+/**
+ * `/T` takes every process the browser started — renderer, GPU, network, crashpad — and `/F` does
+ * not ask: a tree kill is the last step of a close, after the graceful one had its chance.
+ */
+export const taskkillArgv = (pid: number): readonly string[] => [
+  'taskkill',
+  '/T',
+  '/F',
+  '/PID',
+  String(pid),
+];
+
+const within = (ms: number, work: Promise<unknown>): Promise<unknown> =>
+  Promise.race([work, Bun.sleep(ms)]);
+
+/**
+ * Kill whatever is left of the browser's process group and wait until the group is EMPTY — the
+ * condition, asked of the kernel, not a pause: signal 0 to a group with no member throws. Bounded
+ * by `CLOSE_GRACE_MS` for a container whose init never reaps a zombie — on the monotonic clock,
+ * not a count of sleeps: a loaded runner oversleeps every 10 ms, and the close's designed bound
+ * (`LAUNCHED_CLOSE_MS`) is what a hook deadline is derived from.
+ */
+async function reapGroup(pgid: number): Promise<void> {
+  const until = performance.now() + CLOSE_GRACE_MS;
+  try {
+    process.kill(-pgid, 'SIGKILL');
+    while (performance.now() < until) {
+      await Bun.sleep(GROUP_POLL_MS);
+      process.kill(-pgid, 0);
+    }
+  } catch {
+    // ESRCH: nothing is left in the group, which is the answer being waited for.
+  }
+}
+
+/**
+ * Everything the browser `pid` started, gone. On Windows `process.kill(-pgid)` is no call at all —
+ * there is no process group, and the browser's children hold the profile's files open — so the
+ * tree is walked by `taskkill`, which must run while the browser is still ALIVE: its children are
+ * found by parent pid, and a dead parent's children are nobody's.
+ */
+export async function killTree(
+  pid: number,
+  platform: string = process.platform,
+  run: RunCommand = runQuiet,
+): Promise<void> {
+  if (platform !== 'win32') return reapGroup(pid);
+  try {
+    await within(CLOSE_GRACE_MS, run(taskkillArgv(pid)));
+  } catch {
+    // No taskkill, or a tree already gone (exit 128): litter at worst, never the close's verdict.
+  }
+}

package/src/cdp-launch-wire.ts

@@ -0,0 +1,171 @@
+// One responsibility: the WIRE a launched Chrome is driven over, per platform — its debugging pipe
+// (fds 3 and 4) where the parent can hold those fds, else a loopback port the browser picks and
+// announces in its profile's `DevToolsActivePort`. Spawning and reaping are `cdp-launch-attempt.ts`.
+
+// why: Bun exposes no path-join primitive; the announcement file lives in the profile directory.
+import { join } from 'node:path';
+import { renderThrowable, stringField } from '@ultimat3/core';
+import type { CdpConnection } from './cdp-connection';
+import { cdpConnect, cdpConnectOver } from './cdp-connection';
+import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
+import { pipeTransport } from './cdp-pipe';
+
+/**
+ * `pipe` everywhere Bun hands the parent the child's extra fds as descriptors, which is POSIX: no
+ * port, so two suites on one machine never collide and nothing else can drive the browser.
+ * `port` on Windows, where those fds are not descriptors `Bun.file` can open: Chrome binds a
+ * loopback port of its own choosing (`=0`, so never a collision either) and writes it down.
+ */
+export type CdpWire = 'pipe' | 'port';
+
+export const defaultWire = (platform: string): CdpWire => (platform === 'win32' ? 'port' : 'pipe');
+
+/** The one flag that differs between the two wires. */
+export const wireFlag = (wire: CdpWire): string =>
+  wire === 'pipe' ? '--remote-debugging-pipe' : '--remote-debugging-port=0';
+
+/** Chrome's fd 3 is where it READS commands and fd 4 where it WRITES replies — pipe wire only. */
+const PIPE_STDIO = ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] as const;
+const PORT_STDIO = ['ignore', 'ignore', 'pipe'] as const;
+export const wireStdio = (wire: CdpWire): typeof PIPE_STDIO | typeof PORT_STDIO =>
+  wire === 'pipe' ? PIPE_STDIO : PORT_STDIO;
+
+/** The pipe wire over a spawned child's fds 3 and 4. Answers nothing until the first `send`. */
+export function pipeConnection(stdio: unknown, timeoutMs: number): CdpConnection {
+  const [, , , toBrowser, fromBrowser] = stdio as readonly number[];
+  const sink = Bun.file(toBrowser ?? -1).writer();
+  return cdpConnectOver(
+    pipeTransport({
+      write: (bytes) => {
+        sink.write(bytes);
+        void sink.flush();
+      },
+      read: Bun.file(fromBrowser ?? -1).stream(),
+      end: () => {
+        void Promise.resolve(sink.end()).catch(() => undefined);
+      },
+    }),
+    timeoutMs,
+  );
+}
+
+export const DEVTOOLS_ACTIVE_PORT = 'DevToolsActivePort';
+
+/**
+ * `<port>\n/devtools/browser/<id>\n` → the browser's WebSocket url, or `undefined` while the file is
+ * still half-written. Loopback by address, never `localhost`, which may resolve to `::1` first
+ * while Chrome listens on IPv4.
+ */
+export function devToolsEndpoint(text: string): string | undefined {
+  const [port, path] = text.split(/\r?\n/);
+  if (port === undefined || !/^\d{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65_535) {
+    return undefined;
+  }
+  if (path === undefined || !/^\/devtools\/browser\/[\w-]+$/.test(path)) return undefined;
+  return `ws://127.0.0.1:${port}${path}`;
+}
+
+const ANNOUNCE_POLL_MS = 25;
+
+/**
+ * Dial, inside what is left of the LAUNCH deadline — `cdpConnect`'s own deadline is the per-call one
+ * the connection keeps afterwards, so it cannot also be the launch's. A dial that loses the race
+ * and connects later is closed, never left holding a socket nobody reads.
+ */
+async function dialWithin(
+  endpoint: string,
+  leftMs: number,
+  timeoutMs: number,
+): Promise<CdpConnection> {
+  const dialing = cdpConnect({ endpoint, timeoutMs });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new CdpTimeoutError({ method: 'connect', timeoutMs: leftMs })),
+      leftMs,
+    );
+  });
+  try {
+    return await Promise.race([dialing, late]);
+  } catch (error) {
+    void dialing.then((connection) => connection.close()).catch(() => undefined);
+    // A timeout stays one — the launcher reads it as the deadline. Any other refusal names the
+    // endpoint it was for: the browser announced it, so the dial is the step that failed.
+    if (error instanceof CdpTimeoutError) throw error;
+    throw new CdpCallFailedError({
+      method: `connect ${endpoint}`,
+      detail: renderThrowable(error),
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export interface PortConnectionInput {
+  readonly profileDir: string;
+  /** True once the browser process has exited — it will never write the file then. */
+  readonly exited: () => boolean;
+  /** How long the browser has to announce itself AND accept the connection, from now. */
+  readonly deadlineMs: number;
+  /** Every call's deadline once connected. */
+  readonly timeoutMs: number;
+  /**
+   * How the announcement is read — `Bun.file(path).text()` unless a test hands a reader that
+   * refuses the way Windows does, which no Linux file system can be made to.
+   */
+  readonly readText?: ((path: string) => Promise<string>) | undefined;
+}
+
+/**
+ * The read errors that mean "not announced YET", never "the launch failed": `ENOENT`, the file
+ * gone between the existence check and the read, and `EBUSY`, which is how Bun reports a Windows
+ * sharing violation — Chrome writes `DevToolsActivePort` in place and holds it open without read
+ * sharing while it does. Seen on windows-latest (PR #668): "DevTools listening" on stderr, the file
+ * present, the read refused, and the launch reported `closed` with the browser alive.
+ */
+const NOT_YET = new Set(['ENOENT', 'EBUSY']);
+
+const readFile = (path: string): Promise<string> => Bun.file(path).text();
+
+/** The announcement's text, or `undefined` while its writer still holds it. */
+async function readAnnouncement(
+  path: string,
+  read: (path: string) => Promise<string>,
+): Promise<string | undefined> {
+  try {
+    return await read(path);
+  } catch (error) {
+    if (NOT_YET.has(stringField(error, 'code') ?? '')) return undefined;
+    throw error;
+  }
+}
+
+/**
+ * The port wire: wait for the profile's `DevToolsActivePort`, then dial it. A browser that exits
+ * first is a CLOSED launch and one still silent at the deadline a TIMED-OUT one — the same two
+ * answers the pipe gives, so the launcher's failure report reads alike on either wire.
+ */
+export async function portConnection(input: PortConnectionInput): Promise<CdpConnection> {
+  const path = join(input.profileDir, DEVTOOLS_ACTIVE_PORT);
+  const began = performance.now();
+  for (;;) {
+    // A FRESH handle per look: a `BunFile` that once answered "absent" keeps answering it (measured
+    // on Bun 1.4.2 — `exists()` false and `text()` empty after the file was written).
+    const text = (await Bun.file(path).exists())
+      ? await readAnnouncement(path, input.readText ?? readFile)
+      : undefined;
+    const endpoint = text === undefined ? undefined : devToolsEndpoint(text);
+    const left = input.deadlineMs - (performance.now() - began);
+    if (endpoint !== undefined) return dialWithin(endpoint, Math.max(1, left), input.timeoutMs);
+    if (input.exited()) {
+      throw new CdpCallFailedError({
+        method: 'the launch',
+        detail: `the browser exited before it wrote ${DEVTOOLS_ACTIVE_PORT}`,
+      });
+    }
+    if (left <= 0) {
+      throw new CdpTimeoutError({ method: DEVTOOLS_ACTIVE_PORT, timeoutMs: input.deadlineMs });
+    }
+    await Bun.sleep(Math.min(ANNOUNCE_POLL_MS, left));
+  }
+}