@ultimat3/testing 23.0.0 → 24.0.0

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,
+    };
+  }
+}

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;
@@ -197,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;
   }
 }
 
@@ -211,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

@@ -58,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()}`);

package/src/e2e-run.ts

@@ -78,7 +78,7 @@ 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);
   });
@@ -86,7 +86,7 @@ export async function startE2eRun(deps: E2eRunDeps): Promise<void> {
   deps.afterAll(async () => {
     setFailureContext(undefined);
     uninstall();
-    browser.close();
+    await browser.close();
     await app.stop();
   });
 }