@ultimat3/cli 17.0.0 → 19.0.0

package/CLAUDE.md

@@ -8,6 +8,7 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | stdout | `write-line.ts`'s `writeLine` — synchronous fd 1, never `process.stdout.write`, which truncates at the 64KB pipe buffer when `process.exit` follows. Exported, because `create-ultimate`'s entry point needs the same one |
 | stderr | `write-line.ts`'s `writeErrorLine` — the same loop on fd 2, for a line that is not the command's answer. A `CommandResult` declaring `stream: 'stderr'` is routed there by `dispatch.ts`'s `sinkFor`, and `x mcp serve --transport stdio` is the one case: its fd 1 carries JSON-RPC frames, so the `✓ mcp stdio serving 13 tools` line rendered after the loop was a malformed frame. Neither renderer carries `stream`, exactly like `hold` |
 | Boot logs under `--json` | `dispatch.ts` calls core's `setLogStream('stderr')` when `args.json` is set, once, for all thirty commands. `x db migrate --json` printed the boot logger's `ultimate migrate applied` and then the command's own object, so `json.load` raised on the second document. A server's stdout stays its log stream; this is the CLI process only |
+| Test execution | `test-shards.ts`'s `testArgs` — ONE `bun test --parallel=N`, never N processes this repo packs itself. It did pack them, largest-first greedy over file SIZE, and the packer was deleted for buying **nothing**: four interleaved runs each on the 1296-file unit corpus gave 58.2/60.0/65.0/66.5s hand-packed against 54.5/57.8/61.7/64.5s under `--parallel=8`, within noise, because both are work-bound — 436.7s of file time is a 54.6s floor on 8 workers and the slowest single file is 20.5s. A greedy pack of 1296 small items lands near-optimal by accident. `--timings` is refused on the same evidence (#342). `--parallel` implies `--isolate`, so the per-file module registry is unchanged, and the per-worker database is too: `@ultimat3/testing`'s `workerId` already read `BUN_TEST_WORKER_ID`, which Bun sets 1..N. `ULTIMATE_TEST_WORKER` is set only for a single-shard `x test --worker I` rerun, which is one process |
 | Numeric flags | `flag-number.ts` — one reader for `--port` / `--workers` / `--shard`. A bare `Number.parseInt` accepts `4abc` and answers `NaN`, which turned three checks into ones that cannot fail |
 | Shell quoting | `shell-quote.ts`'s `quoteArg` — every value the CLI pastes into a `fix:` or a reproduce line, `exec.ts`'s missing-program refusal and `test-shards.ts`'s reproduce command both. A name holding a space or a `;` interpolated bare is an instruction that runs something else |
 | Missing positionals | `MissingPositionalError`, never `BadFlagError` (names a flag that does not exist) and never `UnknownCommandError` (says a known command form is not one). Its `example` is a REAL invocation — `x g route <name>` in a shell is a redirect |
@@ -273,11 +274,28 @@ image of the wrong thing.
 `page.pageErrors()` are bounded rings over the whole SESSION, so a shared one files state A's
 console errors under state B — and per-state attribution is the half of the artifact that gates.
 
