@ultimat3/testing 22.15.0 → 24.0.0

package/src/cdp-launch.ts

@@ -1,17 +1,15 @@
-// One responsibility: start a Chrome in this container and hand back its DevTools endpoint and the
-// way to stop it. The connection is `cdp-connection.ts` and the page surface `cdp-e2e-page.ts`.
+// One responsibility: WHICH Chrome, with which flags, and how many starts it gets — the candidate
+// list, the launch deadline and the one relaunch. One start of the process is
+// `cdp-launch-attempt.ts`; the connection is `cdp-connection.ts`, the page `cdp-e2e-page.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 { finiteCount } from '@ultimat3/core';
+import type { CdpLaunchAttempt } from './cdp-errors';
 import { CdpBrowserMissingError, CdpLaunchFailedError } from './cdp-errors';
-import { pipeTransport } from './cdp-pipe';
+import type { LaunchedBrowser } from './cdp-launch-attempt';
+import { launchAttempt } from './cdp-launch-attempt';
+
+export type { LaunchedBrowser } from './cdp-launch-attempt';
+export { CLOSE_GRACE_MS } from './cdp-launch-attempt';
 
 /**
  * Where a Chrome is, in the order worth trying. `CHROME_PATH` first because it is the operator's
@@ -81,130 +79,59 @@ export const chromeLaunchFlags = (profileDir: string): readonly string[] => [
   'about:blank',
 ];
 
-export interface LaunchedBrowser {
-  /** The browser's own CDP connection, over its debugging pipe. Already answering. */
-  readonly connection: CdpConnection;
-  /** Idempotent: closes the connection, kills the process, deletes the profile. */
-  close(): void;
-  /**
-   * `close()`, then resolves once the process has EXITED — SIGTERM, then SIGKILL after
-   * `CLOSE_GRACE_MS`, never waiting longer than twice that. What a suite's `afterAll` awaits: a
-   * Chrome told to die but still shutting down competes with the next suite's launch on a 4-CPU
-   * runner, and one still running keeps the test process from exiting at all. Optional so a test
-   * double of a launch need not model a process; `launchChrome` always provides it.
-   */
-  closed?(): Promise<void>;
-}
-
-export interface LaunchOptions {
-  readonly executable: string;
-  /** How long Chrome has to answer its first call, and every call's deadline after that. */
-  readonly timeoutMs: number;
-}
-
-const STDERR_TAIL_CHARS = 4_000;
-
 /**
- * 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.
+ * How long a COLD start may take before the browser is given up on. Its own number, never the
+ * per-call deadline: measured 2026-10-02 over `scaffold-smoke` on free `ubuntu-latest` runners, the
+ * first launch of a job cost 5-19 s more than a warm one in 11 green jobs, and the one red job was
+ * still printing start-up lines when a 30 s deadline killed it. Twice that, and finite: a browser
+ * that exits says so at once (its pipe closes), so only one alive and silent waits this long.
  */
-function stderrTail(stream: ReadableStream<Uint8Array>): {
-  readonly text: () => 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);
-  return { text: () => text, drained };
-}
+export const LAUNCH_TIMEOUT_MS = 60_000;
 
 /**
- * How long a browser that failed its first call gets to finish dying, and its 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.
+ * Starts per launch: the first, and ONE more on a fresh profile after the first was reaped. A
+ * process start is the one step here whose failure can belong to the machine rather than the
+ * binary — and the second start of a cold binary is a warm one. Never a loop: two starts that both
+ * went unanswered are `X_CDP_LAUNCH_FAILED` carrying both.
  */
-const FAILURE_DRAIN_MS = 1_000;
+export const LAUNCH_ATTEMPTS = 2;
 
