@ultimat3/testing 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -72,19 +72,20 @@ is its own entry point and not part of the barrel.
 | Teardown restores, never uninstalls | `describeApp`/`testApp` capture the seal and the determinism snapshot before booting and put those back |
 | Teardown is a `finally` | an `app.close()` that rejects still reaches `db.drop()` and still restores the process state; the first failure is what the caller sees. |
 | A boot that rejects is its own teardown | `acquireWorkerDatabase`, `seed` or `boot` throwing returns no `BootedHarness`, so no caller can ever reach `close()` |
-| A found template is not a migrated one | `template-db.ts` tolerates "already exists" for the `CREATE DATABASE` alone. `config.migrate` runs unconditionally and un-swallowed |
+| A found template is not a migrated one | `template-db.ts` tolerates "already exists" for the `CREATE DATABASE` alone. `config.migrate` runs unconditionally; drop + clone hold the same lock |
 | Fixture teardown | a fixture that installs process-global state (the ambient job or mail driver) implements `Symbol.dispose` / `Symbol.asyncDispose` and restores what was there |
 | Building one by hand | `createRunJobs()` outside a fixture body is not disposed for you — dispose it in `afterEach`, or the next file inherits your queue and your event bus |
 | Factory strategy | an association is built with the strategy that asked for it: `build()` never reaches a database, `create()` writes the parent first. Never a third strategy |
 | One write seam | `usePersister` is the only place `create()` writes. A factory that took a repo argument would put the seam at every call site |
 | Factory seeds | derived from the table name unless given, so two entities never draw the same uuid stream. `reset()` cascades into associated parents — a half-reset row is worse than none |
 | Shared examples | `behavesLike` calls `describe`, so it goes at declaration scope; bun rejects a `describe` inside a test body |
+| A port's contract is shared examples | `jobDriverConformance`, `budgetStoreConformance` — `behavesLike(…, () => yours)` |
 | An island needs a BUILDER, not an import | `buildIslands` is `@ultimat3/cli`'s and both packages are tier 5; the one declared edge is `cli → testing`, so the reverse is a `bun run boundaries` failure. |
 | `mountIsland` AWAITS `mount` | `IslandEntry['mount']` returns `unknown`, not `void`, and the call is awaited |
 | Dispose STOPS the island, then restores the globals | when `mount` resolved to a function, `[Symbol.dispose]` calls it BEFORE `restore()` |
 | The micro-DOM is the fixture's, once **for islands** | `island-dom.ts`. `packages/ui/src/fake-dom.ts` is a second one for keyboard code, and `ui -> testing` is upward, so it is not a copy to collapse. `bun test` has no DOM and no DOM library may be added |
 | `style` and `classList` RECORD | `FakeStyle` is one declaration map behind all four spellings compiled Solid uses (static attribute, `setProperty`, `cssText`, `removeAttribute`), so a test can assert the component set `--form-gap` |
-| `classList` is the class attribute | not a list of its own, so `classList.toggle` — what the compiler emits INLINE for `classList={{ … }}`, with no runtime helper in front of it — and `className` can never answer one element two ways. |
+| `classList` is the class attribute | not a list of its own, so `classList.toggle` — which the compiler emits INLINE for `classList={{ … }}`, no runtime helper between — and `className` can never answer one element two ways. |
 | A `document` listener is the documentElement's | no bubbling: `document.addEventListener` registers on `documentElement`, and `fire(mounted.documentElement, 'keydown', …)` drives it. One handler per type, last wins |
 | `querySelector` skips `this` | descendants only, as the DOM's does. Matching the element it is called on made a host `<div>` answer `find('div')` with the container the test built rather than the markup the island rendered |
 | The selector grammar is SMALL and REFUSES | `island-selector.ts`: compounds of tag, `#id`, `.class`, `[attr]`, `[attr="value"]`, joined by space or `>`. Anything else is `X_TEST_ISLAND_SELECTOR_UNSUPPORTED` with the offset, never an empty answer |
@@ -102,12 +103,10 @@ is its own entry point and not part of the barrel.
 | Loose in, strict out | `findIslandStates` resolves `Settings`, `settings`, `settings.island.tsx` and the full path to one manifest, and refuses a name nothing answers to by listing EVERY valid one |
 | The disk check is not in `defineIslandStates` | a declaration evaluates wherever it is imported from, so a rule that reads the filesystem at import time fails on the cwd rather than on the path. |
 | The island EXTENSION is not restated here | `.island.tsx` is `@ultimat3/render`'s `ISLAND_EXTENSION` and `render` is not a dependency of this package. |