-**The picture is the VIEWPORT, not a crop.** `@ultimat3/scraping`'s `CaptureRequest` is `fullPage`
-alone, so there is no clip rectangle to ask for; the framing knob is the state's own `viewport`,
-passed to `launch()` as `defaultViewport` through `LocalBrowserOptions.options`. That is why there
-is one browser per declared viewport, memoised. The verdict names it as a blind spot rather than
-implying a crop it did not perform.
+**The picture is the CROP TARGET, `As of 2026-08-26`** — the readiness probe's own box, which is
+the selector the manifest declared or the island's host element. Measured on `examples/dummy`
+before it: 720x560 for a component whose box the verdict reported, in the same run, as 688x104.
+`CaptureClip` had been on the port since #336 and `island-shot.ts` passed none, and this paragraph
+said the port "takes no clip rectangle" — so did the verdict's own `blind` list, which is a blind
+spot naming a capability the tool has, the same lie as one hiding a gap. The state's `viewport` is
+still what the page is LAID OUT in, so there is still one browser per declared viewport, memoised;
+it is no longer what the picture is.
+
+**The clip is translated, not copied.** `getBoundingClientRect()` answers VIEWPORT coordinates and
+a capture clip is in PAGE coordinates; they agree only at the origin, which is the one case a
+harness happens to be in and is a rule nothing enforces. So the probe returns `scroll` beside `box`
+and `clipFor` adds them — a component below the fold would otherwise crop a band it is not in, with
+a picture that looks like a picture and nothing anywhere to report it. `box` keeps meaning the DOM's
+own answer, because that is what the verdict publishes.
+
+**Both themes are photographed by emulating the PREFERENCE.** `page.colorScheme(target.theme)`
+before the navigation, so the first paint already has it. The harness's `data-theme` attribute stays
+— it is right for a component that READS a theme it does not own — but it is the OUTCOME of a theme
+decision, and a component that resolves `'system'` itself deletes it on mount: `x shot --island`
+reported four pictures and wrote two, byte-identical, same md5 (#338). Re-setting the attribute
+after readiness is not the repair; it photographs a state the component would never reach.
 
 **`loadApp` does not import a states file**, for the reason it does not import an island: it
 registers no primitive, and importing it would put `@ultimat3/testing` in the server module graph of
@@ -311,26 +329,120 @@ to know about everything — so the join is here, and it is the same rule
 | `e2e-evaluate.ts` | the closure→string crossing, which is the only lossy edge in the adapter |
 | `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 |
-
-**Absent by default, and that is a requirement rather than a state.** CI has no Chrome. Nothing here
-runs until `installE2eDriver` is called, so `hasE2eDriver()` still answers `false` and the gate's
-`e2e` step still refuses instead of passing over a browser it does not have.
+| `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-e2e-page.ts` | `E2eBrowserPage`'s five methods over an attached, flattened session |
+| `cdp-errors.ts` | one constructor per way the browser half refuses |
+
+**Absent by default, and that is a requirement rather than a state.** Nothing here runs until
+`installE2eDriver` is called, so `hasE2eDriver()` still answers `false` and the gate's `e2e` step
+still refuses instead of passing over a browser it does not have. This paragraph also said "CI has
+no Chrome" until 2026-08-27, and that is false and was the reason issue #390's fourth requirement
+— a real browser check — was recorded as out of reach: GitHub-hosted `ubuntu-latest` ships one at
+`/usr/bin/google-chrome`, preinstalled, with no download step and no new dependency.
+
+**The browser is RAW CDP over Bun's own `WebSocket`, and carries no dependency.**
+`packages/scraping/src/cdp-port.ts` declares a ~25-method port because `ScrapePage` is a full
+scraping surface and its intended implementation is `puppeteer-core`. `E2eBrowserPage` is FIVE
+methods, and CDP's wire format is one JSON object with an `id` — so the whole thing an e2e driver
+needs is four small modules, which is why `x test e2e` needs nothing installed that `bun install`
+did not already put there. `e2e/cdp-browser.e2e.test.ts` drives a real Chrome against a real
+`Bun.serve` and asserts all five methods; `openE2eBrowserIfAvailable()` answering `undefined` is
+what makes it a SKIP on a laptop without one rather than a red step.
+
+**The load EVENT is the completion signal, never `Page.navigate`'s reply.** Measured on Chrome 150:
+a navigation that swaps the render process — `about:blank` → `http://localhost:<port>/`, the most
+ordinary one there is — loads the page, hits the server and answers a later `Runtime.evaluate` from
+the new document, and the navigate frame **never comes back at all**. A driver that awaited the
+reply waited out its full deadline on every first navigation. So `cdpConnect().once()` registers a
+`Page.loadEventFired` waiter BEFORE the send, and the reply is raced against it — still read, but
+only for `errorText`, which is the one place a refused navigation is named.
+
+**A CDP call is deadlined and a close settles every call in flight.** Without that, a suite whose
+browser died waits out one full deadline per call and reports a timeout, where the true fault is a
+dead browser. The four codes are four repairs, which is why they are not one:
+`X_CDP_BROWSER_MISSING` (install one), `X_CDP_LAUNCH_FAILED` (read the browser's own stderr, which
+the cause carries), `X_CDP_CALL_FAILED` (look at the page), `X_CDP_TIMEOUT` (raise the deadline).
 
 **`evaluate` is the edge that cannot be lossless.** `PageLike.evaluate` takes a closure and every
 browser port in this framework takes a string, so what crosses is `Function.prototype.toString()`
 and nothing else. A zero-parameter closure naming only page globals is supported; a native or bound
 function, a declared parameter and a method shorthand are refused STATICALLY, before a byte leaves;
 a binding the page does not have comes back named, from the page's own `ReferenceError`. Measured on
-Bun 1.4.0 and load-bearing: **Bun's transpiler folds `wanted === 3` to `!0` before `toString()` ever
+Bun 1.3.14 and 1.4.0 alike — re-measured on both when the repo moved back to the 1.3 series, because a version-stamped claim that names one runtime is unread evidence on the other — and load-bearing: **Bun's transpiler folds `wanted === 3` to `!0` before `toString()` ever
 runs**, so a captured PRIMITIVE can vanish from the source and never fail at all, while a captured
 reference always survives as its name. No static rule in this process can see the difference — which
 is why the refusal is raised from the page's answer rather than from a scan of the source.
 
-**Three of `E2eFixtures`' four members refuse, deliberately.** `offline()` and `online()` need a CDP
-method for the browser's own network state and `CdpPageLike` declares none; `update()` needs a second
-build served under a new id, which is a fact about the server. A fixture that silently no-opped would
-make the assertion after it read as proof — `offline()` followed by "the fallback rendered" is the
-app's ONLINE page passing an offline test.
+**One of `E2eFixtures`' four members still refuses, and it is the one that is not a port gap.**
+`update()` needs a second build served under a new immutable build id, which is a fact about the
+SERVER, and no page port has ever been able to speak for one. `offline()`/`online()` FORWARD — to
+`E2eBrowserPage.offline`, which `cdp-e2e-page.ts` implements as
+`Network.emulateNetworkConditions` and `@ultimat3/scraping` implements through
+`CdpPageLike.setOfflineMode`. They refused until 2026-08-27 on a reason the tree contradicted on
+the day it was written. A fixture that silently no-opped would make the assertion after it read as
+proof — `offline()` followed by "the fallback rendered" is the app's ONLINE page passing an offline
+test — so an `E2eBrowserPage` that declares no `offline` still gets the refusal, now naming the
+method the double is missing rather than a capability the framework does not have.
+
+## The service worker is emitted here, because the emitter needs facts only a build has
+
+`@ultimat3/pwa` shipped `generateServiceWorker`, `buildPrecacheManifest`, `offlineFallbackSource`,
+`backgroundSyncSource` and `pushSource` since it existed, and every one had **zero callers** outside
+its own package. So `pwa.offline`, `pwa.backgroundSync`, `pwa.push` and every route's own `offline:`
+were declarations with no build behind them, and no Ultimate app worked offline however its config
+was written (#390). `sw-artifacts.ts` is the caller.
+
+**Why here and not beside the manifest.** `loadPwaArtifacts(root)` needs a root and a config file;
+the worker needs the ROUTE TABLE and the ISLAND BUNDLE as well — facts only a booted app and a
+finished build have. Splitting them keeps `loadPwaArtifacts` callable before either exists, which
+`x doctor` and the icon writer rely on. The route table is `describeRoutes()`, the one projection
+`x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a route added to the app
+cannot be missing from the precache manifest.
+
+| Surface | What it does with the worker |
+|---|---|
+| `cmd-dev.ts` | mounts `/sw.js` and `/x-sw-register.js`; built ONCE at boot and deliberately not rebuilt on the watcher tick — a worker that changes under a page it already controls is the update path, and re-emitting one per keystroke exercises it on every save |
+| `serve.ts` | the same two routes in the container, from the same call |
+| `prerender.ts` | writes both as FILES into the export — a static host runs no route table, so a `<script src="/x-sw-register.js">` in every document is a 404 unless the bytes are in the artifact |
+
+**Registration is an EXTERNAL script, never inline**, and that is a CSP fact rather than a
+preference: `startWeb` computes a `script-src` sha256 per inline script, so an unhashed one is
+blocked in the container while passing report-only under `x dev` — which is how the hydration
+runtime shipped broken once already.
+
+**`sw.js` is served `no-store` with `Service-Worker-Allowed: /`.** A cached `sw.js` is a worker that
+cannot be replaced: the browser re-fetches it to decide whether an update exists, and an
+intermediary answering the old bytes pins every client to the deploy that shipped them. Without the
+header the browser refuses to let a worker served from `/` control `/` — the failure `assertScope`
+cannot see, because the scope a REGISTRATION asks for has to be allowed by the script's own response
+and not only by its path.
+
+**`api/` and `shared/` never cross.** An API response is a JSON document whose freshness is the
+app's business, and precaching one serves a stale answer to a client that had a network; `shared/`
+is not a URL at all. The filter is a `flatMap` rather than `filter().map()` because the predicate
+does not narrow `surface` for the map that follows it, and a cast would hide the day a fifth surface
+arrives.
+
+**`pwa.push` is read and still wires nothing, and it says so.** `generateServiceWorker` emits a push
+handler only when a VAPID key comes with the capability, there is no `pwa.vapid` config key, and it
+drops the handler in SILENCE otherwise. `pushWarning` is this module's own finding, reported through
+`x build --json`'s `serviceWorkerWarnings` — `jobs.driver`'s shape one package over, refused the same way.
+
+**The browser check is what let any of this ship.** #390's fourth requirement was *"a real browser
+check that the emitted worker installs, activates and serves the fallback offline. Until it exists,
+do not ship the worker"* — a bad `sw.js` is sticky in a way a manifest is not.
+`e2e/service-worker.e2e.test.ts` registers the emitted file in a real Chrome, waits for it to take
+control, takes the network away, and asserts that a runtime route with nothing cached renders the
+offline document.
+
+**And it found the driver bug first.** `E2eFixtures.offline()` did not take the SERVICE WORKER
+offline: a worker fetches on its own CDP target, the condition was only ever set on the page's, and
+a `networkFirst` route the cache had never seen still answered from the network. So an offline
+assertion made on a PWA tested nothing. `cdp-e2e-page.ts` now auto-attaches worker targets and
+carries the condition onto each, including one that attaches AFTER `offline(true)` — the ordinary
+case for a PWA.
 
 ## The `errors` step enforces the error contract
 
@@ -573,6 +685,8 @@ regex and `+` is a quantifier — `n1` is what actually selects these tests.
 | `db-branch.ts` | what a branch IS: the closed verb set, the name it takes on disk and in `pg_database`, and list/create/drop per mode |
 | `cmd-db-branch.ts` | `x db branch`'s wiring alone — which verb, which refusal, and the one connection an external clone runs on |
 | `db-finding.ts` | one thrown value → one `Finding`, shared by `cmd-db.ts` and `cmd-db-branch.ts` |
+| `db-accept-created.ts` | `acceptCreatedTables`: the post-migrate report minus the tables the applied migrations' own SQL creates — the half `@ultimat3/db`'s `unexpectedTable` names |
+| `db-subscribes.ts` | `replicaIdentityTables`: the tables `x db gen` grants `REPLICA IDENTITY FULL`, read off each live query's declared `subscribes:` — and `X_QUERY_SUBSCRIBES_UNKNOWN` for a name no entity's table matches |
 | `drift.ts` | `checkSourceDrift`: the `.hash` sidecar the `drift` step compares, no database needed |
 | `schema-diff.ts` | what two GENERATED snapshots disagree about, as data — the pure half |
 | `schema-drift.ts` | `checkMigrationDrift`: entity declarations against the newest `.snapshot.json`, and the composition the `drift` step and `x doctor` both read |
@@ -674,6 +788,47 @@ is only the channel each has. `ROLE=migrate` logged and exited 0 until it did no
 whose only signal is the exit code reported success over a schema nobody can reconstruct, which is
 the failure the post-migrate check exists to catch.
 
+**`x db gen` emits `REPLICA IDENTITY FULL`, and the set is DECLARED rather than derived**,
+`As of 2026-08-26` (#357). `@ultimat3/realtime` refuses a live subscription to a table without it —
+logical replication carries no old row on an UPDATE, so no patch can be computed — and for two
+years nothing in the framework emitted one. It could not be derived, and that is the load-bearing
+fact: the relation name lives inside the query's `sql:` callback, which no generator can invoke
+without valid input (`describeSql` says so itself — "`null` when no sample input was supplied").
+So a live query DECLARES it (`subscribes:`, `@ultimat3/query`), the declaration is machine-checked
+against the resolved `shape.entity` on the first subscribe (`X_QUERY_SUBSCRIBES_DRIFT`), and
+`db-subscribes.ts` reads it off `describeQueries()` — the same source `frameworkSources` copies onto
+`QueryFact.subscribes`, one hop earlier, because building the manifest here would re-load the app
+and demand a `package.json` that `x db gen` has never needed.
+
+**The third `subscribes:` refusal is this package's, because no other tier can ask it.**
+`@ultimat3/db` keeps only the declared names an entity's table matches and DROPS the rest — it has
+no way to tell a typo from a table another migration owns — and `@ultimat3/query` holds no table
+catalog at all. So `subscribes: ['posts', 'user']` granted the identity to `posts`, dropped `user`
+in silence, and read as granted. `X_QUERY_SUBSCRIBES_UNKNOWN` refuses it BEFORE anything is
+written, naming the query and offering the tables the app does declare. It is checked after
+`loadApp`'s findings, never before: a module that would not import leaves the registry short, and
+every name whose entity lives in it would then look like a typo.
+
+**And it accepts a table the migrations it just applied demonstrably created**, `As of 2026-08-26`
+(issue #345). A snapshot records only what ENTITIES declare, so a table created by a HAND-WRITTEN
+migration reached no sidecar and was `unexpected-table` on every deploy forever — with a `fix:`
+that generated an empty migration, because `x db gen` diffs the entity registry against the newest
+snapshot and the table is on neither side. `@ultimat3/db` fixed the wording; `acceptCreatedTables`
+(`db-accept-created.ts`) is the half that file's `unexpectedTable` names, and it is composed around
+`checkDrift` inside `runMigrations`, so `x db migrate` and `ROLE=migrate` accept the same set.
+**Only `unexpected-table`, and only for a name a migration's SQL creates** — which is what keeps it
+an acceptance rather than the check switched off: a table absent from the snapshot produces exactly
+one difference (`diffSchema` reports it and never compares its columns), and a table nobody
+declared and no migration created is still reported, cause and `fix:` intact. The evidence is the
+applied list itself: `migrate()` runs first, so every file on disk has been applied by the time the
+question is asked. The verb phrase is read ANCHORED off the raw statement, which is the whole
+protection — a `create table` can only be at position 0 by being one, so `values ('create table
+ghost')` opens with `insert` and a comment-only chunk is not a statement at all. A `stripSqlNoise`
+pass was written first and deleted: it could not change one answer, and a defence that cannot fail
+is one nobody can test. Everything the anchor admits and the name grammar does not — a comment
+between the keywords, a `temp` table, a qualifier naming a schema `checkDrift` never introspected —
+contributes nothing, which reports drift that could have been accepted and never the reverse.
+
 **The `drift` step asks a third thing, off the same directory and with no database either: is every
 destructive statement declared?** `db-destructive.ts` reads each committed migration through
 `migrations.ts` — the reader `x db migrate` applies from, because a rail checking a list the
@@ -751,8 +906,15 @@ decisions behind that shape:
 Regenerating is exactly what *discards* these statements, so the command every other db code
 answers with is the one this one must not lead with — `X_MIGRATION_UNGENERATABLE`'s `CLI_FIXES` row
 is `x verify --only drift`, and the re-declare branch (an enum is a text column plus a check
-invariant) rides behind an em-dash because it is available for some of the statements and never
-for `REPLICA IDENTITY FULL`, which nothing in the framework emits.
+invariant) rides behind an em-dash because it is available for some of the statements and not all.
+**`REPLICA IDENTITY FULL` was the statement with no second branch, and stopped being one on
+2026-08-26** (#357): a live query declares the relations it is patched from (`subscribes:`),
+`db-subscribes.ts` reads them off the same registry the manifest is projected from, `x db gen`
+emits the ALTER and `@ultimat3/db` records it on the snapshot so it is emitted once. The re-declare
+branch covers it now: declare `subscribes:` and regenerate. A statement already committed is a
+different question and still counts — `GENERATABLE_FORMS` (`@ultimat3/db`) matches a leading verb
+phrase and does not carry this one, measured at 7 found / 7 declared on `examples/dummy`'s
+`0001_init.sql`, `As of 2026-08-26` — so the marker branch remains the only remedy for SQL on disk.
 
 **`x db gen` reports what it could not write, and exits 0.** `GeneratedMigration.unrendered` reached
 the committed `.sql` as a `-- UNRENDERED` comment and nothing else read it; `db-generate.ts` now
@@ -813,6 +975,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `dev-runtime.ts` | start the rest on top of it and install the remaining accessors (storage, mail, transport) |
 | `dev-cache.ts` | which cache tiers this process reads through, and the cross-instance invalidation hop |
 | `dev-purge.ts` | the hourly retention sweep: which framework tables this boot owns, the `purge()` job over them and the `task` that fires it |
+| `dev-notify-retention.ts` | `notify.inboxReadRetentionMs` / `inboxUnreadRetentionMs` off the app's own `app.config.ts` — the sibling of `loadSignInPath` and `loadCacheTiers`, because `startServices` holds no `AppConfig` |
 | `dev-sync.ts` | the `sync` role: its live-query registry, who is dialling it, and the socket it owns |
 | `runtime-overrides.ts` | the one field a host hands the framework a driver through |
 | `sync-authenticator.ts` | the app's HTTP authenticator, seen as the sync node's |
@@ -824,6 +987,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `favicon.ts` | `/favicon.ico`: the app's own file, and the bytes the framework answers with when there is none |
 | `dev-hooks.ts` | the pipeline's `authorize` seam, decided from the app's own `Policy` objects |
 | `dev-replica.ts` | which boot gets a standby, and the one middleware frame that opens the read scope |
+| `dev-replicator.ts` | the `replicator` role: the feed selected, locked and pumped — and `replicatedRelations()`, the entity TABLES it filters on |
 | `dev-roles.ts` | `--role` selection plus start/stop for `web`, `sync`, `worker`, `scheduler` |
 | `dev-dashboard.ts` | the `DevSources` hooks only this process can answer, and the two CLI panels |
 | `dev-traces.ts` | core's spans → the `/_x` timeline's request traces |
@@ -912,6 +1076,19 @@ The per-TENANT subscription cap is deliberately unset, and **both halves of it a
 nothing — and no default is defensible when one tenant is a person and the next is five thousand
 seats. The per-socket 128 stands because a socket is one browser tab.
 
+**The change feed is filtered by TABLE, never by entity name**, `As of 2026-08-26`.
+`replicatedRelations()` (`dev-replicator.ts`) is the one projection, and both of its readers are
+catalog readers: `PgReplicationStream` keeps a change only when `#entities.has(relation.name)` and a
+pgoutput Relation message names the table, while `warnPartialIdentity` matches the same list against
+`pg_class.relname`. An entity NAME is the framework's own registry key — a cache tag, a policy and
+`x entities describe` are all keyed by it — and `entity('user', { table: 'users' })` makes the two
+different strings. It passed `.name`, so a renamed table matched on neither side: **every change
+skipped** and a replica-identity warning that could never fire, with no error anywhere. Invisible to
+every fixture in the tree, because `table` defaults to the name verbatim and all six entities in
+`examples/dummy` have `name === table` — `dev-replicator.test.ts` uses `billingAccount` on
+`billing_accounts` for exactly that reason, and proves the value through the real call chain:
+`assertIdentifier` refuses `billingAccount` before any connection and accepts `billing_accounts`.
+
 `trustProxy` is read from `TRUSTED_PROXY_HOPS` in `startWeb`, the way `PORT` and `ROLE` are read: it
 is a fact about the deployment, not an app config choice, and one image runs behind an ingress in
 one cluster and behind nothing on a laptop. Without it `ctx.ip` is the ingress's socket address on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "17.0.0",
+  "version": "19.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -28,7 +28,7 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "17.0.0",
-    "@ultimat3/admin": "17.0.0",
-    "@ultimat3/ai": "17.0.0",
-    "@ultimat3/auth": "17.0.0",
-    "@ultimat3/cache": "17.0.0",
-    "@ultimat3/core": "17.0.0",
-    "@ultimat3/db": "17.0.0",
-    "@ultimat3/entity": "17.0.0",
-    "@ultimat3/flags": "17.0.0",
-    "@ultimat3/http": "17.0.0",
-    "@ultimat3/i18n": "17.0.0",
-    "@ultimat3/jobs": "17.0.0",
-    "@ultimat3/mail": "17.0.0",
-    "@ultimat3/manifest": "17.0.0",
-    "@ultimat3/mcp": "17.0.0",
-    "@ultimat3/money": "17.0.0",
-    "@ultimat3/notify": "17.0.0",
-    "@ultimat3/policy": "17.0.0",
-    "@ultimat3/pwa": "17.0.0",
-    "@ultimat3/query": "17.0.0",
-    "@ultimat3/realtime": "17.0.0",
-    "@ultimat3/render": "17.0.0",
-    "@ultimat3/schema": "17.0.0",
-    "@ultimat3/scraping": "17.0.0",
-    "@ultimat3/seo": "17.0.0",
-    "@ultimat3/storage": "17.0.0",
-    "@ultimat3/testing": "17.0.0",
-    "@ultimat3/time": "17.0.0",
+    "@ultimat3/action": "19.0.0",
+    "@ultimat3/admin": "19.0.0",
+    "@ultimat3/ai": "19.0.0",
+    "@ultimat3/auth": "19.0.0",
+    "@ultimat3/cache": "19.0.0",
+    "@ultimat3/core": "19.0.0",
+    "@ultimat3/db": "19.0.0",
+    "@ultimat3/entity": "19.0.0",
+    "@ultimat3/flags": "19.0.0",
+    "@ultimat3/http": "19.0.0",
+    "@ultimat3/i18n": "19.0.0",
+    "@ultimat3/jobs": "19.0.0",
+    "@ultimat3/mail": "19.0.0",
+    "@ultimat3/manifest": "19.0.0",
+    "@ultimat3/mcp": "19.0.0",
+    "@ultimat3/money": "19.0.0",
+    "@ultimat3/notify": "19.0.0",
+    "@ultimat3/policy": "19.0.0",
+    "@ultimat3/pwa": "19.0.0",
+    "@ultimat3/query": "19.0.0",
+    "@ultimat3/realtime": "19.0.0",
+    "@ultimat3/render": "19.0.0",
+    "@ultimat3/schema": "19.0.0",
+    "@ultimat3/scraping": "19.0.0",
+    "@ultimat3/seo": "19.0.0",
+    "@ultimat3/storage": "19.0.0",
+    "@ultimat3/testing": "19.0.0",
+    "@ultimat3/time": "19.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-root.ts

@@ -7,7 +7,28 @@ import { BunVersionError, NotInAppError } from './errors';
 
 export const APP_CONFIG_FILE = 'app.config.ts';
 export const MANIFEST_FILE = 'x.manifest.json';
-export const REQUIRED_BUN = '1.3.0';
+/**
+ * The floor the shipped `x` enforces, and it must not sit below what `x` EMITS. It said `1.3.0`
+ * through 2026-08-27 while `x test` spent `bun test --isolate` — a flag Bun introduced in
+ * **1.3.13** — so a user on a Bun this file declared supported got an unknown-flag failure out of
+ * the gate's dominant step, with `x doctor` reporting the runtime as fine. `--parallel` arrived in
+ * the same release and is emitted now, so the floor may never fall below that patch.
+ *
+ * `1.4.0` rather than `1.3.13` because a floor is a claim about a runtime somebody TESTED: CI pins
+ * `1.4.x`, both images build on `oven/bun:1.4-*`, and the per-worker database rests on
+ * `BUN_TEST_WORKER_ID`'s numbering, probed on 1.4.0 and on nothing older. `scripts/bun-pin.test.ts`
+ * holds this to the same series as every other pin.
+ *
+ * **Lowering it to 1.3.14 was tried on 2026-08-27 and refused**, and the argument for trying was
+ * sound — `--isolate` and `--parallel` are 1.3.13 features, no package here calls a 1.4-only API
+ * (`bun run typecheck` is clean against `@types/bun@1.3.14`), and `>=1.4.0` therefore bars Bun 1.3
+ * users for a capability the framework does not use. What refused it is a Bun 1.3.14 defect, not
+ * the paperwork: a service shutdown against a destroyed database never resolves there
+ * (`queue.stop()`, reproduced by `dev-runtime.live.test.ts`), so an app on a runtime this line
+ * declared supported would hang on graceful shutdown the moment its database went away. The full
+ * measurement is in `.github/actions/setup/action.yml`; read it before lowering this.
+ */
+export const REQUIRED_BUN = '1.4.0';
 
 export interface AppRoot {
   readonly dir: string;

package/src/cdp-browser.ts

@@ -0,0 +1,100 @@
+// One responsibility: compose the three halves — find a browser, connect to it, 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 { CdpConnection } from './cdp-connection';
+import { cdpConnect } from './cdp-connection';
+import { cdpE2ePage } from './cdp-e2e-page';
+import { CdpBrowserMissingError } from './cdp-errors';
+import type { LaunchedBrowser } from './cdp-launch';
+import { CHROME_CANDIDATES, findChrome, launchChrome } from './cdp-launch';
+import type { E2eBrowserPage } from './e2e-page';
+
+/** 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 {
+  readonly page: E2eBrowserPage;
+  /** 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,
+  connection: CdpConnection,
+  page: E2eBrowserPage,
+): E2eBrowser => ({
+  page,
+  close(): void {
+    // The socket first: 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.
+    connection.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 });
+  let connection: CdpConnection;
+  try {
+    connection = await cdpConnect({ endpoint: launched.endpoint, timeoutMs });
+  } catch (error) {
+    launched.close();
+    throw error;
+  }
+  try {
+    const page = await cdpE2ePage({ connection, loadTimeoutMs: timeoutMs });
+    return compose(launched, connection, page);
+  } catch (error) {
+    connection.close();
+    launched.close();
+    throw error;
+  }
+}