@ultimat3/testing 22.15.0 → 24.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -35,18 +36,19 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "22.15.0",
-    "@ultimat3/cache": "22.15.0",
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/db": "22.15.0",
-    "@ultimat3/entity": "22.15.0",
-    "@ultimat3/i18n": "22.15.0",
-    "@ultimat3/jobs": "22.15.0",
-    "@ultimat3/mail": "22.15.0",
-    "@ultimat3/policy": "22.15.0",
-    "@ultimat3/query": "22.15.0",
-    "@ultimat3/realtime": "22.15.0",
-    "@ultimat3/render": "22.15.0",
-    "@ultimat3/time": "22.15.0"
+    "@ultimat3/action": "24.0.0",
+    "@ultimat3/cache": "24.0.0",
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/db": "24.0.0",
+    "@ultimat3/entity": "24.0.0",
+    "@ultimat3/http": "24.0.0",
+    "@ultimat3/i18n": "24.0.0",
+    "@ultimat3/jobs": "24.0.0",
+    "@ultimat3/mail": "24.0.0",
+    "@ultimat3/policy": "24.0.0",
+    "@ultimat3/query": "24.0.0",
+    "@ultimat3/realtime": "24.0.0",
+    "@ultimat3/render": "24.0.0",
+    "@ultimat3/time": "24.0.0"
   }
 }

package/src/auth-request.ts

@@ -0,0 +1,54 @@
+// `authRequest()` — the two arguments `hooks.authenticate` is handed, built the way the pipeline
+// builds them, so a test of an app's authenticator calls it with no server and no cast.
+// `@ultimat3/http` is imported INSIDE the function: this module is on the `.` barrel, which a
+// tier-0 test imports for `expect` alone.
+
+import type { Authenticator } from '@ultimat3/http';
+
+/** What an authenticator reads off a request: where it came in, and the credentials it carries. */
+export interface AuthRequestInit {
+  /** The URL the request names. `https://example.test/` when absent. */
+  readonly url?: string;
+  /** `GET` when absent. */
+  readonly method?: string;
+  /** Any header. `cookies` and `bearer` below win over the same header spelled here. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Cookies by name, sent as the ONE `cookie` header a browser sends, values percent-encoded. */
+  readonly cookies?: Readonly<Record<string, string>>;
+  /** `Authorization: Bearer <token>`. */
+  readonly bearer?: string;
+}
+
+const DEFAULT_URL = 'https://example.test/';
+
+/**
+ * The authenticator's own parameter list — `await authenticate(...(await authRequest({ cookies })))`
+ * — as a real `UltimateRequest` over a real `RequestContext`. Typed off `Authenticator`, so a
+ * third parameter on the hook is a compile error here rather than an `undefined` in a test.
+ *
+ * The context is the one the `auth` stage sees: the actor is still anonymous, because resolving
+ * it is the function under test.
+ */
+export async function authRequest(init: AuthRequestInit = {}): Promise<Parameters<Authenticator>> {
+  const http = await import('@ultimat3/http');
+  const url = new URL(init.url ?? DEFAULT_URL);
+  const method = (init.method ?? 'GET').toUpperCase();
+  const headers = new Headers(init.headers);
+  const cookies = Object.entries(init.cookies ?? {});
+  if (cookies.length > 0) {
+    headers.set(
+      'cookie',
+      cookies.map(([name, value]) => `${name}=${encodeURIComponent(value)}`).join('; '),
+    );
+  }
+  if (init.bearer !== undefined) headers.set('authorization', `Bearer ${init.bearer}`);
+  const ctx = http.createRequestContext({
+    url,
+    method,
+    role: 'web',
+    // One process, one test: the limiter's scope has no default, and nothing here spends a bucket.
+    config: http.defineHttpConfig({ rateLimit: { scope: 'process' } }),
+    requestHeaders: headers,
+  });
+  return [new http.UltimateRequest(new Request(url, { method, headers }), ctx), ctx];
+}

package/src/budget-store-conformance.ts

