@ultimat3/cli 21.0.0 → 22.1.0

package/src/verify-checks.ts

@@ -15,12 +15,13 @@ import {
 import type { MetaIssue } from '@ultimat3/seo';
 import { validateMeta } from '@ultimat3/seo';
 import { checkAgentsMd } from './app-agents-md';
-import { checkAppBoundaries } from './app-boundaries';
 import { envExampleFindings } from './app-env';
 import { appManifest, readAppManifest } from './app-manifest';
-import { OPENAPI_FILE, openApiJson } from './app-openapi';
+import { OPENAPI_FILE, openApiStaleness } from './app-openapi';
 import { policyFindings } from './app-permissions';
 import { APP_CONFIG_FILE } from './app-root';
+import { asyncPageFindings } from './async-pages';
+import { appBoundaryFindings } from './boundary-findings';
 import { checkBudgets, readBuildStats } from './budgets';
 import { checkDestructiveMigrations } from './db-destructive';
 import { checkUngeneratableMigrations } from './db-ungeneratable';
@@ -28,17 +29,21 @@ import { checkDocumentStyles, documentSurfaces } from './document-styles';
 import { checkErrorCodeResolution, checkErrorFixReport } from './error-contract';
 import { guardFindings } from './guards';
 import { catalogFindings } from './i18n-registration';
+import { unregisteredJobFindings } from './job-registration';
 import { liveRouteFindings } from './live-routes';
+import { withLoadFindings, withoutLoadFindings } from './load-findings';
 import { msg } from './messages';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { checkMigrationDrift } from './schema-drift';
 import { scanSiteMeta } from './seo-meta';
+import { quoteArg } from './shell-quote';
 import { readStaticReport } from './static-report';
 import { floorProblemFindings, readVerifyFloor } from './verify-floor';
 import type { VerifyStep } from './verify-step';
 import { fromExec, fromFindings, hostFindings } from './verify-step';
 import { TEST_STEPS } from './verify-tests';
+import { typecheckArgs } from './verify-typecheck';
 import { checkFileSizes, checkPackageShape, hasWorkspacePackages } from './workspace-checks';
 import { checkWorkspaceDependencies } from './workspace-graph';
 
@@ -49,22 +54,21 @@ const ROADMAP_FILE = join('docs', 'idea', '14-roadmap.md');
 export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'typecheck',
-    summary: 'tsc -b across every project the root references',
+    summary: 'tsc -b across every project the root references, tsc -p . where it references none',
     // `typecheckBin` (`x.verify.json`, beside `agentsMdMaxBytes`) swaps the binary and nothing
-    // else: same `-b --pretty false` invocation, same output format to parse, same `X_TYPECHECK_
-    // FAILED` finding either way. Absent means `tsc` — the only checker every app already has,
-    // since `typescript` is a framework dependency and a drop-in replacement is the app's own
-    // devDependency to add, never a default this step could assume.
+    // else: same invocation, same output format to parse, same `X_TYPECHECK_FAILED` finding either
+    // way. Absent means `tsc` — the only checker every app already has, since `typescript` is a
+    // framework dependency and a drop-in replacement is the app's own devDependency to add, never
+    // a default this step could assume. `-b` or `-p .` is `typecheckArgs`' call (#450).
     async run(ctx) {
       const floor = await readVerifyFloor(ctx.root);
-      const bin = floor?.typecheckBin ?? 'tsc';
-      const result = await ctx.runner(['bunx', bin, '-b', '--pretty', 'false'], {
-        cwd: ctx.root,
-      });
+      const argv = await typecheckArgs(ctx.root, floor?.typecheckBin ?? 'tsc');
+      const result = await ctx.runner(['bunx', ...argv], { cwd: ctx.root });
       return fromExec(result, {
         code: 'X_TYPECHECK_FAILED',
         cause: 'the project does not typecheck',
-        fix: `bunx ${bin} -b --pretty false`,
+        // Joined, never spliced: `typecheckBin` is a value from the app's `x.verify.json`.
+        fix: ['bunx', ...argv.map(quoteArg)].join(' '),
       });
     },
   },
@@ -99,7 +103,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     // extension model rejects.
     run: async (ctx) =>
       fromFindings([
-        ...(await checkAppBoundaries(ctx.root)),
+        ...(await appBoundaryFindings(ctx.root)),
         ...(await guardFindings(ctx.root)),
         ...(await hostFindings(ctx, 'boundaries')),
       ]),
