@ultimat3/cli 18.0.0 → 19.1.0

package/CLAUDE.md

@@ -4,7 +4,7 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 
 | Rule | Detail |
 |---|---|
-| Entry | `src/bin.ts` (`#!/usr/bin/env bun`) — argv, stdout, exit code only |
+| Entry | `src/bin.ts` (`#!/usr/bin/env bun`) — argv, stdout, exit code only. Before `dispatch`, `local-cli.ts` decides whether THIS process is the app's own CLI: a global `x` inside an app re-executes `node_modules/@ultimat3/cli/src/bin.ts` when that is a different realpath, because a second module instance of `@ultimat3/entity` is an empty registry (a zero-entity manifest, green, 2026-09-05). Same realpath (a workspace symlink), no app, a compiled binary, or `ULTIMATE_KEEP_GLOBAL_CLI` set: no hand-over |
 | 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 |
@@ -329,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
 

package/README.md

@@ -34,6 +34,25 @@ Everything in [CLI reference](../../wiki/CLI-Reference.md)'s planned table is al
 and exits `X_NOT_IMPLEMENTED` with a `fix:` naming the closest shipped command — "not built yet"
 and "not a command" are different facts.
 
+## Which `x` runs
+
+**The app's own.** `x` is a workspace dependency, and `bunx x` / the `package.json` scripts resolve
+`node_modules/.bin/x`. A **globally** installed `x` — `bun link` of a checkout, `bun add -g` — is
+a second copy of every `@ultimat3/*` package, and a second copy of `@ultimat3/entity` is a second,
+**empty** registry: the app's entities register into the instance under its `node_modules`, and
+only the CLI under that same `node_modules` can see them. Measured 2026-09-05, in an app run with a
+linked checkout's `x`: `x entities list` answered `0 entities`, `x policy list` answered
+`0 permission(s), 0 role(s)`, and `x manifest` wrote a manifest with **zero entities and zero
+actions** — exit 0, green — which `x db gen` then read as "drop every table".
+
+So a global `x` inside an app **hands over** to `node_modules/@ultimat3/cli/src/bin.ts` when that
+is a different file (`local-cli.ts`), prints one line on stderr saying so, and exits with the
+child's code; fd 1 is the child's alone, so a `--json` consumer sees one document. A workspace
+symlink resolves to the same file and is not handed over (both tracked apps, and every scaffold
+CI installs), and a compiled `x` keeps itself — its own path is not one `realpath` can resolve.
+`ULTIMATE_KEEP_GLOBAL_CLI=1` keeps the CLI that was invoked, for the one deliberate case: running a
+checkout's `x` against an app pinned to an older release to see what the next one would say.
+
 ## The output contract
 
 Every command returns one `CommandResult`; the human renderer and the JSON renderer are
@@ -95,6 +114,11 @@ is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUAR
 | `cmd-*.ts` | one command group each |
 | `templates/` | scaffolding as typed string modules, not copied fixtures |
 | `app-load.ts` | import an app's modules so the framework registries hold it |
+| `app-mcp.ts` | the app's own MCP endpoint: `apps/<app>/mcp.ts` exports `mcp`, and both boots mount `POST config.ai.mcp.path` through this one call |
+| `app-runtime.ts` | the app's `RuntimeOverrides`: `apps/<app>/runtime.ts` exports `runtime`, read by `x dev` and by `runRole` when its caller passed none |
+| `local-cli.ts` | which `x` runs: a global CLI inside an app hands over to the app's own, because a second module instance is an empty registry |
+| `measurement-actor.ts` | the actor a weigh-and-discard render runs as — every permission, never served |
+| `dev-live-feed.ts` | what feeds the sync node this process booted: the in-process row observer under the embedded database, the WAL decoder with a real one, nothing without the role — `live=` on the ready line |
 | `app-manifest.ts` | `x.manifest.json`, projected by `@ultimat3/manifest` |
 | `app-openapi.ts` | `openapi.json`, projected by `@ultimat3/action` |
 | `app-boundaries.ts` | app import boundaries, over `@ultimat3/render`'s surface check |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "18.0.0",
