@ultimat3/cli 10.0.0 → 11.1.0

package/CLAUDE.md

@@ -193,6 +193,7 @@ cast: a `null` where an id was expected would otherwise become a mutation agains
 | `fix-imports.ts` | which of those factories a file can call that it did not declare — one relative specifier, one file read |
 | `error-contract.ts` | the rules, the two checks that turn them into findings, and `collectDeclaredCodes` |
 | `fix-command.ts` | resolving an `x <command>` a `fix:` cites against the registry |
+| `fix-path.ts` | resolving a PATH or a glob a `fix:` cites against the root the gate is running in |
 | `source-files.ts` | which files are shipped source — shared with `filesize`, never a second list |
 
 **A `fix:` may not cite a command this build does not ship.** Six shipped fix lines named
@@ -201,6 +202,26 @@ one passed — the text rule checks that a fix NAMES a command, never that the r
 `fix-command.ts` resolves the citation, and a PLANNED command fails too: `x logs` parses, `x help`
 lists it, and running it hands the reader `X_NOT_IMPLEMENTED` instead of the fix.
 
+**A `fix:` may not cite a file this repo does not have, either.** That was the other half, and
+nothing resolved it: `X_UI_RUNTIME_MISSING` told its reader to paste a line no generator ever wrote,
+through every gate since it shipped (#274, #246). A file token is one of the four things that make a
+fix an instruction at all (`COMMAND_TOKENS`), so `fix-path.ts` is built from the SAME extension list
+— a token that satisfies the instruction rule is exactly the token this one has to resolve, and two
+lists would be a citation the second rule cannot see. `X_ERROR_FIX_PATH_MISSING` is its own code:
+`X_ERROR_FIX_INVALID` means the fix is not an instruction, this one means it is one and points at
+nothing, and the repairs differ.
+
+It is narrow so a finding never has to be argued with — three shapes are not judged at all, because
+each resolves against something other than the root the gate is running in: a scoped specifier
+(`@ultimat3/ui/global.scss`, which resolves through `node_modules`), a dot-relative path
+(`./global.scss`, which resolves against the reader's own file) and any path whose **parent
+directory** this root does not have (`src/errors.ts`, `apps/web/server.ts`,
+`packages/i18n/catalogs/en.json` — all three name a directory a generated app has and this repo does
+not). What is left is the citation a root really can answer: a directory that exists, named as
+holding a file it does not hold. A glob must match at least one file. Measured over all three roots
+the gate runs in — the framework, `examples/dummy`, `dummy/social-media-clone` — **117 path citations
+read, 0 findings**, so it enforces outright with no pin table.
+
 The rule is **conditional, and that is load-bearing**: *if* a fix cites `x <command>`, it must
 resolve. It does not require every fix to name one — `set OTEL_EXPORTER_OTLP_ENDPOINT=…` and
 `counter('orders_total', { maxSeries: 4000 })` are executable and correctly cite nothing, and a
@@ -235,6 +256,33 @@ that named the code in its `<PKG>_BORROWED_ERROR_CODES`. The docs check reads it
 framework's own `framework.manifest.json`, because a second scanner over a narrower file set is a
 manifest that claims completeness it does not have.
 
+**A `code:` is a literal, a module-scope const in the same file, or a finding** — `As of 2026-08-23`,
+and until then it was a literal or silence. `scanCodes` matched `code\s*[:=]\s*'X_…'`, so
+`const STALE = 'X_DOC_PACKAGE_GRAPH_STALE'` followed by `code: STALE` — the DRY thing to write, and
+what `scripts/package-map-graph.ts` really wrote — was a declaration to nobody: no manifest row, no
+row demanded on `wiki/Error-Codes.md`, no entry for `bun run gate-codes`, and `x errors explain`
+answering `X_ERROR_CODE_UNKNOWN` for a code the build throws. Silent, and in the **permissive**
+direction: the DRYer the author, the less the gate saw (#277).
+
+`scanCodeDeclarations` is that one pass, and it returns both halves. It resolves the identifier
+against the module-scope consts of the **same file** — anchored at column 0, which is what makes it
+module scope without a parser — and reports every name it cannot resolve as `X_ERROR_CODE_UNRESOLVED`
+rather than skipping it, which is the whole point: a scanner that reads only what it likes enforces
+only what it sees. `scanCodes` is its `.sites`, so the manifest, the docs check, `bun run gate-codes`
+and `x errors explain` (through `scanCodeFixSites`, which resolves the same way) cannot see different
+sets. Cross-file resolution was **refused** even though `fix-imports.ts` already does the harder
+version for `fix:`: it would make the scan async for every caller, and the finding is the better
+answer anyway — one file holds both the code and its only spelling.
+
+Three shapes are deliberately not judged, each measured over the framework and both tracked apps
+before the rule shipped. A name that resolves to something that is **not** a code is an answer, not
+a gap (`const STATUS_NOT_FOUND = 404` in `@ultimat3/realtime`'s NATS fake, the one live instance). A
+**table read** is not judged — `SEO_ERROR_CODES.metaMissing` is how `@ultimat3/seo` and
+`@ultimat3/ui` raise all 18 of their codes, and the registry those literals live in already declares
+them. A **lowercase** name is not judged: 164 sit at a `code:` position in this tree and every one is
+a type annotation (`readonly code: string`) or a re-raise (`code: opts.code`). Measured on all three
+roots: **0 findings**, so it enforces outright with no pin table.
+
 An empty `fix`, or a `fix` that says `check` / `make sure` / `try` / `see the docs` and names no
 command, call or file path, is `X_ERROR_FIX_INVALID`. A declared code the host's error reference
 does not name is `X_ERROR_CODE_UNDOCUMENTED` — `wiki/Error-Codes.md` here, nothing in a generated
@@ -542,7 +590,9 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `otlp-export.ts` | the exporters `OTEL_EXPORTER_OTLP_ENDPOINT` switches on, and their drain hooks |
 | `dev-render.ts` | one HTTP route per registered `route`, through render's own mode function |
 | `style-csp.ts` | the `style-src` sha256 of every inline `<style>` the web role serves |
+| `script-csp.ts` | the `script-src` sha256 of every inline `<script>` it serves — the hydration runtime, from `@ultimat3/render`'s own `HYDRATE_RUNTIME_BODIES` |
 | `dev-assets.ts` | the image pipeline's only HTTP surface: `/icons/*` and `/media/*` |
+| `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-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 |
@@ -654,6 +704,23 @@ missing.
 | `prerender.ts` | build first, write the chunks into the export, then measure |
 | `budgets.ts` | `measureDocumentJs` weighs `data-x-entry` as well as `<script src>` |
 
+**A stats row is keyed by the route's DECLARED path, and holds its heaviest page**
+(`As of 2026-08-23`). `checkBudgets` looks a route up by `route.url` off the manifest, which is the
+pattern (`/blog/:slug`), and `prerenderSite` pushed `artifact.path` — the filled one
+(`/blog/hello`). So no dynamic static route had ever been weighed: each was `X_BUDGET_UNMEASURED`
+and `X_BUDGET_EXCEEDED` could not fire for the whole class. The heaviest page and not the first,
+because a budget is a ceiling and the page that breaks it is the one the route answers for; the
+report's `emitted` list still names every filled path.
+
+**Both halves of the CSP are computed at boot, `As of 2026-08-23`.** `style-csp.ts` was alone, and
+the hydration runtime is emitted INLINE in every document carrying an island — so with
+`script-src 'self' 'wasm-unsafe-eval'` no island booted in any container. `x dev` sends the policy
+report-only (`dev: true`), which is exactly why nobody saw it: the page hydrated on a laptop and
+never in the image. `startWeb` extends both directives; the property is pinned end to end by
+`dev-roles-script-csp.test.ts`, which parses a served document, hashes every executable inline
+script in it and asserts the response's own `script-src` names each one — with `dev: false`, the
+only mode in which the policy can block anything.
+
 **One `Bun.build` per island, never one call with N entry points**, and `splitting: false`. The
 island's `src` is a string, so no import edge reaches it and the page's graph stays the page's
 (axiom 6) — a shared chunk would put that number back behind a graph walk, and the budget compares
@@ -719,6 +786,21 @@ width is not one of the eight. Anything outside it is still served; only the `pu
 no caller gains a new 4xx. `?q=` is deliberately still unbounded here — the closed set for quality
 is `@ultimat3/seo`'s to declare, not this file's.
 
+**`/favicon.ico` is a mechanism, not a scaffolded file.** Every browser requests it unprompted, the
+scaffold wrote none and neither served surface mounted a route, so a permanent 404 sat in the console
+of every app the framework produces — noise that trains the reader to ignore console errors, which is
+the opposite of what `--json` and an executable `fix:` are for (#272). Two rungs and one path: the
+app's own `apps/web/site/favicon.ico` wins, and `favicon.ts` answers a 32x32 PNG encoded through
+`@ultimat3/core`'s own pipeline when there is none — the same encoder `x new`'s icon goes through, so
+there is no second image format in the tree and no base64 blob nobody can verify. It is deliberately
+NOT derived from `ICON_SOURCE`: resizing the install icon needs `@ultimat3/pwa`'s pipeline and would
+make the answer depend on a file that may be absent, which is a third rung under a mechanism that has
+exactly two. The file is read per REQUEST, so dropping one into a running `x dev` takes effect
+without a restart. It mounts through `assetRoutes`, which is the one route set `serve.ts` and
+`cmd-dev.ts` both compose — a favicon added to one of them alone is a 404 that comes back in
+production only — and `prerenderSite` writes the same bytes into the static export, because an
+artifact served with no process behind it has to carry every byte the browser will ask for.
+
 `ICON_SOURCE` lives here, not in `cmd-doctor.ts`, because this is the module that reads it: the
 diagnostic checks what `x dev` serves, so one constant cannot pass the check and serve nothing.
 It is a **PNG** — core decodes PNG and JPEG only, and the SVG this used to name could never
@@ -745,6 +827,22 @@ watcher — *after* the drain, so an in-flight request still has the database it
 Ctrl-C is therefore the same three phases production runs, not a kill that leaves `.x/pgdata`
 locked by a process that no longer exists.
 
+**The release runs INSIDE the drain's own deadline, `As of 2026-08-23`, and it is the same
+deadline.** `drain()` ABANDONS a hook that overruns `ShutdownReason.deadlineAt` — the process is
+meant to exit without it — and `release` re-enters the very same teardown one call later:
+`app.stop()` → `startRoles().stop()` → `worker.stop()`, memoised in the package that owns it, so
+awaiting it is awaiting the promise the drain just walked away from. Unbounded, that hung past
+`terminationGracePeriodSeconds` and the kubelet SIGKILLed a process that had already drained
+cleanly. The budget is the hook's own `reason.deadlineAt`, not a stopwatch of ours, so there is one
+number and not two; an overrun is logged as `X_SHUTDOWN_TIMEOUT` and a REJECTION still rejects,
+because `dispatch` awaits the hold inside its own `try`.
+
+**`options.exit` has exactly one caller: `runRole` in `serve.ts`.** `bin.ts` ends in
+`process.exit(code)`, so `x dev` and `x mcp` need nothing; `apps/web/server.ts` — which is what a
+container runs — has no such line, and one non-unref'd interval anywhere in the app then holds an
+event loop with nothing left to do. A function rather than a boolean because `process.exit` inside
+a library is untestable, and the caller is the one that knows.
+
 Commands: `bun test`, `bunx tsc --noEmit -p tsconfig.json`.
 
 ## A declared flag with no reader is a promise `x help` makes and nothing keeps

package/package.json

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

package/src/budgets.ts

@@ -16,6 +16,12 @@ import type { Finding } from './output';
 export const BUILD_STATS_FILE = join('.x', 'build-stats.json');
 
 export interface RouteStats {
+  /**
+   * The route's DECLARED path — `/blog/:slug`, never `/blog/hello`. `checkBudgets` looks a row up
+   * by `route.url` off the manifest, which is the pattern, so a row keyed by a filled path is a
+   * row nothing can find: every dynamic static route read as `X_BUDGET_UNMEASURED`. A route that
+   * prerenders many pages contributes ONE row, holding its heaviest.
+   */
   readonly path: string;
   readonly jsBytes: number;
   /**

package/src/cmd-db-backfill.ts

@@ -27,6 +27,7 @@ import type { CommandResult } from './output';
 import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
+import { quoteArg } from './shell-quote';
 
 /** Which of the four questions an invocation asked. `pass` is `<name>` and `--all` both. */
 type BackfillShape = 'list' | 'pending' | 'pass';
@@ -73,11 +74,23 @@ function readShape(args: ParsedArgs): { readonly shape: BackfillShape; readonly
   // `--name` is a FILTER under `--list` and a target everywhere else, so it selects a shape only
   // where `--list` is absent. Two spellings of one target are still two, and are refused.
   const target = list ? undefined : (positional ?? named);
+  // Under `--list` the positional is DROPPED by the line above, and until 2026-08 nothing said so:
+  // `x db backfill cleanup --list` printed the whole ledger and reported `ok: true` while the
+  // operator had named one sweep. `--name` is the filter's one spelling here, so this is a refusal
+  // and not a second reading of the argument — the same rule every other shape in this function
+  // follows, and the same argv one flag over (`--pending cleanup`) has always been refused.
+  if (list && positional !== undefined) {
+    return refuseShape(
+      'name',
+      `x db backfill --list filters the ledger with --name, so the positional "${positional}" selects nothing — it is a pass target in every other shape`,
+      `x db backfill --list --name ${quoteArg(positional)} --json`,
+    );
+  }
   if (!list && positional !== undefined && named !== undefined) {
     return refuseShape(
       'name',
       `x db backfill names two backfills ("${positional}" and "${named}") — a pass sweeps the positional or --name, never both`,
-      `x db backfill ${positional} --write --json`,
+      `x db backfill ${quoteArg(positional)} --write --json`,
     );
   }
   const asked = [

package/src/cmd-dev.ts

@@ -199,6 +199,9 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // declaration, and `x dev` and `serve.ts` must not be able to disagree about where the app's
     // sign-in page is.
     signInPath: await loadSignInPath(options.root),
+    // The same seam `serve.ts` passes: the app's own error page is a FILE, so the root is what
+    // `startWeb` needs to find one.
+    root: options.root,
     // The one document this process serves that the app did not write; `startRoles` covers the
     // app's own surfaces itself. `x dev` sends the policy report-only, so an uncovered `<style>`
     // here is a console report rather than a blank page — which is how this reached production.

package/src/cmd-new.ts

@@ -8,7 +8,8 @@ import { isAbsolute, join, resolve } from 'node:path';
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { dedupe } from './cmd-generate';
 import type { CliCommand, CommandContext } from './command';
-import { MissingPositionalError } from './errors';
+import { invocationOf } from './command';
+import { AppNameIsPathError, MissingPositionalError } from './errors';
 import type { Runner } from './exec';
 import { msg } from './messages';
 import type { CommandResult } from './output';
@@ -116,7 +117,8 @@ export interface WrittenApp {
  * a migration whose snapshot never existed is what made the app's first two database commands
  * refuse each other — `x db migrate` naming `x db gen`, and `x db gen` refusing a sidecar version
  * control never had. The consequence is deliberate: `x verify`'s `drift` step is red on a pristine
- * scaffold until `x db gen "initial"` runs, which is what `cli.new.done` tells the author to do.
+ * scaffold until `x db gen "initial"` runs — which `bin/setup` does, and which is what
+ * `cli.new.done` tells the author to run.
  */
 export async function writeNewApp(target: string, options: NewAppOptions): Promise<WrittenApp> {
   const files = planNewApp(options);
@@ -130,6 +132,24 @@ function parentDir(cwd: string, dirFlag: string | undefined): string {
   return isAbsolute(dirFlag) ? dirFlag : join(cwd, dirFlag);
 }
 
+/**
+ * The `--dir`/name split of a positional that is really a path, or `undefined` when it is a name.
+ *
+ * Separator-agnostic: a Windows path pasted into a shell here is the same mistake, and `\` is not
+ * a character any app name may hold either.
+ */
+export function appNamePath(raw: string): { parent: string; base: string } | undefined {
+  if (!/[\\/]/.test(raw)) return undefined;
+  const trimmed = raw.replace(/[\\/]+$/, '');
+  const segments = trimmed.split(/[\\/]+/).filter((segment) => segment.length > 0);
+  const base = segments.at(-1) ?? 'myapp';
+  const parent = trimmed.slice(0, trimmed.lastIndexOf(base)).replace(/[\\/]+$/, '');
+  // `x new ./shop` and `x new shop/` both name the directory the caller is already in; `/shop`
+  // names the root, which is a directory and not "here".
+  if (parent !== '' && parent !== '.') return { parent, base };
+  return { parent: /^[\\/]/.test(trimmed) ? '/' : '.', base };
+}
+
 export const newCommand: CliCommand = {
   spec: {
     name: 'new',
@@ -143,7 +163,7 @@ export const newCommand: CliCommand = {
       {
         // The summary carries the default and the negation because the page has to answer "which
         // one do I get if I type neither": the usage line offered `--no-example`, this table said
-        // `--example`, and `default: true` is a field only `--json` renders. 134 files against 107.
+        // `--example`, and `default: true` is a field only `--json` renders. 136 files against 109.
         name: 'example',
         type: 'boolean',
         summary: 'include the example feature slice (default: on; --no-example for an empty app/)',
@@ -168,9 +188,19 @@ export const newCommand: CliCommand = {
       throw new MissingPositionalError({
         command: 'new',
         positional: 'name',
-        example: 'x new myapp',
+        // Never the literal `x new`: this command is also the whole of `bunx create-ultimate`,
+        // which runs BEFORE `x` exists — so the one instruction the reader was given named a
+        // binary they had not installed yet.
+        example: `${invocationOf(ctx, 'new')} myapp`,
       });
     }
+    // Before `names()`, which is what makes this reachable at all: it slugifies a path into one
+    // kebab-case directory name, so `/srv/apps/shop` becomes `srv-apps-shop` inside the cwd and
+    // the scaffold lands somewhere nobody asked for. `--dir` is the flag that takes a path.
+    const path = appNamePath(raw);
+    if (path !== undefined) {
+      throw new AppNameIsPathError({ name: raw, invocation: invocationOf(ctx, 'new'), ...path });
+    }
     const app = names(raw);
     const target = resolve(parentDir(ctx.cwd, flagString(ctx.args, 'dir')), app.kebab);
     const options: NewAppOptions = { name: raw, example: ctx.args.flags.get('example') !== false };

package/src/command.ts

@@ -13,8 +13,20 @@ export interface CommandContext {
   readonly runner: Runner;
   readonly env: Readonly<Record<string, string | undefined>>;
   readonly bunVersion: string;
+  /**
+   * How this process was invoked, up to and including the subcommand — `x new`, or
+   * `bunx create-ultimate` when `create-ultimate` is the entry point. Read by a `fix:` line, which
+   * is a command the reader is meant to RUN: `create-ultimate`'s whole reason to exist is running
+   * before `x` is installed, so `x new myapp` was an instruction nobody in that process could
+   * follow. Absent means the default below — a caller that builds a context by hand owes nothing.
+   */
+  readonly invocation?: string;
 }
 
+/** What `ctx.invocation` means when nobody said: the binary, then the subcommand they typed. */
+export const invocationOf = (ctx: CommandContext, command: string): string =>
+  ctx.invocation ?? `x ${command}`;
+
 export interface CliCommand {
   readonly spec: CommandSpec;
   run(ctx: CommandContext): Promise<CommandResult>;

package/src/dev-assets.ts

@@ -23,6 +23,7 @@ import {
   authorizeStorageRead,
   STORAGE_READ_PERMISSION,
 } from './dev-storage';
+import { faviconRoute } from './favicon';
 
 /**
  * The one source image every generated icon derives from. `x new` scaffolds it, `x doctor` checks
@@ -254,6 +255,11 @@ export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
     handler: async (request: UltimateRequest, ctx: RequestContext): Promise<Response> =>
       mediaResponse(request, ctx, options.storage, options.images),
   });
+  // Mounted here rather than in `serve.ts` and `cmd-dev.ts` separately: this is the one route set
+  // both served surfaces already compose, and a favicon that answers on a laptop and 404s in the
+  // container is the dev/prod difference this package's own rule forbids. `favicon.ts` owns what
+  // the answer IS — this file only says the app's asset surface is where it hangs.
+  routes.push(faviconRoute(options.root));
 
   return routes;
 }

package/src/dev-hooks.ts

@@ -41,14 +41,22 @@ export interface DevHookOptions {
    * that starts a web role — `serve.ts` included — carry a diagnostic only one of them installs.
    */
   readonly devNotices?: ServerHooks['devNotices'];
+  /**
+   * The app's own error page for a status, read off its disk. Passed for `devNotices`' reason: a
+   * hook that reached for the app root itself would make every host that starts a web role carry a
+   * path only the one that knows the root can supply.
+   */
+  readonly errorPage?: ServerHooks['errorPage'];
 }
 
 export function devHooks(options: DevHookOptions = {}): ServerHooks {
   const authenticate = configuredAuthenticator();
   const devNotices = options.devNotices;
+  const errorPage = options.errorPage;
   return {
     ...(authenticate === undefined ? {} : { authenticate }),
     ...(devNotices === undefined ? {} : { devNotices }),
+    ...(errorPage === undefined ? {} : { errorPage }),
     authorize: (route, _request, ctx): AuthzDecision => {
       // An action route never arrives here: it carries `enforcedBy: 'handler'`, so the pipeline
       // never asks. `invoke` is its one evaluation, and the only one holding the row a row-level

package/src/dev-purge.ts

@@ -112,9 +112,15 @@ function declareSweep(): void {
  * background work at all, and this is one more thing it does not do.
  */
 export function installRetentionSweep(stores: RetentionStores): () => void {
-  installed = retentionTargets(stores);
+  const mine = retentionTargets(stores);
+  installed = mine;
   declareSweep();
   return () => {
-    installed = [];
+    // Only if the slot is still OURS. Two runtimes can share one process — a test harness, or
+    // `x shot`'s scratch server beside the one it photographs — and a boot that installed after
+    // this one owns the slot now: emptying it there would leave the LIVE boot's hourly sweep
+    // deleting nothing, forever, with no error anywhere. Same rule, and the same comment, as
+    // `installedRevalidator` in `@ultimat3/render`'s ISR controller.
+    if (installed === mine) installed = [];
   };
 }

package/src/dev-render.ts

@@ -183,11 +183,14 @@ async function resultFor(
       return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'isr': {
-      // `isrKey(url)`, never `url.pathname`: the query is part of what was rendered — this
+      // `isrKey(url, locale)`, never `url.pathname`: the query is part of what was rendered — this
       // route's own `meta` reads `data.url` — so two URLs differing only in their query are two
       // documents. Keyed on the pathname alone, the first render answered every later query
       // string (#171). Render owns the derivation so no second caller can invent another.
-      const served = await isr.serve(isrKey(url), () =>
+      // The locale is the second dimension and it is `ctx.locale`, the answer the `locale` stage
+      // already negotiated for THIS request — never `currentLocale()`, which would read the same
+      // value through an ambient store the key does not need.
+      const served = await isr.serve(isrKey(url, ctx.locale), () =>
         documentFrom(entry, request, data, options),
       );
       return served.result;

package/src/dev-roles.ts

@@ -26,9 +26,11 @@ import { startReplicator } from './dev-replicator';
 import type { RunningServices } from './dev-runtime';
 import type { Env } from './dev-services';
 import { startSync } from './dev-sync';
+import { errorPageHook } from './error-pages';
 import { BadFlagError, PortInvalidError, RuntimeDriverSplitError } from './errors';
 import { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
 import type { RuntimeOverrides } from './runtime-overrides';
+import { inlineScriptSources } from './script-csp';
 import { inlineStyleSources } from './style-csp';
 
 /** The roles `x dev` starts when `--role` names none, in boot order. */
@@ -63,6 +65,16 @@ export interface StartRolesOptions {
    * `startRoles` takes plain values — a test starts a web role with no `app.config.ts` at all.
    */
   readonly signInPath?: string | null;
+  /**
+   * The app root, for the one seam that is a FILE and not a value: `apps/web/site/errors/404.html`
+   * and its siblings. Bound HERE rather than passed by each caller, because `x dev` and `serve.ts`
+   * both boot through this function and an override wired at one of them alone is a page that
+   * appears in dev and not in production — `/favicon.ico`'s rule, one seam over.
+   *
+   * Optional for the reason `signInPath` is: `startRoles` takes plain values, and a test starts a
+   * web role with no app on disk at all. Absent, every error page is the framework's.
+   */
+  readonly root?: string;
   /**
    * Inline `<style>` bodies this process serves that the app's own surfaces do not account for —
    * `/_x`'s shell. The surfaces themselves are read from the stylesheet registry here rather than
@@ -235,7 +247,10 @@ function startWeb(options: StartRolesOptions): ServerHandle {
   return createServer({
     routes: options.routes,
     role: 'web',
-    hooks: devHooks(options.devNotices === undefined ? {} : { devNotices: options.devNotices }),
+    hooks: devHooks({
+      ...(options.devNotices === undefined ? {} : { devNotices: options.devNotices }),
+      ...(options.root === undefined ? {} : { errorPage: errorPageHook(options.root) }),
+    }),
     // Both seams `createServer` already had and `startRoles` passed neither of, so an app's own
     // middleware could not reach the pipeline any process the framework boots actually runs.
     ...(options.overrides?.middleware === undefined
@@ -260,8 +275,17 @@ function startWeb(options: StartRolesOptions): ServerHandle {
       // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
       // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a
       // function of that body. Read after `loadApp` — importing the app IS what registered them.
+      // BOTH directives, and the script half is the one that was missing: the hydration runtime
+      // is emitted inline in every document that carries an island, so `script-src 'self'` meant
+      // no island booted anywhere the policy is enforced — which is every container, and never
+      // `x dev`, where it is report-only.
       security: {
-        csp: { extend: { 'style-src': inlineStyleSources(options.inlineStyles ?? []) } },
+        csp: {
+          extend: {
+            'style-src': inlineStyleSources(options.inlineStyles ?? []),
+            'script-src': inlineScriptSources(),
+          },
+        },
       },
     }),
   }).start();

package/src/dispatch.ts

@@ -31,6 +31,13 @@ export interface DispatchOptions {
    * it cannot produce. `bin.ts` passes the real fd 2.
    */
   readonly writeError?: (line: string) => void;
+  /**
+   * How the caller invoked this process, up to and including the subcommand — passed straight to
+   * `CommandContext.invocation` and read by the `fix:` lines that quote a whole command back.
+   * `create-ultimate` is the one caller that supplies it, because it is the one entry point whose
+   * name is not `x`.
+   */
+  readonly invocation?: string;
 }
 
 /**
@@ -122,6 +129,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     runner: options.runner ?? exec,
     env: options.env,
     bunVersion: options.bunVersion,
+    ...(options.invocation === undefined ? {} : { invocation: options.invocation }),
   };
 
   try {

package/src/error-catalog.ts

@@ -44,12 +44,22 @@ export const CATALOG_PACKAGES = [
   '@ultimat3/ui',
 ] as const;
 
+/**
+ * The two packages the catalog may import WITHOUT `@ultimat3/cli` declaring them: they reach for a
+ * JSX runtime an app has and a bare CLI process does not, so a hard dependency would make the CLI
+ * uninstallable where the codes are merely absent today. Every other entry above is a real runtime
+ * import and must be a declared dependency — `error-catalog.test.ts` holds the list to exactly that,
+ * because an undeclared one resolves through workspace symlinks here and through nothing in an
+ * installed app, where `x errors explain X_FLAG_EXPIRED` then refuses a code the wiki promises.
+ */
+export const CATALOG_OPTIONAL_HOSTS: readonly string[] = ['@ultimat3/admin', '@ultimat3/ui'];
+
 export interface ErrorCatalog {
   /** Packages whose codes are now registered. */
   readonly loaded: readonly string[];
   /**
    * Packages this process could not *resolve*, so their codes are absent from the answer. The one
-   * tolerated case is the optional host: `@ultimat3/ui` and `@ultimat3/admin` reach for a JSX
+   * tolerated case is the optional host: `CATALOG_OPTIONAL_HOSTS` reach for a JSX
    * runtime an app has and a bare CLI process does not, and a list silently missing their codes is
    * worse than one that says which packages are missing. A package that resolved and then threw is
    * a defect, not a host gap, and goes to `failed`.

package/src/error-codes.ts

@@ -21,8 +21,15 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_JOB_UNKNOWN',
   'X_FIX_TARGET_UNKNOWN',
   'X_ERROR_FIX_INVALID',
+  // The second half of the same contract: X_ERROR_FIX_INVALID means the fix is not an instruction,
+  // this one means it is one and cites a file that is not there. Two conditions, two repairs.
+  'X_ERROR_FIX_PATH_MISSING',
   'X_ERROR_CODE_UNDOCUMENTED',
   'X_ERROR_CODE_UNREGISTERED',
+  // The third: a `code:` the scan cannot read at all. `const STALE = 'X_…'` in another file and
+  // `code: STALE` here is invisible to every reader of the code set, and silence there is
+  // permissive — the DRYer the author, the less the gate sees (#277).
+  'X_ERROR_CODE_UNRESOLVED',
   // Reported as `Finding`s rather than thrown, and unregistered until now because of it — so
   // `x errors explain X_TYPECHECK_FAILED` refused a code `x verify` had just printed. A finding
   // carries an `X_*` code to the same reader a throw does; the registry is what makes that code
@@ -46,6 +53,11 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_STORAGE_SECRET_DEV',
   'X_MANIFEST_STALE',
   'X_BUDGET_UNMEASURED',
+  // The other half of #271, and the half no runtime can raise: a route reads a live hook and boots
+  // no module in a browser, so its rows have nowhere to arrive and the page renders its loading
+  // branch forever, at 200. Only this package can see it — `@ultimat3/realtime` cannot see a route
+  // and `@ultimat3/render` may not import realtime.
+  'X_LIVE_ROUTE_NO_ISLAND',
   'X_BUILD_FAILED',
   'X_BUILD_ENTRY_MISSING',
   'X_DEPLOY_FAILED',
@@ -160,8 +172,10 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_JOB_UNKNOWN: 'the queue holds no job with this id',
   X_FIX_TARGET_UNKNOWN: 'the named file is not one of the app source files',
   X_ERROR_FIX_INVALID: "an error's fix line is not a runnable instruction",
+  X_ERROR_FIX_PATH_MISSING: "an error's fix line cites a file this repository does not have",
   X_ERROR_CODE_UNDOCUMENTED: 'a shipped error code has no row in the error reference',
   X_ERROR_CODE_UNREGISTERED: 'the error reference documents a code no package registers',
+  X_ERROR_CODE_UNRESOLVED: 'an error code is written as a name this repository cannot resolve',
   X_STORAGE_UNWRITABLE: 'the storage disk this process needs cannot be written to',
   X_STORAGE_SECRET_DEV: 'upload grants would be signed with the shipped development key',
   X_CLI_UNEXPECTED: 'the CLI itself failed',
@@ -175,6 +189,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_RELEASE_VERSION_SKEW: 'a workspace is not at the lockstep version',
   X_MANIFEST_STALE: 'openapi.json is stale',
   X_BUDGET_UNMEASURED: 'a route declares a budget the build never measured',
+  X_LIVE_ROUTE_NO_ISLAND: 'a route reads live rows and boots nothing that could receive them',
   X_BUILD_FAILED: 'x build failed',
   X_BUILD_ENTRY_MISSING: "the build target's entry file is not in the app",
   X_DEPLOY_FAILED: 'a deploy step failed',