@@ -187,10 +191,11 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     async run(ctx) {
       const committed = await readAppManifest(ctx.root);
       const { manifest, findings } = await appManifest(ctx.root);
-      return fromFindings([
+      // A module that will not import is `manifest`'s to report (`load-findings.ts`).
+      return withoutLoadFindings(ctx.root, [
         ...findings,
         ...(committed === undefined ? [] : contractFindings(committed, manifest)),
-        ...(await specFindings(ctx.root, manifest)),
+        ...(await openApiStaleness(ctx.root, manifest)),
       ]);
     },
   },
@@ -224,21 +229,27 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       // reported under `X_ISLAND_PROPS_INVALID` — the build's own sentence, naming the prop and
       // its bytes — and not as an `X_BUDGET_UNMEASURED` whose fix is to go and read this file.
       const report = await readStaticReport(ctx.root);
-      // The load's own findings, FIRST and never dropped. A module that would not import registers
-      // no route, so its budget is missing from the manifest and every route it declared reads as
-      // `X_BUDGET_UNMEASURED` — the symptom, pointing the reader at `x build` for a file that will
-      // not compile. `contract-diff` reports these too when it applies; two red steps naming one
-      // broken module is honest, and one of them silently green over it is the false green.
+      // The load's own findings are `manifest`'s, reported there once; this step's output says so.
+      // A module that would not import registers no route, so every route it declared still reads
+      // as `X_BUDGET_UNMEASURED` here — the symptom stays this step's, and the gate stays red.
       const { manifest, findings } = await appManifest(ctx.root);
-      return fromFindings([
+      const outcome = await withoutLoadFindings(ctx.root, [
         ...findings,
         ...checkDocumentStyles(documentSurfaces()),
         // The third rider, and the same question this step already asks one level down: what
         // JavaScript does this route's document boot? A live read with no island is a route
         // whose answer is "none", which no suite can fail on — the page renders, at 200.
         ...(await liveRouteFindings(ctx.root)),
+        // The fourth: a data read in an async Page rather than in `load` (`async-pages.ts`).
+        ...asyncPageFindings(),
         ...checkBudgets(manifest, stats, report?.unmeasured),
       ]);
+      // What no build can weigh, said out loud rather than dropped (`measure-paths.ts`).
+      const notes = (report?.unmeasured ?? [])
+        .filter((one) => one.weighable === false)
+        .map((one) => `not weighed: ${one.reason}`);
+      const output = [outcome.output, ...notes].filter((line) => line !== undefined).join('\n');
+      return output === '' ? outcome : { ...outcome, output };
     },
   },
   {
@@ -293,7 +304,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     // registers no routes — SKIPPED there, never passed, for the reason `i18n` gives: a step that
     // answers `ok` about nothing is the vacuous green these checks exist to refuse.
     applies: async (ctx) => existsSync(join(ctx.root, APP_CONFIG_FILE)),
-    run: async (ctx) => fromFindings(await policyFindings(ctx.root)),
+    run: async (ctx) => withoutLoadFindings(ctx.root, await policyFindings(ctx.root)),
   },
   {
     name: 'manifest',
@@ -315,9 +326,16 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       // and reading it after the check would enforce the default on a repo that raised it.
       const floor = await readVerifyFloor(ctx.root);
       const agents = await checkAgentsMd(ctx.root, floor?.agentsMdMaxBytes);
+      // The app's load failures, once, here — every other step that loaded it points at this one.
+      const app = existsSync(join(ctx.root, APP_CONFIG_FILE));
+      const drift = await driftFindings(ctx.root);
       const findings = [
         ...manifestMissingFindings(ctx.root),
-        ...(await driftFindings(ctx.root)),
+        ...(app ? await withLoadFindings(ctx.root, drift) : drift),
+        // An app only: the framework monorepo declares no `defineApi`, so it has no list to be in.
+        ...(existsSync(join(ctx.root, APP_CONFIG_FILE))
+          ? await unregisteredJobFindings(ctx.root)
+          : []),
         ...(await envExampleFindings(ctx.root)),
         ...floorProblemFindings(floor),
         ...agents.findings,
@@ -394,22 +412,6 @@ function contractFindings(before: Manifest, after: Manifest): readonly Finding[]
   }
 }
 
-/** The typed client is generated from `openapi.json`, so a stale spec ships a wrong client. */
-async function specFindings(root: string, manifest: Manifest): Promise<readonly Finding[]> {
-  const path = join(root, OPENAPI_FILE);
-  if (!existsSync(path)) return [];
-  if ((await Bun.file(path).text()) === openApiJson(manifest)) return [];
-  return [
-    {
-      code: 'X_MANIFEST_STALE',
-      cause: `${OPENAPI_FILE} does not match the actions the code registers`,
-      fix: 'x manifest',
-      docs: ERROR_DOCS_URL,
-      at: OPENAPI_FILE,
-    },
-  ];
-}
-
 /**
  * One `MetaIssue` as the gate reports it. `at` is the route FILE and never the URL: every seo error
  * already names the file in its cause, and `at` is what an agent opens.

package/src/verify-e2e.ts

@@ -4,14 +4,17 @@
 // app: the suite runs as before and its browser-backed cases skip — or refuse under
 // `E2E_BROWSER_REQUIRED=1`.
 
-// why: Bun exposes no path API — the preload is addressed by an absolute path the child resolves.
-import { join } from 'node:path';
-import { findChrome } from './cdp-launch';
-import { E2E_ROOT_ENV } from './e2e-browser-handle';
+import { E2E_ROOT_ENV, findChrome } from '@ultimat3/testing';
 import type { ExecResult } from './exec';
 
-/** The preload `bun test` is handed, beside the app's own from `bunfig.toml`. */
-export const E2E_PRELOAD = join(import.meta.dir, 'e2e-preload.ts');
+/**
+ * The preload `bun test` is handed, beside the app's own from `bunfig.toml` — `@ultimat3/testing`'s,
+ * resolved from here to the absolute path the child process loads. A FUNCTION, resolved when a run
+ * needs it: at module scope it ran on every import of the registry, and a compiled `x` binary —
+ * whose `/$bunfs` holds no `node_modules` — died at boot resolving a file it never uses.
+ */
+export const e2ePreload = (): string =>
+  Bun.resolveSync('@ultimat3/testing/e2e-preload', import.meta.dir);
 
 export interface E2eRun {
   readonly command: readonly string[];
@@ -32,7 +35,7 @@ export async function withE2eApp(
   if (chrome === undefined) return run({ command: input.command, env: input.env });
   const [bun = 'bun', test = 'test', ...rest] = input.command;
   return run({
-    command: [bun, test, '--preload', E2E_PRELOAD, ...rest],
+    command: [bun, test, '--preload', e2ePreload(), ...rest],
     env: { ...input.env, [E2E_ROOT_ENV]: input.root },
   });
 }

package/src/verify-run.ts

@@ -128,6 +128,8 @@ function verifySummary(input: {
  * files; the rest are in-process scans), so they run BESIDE the serial suites — `live` and `e2e`
  * are one worker each, Postgres- and browser-bound, and mostly waiting. `typecheck` stays first
  * and alone: `tsc -b` writes `.tsbuildinfo` and `dist/`, and `unit` saturates every core.
+ * `manifest` joined them 2026-09-23: it compares committed files against the code and writes
+ * nothing, and at the repo root its host checks are ~20 whole-tree reads that sat alone at the end.
  */
 export const BESIDE_SERIAL_SUITES: ReadonlySet<string> = new Set([
   'lint',
@@ -135,6 +137,7 @@ export const BESIDE_SERIAL_SUITES: ReadonlySet<string> = new Set([
   'filesize',
   'package-shape',
   'errors',
+  'manifest',
 ]);
 
 /** The consecutive run of steps the static group overlaps, in the order `VERIFY_STEP_NAMES` holds. */
@@ -145,7 +148,14 @@ async function runStep(
   ctx: VerifyContext,
   floor: Awaited<ReturnType<typeof readVerifyFloor>>,
 ): Promise<StepResult> {
-  const applies = step.applies === undefined ? true : await step.applies(ctx);
+  // Inside the step's own failure, like a throwing `run`: an `applies` that threw escaped every
+  // catch and aborted the whole gate, which is the one outcome `runVerify` exists to prevent.
+  let applies: boolean;
+  try {
+    applies = step.applies === undefined ? true : await step.applies(ctx);
+  } catch (error) {
+    return { name: step.name, ok: false, durationMs: 0, findings: [findingOf(error, step.name)] };
+  }
   if (!applies) {
     // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
     // that claim, committed — so "nothing to check" now means the suite was deleted, and the

package/src/verify-step.ts

@@ -79,9 +79,9 @@ export interface VerifyContext {
    */
   readonly workers?: number;
   /**
-   * ONE step, by name — an iteration loop, and the one thing here that IS a narrowing. Every
-   * iteration of the whole gate costs ~18s (14s of it `tsc -b`), which is the cost of asking a
-   * question about one step. It does not weaken axiom 5, and the two rules that keep it honest are
+   * ONE step, by name — an iteration loop, and the one thing here that IS a narrowing. The
+   * whole gate costs minutes (3m19s at the framework root on 12 cores, `As of 2026-09-23`), which
+   * is the cost of asking a question about one step. It does not weaken axiom 5, and the two rules that keep it honest are
    * mechanical rather than remembered: a run with this set prints `NOT A GATE RUN` in the summary
    * AND carries `notAGateRun` in `--json` (`verify-run.ts`), so no reader of either can mistake it
    * for the gate; and nothing writes `x.verify.json`, so the suite floor cannot be lowered by a

package/src/verify-tests.ts

@@ -18,7 +18,7 @@ import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
 import type { TestFile } from './test-select';
 import { discoverTests } from './test-select';
-import { defaultWorkers } from './test-workers';
+import { defaultWorkers, SERIAL_TYPES } from './test-workers';
 import { withE2eApp } from './verify-e2e';
 import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 import { fromExec, fromFindings } from './verify-step';
@@ -111,31 +111,6 @@ export const ownerOf = (path: string): TestType =>
 const disownedBy = (type: TypedTest): readonly string[] =>
   type === 'e2e' ? [`**/e2e/**/*.{${OUTRANKING_E2E.join(',')}}.test.*`] : [];
 
-/**
- * Which types run across worker processes, and why the other two cannot.
- *
- * Parallel is safe when the only thing a test file shares with another file is the database, and
- * the database is per worker by construction (`ULTIMATE_TEST_WORKER` → one clone of the migrated
- * template, `@ultimat3/testing`'s `acquireWorkerDatabase`). Every other process-global in this
- * framework — the permission set, the roles, the entity/action/query registries, the error-code
- * titles, the fixture bag — is handled by `--isolate` giving each FILE its own module registry.
- *
- * | Type | Why |
- * |---|---|
- * | `live` | **serial.** A logical replication slot and a publication are named at the Postgres
- * CLUSTER level, not inside a database, and this repo's own feed tests hard-code
- * `x_live_slot` / `x_live_pub` against `TEST_REPLICATION_URL` — the one server, never a per-worker
- * clone. Two workers would race `pg_create_logical_replication_slot` and the loser's failure would
- * read as a flake. A per-worker database does not isolate a cluster-wide object |
- * | `e2e` | **serial.** It runs against the *built output*: one `dist/`, one service-worker
- * registration, one browser profile. There is nothing per-worker to hand it, and the type is
- * seconds at most, so a split would buy a race and no time |
- *
- * The two are named here rather than tested for, because "can this type be sharded?" is a design
- * fact about the type, not something a run can discover about itself.
- */
-export const SERIAL_TYPES: readonly TestType[] = ['live', 'e2e'];
-
 const isSerial = (type: TestType): boolean => SERIAL_TYPES.includes(type);
 
 /**

package/src/verify-typecheck.ts

@@ -0,0 +1,28 @@
+// Which `tsc` invocation the `typecheck` step runs. `tsc -b` decides "up to date" by mtime, and Bun
+// installs a package as HARDLINKS out of its cache, carrying the cache's old mtimes — so upgrading
+// a dependency to a version already in the cache left every input older than the buildinfo, `-b`
+// skipped the program and reported green while a cold CI went red (#450). `-p` with `incremental`
+// re-reads every input and compares content hashes, so it cannot be fooled by a date.
+
+import { checkRootReferences } from './tsconfig-references';
+
+/**
+ * A package dir no reference can name. `checkRootReferences` answers `[]` when the root has no
+ * `references` array at all and one finding for this probe when it has one, which is the one
+ * question asked here — without a second JSONC parser beside the one that file owns.
+ */
+const PROBE = '\u0000x-verify-typecheck-probe';
+
+/** True when the root tsconfig declares `references`: a build graph that only `-b` can walk. */
+export const usesProjectReferences = async (root: string): Promise<boolean> =>
+  (await checkRootReferences(root, [PROBE])).length > 0;
+
+/**
+ * The argv after `bunx`. A root with references keeps `-b` — the framework's 32 projects are only
+ * reachable that way, and `tsc -b` rebuilds a project whose own sources moved. A root without them
+ * (every scaffolded app) is ONE program, and `-p .` is the content-hashed check of it.
+ */
+export async function typecheckArgs(root: string, bin: string): Promise<readonly string[]> {
+  const mode = (await usesProjectReferences(root)) ? ['-b'] : ['-p', '.'];
+  return [bin, ...mode, '--pretty', 'false'];
+}

package/src/web-binding.ts

@@ -1,6 +1,6 @@
 // How a process binds its sockets, and what it admits about itself. A LEAF: it imports nothing,
-// so every role can read it without pulling `dev-roles` — which is what made this its own file.
-// `dev-sync` needs the default and `dev-roles` already imports `dev-sync`, so reading it from
+// so every role can read it without pulling `role-start` — which is what made this its own file.
+// `role-sync` needs the default and `role-start` already imports `role-sync`, so reading it from
 // there would be a runtime import cycle in the framework's own boot path.
 
 export interface WebBinding {

package/src/workspace-graph.ts

@@ -5,9 +5,9 @@
 
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { scanAllImports } from './import-scan';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest, isVendored } from './source-files';
-import { maskLiterals } from './ts-scan';
 
 export interface WorkspaceNode {
   /** package.json "name". */
@@ -144,43 +144,20 @@ export function packageOfSpecifier(specifier: string): string | undefined {
 }
 
 /**
- * Every form that names a module: `… from '…'`, a bare `import '…'`, `import('…')`, `require('…')`.
- * `from` is matched only where a quote follows it directly, so `from<Row>('posts', …)` — the query
- * builder, which reads exactly like an import — cannot be one.
+ * Every package a source file imports, deduplicated, in first-appearance order — type-only imports
+ * included, because a type edge still needs its manifest line. The transpiler is the parser, so a
+ * generator's template literal (even one nested in a `${…}`, #493) is a string and never an import,
+ * and `from<Row>('posts')` is a call. A file it cannot parse throws rather than reading as empty.
  */
-const IMPORT_FORM =
-  /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|(?:^|[;{])\s*import\s+)['"]([^'"]*)['"]/g;
-
-/**
- * Every package a source file imports, deduplicated, in first-appearance order.
- *
- * Read from the MASKED text, because a generator's template literal holds whole programs: every
- * `templates/*.ts` here emits `import … from '@ultimat3/ui'` as a string, and a scan that read
- * those would bill the CLI for the imports of the app it writes. The line a masked hit falls on is
- * then re-read from the real source — the specifier itself is what masking blanks.
- */
-export function importedPackages(source: string): readonly string[] {
-  const masked = maskLiterals(source).split('\n');
-  const lines = source.split('\n');
+export function importedPackages(source: string, path = 'source.ts'): readonly string[] {
   const packages = new Set<string>();
-  for (const [index, maskedLine] of masked.entries()) {
-    const line = lines[index];
-    // `matchAll` clones the regex, so the shared `lastIndex` is never carried between lines.
-    if (line === undefined || [...maskedLine.matchAll(IMPORT_FORM)].length === 0) continue;
-    for (const match of line.matchAll(IMPORT_FORM)) {
-      const name = packageOfSpecifier(match[1] ?? '');
-      if (name !== undefined) packages.add(name);
-    }
+  for (const specifier of scanAllImports({ path, source })) {
+    const name = packageOfSpecifier(specifier);
+    if (name !== undefined) packages.add(name);
   }
   return [...packages];
 }
 
-/**
- * Borrowed, not twinned: `X_APP_PACKAGE_INVALID` already means "this package.json supplies no
- * usable name", and a workspace manifest is that same file one directory down. `bun pm pkg set`
- * is not the fix here — it parses the file it edits, so it fails on exactly the input this
- * reports.
- */
 export const unreadableWorkspaceFinding = (path: string): Finding => ({
   code: 'X_APP_PACKAGE_INVALID',
   cause: `${path} is claimed by the root "workspaces" globs and supplies no readable "name"`,
@@ -228,7 +205,7 @@ export async function checkWorkspaceDependencies(root: string): Promise<readonly
     if (isTest(path) || isGenerated(path)) continue;
     const owner = owners.find((node) => path.startsWith(`${node.dir}/`));
     if (owner === undefined) continue;
-    for (const name of importedPackages(await Bun.file(join(root, path)).text())) {
+    for (const name of importedPackages(await Bun.file(join(root, path)).text(), path)) {
       const target = byName.get(name);
       if (target === undefined || target.name === owner.name) continue;
       if (owner.dependencies.includes(target.name)) continue;

package/src/cdp-browser.ts

@@ -1,94 +0,0 @@
-// One responsibility: compose the halves — find a browser, launch it over its pipe, attach a page —
-// into the one object `installE2eDriver({ page })` takes, plus the way to shut it down.
-//
-// **Absent is a SKIP, never a failure, and that is a requirement rather than a state.** A CI box
-// with no Chrome must not turn the `e2e` step red for a reason unrelated to the change, which is
-// the rule `packages/cli/CLAUDE.md` already states about `x shot`, `x pr` and `x ci`.
-// `openE2eBrowserIfAvailable` is that door; `openE2eBrowser` refuses by name for a caller that has
-// already decided a browser is required.
-
-import { finiteCount } from '@ultimat3/core';
-import type { E2eTab } from './cdp-e2e-page';
-import type { E2eSession } from './cdp-e2e-session';
-import { cdpE2eSession } from './cdp-e2e-session';
-import { CdpBrowserMissingError } from './cdp-errors';
-import type { LaunchedBrowser } from './cdp-launch';
-import { CHROME_CANDIDATES, findChrome, launchChrome } from './cdp-launch';
-
-/** How long a launch, a connect or a single CDP call may take. One number, three deadlines. */
-export const DEFAULT_CDP_TIMEOUT_MS = 30_000;
-
-export interface E2eBrowser {
-  /** The first tab — what `installE2eDriver({ page })` drives. */
-  readonly page: E2eTab;
-  /**
-   * The browser itself: more tabs in the same profile, init scripts, the offline switch for every
-   * page and worker, and the log of every socket and request. What a multi-tab acceptance suite
-   * 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;
-}
-
-export interface OpenE2eBrowserOptions {
-  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
-  readonly timeoutMs?: number | undefined;
-}
-
-/**
- * Screened HERE, before a browser exists, and not where it lands. It becomes three deadlines — the
- * launch, the handshake and every CDP call — and `Number(process.env.E2E_TIMEOUT ?? '')` is `NaN`
- * for an unset variable and is not nullish, so `??` keeps it: a `setTimeout` given `NaN` fires at
- * 1ms in this Bun, which makes every call report `X_CDP_TIMEOUT` against a browser that was
- * answering. A misdiagnosis reported as a test failure is worse than the failure.
- */
-const budget = (options: OpenE2eBrowserOptions): number =>
-  finiteCount('openE2eBrowser', 'timeoutMs', options.timeoutMs ?? DEFAULT_CDP_TIMEOUT_MS);
-
-const compose = (launched: LaunchedBrowser, session: E2eSession, page: E2eTab): E2eBrowser => ({
-  page,
-  session,
-  // The connection first, then the process — `launched.close()` does both, in that order: closing
-  // 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(),
-});
-
-/**
- * Launch a browser and attach one page to it. Refuses with `X_CDP_BROWSER_MISSING` when there is
- * nothing to launch — the caller that wants a skip asks `openE2eBrowserIfAvailable` instead.
- */
-export async function openE2eBrowser(options: OpenE2eBrowserOptions = {}): Promise<E2eBrowser> {
-  const timeoutMs = budget(options);
-  const executable = await findChrome(options.env ?? process.env);
-  if (executable === undefined) throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
-  return openLaunched(executable, timeoutMs);
-}
-
-/** `undefined` when this machine has no browser. Every other failure still throws. */
-export async function openE2eBrowserIfAvailable(
-  options: OpenE2eBrowserOptions = {},
-): Promise<E2eBrowser | undefined> {
-  const timeoutMs = budget(options);
-  const executable = await findChrome(options.env ?? process.env);
-  if (executable === undefined) return undefined;
-  return openLaunched(executable, timeoutMs);
-}
-
-/**
- * The half both doors share. Each step undoes the ones before it on the way out: a Chrome that
- * launched and then refused the CDP handshake would otherwise be left running, holding its profile
- * directory, for the rest of the test process — one leaked browser per failing suite.
- */
-async function openLaunched(executable: string, timeoutMs: number): Promise<E2eBrowser> {
-  const launched = await launchChrome({ executable, timeoutMs });
-  const { connection } = launched;
-  try {
-    const session = await cdpE2eSession({ connection, loadTimeoutMs: timeoutMs });
-    return compose(launched, session, await session.newTab());
-  } catch (error) {
-    launched.close();
-    throw error;
-  }
-}