+  "version": "19.1.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "18.0.0",
-    "@ultimat3/admin": "18.0.0",
-    "@ultimat3/ai": "18.0.0",
-    "@ultimat3/auth": "18.0.0",
-    "@ultimat3/cache": "18.0.0",
-    "@ultimat3/core": "18.0.0",
-    "@ultimat3/db": "18.0.0",
-    "@ultimat3/entity": "18.0.0",
-    "@ultimat3/flags": "18.0.0",
-    "@ultimat3/http": "18.0.0",
-    "@ultimat3/i18n": "18.0.0",
-    "@ultimat3/jobs": "18.0.0",
-    "@ultimat3/mail": "18.0.0",
-    "@ultimat3/manifest": "18.0.0",
-    "@ultimat3/mcp": "18.0.0",
-    "@ultimat3/money": "18.0.0",
-    "@ultimat3/notify": "18.0.0",
-    "@ultimat3/policy": "18.0.0",
-    "@ultimat3/pwa": "18.0.0",
-    "@ultimat3/query": "18.0.0",
-    "@ultimat3/realtime": "18.0.0",
-    "@ultimat3/render": "18.0.0",
-    "@ultimat3/schema": "18.0.0",
-    "@ultimat3/scraping": "18.0.0",
-    "@ultimat3/seo": "18.0.0",
-    "@ultimat3/storage": "18.0.0",
-    "@ultimat3/testing": "18.0.0",
-    "@ultimat3/time": "18.0.0",
+    "@ultimat3/action": "19.1.0",
+    "@ultimat3/admin": "19.1.0",
+    "@ultimat3/ai": "19.1.0",
+    "@ultimat3/auth": "19.1.0",
+    "@ultimat3/cache": "19.1.0",
+    "@ultimat3/core": "19.1.0",
+    "@ultimat3/db": "19.1.0",
+    "@ultimat3/entity": "19.1.0",
+    "@ultimat3/flags": "19.1.0",
+    "@ultimat3/http": "19.1.0",
+    "@ultimat3/i18n": "19.1.0",
+    "@ultimat3/jobs": "19.1.0",
+    "@ultimat3/mail": "19.1.0",
+    "@ultimat3/manifest": "19.1.0",
+    "@ultimat3/mcp": "19.1.0",
+    "@ultimat3/money": "19.1.0",
+    "@ultimat3/notify": "19.1.0",
+    "@ultimat3/policy": "19.1.0",
+    "@ultimat3/pwa": "19.1.0",
+    "@ultimat3/query": "19.1.0",
+    "@ultimat3/realtime": "19.1.0",
+    "@ultimat3/render": "19.1.0",
+    "@ultimat3/schema": "19.1.0",
+    "@ultimat3/scraping": "19.1.0",
+    "@ultimat3/seo": "19.1.0",
+    "@ultimat3/storage": "19.1.0",
+    "@ultimat3/testing": "19.1.0",
+    "@ultimat3/time": "19.1.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-mcp.ts