@@ -0,0 +1,81 @@
+// The `BudgetStore` contract of `@ultimat3/ai` as shared examples, for a store of your own (Redis,
+// SQL): `behavesLike(budgetStoreConformance, () => store)`. The race is the point — `take` is the
+// one atomic step, and a store that awaits between its read and its write overspends under it.
+// Structural, so this package takes no dependency on `ai`: a `BudgetStore` is assignable.
+
+import { expect, test } from 'bun:test';
+import type { SharedExamples } from './shared-examples';
+import { sharedExamples } from './shared-examples';
+
+type Maybe<T> = T | Promise<T>;
+
+/** The four members of `@ultimat3/ai`'s `BudgetStore`, structurally. */
+export interface BudgetStoreLike {
+  spent(key: string): Maybe<number>;
+  add(key: string, tokens: number): Maybe<void>;
+  take(key: string, tokens: number, limit: number): Maybe<{ readonly taken: boolean }>;
+  reset(key?: string): Maybe<void>;
+}
+
+export interface BudgetStoreCheck {
+  readonly name: string;
+  run(store: BudgetStoreLike): Promise<void>;
+}
+
+/** Concurrent takers, and the ceiling only some of them fit under. */
+const BUDGET_RACE_TAKERS = 24;
+const RACE_LIMIT = 5;
+
+let minted = 0;
+const keyOf = (): string => {
+  minted += 1;
+  return `conformance:${process.pid.toString(36)}:${minted.toString(36)}`;
+};
+
+export const BUDGET_STORE_CHECKS: readonly BudgetStoreCheck[] = [
+  {
+    name: `${BUDGET_RACE_TAKERS} concurrent takes against one key never overspend the limit`,
+    async run(store) {
+      const key = keyOf();
+      const takes = Array.from({ length: BUDGET_RACE_TAKERS }, async () =>
+        store.take(key, 1, RACE_LIMIT),
+      );
+      const taken = (await Promise.all(takes)).filter((each) => each.taken).length;
+      expect([taken, await store.spent(key)]).toEqual([RACE_LIMIT, RACE_LIMIT]);
+    },
+  },
+  {
+    name: 'a refused take spends nothing, and a take that fits exactly is taken',
+    async run(store) {
+      const key = keyOf();
+      expect((await store.take(key, 3, 4)).taken).toBe(true);
+      expect((await store.take(key, 2, 4)).taken).toBe(false);
+      expect(await store.spent(key)).toBe(3);
+      expect((await store.take(key, 1, 4)).taken).toBe(true);
+      expect(await store.spent(key)).toBe(4);
+    },
+  },
+  {
+    name: 'add takes a negative credit, and reset(key) clears that key alone',
+    async run(store) {
+      const [key, other] = [keyOf(), keyOf()];
+      await store.add(key, 5);
+      await store.add(key, -2);
+      await store.add(other, 1);
+      expect(await store.spent(key)).toBe(3);
+      await store.reset(key);
+      expect([await store.spent(key), await store.spent(other)]).toEqual([0, 1]);
+    },
+  },
+];
+
+export const budgetStoreConformance: SharedExamples<Maybe<BudgetStoreLike>> = sharedExamples(
+  'a budget store',
+  (subject) => {
+    for (const check of BUDGET_STORE_CHECKS) {
+      test(check.name, async () => {
+        await check.run(await subject());
+      });
+    }
+  },
+);

package/src/cdp-browser.ts