-| The chunk is imported from a temp FILE | named by its SHA-256, so an edit is a new module and nothing is left in the app. Never a `data:` URL: `bun test --coverage` panics importing one past ~4 kB (Bun 1.4.0); `fixture-island.test.ts` pins it |
-| The scratch directory is lazy and removed | made on the first mount, deleted on `exit`; never at module scope — this module is on the `.` barrel |
+| A mount imports from its own temp DIRECTORY | `island-scratch.ts`: per mount (identical chunks stay two modules); removed on dispose, at the file boundary and in the run's `afterAll` — `exit` never fires under `bun test`. Never a `data:` URL (coverage panics past ~4 kB) |
 | Attaching a node MOVES it | `appendChild`, `insertBefore`, `replaceChild` detach it from its old parent first; `removeChild` clears `parentNode` |
 | Globals install all-or-nothing | `installGlobals` saves DESCRIPTORS, not values — a saved value cannot tell "no such global" from "a global holding `undefined`", and the teardown deleted both |
-| Which command shards | `bun test` is one process on one database, and that is still what a scaffolded app's `test` script runs. |
-
+| Which command shards | `bun test` is one process on one database — what a scaffolded app's `test` script runs |
 
 ## The frozen instant and the seed are screened
 
@@ -145,11 +144,12 @@ lives beside the `PageLike` it implements. `cli` imports it over the declared `c
 | `e2e-errors.ts` | one constructor per refusal |
 | `e2e-dom-fixture.ts` | a document small enough to hold in a test and real enough to RUN the expressions above |
 | `cdp-browser.ts` | the two doors: `openE2eBrowserIfAvailable()` (undefined when there is no browser) and `openE2eBrowser()` (refuses by name), and the close that undoes both halves |
-| `cdp-launch.ts` | which Chrome, and starting it — the candidate list, the flags, and the endpoint read off its stderr |
-| `cdp-connection.ts` | CDP over Bun's own `WebSocket`: request framing, reply correlation by `id`, one-shot event waiters, the per-call deadline |
+| `cdp-launch.ts` | which Chrome, its flags, the launch deadline (`LAUNCH_TIMEOUT_MS`, 60 s — a cold start is not a call) and the ONE relaunch (`LAUNCH_ATTEMPTS`) |
+| `cdp-launch-attempt.ts` | one start: its own process group, the first answer over the pipe; on none, a full reap (group killed, profile removed) before the next. ONE `close()`, a promise, always awaited — no sync close |
+| `cdp-connection.ts` | CDP over a transport — the launched Chrome's pipe (`cdp-pipe.ts`), a remote one's `WebSocket` (`cdpConnect`): reply correlation by `id`, event waiters, the per-call deadline; why one went unanswered is `cdp-wire-watch.ts` |
 | `cdp-e2e-session.ts` | the BROWSER half, `E2eSession`: every target auto-attached at browser level and PAUSED until its Network domain is on (a SharedWorker opens its socket at start-up) |
 | `cdp-e2e-page.ts` | one TAB, `E2eTab`: `E2eBrowserPage`'s five methods plus `reload`, `waitFor`, `indexedDbNames`, `close`. `offline()` forwards to the session — the switch is browser-wide |
-| `e2e-app.ts` | `startE2eApp({ root, mode, seed })`: reset + seed + spawn on a THROWAWAY `ULTIMATE_STATE_DIR` and free ports, `/readyz`-gated, spawned through the app's own `@ultimat3/cli` bin (`xBin`); `stop()` removes the directory |
+| `e2e-app.ts` | `startE2eApp({ root, mode, seed })`: reset + seed + spawn on a THROWAWAY `ULTIMATE_STATE_DIR` and free ports a browser opens (`free-port.ts`), `/readyz`-gated, spawned through the app's own `@ultimat3/cli` bin (`xBin`); `stop()` removes the directory |
 | `failure-context.ts` | a FAILED test's message ends with the e2e app's last 40 log lines (≤ 4 kB): `e2e-run.ts` installs `app.log()`, `fixtureTest` and `e2eTest` append it. Never on a pass |
 | `e2e-preload.ts` + `e2e-browser-handle.ts` | the `e2e` step's preload (`@ultimat3/testing/e2e-preload`): with `ULTIMATE_E2E_ROOT` set it spawns the app, opens ONE browser, installs its first tab, and publishes `e2eBrowser()`, `e2eApp()`, `e2eBaseUrl()` |
 | `packages/cli/src/verify-e2e.ts` | `withE2eApp` (cli's): in an app on a machine with Chrome, the `e2e` step runs the suite with that preload; otherwise exactly as before |

package/README.md

@@ -217,6 +217,14 @@ It registers `page` and nothing else. `budget`, `signIn` and `deploy` keep refus
 browser's own network state and a second build id are not things a page port can answer for, and a
 fixture that silently no-opped would make the assertion after it read as proof.
 
+**A browser call that is never answered says why.** `X_CDP_TIMEOUT` from the connection carries
+`meta.reading` — `target-gone` (session detached, target destroyed or crashed), `lost-in-transport`
+(`meta.framesDropped` frames arrived unparseable after the call) or `no-answer` — beside
+`framesArrived`, `lastFrames` (the last 8), `transportOpen` and `navigations`; `cause` is the
+one-line reading. `E2eSession.offline(false)` rejects with `X_CDP_CALL_FAILED` when a page that is
+still there refuses to take `navigator.onLine` back: the restore is attempted regardless, and the
+page stays in the set.
+
 Each helper prefixes the test name with its type (`job · onboards an org`), which is what
 `bun test --test-name-pattern "job · "` selects — the six lines of `x verify` come from the tests
 themselves, not from a directory convention.
@@ -271,14 +279,36 @@ failure line reads `publishPost > behaves like an authenticated action > denies
 — which subject, and which shared rule. `behavesLike` calls `describe`, so it goes at declaration
 scope, never inside a test body.
 