@@ -0,0 +1,152 @@
+// The app's own MCP endpoint, mounted by the web role. `defineAppMcp` built `mcp.route` — a
+// `POST` handler with token auth and per-class rate limits — and `app.config.ts` declared
+// `ai: { mcp: { expose: true, path: '/mcp' } }` by DEFAULT, and nothing between the two served it:
+// neither `x dev` nor `runRole` mounted the route, so `POST /mcp` answered `X_ROUTE_NOT_FOUND` in
+// every app ever scaffolded (measured 2026-09-05). The contract is one file: `apps/<app>/mcp.ts`
+// exports `mcp`, an `AppMcp`; this module finds it, and both boots mount what it carries.
+
+// why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join primitive; the config file and each candidate are joined to root.
+import { join } from 'node:path';
+import { logger } from '@ultimat3/core';
+import type { Route } from '@ultimat3/http';
+import { type AppMcp, McpAppUnmountedError } from '@ultimat3/mcp';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+/** The one file an app writes, per app directory. */
+export const APP_MCP_GLOB = 'apps/*/mcp.ts';
+/** The export that file makes — an `AppMcp`, the value `defineAppMcp` returns. */
+export const APP_MCP_EXPORT = 'mcp';
+/** What the boot line and `/_x` call the route. */
+export const APP_MCP_ROUTE_NAME = 'mcp';
+
+export interface AppMcpMount {
+  /** `[]` when `expose` is false, when nothing exports `mcp`, or when the export has no route. */
+  readonly routes: readonly Route[];
+  /** `POST <path>` when mounted, else `null` — the boot line prints it. */
+  readonly path: string | null;
+  /** Set exactly when `expose` is true and `routes` is empty: the reason, as an instruction. */
+  readonly warning: McpAppUnmountedError | undefined;
+}
+
+interface ExposeDeclaration {
+  readonly expose: boolean;
+  readonly path: string;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * `config.ai.mcp`, off the app's own resolved config — the exported `config` is what
+ * `defineConfig` returned, so both keys are present and defaulted. Read the same way
+ * `loadSignInPath` reads `auth.signInPath`: the config file is imported, never re-parsed.
+ * An app with no config file has nothing exposed and nothing to warn about.
+ */
+async function exposeDeclaration(root: string): Promise<ExposeDeclaration | undefined> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(configPath).exists())) return undefined;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!isRecord(config) || !isRecord(config['ai']) || !isRecord(config['ai']['mcp'])) {
+    return undefined;
+  }
+  const mcp = config['ai']['mcp'];
+  const path = mcp['path'];
+  return {
+    expose: mcp['expose'] === true,
+    path: typeof path === 'string' && path.startsWith('/') ? path : '/mcp',
+  };
+}
+
+const isAppMcp = (value: unknown): value is AppMcp =>
+  isRecord(value) && 'server' in value && 'tools' in value && 'route' in value;
+
+/** Every `apps/<app>/mcp.ts`, app-root-relative and sorted, so two apps answer in one order. */
+async function candidates(root: string): Promise<readonly string[]> {
+  // A root with no `apps/` is an app with no MCP file, never a boot failure — the scan's ENOENT
+  // is answered as "none", and the warning below says which file to write.
+  if (!existsSync(join(root, 'apps'))) return [];
+  const files: string[] = [];
+  for await (const file of new Bun.Glob(APP_MCP_GLOB).scan({ cwd: root })) files.push(file);
+  return files.sort();
+}
+
+/**
+ * The route to mount, or the reason there is none. Pure over the filesystem it is pointed at;
+ * `mountAppMcp` below is the one place the warning becomes a log line.
+ *
+ * `meta.auth: 'public'` and `enforcedBy: 'handler'` — the http pipeline must not pre-judge:
+ * `mcp.route.handle` is the one evaluation, and it reads `Authorization: Bearer` through the
+ * `resolveToken` the app gave `defineAppMcp`, then decides per tool through the same policy every
+ * other surface evaluates. A pipeline `auth: 'required'` would demand a session cookie an agent
+ * does not have and answer 401 before the token was ever read.
+ */
+export async function appMcpMount(root: string): Promise<AppMcpMount> {
+  const declared = await exposeDeclaration(root);
+  if (declared === undefined || !declared.expose)
+    return { routes: [], path: null, warning: undefined };
+  const files = await candidates(root);
+  const fallbackFile = 'apps/web/mcp.ts';
+  if (files.length === 0) {
+    return {
+      routes: [],
+      path: null,
+      warning: new McpAppUnmountedError({
+        reason: 'missing',
+        path: declared.path,
+        file: fallbackFile,
+      }),
+    };
+  }
+  for (const file of files) {
+    const module = (await import(join(root, file))) as Record<string, unknown>;
+    const exported = module[APP_MCP_EXPORT];
+    if (!isAppMcp(exported)) continue;
+    const route = exported.route;
+    if (route === undefined) {
+      return {
+        routes: [],
+        path: null,
+        warning: new McpAppUnmountedError({ reason: 'no-route', path: declared.path, file }),
+      };
+    }
+    return {
+      routes: [
+        {
+          method: 'POST',
+          path: declared.path,
+          handler: (request) => route.handle(request.raw),
+          meta: { name: APP_MCP_ROUTE_NAME, auth: 'public', enforcedBy: 'handler' },
+        },
+      ],
+      path: declared.path,
+      warning: undefined,
+    };
+  }
+  return {
+    routes: [],
+    path: null,
+    warning: new McpAppUnmountedError({
+      reason: 'missing',
+      path: declared.path,
+      file: files[0] ?? fallbackFile,
+    }),
+  };
+}
+
+/**
+ * The boot's call: the routes to spread into the table, with the warning already logged ONCE and
+ * the mount announced. Both `x dev` and `runRole` go through here, so a developer's terminal and a
+ * container's log say the same thing about the same endpoint.
+ */
+export async function mountAppMcp(root: string): Promise<AppMcpMount> {
+  const mount = await appMcpMount(root);
+  if (mount.warning !== undefined) {
+    logger.warn(`${mount.warning.code}: ${mount.warning.cause} — fix: ${mount.warning.fix}`);
+  }
+  if (mount.path !== null) logger.info('app mcp mounted', { method: 'POST', path: mount.path });
+  return mount;
+}