-/** 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)]);
+export interface LaunchOptions {
+  readonly executable: string;
+  /** Every CDP call's deadline once the browser is up. */
+  readonly timeoutMs: number;
+  /** The first answer's deadline, per start. Defaults to the larger of `timeoutMs` and `LAUNCH_TIMEOUT_MS`. */
+  readonly launchTimeoutMs?: number | undefined;
+}
 
 /**
- * Start Chrome on a throwaway profile and answer once 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, and
- * a browser that dies or stays silent before it is `X_CDP_LAUNCH_FAILED` carrying its own stderr.
+ * Start Chrome on a throwaway profile and answer once it has answered one CDP call. A browser that
+ * dies or stays silent is started once more; twice is `X_CDP_LAUNCH_FAILED` with each start's own
+ * stderr and whether it exited or was killed at the deadline.
  */
 export async function launchChrome(options: LaunchOptions): Promise<LaunchedBrowser> {
-  const profileDir = mkdtempSync(join(tmpdir(), 'x-e2e-chrome-'));
-  const child = Bun.spawn([options.executable, ...chromeLaunchFlags(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'],
-  });
-  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,
+  // Screened: `setTimeout(fn, NaN)` fires in 1 ms, which reports a healthy browser as silent.
+  const launchTimeoutMs = finiteCount(
+    'launchChrome',
+    'launchTimeoutMs',
+    options.launchTimeoutMs ?? Math.max(options.timeoutMs, LAUNCH_TIMEOUT_MS),
+    1,
   );
-  let closed = false;
-  const close = (): void => {
-    if (closed) return;
-    closed = true;
-    connection.close();
-    child.kill();
-    rmSync(profileDir, { recursive: true, force: true });
-  };
-  let exiting: Promise<void> | undefined;
-  const closeAndWait = (): Promise<void> => {
-    close();
-    exiting ??= (async () => {
-      const exited =
-        (await within(
-          CLOSE_GRACE_MS,
-          child.exited.then(() => true),
-        )) === true;
-      if (exited) return;
-      child.kill('SIGKILL');
-      await within(CLOSE_GRACE_MS, child.exited);
-    })();
-    return exiting;
-  };
-  try {
-    await connection.send('Browser.getVersion');
-    return { connection, close, closed: closeAndWait };
-  } catch {
-    await within(FAILURE_DRAIN_MS, child.exited);
-    close();
-    await within(FAILURE_DRAIN_MS, tail.drained);
-    const seen = tail.text().trim();
-    throw new CdpLaunchFailedError({
+  const failures: CdpLaunchAttempt[] = [];
+  while (failures.length < LAUNCH_ATTEMPTS) {
+    const started = await launchAttempt({
       executable: options.executable,
-      detail:
-        seen === ''
-          ? 'it answered no DevTools call and printed nothing before the deadline'
-          : seen.split('\n').slice(-3).join(' | '),
+      flags: chromeLaunchFlags,
+      timeoutMs: options.timeoutMs,
+      launchTimeoutMs,
     });
+    if (started.ok) return started.browser;
+    failures.push(started.failure);
+    // A process that outlived SIGKILL's grace still holds the machine; a second beside it is the
+    // load that made the first one late.
+    if (!started.reaped) break;
   }
+  throw new CdpLaunchFailedError({ executable: options.executable, attempts: failures });
 }
 
 /** `findChrome` then `launchChrome`. Refuses by name when there is no browser to drive. */

package/src/cdp-offline-script.ts

@@ -11,7 +11,9 @@
 // `delete` away. A document Chrome DID tell (it saw `offline`) gets Chrome's own `online` event on
 // restore; one it never told gets one from `RESTORE_ONLINE`, so a page reconnects exactly once.
 
+import { stringField } from '@ultimat3/core';
 import type { CdpResult } from './cdp-connection';
+import { CdpCallFailedError } from './cdp-errors';
 
 type Send = (
   method: string,
@@ -68,9 +70,37 @@ export function offlineScripts(send: Send): OfflineScripts {
     async remove(session) {
       const identifier = held.get(session);
       if (identifier === undefined) return undefined;
-      held.delete(session);
-      await send('Page.removeScriptToEvaluateOnNewDocument', { identifier }, session);
-      return send('Runtime.evaluate', { expression: RESTORE_ONLINE }, session);
+      // Both halves are ATTEMPTED whatever the first answers, and a refusal of either surfaces.
+      // Traced 2026-10-02: a navigation in flight made the removal answer `Script not found`, the
+      // throw skipped the restore, and the open document kept reading `navigator.onLine === false`.
+      const refused: string[] = [];
+      const attempt = async (step: string, call: () => Promise<CdpResult>): Promise<boolean> => {
+        try {
+          await call();
+          return true;
+        } catch (error) {
+          refused.push(
+            `${step}: ${stringField(error, 'cause') ?? stringField(error, 'message') ?? 'refused'}`,
+          );
+          return false;
+        }
+      };
+      const removed = await attempt('removing the first-script override', () =>
+        send('Page.removeScriptToEvaluateOnNewDocument', { identifier }, session),
+      );
+      // Kept while the browser may still hold it: the next `remove` asks again, and `add` cannot
+      // register a second copy beside one that is still there.
+      if (removed) held.delete(session);
+      await attempt('restoring the open document', () =>
+        send('Runtime.evaluate', { expression: RESTORE_ONLINE }, session),
+      );
+      if (refused.length > 0) {
+        throw new CdpCallFailedError({
+          method: `putting navigator.onLine back on session ${session}`,
+          detail: refused.join(' · '),
+        });
+      }
+      return undefined;
     },
   };
 }

package/src/cdp-wire-watch.ts

@@ -0,0 +1,113 @@
+// One responsibility: remember what the wire did, so a call that is never answered can say WHY —
+// its target went away, frames arrived that nothing could parse, or the target simply stayed
+// silent. The connection (`cdp-connection.ts`) feeds every frame in; `CdpTimeoutError` reads it out.
+
+import type { CdpTargetGone, CdpTimeoutObservation } from './cdp-errors';
+
+/** How many of the latest frames a timeout quotes. Bounded: a busy page sends thousands. */
+export const LAST_FRAMES = 8;
+
+/** Where the wire stood when a call was sent — what "since the call" is measured from. */
+export interface WireMark {
+  readonly arrived: number;
+  readonly dropped: number;
+  readonly navigations: number;
+}
+
+export interface WireWatch {
+  /** One frame that parsed: a reply or an event. */
+  frame(frame: Record<string, unknown>): void;
+  /** One frame nothing could parse. It has no `id`, so no call can be failed with it — only counted. */
+  drop(): void;
+  mark(sessionId: string | undefined): WireMark;
+  /** What happened between `mark` and now, for the call sent on `sessionId`. */
+  observe(mark: WireMark, sessionId: string | undefined, open: boolean): CdpTimeoutObservation;
+}
+
+const text = (from: unknown, key: string): string | undefined => {
+  const value =
+    typeof from === 'object' && from !== null ? (from as Record<string, unknown>)[key] : undefined;
+  return typeof value === 'string' ? value : undefined;
+};
+
+export function wireWatch(): WireWatch {
+  let arrived = 0;
+  let dropped = 0;
+  const last: string[] = [];
+  const targetOf = new Map<string, string>(); // sessionId → targetId
+  const gone = new Map<string, CdpTargetGone>(); // sessionId → how it went
+  const navigations = new Map<string, number>(); // sessionId → main-frame navigations
+
+  const goneTarget = (targetId: string | undefined, how: CdpTargetGone): void => {
+    for (const [session, target] of targetOf) if (target === targetId) gone.set(session, how);
+  };
+
+  /** The few events that say a session can no longer answer, or that its page was replaced. */
+  const track = (method: string, session: string | undefined, params: unknown): void => {
+    if (method === 'Target.attachedToTarget') {
+      const attached = text(params, 'sessionId');
+      const target = text(
+        (params as Record<string, unknown> | undefined)?.['targetInfo'],
+        'targetId',
+      );
+      if (attached !== undefined && target !== undefined) targetOf.set(attached, target);
+    } else if (method === 'Target.detachedFromTarget') {
+      const detached = text(params, 'sessionId');
+      if (detached !== undefined) gone.set(detached, 'detached');
+    } else if (method === 'Target.targetDestroyed') {
+      goneTarget(text(params, 'targetId'), 'destroyed');
+    } else if (method === 'Target.targetCrashed') {
+      goneTarget(text(params, 'targetId'), 'crashed');
+    } else if (method === 'Inspector.targetCrashed' && session !== undefined) {
+      gone.set(session, 'crashed');
+    } else if (method === 'Page.frameNavigated' && session !== undefined) {
+      const frame = (params as Record<string, unknown> | undefined)?.['frame'];
+      // A frame with a parent is an iframe: the document the call was sent to is still there.
+      if (text(frame, 'parentId') === undefined) {
+        navigations.set(session, (navigations.get(session) ?? 0) + 1);
+      }
+    }
+  };
+
+  const note = (label: string): void => {
+    last.push(label);
+    if (last.length > LAST_FRAMES) last.shift();
+  };
+
+  return {
+    frame(frame): void {
+      arrived += 1;
+      const session = text(frame, 'sessionId');
+      const id = frame['id'];
+      const method = text(frame, 'method');
+      if (typeof id === 'number') note(`reply ${String(id)}`);
+      else if (method === undefined) note('a frame with neither an id nor a method');
+      else {
+        note(session === undefined ? method : `${method} @${session}`);
+        track(method, session, frame['params']);
+      }
+    },
+    drop(): void {
+      dropped += 1;
+    },
+    mark: (sessionId) => ({
+      arrived,
+      dropped,
+      navigations: sessionId === undefined ? 0 : (navigations.get(sessionId) ?? 0),
+    }),
+    observe(mark, sessionId, open): CdpTimeoutObservation {
+      const since = arrived - mark.arrived;
+      return {
+        sessionId: sessionId ?? null,
+        framesArrived: since,
+        // Only frames that arrived AFTER the call: an older one says nothing about its reply.
+        lastFrames: since === 0 ? [] : last.slice(-Math.min(since, LAST_FRAMES)),
+        framesDropped: dropped - mark.dropped,
+        transportOpen: open,
+        targetGone: sessionId === undefined ? null : (gone.get(sessionId) ?? null),
+        navigations:
+          sessionId === undefined ? 0 : (navigations.get(sessionId) ?? 0) - mark.navigations,
+      };
+    },
+  };
+}

package/src/determinism.ts

@@ -2,7 +2,7 @@
 // bug: a frozen clock means "advance it", a seeded RNG means "same values every run", and both are
 // restorable so a test that genuinely needs real time can opt out explicitly.
 
-import { finiteCount, finiteOption } from '@ultimat3/core';
+import { canonicalJson, finiteCount, finiteOption, renderCauseValue } from '@ultimat3/core';
 import { NondeterministicError } from './errors';
 
 export const DEFAULT_SEED = 20260101;
@@ -154,6 +154,24 @@ export function restoreCapturedDeterminism(snapshot: DeterminismSnapshot): void
 
 export const isDeterminismInstalled = (): boolean => installed;
 
+/**
+ * Told each time a test MOVES the clock — `advanceClock` and `setFrozenClock`. A frozen clock that
+ * nothing can hear move is one a timer can only ignore: `frozen-scheduler.ts` is the listener, and
+ * it is how the `runJobs` fixture renews a lease when time passes instead of on the wall clock.
+ */
+const clockMoved = new Set<() => void>();
+
+export function onClockMoved(listener: () => void): () => void {
+  clockMoved.add(listener);
+  return () => {
+    clockMoved.delete(listener);
+  };
+}
+
+const announceMove = (): void => {
+  for (const listener of [...clockMoved]) listener();
+};
+
 /** Move the frozen clock forward. The only legal way for time to pass inside a test. */
 export function advanceClock(ms: number): Date {
   // A required parameter with no default, so no `??` and no ratchet can see it — and it writes the
@@ -161,6 +179,7 @@ export function advanceClock(ms: number): Date {
   // process, which no later `advance` and no later `set` undoes. Negative is legal: a test may
   // move the clock backwards.
   frozenAt += finiteOption('advanceClock', 'ms', ms);
+  announceMove();
   return new RealDate(frozenAt);
 }
 
@@ -168,6 +187,7 @@ export const frozenNow = (): Date => new RealDate(frozenAt);
 
 export function setFrozenClock(now: string | number): void {
   frozenAt = instantMs('setFrozenClock', now);
+  announceMove();
 }
 
 /** Run `body` with the clock frozen at `now`, then restore whatever was there before. */
@@ -177,10 +197,32 @@ export async function frozenClock<T>(now: string, body: () => T | Promise<T>): P
   const at = instantMs('frozenClock', now);
   const previous = frozenAt;
   frozenAt = at;
+  // Both moves announced, as `setFrozenClock` announces one: the frozen scheduler renews leases on
+  // the announcement alone, so an unannounced jump is time its timers never see.
   try {
+    // Inside the `try`: a listener that throws on entry must still get the outer instant back.
+    announceMove();
     return await body();
   } finally {
     frozenAt = previous;
+    announceMove();
+  }
+}
+
+/**
+ * Core's canonical form — a BigInt, a Date, a Map have tokens of their own where `JSON.stringify`
+ * threw a bare `TypeError` or folded them to `{}` — or `undefined` for the one shape it cannot
+ * walk, a cycle, which `Bun.deepEquals` then compares instead. A top-level `undefined`, function
+ * or symbol is a token of its type.
+ */
+function comparable(value: unknown): string | undefined {
+  // Canonical JSON spells all three `null`, so `undefined` and `null` compared equal: a token each.
+  const kind = typeof value;
+  if (kind === 'undefined' || kind === 'function' || kind === 'symbol') return `<${kind}>`;
+  try {
+    return canonicalJson(value);
+  } catch {
+    return undefined;
   }
 }
 
@@ -191,8 +233,15 @@ export async function frozenClock<T>(now: string, body: () => T | Promise<T>): P
 export async function assertDeterministic<T>(what: string, body: () => T | Promise<T>): Promise<T> {
   const first = await body();
   const second = await body();
-  const a = JSON.stringify(first);
-  const b = JSON.stringify(second);
-  if (a !== b) throw new NondeterministicError({ what, first: a, second: b });
+  const a = comparable(first);
+  const b = comparable(second);
+  const same = a === undefined || b === undefined ? Bun.deepEquals(first, second) : a === b;
+  if (!same) {
+    throw new NondeterministicError({
+      what,
+      first: a ?? renderCauseValue(first),
+      second: b ?? renderCauseValue(second),
+    });
+  }
   return first;
 }

package/src/e2e-app.ts

@@ -12,6 +12,7 @@ import { join } from 'node:path';
 import { finiteCount } from '@ultimat3/core';
 import type { E2eAppMode } from './e2e-spawn';
 import { inherited, refuse, spawnE2eApp, xBin } from './e2e-spawn';
+import { testSealKeyEnv } from './test-seal-key';
 
 export type { E2eAppMode } from './e2e-spawn';
 
@@ -35,6 +36,11 @@ export interface E2eApp {
   readonly base: string;
   /** The throwaway `.x` this app runs on — the one directory a test may inspect or corrupt. */
   readonly stateDir: string;
+  /**
+   * The last of what the app printed, bounded — what a failing e2e test carries in its message
+   * (`failure-context.ts`), so a live-path bug is readable without running `x dev` by hand.
+   */
+  log(): string;
   /** Kill the app and delete its state directory. Idempotent. */
   stop(): Promise<void>;
   /**
@@ -52,6 +58,9 @@ function x(bin: string, args: readonly string[], root: string, env: Record<strin
     env: { ...inherited(), ...env },
     stdout: 'pipe',
     stderr: 'pipe',
+    // Synchronous inside a test, where the test's own timeout cannot interrupt it: a hung reset is
+    // killed here and refused below with what it printed, never a suite that waits forever.
+    timeout: DEFAULT_READY_TIMEOUT_MS,
   });
   if (run.exitCode !== 0) {
     throw refuse(`x ${args.join(' ')}`, `${run.stdout.toString()}${run.stderr.toString()}`);
@@ -72,7 +81,13 @@ export async function startE2eApp(options: StartE2eAppOptions): Promise<E2eApp>
   // Before the state directory too: an app that cannot name its `x` leaves nothing behind.
   const bin = await xBin(options.root);
   const stateDir = await mkdtemp(join(tmpdir(), 'ultimate-e2e-'));
-  const env: Record<string, string> = { ...options.env, ULTIMATE_STATE_DIR: stateDir };
+  // The app is a server, not a test process: it installs no seal key for itself. The harness hands
+  // down the throwaway one when the app's root has none, so a `.sealed()` column works under e2e.
+  const env: Record<string, string> = {
+    ...testSealKeyEnv({ root: options.root }),
+    ...options.env,
+    ULTIMATE_STATE_DIR: stateDir,
+  };
   const cleanup = (): Promise<void> => rm(stateDir, { recursive: true, force: true });
   try {
     x(bin, ['db', 'reset'], options.root, env);
@@ -93,6 +108,7 @@ export async function startE2eApp(options: StartE2eAppOptions): Promise<E2eApp>
     return {
       base: spawned.base,
       stateDir,
+      log: () => spawned.log(),
       restart: (next) => spawned.restart(next),
       async stop(): Promise<void> {
         await spawned.stop();

package/src/e2e-driver.ts

@@ -6,6 +6,7 @@ import { test as bunTest } from 'bun:test';
 import type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
 import { e2ePage } from './e2e-page';
 import { FixtureUnavailableError } from './errors';
+import { withFailureContext } from './failure-context';
 import { unavailableFixture } from './fixture-drivers';
 import { defineFixtures } from './fixtures';
 import type { E2eBody, E2eFixtures, PageLike } from './test-types';
@@ -97,8 +98,16 @@ export function installE2eDriver(options: E2eDriverOptions): () => void {
     page: () => page,
     ...(newBuild === undefined ? {} : { deploy: () => ({ newBuild }) }),
   });
-  useE2eDriver((name, body: E2eBody) => {
-    bunTest(name, () => body(e2eFixtures(page, options.page, newBuild)));
+  useE2eDriver((name, body: E2eBody, test) => {
+    // Through `withFailureContext`, as `fixtureTest` is: the failing test carries the app's log.
+    const run = async (): Promise<void> => {
+      try {
+        await body(e2eFixtures(page, options.page, newBuild));
+      } catch (error) {
+        throw withFailureContext(error);
+      }
+    };
+    bunTest(name, run, test?.timeoutMs);
   });
   return () => {
     // Both halves, because both were installed. Putting the DECLARATION back — rather than

package/src/e2e-run.ts

@@ -10,6 +10,7 @@ import { e2eBrowser, publishE2eRun, republishE2eBrowser } from './e2e-browser-ha
 import type { E2eDriverOptions } from './e2e-driver';
 import type { E2eBrowserPage } from './e2e-page';
 import { answersWithin } from './e2e-probe';
+import { setFailureContext } from './failure-context';
 
 /** How long a live browser gets to answer `1` before it is declared hung and relaunched. */
 export const PROBE_MS = 5_000;
@@ -54,6 +55,9 @@ export async function startE2eRun(deps: E2eRunDeps): Promise<void> {
   };
   let browser = await openOrStop(app, deps.openBrowser);
   publishE2eRun({ browser, app });
+  // Every test that fails from here on carries the app's log tail: the server's half of a failure
+  // the browser can only report as "the row never arrived".
+  setFailureContext(() => app.log());
   // Installed ONCE, over a page that delegates to whichever browser is current: an `e2eTest` body
   // is bound to its fixtures when the file DEFINES it, so reinstalling on a relaunch would leave
   // every test defined before it driving a closed browser.
@@ -74,14 +78,15 @@ export async function startE2eRun(deps: E2eRunDeps): Promise<void> {
     const alive = !deployed && (await answersWithin(e2eBrowser().page, probeMs));
     if (alive) return;
     deployed = false;
-    browser.close();
+    await browser.close();
     browser = await deps.openBrowser();
     republishE2eBrowser(browser);
   });
 
   deps.afterAll(async () => {
+    setFailureContext(undefined);
     uninstall();
-    browser.close();
+    await browser.close();
     await app.stop();
   });
 }

package/src/e2e-spawn.ts

@@ -10,6 +10,7 @@ import { get } from 'node:http';
 import { dirname, join } from 'node:path';
 import { assert } from '@ultimat3/core';
 import { E2eAppFailedError } from './e2e-errors';
+import { freePort } from './free-port';
 
 /** `x dev` (sync included), or the production entry `apps/web/server.ts` under `ROLE=web`. */
 export type E2eAppMode = 'dev' | 'serve';
@@ -45,6 +46,8 @@ const POLL_MS = 250;
 export interface SpawnedE2eApp {
   /** `http://localhost:<port>`, no trailing slash. */
   readonly base: string;
+  /** The last of what the CURRENT process printed, stdout and stderr, bounded. */
+  log(): string;
   /** Kill the process. Idempotent. */
   stop(): Promise<void>;
   /** Kill it and start it again on the SAME port, with `env` added — a deploy. Refused after `stop()`. */
@@ -62,14 +65,6 @@ export interface SpawnE2eAppOptions {
   readonly bin?: string | undefined;
 }
 
-/** A port nothing holds right now, asked of the OS and handed to the child. */
-const freePort = (): number => {
-  const probe = Bun.serve({ port: 0, fetch: () => new Response() });
-  const port = probe.port ?? 0;
-  probe.stop(true);
-  return port;
-};
-
 /**
  * This process's environment minus what makes the child a TEST process. Spawned from `bun test`,
  * `NODE_ENV=test` rode along and the app resolved its environment as `test` — so a development-only
@@ -142,6 +137,7 @@ export async function spawnE2eApp(options: SpawnE2eAppOptions): Promise<SpawnedE
   }
   return {
     base,
+    log: () => tail(),
     stop,
     async restart(next: Readonly<Record<string, string>> = {}): Promise<void> {
       // `stop()` is final. A child respawned here would be one no later `stop()` kills — the flag

package/src/errors.ts

@@ -47,6 +47,8 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_POLICY_EXPECTED',
   'X_TEST_OPENAPI_EXPECTED',
   'X_TEST_NUMBER_EXPECTED',
+  'X_TEST_ISLAND_STATE_UNKNOWN',
+  'X_TEST_APP_NOT_BOOTED',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -85,6 +87,8 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_POLICY_EXPECTED: 'a matcher expected a policy and got something else',
   X_TEST_OPENAPI_EXPECTED: 'a matcher expected an OpenAPI document and got something else',
   X_TEST_NUMBER_EXPECTED: 'a matcher expected a finite number and got something else',
+  X_TEST_ISLAND_STATE_UNKNOWN: 'an island state manifest declares no state with that id',
+  X_TEST_APP_NOT_BOOTED: 'describeApp handle read before boot',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -133,7 +137,18 @@ export class NondeterministicError extends UltimateError {
     super({
       code: 'X_TEST_NONDETERMINISTIC',
       cause: `${input.what} produced "${input.first}" then "${input.second}"`,
-      fix: 'wrap the test in frozenClock() / seededRandom(), or remove the wall-clock read',
+      fix: "assertDeterministic('…', () => { installDeterminism(); return body(); })",
+    });
+  }
+}
+
+/** `describeApp`'s `app()` read while the block was still being registered, before `beforeAll`. */
+export class AppNotBootedError extends UltimateError {
+  constructor(input: { suite: string }) {
+    super({
+      code: 'X_TEST_APP_NOT_BOOTED',
+      cause: `describeApp('${input.suite}') — app() was called while the describe block was being registered, before its beforeAll booted the app`,
+      fix: "test('…', () => { const handle = app(); })",
     });
   }
 }