+Two ship, for the ports an app may implement itself — a `JobDriver` and `@ultimat3/ai`'s
+`BudgetStore`:
+
+```ts
+import { MemoryBudgetStore } from '@ultimat3/ai';
+import { createMemoryDriver } from '@ultimat3/jobs';
+import { behavesLike, budgetStoreConformance, describe, jobDriverConformance } from '@ultimat3/testing';
+
+// The shipped ports pass; put your own driver or store where these are.
+describe('my queue', () => behavesLike(jobDriverConformance, () => createMemoryDriver()));
+describe('my budget store', () => behavesLike(budgetStoreConformance, () => new MemoryBudgetStore()));
+```
+
+| Suite | Holds a store to |
+|---|---|
+| `jobDriverConformance` | claim once · ack/nack fenced on the claim · a live key dedupes · `queues: []` refused · dead-letter never re-claimed · a lapsed lease re-claimed, the loser unable to renew · a lease lapsed on the final attempt buried, reported through `onExhausted` once, `failed` under `dropExhausted` |
+| `budgetStoreConformance` | 24 concurrent `take`s on one key never overspend · a refused take spends nothing · negative `add` · `reset(key)` scoped |
+
+The subject is called once per test. Each check claims from a queue — or counts under a key — of
+its own, so one shared store is enough.
+
 ## Parallel databases
 
 ```ts
 const db = await acquireWorkerDatabase({ adminUrl, migrate });
 ```
 
-The first worker creates the template under a Postgres advisory lock and migrates it once; every
-worker then clones it copy-on-write. With no Postgres configured it falls back to PGlite, so
+The first worker creates the template under a Postgres advisory lock and migrates it; every
+worker then clones it copy-on-write, under the same lock — a clone waits only 5 s for a session on
+the template to leave, and the next worker's migration holds one. With no Postgres configured it falls back to PGlite, so
 `bun test` works on a laptop with nothing installed.
 
 **The gate shards; a bare `bun test` does not.** `As of 2026-08`:
@@ -286,9 +316,9 @@ worker then clones it copy-on-write. With no Postgres configured it falls back t
 | Command | Processes | Worker ids | Databases |
 |---|---|---|---|
 | `bun test` (what a scaffolded app's `test` script still runs) | 1 | `0` | one |
-| `x verify` (`unit`, `contract`, `job`, `eval`; `live` and `e2e` stay serial) | `clamp(round(cpus * 1.5), 2, 8)` | `0..N-1`, from `ULTIMATE_TEST_WORKER` | N |
+| `x verify` (`unit`, `contract`, `job`, `eval`; `live` and `e2e` stay serial) | `clamp(round(cpus * 1.5), 2, 8)` | `1..N`, from Bun's own `BUN_TEST_WORKER_ID` — `0..N-1` from `ULTIMATE_TEST_WORKER` in its coverage run | N |
 | `bun test --parallel[=N]` | N (default: CPU count) | `1..N`, from Bun's own `BUN_TEST_WORKER_ID` | N |
-| `x test --workers N` | N | `0..N-1`, from `ULTIMATE_TEST_WORKER` | N |
+| `x test --workers N` | N | `1..N`, from Bun's own `BUN_TEST_WORKER_ID` | N |
 
 `ULTIMATE_TEST_WORKER` is read first so a runner-assigned shard always beats the index Bun assigns
 its own `--parallel` worker — measured on Bun 1.3.14, `--parallel` populates `BUN_TEST_WORKER_ID`
@@ -678,6 +708,20 @@ This package still owns the vocabulary, the expansion and the refusals, and owns
 capture, the harness page and the crop are `@ultimat3/cli`'s, because `cli → testing` is the
 declared edge and the reverse is a `bun run boundaries` failure.
 
+## Launching Chrome
+
+`launchChrome({ executable, timeoutMs, launchTimeoutMs? })` — what the `e2e` step and `x shot` both
+start a browser with. Driven over `--remote-debugging-pipe`; the first answer is readiness.
+
+| Export | What it is |
+|---|---|
+| `LAUNCH_TIMEOUT_MS` | `60_000` — the first answer's deadline per start. `launchTimeoutMs` defaults to the larger of this and `timeoutMs`; every later call has `timeoutMs` |
+| `LAUNCH_ATTEMPTS` | `2` — an unanswered start is reaped and started once more on a fresh profile. Never more |
+| `CdpLaunchAttempt` | one unanswered start, in `X_CDP_LAUNCH_FAILED`'s `meta.attempts`: `why` (`deadline` \| `closed`), `waitedMs`, `exitCode` (`null` when killed), `stderr` (its last lines) |
+| `LaunchedBrowser.close()` · `E2eBrowser.close()` | THE close, a promise, always awaited: the process, its whole process group, its profile directory. There is no synchronous close |
+
+`As of 2026-10-02`.
+
 ## The one assertion that waits
 
 ```ts
@@ -707,7 +751,7 @@ fails on a page that simply has not painted yet.
 ## Errors
 
 `X_TEST_NETWORK_SEALED` `X_TEST_DB_UNAVAILABLE` `X_TEST_NONDETERMINISTIC` `X_TEST_FIXTURE_UNKNOWN`
-`X_TEST_FACTORY_TRAIT_UNKNOWN` `X_TEST_FACTORY_NOT_PERSISTED` `X_TEST_REGISTRY_LEAK`
+`X_TEST_APP_NOT_BOOTED` `X_TEST_FACTORY_TRAIT_UNKNOWN` `X_TEST_FACTORY_NOT_PERSISTED` `X_TEST_REGISTRY_LEAK`
 `X_TEST_ISLAND_NOT_BUILT` `X_TEST_ISLAND_NO_MOUNT` `X_TEST_ISLAND_SELECTOR_UNSUPPORTED`
 `X_TEST_ISLAND_STATES_EMPTY` `X_TEST_ISLAND_STATE_UNKNOWN`
 `X_TEST_ISLAND_STATES_NOT_PURE` `X_TEST_ISLAND_STATES_MISSING_FILE` `X_TEST_ISLAND_STATES_UNKNOWN`
@@ -722,6 +766,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
+| `AppNotBootedError` | `X_TEST_APP_NOT_BOOTED` | `src/errors.ts` |
 | `FixtureUnavailableError` | `X_TEST_FIXTURE_UNAVAILABLE` | `src/errors.ts` |
 | `NetworkOfflineError` | `X_TEST_NETWORK_OFFLINE` | `src/errors.ts` |
 | `NetworkSealedError` | `X_TEST_NETWORK_SEALED` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "23.0.0",
+  "version": "24.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -36,19 +36,19 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "23.0.0",
-    "@ultimat3/cache": "23.0.0",
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/db": "23.0.0",
-    "@ultimat3/entity": "23.0.0",
-    "@ultimat3/http": "23.0.0",
-    "@ultimat3/i18n": "23.0.0",
-    "@ultimat3/jobs": "23.0.0",
-    "@ultimat3/mail": "23.0.0",
-    "@ultimat3/policy": "23.0.0",
-    "@ultimat3/query": "23.0.0",
-    "@ultimat3/realtime": "23.0.0",
-    "@ultimat3/render": "23.0.0",
-    "@ultimat3/time": "23.0.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/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 } }),
     });
   }
 }