package/src/app-root.ts

@@ -12,12 +12,21 @@ export const MANIFEST_FILE = 'x.manifest.json';
  * 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.
+ * 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';
 

package/src/app-runtime.ts

@@ -0,0 +1,39 @@
+// The app's `RuntimeOverrides`, found rather than handed over. `runRole({ runtime })` has taken
+// them since the seam existed, and the scaffolded `apps/web/server.ts` passes none — so an app's
+// own middleware reached no process the framework boots, and `x dev` had no parameter to reach at
+// all (measured 2026-09-05: `x dev` passed only the read-replica override). The contract is one
+// file: `apps/<app>/runtime.ts` exports `runtime`, a `RuntimeOverrides`; `x dev` reads it, and
+// `runRole` reads it when its caller passed nothing, so the two boots compose the same chain.
+
+// why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join primitive; each candidate is joined to the app root.
+import { join } from 'node:path';
+import type { RuntimeOverrides } from './runtime-overrides';
+
+/** The one file an app writes, per app directory. */
+export const APP_RUNTIME_GLOB = 'apps/*/runtime.ts';
+/** The export that file makes — a `RuntimeOverrides`. */
+export const APP_RUNTIME_EXPORT = 'runtime';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * The first `apps/<app>/runtime.ts` exporting `runtime`, or `undefined` when no app declares one.
+ * Sorted, so two apps answer in one order; the object is handed on as declared, because every key
+ * of `RuntimeOverrides` already means "replace the resolved default" wherever a boot reads it.
+ */
+export async function loadAppRuntime(root: string): Promise<RuntimeOverrides | undefined> {
+  // A root with no `apps/` — a bare test fixture, a directory that does not exist — is no app
+  // declaring an override, never a boot failure: the scan's ENOENT is answered as "none".
+  if (!existsSync(join(root, 'apps'))) return undefined;
+  const files: string[] = [];
+  for await (const file of new Bun.Glob(APP_RUNTIME_GLOB).scan({ cwd: root })) files.push(file);
+  for (const file of files.sort()) {
+    const module = (await import(join(root, file))) as Record<string, unknown>;
+    const exported = module[APP_RUNTIME_EXPORT];
+    if (isRecord(exported)) return exported as RuntimeOverrides;
+  }
+  return undefined;
+}

package/src/bin.ts

@@ -3,12 +3,30 @@
 // dispatch.ts, so the whole CLI is testable without spawning a process.
 
 import { dispatch } from './dispatch';
+import { resolveLocalCli } from './local-cli';
 // The writes themselves are `write-line.ts`: `create-ultimate`'s entry point needs the identical
 // one, and a second copy of a note about pipe truncation is a second copy that drifts. Two sinks,
 // because fd 1 is not always this process's to write on — `x mcp serve --transport stdio` hands it
 // to the protocol, and `dispatch` addresses that result to the second.
 import { writeErrorLine, writeLine } from './write-line';
 
+// An app's own CLI sees the app's entity registry; a global one does not. Hand over before
+// deciding anything — see local-cli.ts for the zero-entity manifest this prevents. On fd 2, so a
+// `--json` consumer reading fd 1 sees exactly the child's one document. `process.execPath` is the
+// Bun that is already running, never a `PATH` lookup: the child's `import.meta.path` resolves to
+// the app's file, so its own `resolveLocalCli` answers "same file" and the chain stops at one hop.
+const local = resolveLocalCli({ cwd: process.cwd(), selfPath: import.meta.path, env: Bun.env });
+if (local !== undefined) {
+  writeErrorLine(`x: using the app's own @ultimat3/cli at ${local}`);
+  const child = Bun.spawn([process.execPath, local, ...Bun.argv.slice(2)], {
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+    env: Bun.env,
+  });
+  process.exit(await child.exited);
+}
+
 const code = await dispatch({
   argv: Bun.argv.slice(2),
   cwd: process.cwd(),

package/src/budgets.ts

@@ -111,7 +111,7 @@ export function checkBudgets(
     if (js !== null && measured.jsBytes > js) {
       findings.push({
         code: 'X_BUDGET_EXCEEDED',
-        cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS over a ${formatBytes(js)} budget via ${chainOf(measured)}`,
+        cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS (minified, uncompressed) over a ${formatBytes(js)} budget via ${chainOf(measured)}`,
         fix: `x routes --json to see the chain, then move the heavy import behind hydrate: 'interaction'`,
         docs: ERROR_DOCS_URL,
         at: route.url,

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