@ultimat3/scraping 30.8.0 → 31.0.0

package/src/cdp-launch-attempt.ts

@@ -0,0 +1,234 @@
+// 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;
+  /**
+   * The longest the browser may live at all, from its spawn: past it the OS process is killed
+   * (`SIGKILL`) even if no `close()` ever ran — a caller that crashed, a hook Bun cut short. The
+   * normal end is still `close()`; this is the bound the spawn-timeout guard asks for.
+   */
+  readonly lifetimeMs: 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',
+    // A backstop, never the close: `close()` ends a browser its caller is done with. This ends one
+    // whose caller vanished, so no Chrome outlives every reason it was started for.
+    timeout: options.lifetimeMs,
+    killSignal: 'SIGKILL',
+  });
+}

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-probe.ts

@@ -0,0 +1,75 @@
+// One responsibility: whether a candidate Chrome is one this machine can START — `--version`, under
+// a deadline of its own. Which candidates are tried, and in what order, is `cdp-launch.ts`.
+
+/**
+ * The longest a candidate gets to answer `--version`. A warm Chrome answers in ~40 ms; a cold binary
+ * on a loaded runner is the slow case, and one that has not answered by then is not a browser this
+ * run can drive. Its own number, never the launch deadline: this is spent BEFORE one.
+ */
+export const CHROME_PROBE_TIMEOUT_MS = 15_000;
+
+/**
+ * A browser banner: a product this launcher can drive, then a dotted version.
+ *
+ * Read only when the candidate PRINTED something. `--version` is not a browser's alone — `bun
+ * --version` exits 0 and prints `1.4.4` — so output that names no browser is output from something
+ * that is not one. Silence is the other case, and it is accepted: a browser that starts and stops
+ * cleanly saying nothing judges nothing it was not told.
+ */
+const BROWSER_BANNER = /(?:chrome|chromium|edge)[^\n]*?\d+\.\d+/i;
+
+/**
+ * Whether `candidate` is a browser this machine can actually START — not merely a file that exists.
+ *
+ * The two are not the same, and the difference is a whole red gate: Ubuntu 24.04 ships
+ * `/usr/bin/chromium-browser` as a shell wrapper around `snap`, which is present and executable on
+ * every install and which exits 1 having started nothing where no snap cgroup exists (`is not a snap
+ * cgroup for tag snap.chromium.chromium`, measured 2026-11). A candidate that cannot start is an
+ * ABSENT candidate: the browser-backed suites' headers promise a SKIP, not `X_CDP_LAUNCH_FAILED`.
+ *
+ * NOT RUN on `win32`, where existence is the answer: `chrome.exe` is a GUI binary, and `--version`
+ * there opens a browser and never exits — #1033's Windows job spent 15 s on each of two candidates
+ * and timed out the test that asked. The snap wrapper this probe exists for is Linux-only.
+ *
+ * TOTAL: a candidate that cannot be spawned, dies, misses the deadline, or PRINTS something that
+ * names no browser is `false`, never a throw. One deadline covers the exit AND the banner: a
+ * grandchild that inherits stdout holds the pipe open past the child's own exit.
+ */
+export async function startsChrome(
+  candidate: string,
+  platform: string,
+  timeoutMs: number = CHROME_PROBE_TIMEOUT_MS,
+): Promise<boolean> {
+  if (platform === 'win32') return true;
+  let child: ReturnType<typeof Bun.spawn>;
+  try {
+    // `timeout:` is Bun's own kill at the deadline, so a probe this function stopped waiting on
+    // is never left running.
+    child = Bun.spawn([candidate, '--version'], {
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'ignore',
+      timeout: timeoutMs,
+    });
+  } catch {
+    return false;
+  }
+  const banner = new Response(child.stdout as ReadableStream<Uint8Array>).text().catch(() => '');
+  const answered = child.exited.then(async (code) =>
+    code === 0 ? (await banner).trim() : undefined,
+  );
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<undefined>((resolve) => {
+    // real-clock: bounds a spawned process, not a timer a test arms.
+    timer = setTimeout(() => resolve(undefined), timeoutMs);
+  });
+  try {
+    const printed = await Promise.race([answered, deadline]);
+    if (printed === undefined) return false;
+    return printed === '' || BROWSER_BANNER.test(printed);
+  } finally {
+    clearTimeout(timer);
+    // A probe that timed out is still a live process; one that exited ignores this.
+    child.kill();
+  }
+}

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 `settleMs` (`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, settleMs?: 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, settleMs = PROFILE_SETTLE_MS) {
+      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(settleMs / 5);
+          continue;
+        }
+        // Gone NOW is not gone: the look after the settle is what a late writer fails.
+        await Bun.sleep(settleMs);
+        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.
+  }
+}