@@ -27,13 +27,12 @@ export interface E2eBrowser {
    * drives, on the same launch as `page` — one harness, never a second one beside the driver.
    */
   readonly session: E2eSession;
-  /** Idempotent, and it closes both halves: the CDP socket, then the process and its profile. */
-  close(): void;
   /**
-   * `close()`, resolving once the process has exited (bounded — `CLOSE_GRACE_MS`, then SIGKILL).
-   * Optional so a test double need not model a process; the launched browser always has it.
+   * THE close, idempotent, awaited: the CDP connection, then the process, its process group and its
+   * profile (bounded — `CLOSE_GRACE_MS` per step). Unawaited, a process that exits next leaves a
+   * Chrome child and a profile directory behind.
    */
-  closed?(): Promise<void>;
+  close(): Promise<void>;
 }
 
 export interface OpenE2eBrowserOptions {
@@ -60,10 +59,6 @@ const compose = (launched: LaunchedBrowser, session: E2eSession, page: E2eTab):
   // the process out from under an open connection makes every in-flight call report "the browser
   // closed the CDP connection", which is true and useless.
   close: () => launched.close(),
-  closed: async () => {
-    if (launched.closed === undefined) launched.close();
-    else await launched.closed();
-  },
 });
 
 /**
@@ -107,7 +102,7 @@ async function openLaunched(
     });
     return compose(launched, session, await session.newTab());
   } catch (error) {
-    launched.close();
+    await launched.close();
     throw error;
   }
 }

package/src/cdp-connection.ts

@@ -13,6 +13,7 @@
 
 import { assert } from '@ultimat3/core';
 import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
+import { wireWatch } from './cdp-wire-watch';
 
 /** One CDP result. `unknown` because every payload here is somebody else's JSON. */
 export interface CdpResult {
@@ -20,8 +21,17 @@ export interface CdpResult {
 }
 
 export interface CdpConnection {
-  /** Send one command. `sessionId` targets an attached page rather than the browser itself. */
-  send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<CdpResult>;
+  /**
+   * Send one command. `sessionId` targets an attached page rather than the browser itself.
+   * `deadlineMs` replaces the connection's per-call deadline for THIS call — the launcher's first
+   * call is a cold start, not a call, and is the only caller that passes one.
+   */
+  send(
+    method: string,
+    params?: Record<string, unknown>,
+    sessionId?: string,
+    deadlineMs?: number,
+  ): Promise<CdpResult>;
   /**
    * Wait for the next occurrence of one CDP **event**, or for the deadline. Answers `true` when the
    * event arrived and `false` when it did not — it never throws, because every caller has a better
@@ -145,6 +155,8 @@ export function cdpConnectOver(transport: CdpTransport, timeoutMs: number): CdpC
   const listeners = new Map<string, Set<CdpEventListener>>();
   let nextId = 0;
   let closed = false;
+  // What a call that is never answered reports instead of a bare "did not answer".
+  const watch = wireWatch();
 
   // Every in-flight call is settled on close. Without this a suite whose browser died waits out
   // one full deadline per call and reports a timeout, where the true fault is a dead browser.
@@ -167,9 +179,12 @@ export function cdpConnectOver(transport: CdpTransport, timeoutMs: number): CdpC
       frame = JSON.parse(raw) as Record<string, unknown>;
     } catch {
       // An unparseable frame is the browser's, not ours, and there is no call to fail with it:
-      // correlation is by `id`, and a frame we cannot read has none. Events land here too.
+      // correlation is by `id`, and a frame we cannot read has none. COUNTED, though: the call
+      // whose reply it was waits out its deadline, and its timeout says frames were dropped.
+      watch.drop();
       return;
     }
+    watch.frame(frame);
     const id = frame['id'];
     if (typeof id !== 'number') {
       const method = frame['method'];
@@ -206,7 +221,7 @@ export function cdpConnectOver(transport: CdpTransport, timeoutMs: number): CdpC
   transport.listen({ message, closed: abandon });
 
   return {
-    send(method, params = {}, sessionId): Promise<CdpResult> {
+    send(method, params = {}, sessionId, deadlineMs = timeoutMs): Promise<CdpResult> {
       if (closed) {
         return Promise.reject(
           new CdpCallFailedError({ method, detail: 'the CDP connection is already closed' }),
@@ -215,10 +230,12 @@ export function cdpConnectOver(transport: CdpTransport, timeoutMs: number): CdpC
       nextId += 1;
       const id = nextId;
       return new Promise<CdpResult>((resolve, reject) => {
+        const sentAt = watch.mark(sessionId);
         const timer = setTimeout(() => {
           pending.delete(id);
-          reject(new CdpTimeoutError({ method, timeoutMs: timeoutMs }));
-        }, timeoutMs);
+          const observed = watch.observe(sentAt, sessionId, !closed);
+          reject(new CdpTimeoutError({ method, timeoutMs: deadlineMs, observed }));
+        }, deadlineMs);
         pending.set(id, { resolve, reject, timer });
         transport.send(
           JSON.stringify({ id, method, params, ...(sessionId === undefined ? {} : { sessionId }) }),

package/src/cdp-e2e-session.ts

@@ -155,10 +155,19 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
     }
     // And `navigator.onLine` from a new document's first script (`cdp-offline-script.ts`) — the
     // network condition alone reaches a reloaded page only after its scripts have run.
+    // A page that is still THERE and refuses is kept and reported once every page has been asked:
+    // dropping it meant every later `offline()` skipped that tab in silence. Only a session the
+    // loop above just found gone is dropped — a closed tab refuses every call.
+    const refused: unknown[] = [];
     for (const session of [...pageSessions]) {
+      if (!sessions.has(session)) {
+        pageSessions.delete(session);
+        continue;
+      }
       const toggled = enabled ? onLineScripts.add(session) : onLineScripts.remove(session);
-      await toggled.catch(() => pageSessions.delete(session));
+      await toggled.catch((error: unknown) => refused.push(error));
     }
+    if (refused.length > 0) throw refused[0];
   };
 
   const attached = async (targetId: string): Promise<string> => {

package/src/cdp-errors.ts

@@ -2,7 +2,7 @@
 // out of a BROWSER or off a spawned process's stderr, so every one is rendered rather than
 // interpolated — the rule `e2e-errors.ts` already states.
 
-import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import { isFixShellSafe, renderCauseValue, UltimateError } from '@ultimat3/core';
 // Bare: the titles these constructors' codes render with are registered there.
 import './e2e-error-codes';
 
@@ -20,13 +20,50 @@ export class CdpBrowserMissingError extends UltimateError {
   }
 }
 
-/** The binary ran and never announced an endpoint — a crash, a bad flag, or a sandbox refusal. */
+/** One start of the browser that ended without an answer — what `cdp-launch-attempt.ts` reports. */
+export interface CdpLaunchAttempt {
+  /** `deadline`: alive and silent for `waitedMs`. `closed`: its pipe ended before any answer. */
+  readonly why: 'deadline' | 'closed';
+  readonly waitedMs: number;
+  /** The code it exited with on its own, or `null` when the launcher had to kill it. */
+  readonly exitCode: number | null;
+  /** The last lines it wrote to stderr; empty when it wrote none. */
+  readonly stderr: string;
+}
+
+const HAND_FLAGS =
+  '--headless=new --no-sandbox --disable-dev-shm-usage --disable-gpu --remote-debugging-port=0 about:blank';
+
+const attemptText = (attempt: CdpLaunchAttempt, index: number): string => {
+  const ended =
+    attempt.why === 'deadline'
+      ? `no answer inside ${String(attempt.waitedMs)}ms, so it was killed`
+      : attempt.exitCode === null
+        ? `closed its DevTools pipe after ${String(attempt.waitedMs)}ms without answering, and was killed`
+        : `exited with code ${String(attempt.exitCode)} after ${String(attempt.waitedMs)}ms without answering`;
+  const said = attempt.stderr === '' ? 'it printed nothing' : renderCauseValue(attempt.stderr);
+  return `launch ${String(index + 1)}: ${ended}; stderr: ${said}`;
+};
+
+/**
+ * The binary ran and never answered a DevTools call — a crash, a bad flag, a sandbox refusal, or a
+ * machine too loaded to start it inside the launch deadline. Every attempt is in the cause with its
+ * own stderr, because Chrome's start-up noise reads the same in a healthy browser and a dead one:
+ * what tells them apart is whether it EXITED or was still starting when the deadline passed.
+ */
 export class CdpLaunchFailedError extends UltimateError {
-  constructor(input: { readonly executable: string; readonly detail: string }) {
+  constructor(input: {
+    readonly executable: string;
+    readonly attempts: readonly CdpLaunchAttempt[];
+  }) {
+    // Run by hand, a healthy Chrome prints `DevTools listening on ws://…` and a broken one prints
+    // why. A path that is not shell-inert is the operator's own CHROME_PATH — every candidate is.
+    const binary = isFixShellSafe(input.executable) ? input.executable : '"$CHROME_PATH"';
     super({
       code: 'X_CDP_LAUNCH_FAILED',
-      cause: `${renderCauseValue(input.executable)} did not announce a DevTools endpoint: ${renderCauseValue(input.detail)}`,
-      fix: 'run the same binary by hand with --headless=new --remote-debugging-port=0 and read its stderr; inside a container add --no-sandbox --disable-dev-shm-usage, which this launcher already passes',
+      cause: `${renderCauseValue(input.executable)} did not announce a DevTools endpoint: it answered no DevTools call in ${String(input.attempts.length)} ${input.attempts.length === 1 ? 'launch' : 'launches, each on its own fresh profile'} — ${input.attempts.map(attemptText).join(' · ')}`,
+      fix: `${binary} ${HAND_FLAGS}`,
+      meta: { executable: input.executable, attempts: input.attempts },
     });
   }
 }
@@ -42,17 +79,85 @@ export class CdpCallFailedError extends UltimateError {
   }
 }
 
+/** How a call's target went away: its session detached, its target was destroyed, or it crashed. */
+export type CdpTargetGone = 'detached' | 'destroyed' | 'crashed';
+
+/** What the wire did between a call being sent and its deadline (`cdp-wire-watch.ts`). */
+export interface CdpTimeoutObservation {
+  /** The session the call was sent on; `null` for a browser-level call. */
+  readonly sessionId: string | null;
+  /** Frames that arrived and parsed after the call was sent — replies to other calls, and events. */
+  readonly framesArrived: number;
+  /** The last of those, oldest first, bounded: `reply <id>`, or `<method> @<session>`. */
+  readonly lastFrames: readonly string[];
+  /** Frames that arrived after the call and could not be parsed. One of them may be its reply. */
+  readonly framesDropped: number;
+  readonly transportOpen: boolean;
+  /** `detached`, `destroyed` or `crashed` when the call's target went away; `null` while it is there. */
+  readonly targetGone: CdpTargetGone | null;
+  /** Main-frame navigations on the call's session since it was sent. */
+  readonly navigations: number;
+}
+
+/** The one-word verdict a reader — or a script over `--json` — branches on. */
+export type CdpTimeoutReading = 'target-gone' | 'lost-in-transport' | 'no-answer';
+
+export const readTimeout = (seen: CdpTimeoutObservation): CdpTimeoutReading =>
+  seen.targetGone !== null
+    ? 'target-gone'
+    : seen.framesDropped > 0
+      ? 'lost-in-transport'
+      : 'no-answer';
+
+const READING: Record<CdpTimeoutReading, (seen: CdpTimeoutObservation) => string> = {
+  'target-gone': (seen) =>
+    `its target is gone (${String(seen.targetGone)}), so nothing was left to answer`,
+  'lost-in-transport': (seen) =>
+    `${String(seen.framesDropped)} frame(s) arrived unparseable after it was sent and were dropped, so its reply may have been lost in transport (${String(seen.framesArrived)} other frame(s) arrived intact)`,
+  'no-answer': (seen) => {
+    if (seen.framesArrived === 0) {
+      return `nothing at all arrived after the call was sent, on a transport that is ${seen.transportOpen ? 'still open' : 'closed'} — the whole browser went silent`;
+    }
+    const moved =
+      seen.navigations === 0
+        ? ''
+        : `; the page navigated ${String(seen.navigations)} time(s) since the call`;
+    return `the target did not answer: ${String(seen.framesArrived)} other frame(s) arrived intact after the call, the last ${renderCauseValue(seen.lastFrames)}${moved}`;
+  },
+};
+
 /**
  * A call that never answered. Its own code rather than `X_TIMEOUT`, because the actionable half is
  * WHICH call: a hung `Page.navigate` is an app that never finishes responding, and a hung
  * `Runtime.evaluate` is an expression that never settles.
+ *
+ * `observed` is what the connection saw meanwhile, and it is what tells three failures apart that
+ * all read "did not answer": the target went away, the reply was dropped on the wire, or the target
+ * was there and silent. A deadline the connection did not keep (`waitFor`, the handshake) has none.
  */
 export class CdpTimeoutError extends UltimateError {
-  constructor(input: { readonly method: string; readonly timeoutMs: number }) {
+  constructor(input: {
+    readonly method: string;
+    readonly timeoutMs: number;
+    readonly observed?: CdpTimeoutObservation | undefined;
+  }) {
+    const { observed } = input;
+    const base = `${renderCauseValue(input.method)} did not answer inside ${String(input.timeoutMs)}ms`;
+    const reading = observed === undefined ? undefined : readTimeout(observed);
     super({
       code: 'X_CDP_TIMEOUT',
-      cause: `${renderCauseValue(input.method)} did not answer inside ${String(input.timeoutMs)}ms`,
-      fix: 'raise timeoutMs on installE2eDriver({ timeoutMs }), or find the request the page is still waiting on — a navigation that never settles is an app that never finishes its response',
+      cause:
+        observed === undefined || reading === undefined
+          ? base
+          : `${base} — ${READING[reading](observed)}`,
+      fix:
+        reading === undefined || reading === 'no-answer'
+          ? 'raise timeoutMs on installE2eDriver({ timeoutMs }), or find the request the page is still waiting on — a navigation that never settles is an app that never finishes its response'
+          : // `--json`: the rerun's `meta.reading` and `meta.framesDropped` are only printed there.
+            'x test e2e --json',
+      ...(observed === undefined
+        ? {}
+        : { meta: { method: input.method, timeoutMs: input.timeoutMs, reading, ...observed } }),
     });
   }
 }

package/src/cdp-launch-attempt.ts

@@ -0,0 +1,192 @@
+// 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`.
+
+// why: Bun exposes no recursive-remove and no temp-root primitive, so the throwaway profile
+// directory this launcher must create and delete needs both.
+import { mkdtempSync, 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 { join } from 'node:path';
+import type { CdpConnection } from './cdp-connection';
+import { cdpConnectOver } from './cdp-connection';
+import type { CdpLaunchAttempt } from './cdp-errors';
+import { CdpTimeoutError } from './cdp-errors';
+import { pipeTransport } from './cdp-pipe';
+
+export interface LaunchedBrowser {
+  /** The browser's own CDP connection, over its debugging pipe. 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 the profile removed —
+   * bounded at three graces. 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[];
+  /** 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;
+
+/** How long a closed Chrome gets to exit on SIGTERM before it is killed outright. */
+export const CLOSE_GRACE_MS = 5_000;
+
+const within = (ms: number, work: Promise<unknown>): Promise<unknown> =>
+  Promise.race([work, Bun.sleep(ms)]);
+
+const GROUP_POLL_MS = 10;
+
+/**
+ * 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.
+ */
+async function reapGroup(pgid: number): Promise<void> {
+  try {
+    process.kill(-pgid, 'SIGKILL');
+    for (let looks = CLOSE_GRACE_MS / GROUP_POLL_MS; looks > 0; looks -= 1) {
+      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.
+  }
+}
+
+/**
+ * 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 profileDir = mkdtempSync(join(tmpdir(), 'x-e2e-chrome-'));
+  const removeProfile = (): void => {
+    try {
+      rmSync(profileDir, { recursive: true, force: true });
+    } catch {
+      // A throwaway directory that will not go is litter, never the launch's or the close's verdict.
+    }
+  };
+  const began = performance.now();
+  const child = Bun.spawn([options.executable, ...options.flags(profileDir)], {
+    // Chrome's fd 3 is where it READS commands and fd 4 where it WRITES replies and events.
+    stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
+    // Its own process GROUP, so the zygote, GPU and network processes can be reaped with it
+    // (`reapGroup`). It still ends with this process: Chrome exits when its fd 3 closes.
+    detached: true,
+  });
+  const tail = stderrTail(child.stderr as ReadableStream<Uint8Array>);
+  const [, , , toBrowser, fromBrowser] = child.stdio as unknown as readonly number[];
+  const sink = Bun.file(toBrowser ?? -1).writer();
+  const connection = cdpConnectOver(
+    pipeTransport({
+      write: (bytes) => {
+        sink.write(bytes);
+        void sink.flush();
+      },
+      read: Bun.file(fromBrowser ?? -1).stream(),
+      end: () => {
+        void Promise.resolve(sink.end()).catch(() => undefined);
+      },
+    }),
+    options.timeoutMs,
+  );
+  let exiting: Promise<void> | undefined;
+  const close = (): Promise<void> => {
+    exiting ??= (async () => {
+      connection.close();
+      child.kill();
+      removeProfile();
+      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 reapGroup(child.pid);
+      // Again, now that nothing is writing: Chrome's network process outlives the browser process
+      // and flushes into the profile, re-creating a directory removed a moment before. Measured on
+      // Chrome 150, 30 launches each: left behind 6 and 12 times without the group reap, 0 with.
+      removeProfile();
+    })();
+    return exiting;
+  };
+  try {
+    await connection.send('Browser.getVersion', {}, undefined, options.launchTimeoutMs);
+    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,
+      failure: { why, waitedMs, exitCode, stderr: tail.lastLines() },
+      reaped: child.exitCode !== null || child.signalCode !== null,
+    };
+  }
+}