@ultimat3/cli 20.2.1 → 22.0.0

package/src/cmd-verify.ts

@@ -9,13 +9,14 @@
 
 import { nearestName } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
+import { verifySpec } from './cmd-verify-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
 import { readIntFlag } from './flag-number';
 import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
-import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+import { WORKER_CEILING, WORKER_FLOOR } from './test-workers';
 import { VERIFY_STEPS } from './verify-checks';
 import { runVerify } from './verify-run';
 import type { VerifyStepName } from './verify-step';
@@ -28,28 +29,7 @@ export { VERIFY_STEPS } from './verify-checks';
 export { runVerify } from './verify-run';
 
 export const verifyCommand: CliCommand = {
-  spec: {
-    name: 'verify',
-    summary: 'the gate: typecheck, lint, boundaries, all tests, drift, contract, budgets',
-    usage: 'x verify [--only <step>] [--workers N] [--json]',
-    requiresApp: true,
-    // Two flags, and only one of them narrows. `--workers` changes how wide the test steps
-    // spread, never which steps run. `--only` runs one step and says so in both renderers —
-    // never silently, which is the whole of what makes it safe to have.
-    flags: [
-      {
-        name: 'workers',
-        type: 'string',
-        summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
-      },
-      {
-        name: 'only',
-        type: 'string',
-        summary:
-          'run ONE step by name — an iteration loop, NOT A GATE RUN; the gate is this command with no flag',
-      },
-    ],
-  },
+  spec: verifySpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('verify', ctx.cwd).dir;
     // Both readers before the run: an unrunnable flag must be refused in milliseconds, not after

package/src/db-seed.ts

@@ -16,6 +16,7 @@ import { BadFlagError } from './errors';
 import type { Finding, JsonValue } from './output';
 import { findingFrom } from './output';
 import { hasPathSegment } from './path-segments';
+import { isTest } from './source-files';
 import { renderTable } from './table';
 
 /**
@@ -102,10 +103,11 @@ export async function discoverSeeds(root: string): Promise<SeedDiscovery> {
   const seen = new Set<string>();
   for (const pattern of SEED_GLOBS) {
     for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
-      if (hasPathSegment(absolute, 'node_modules') || absolute.includes('.test.')) continue;
+      const file = relative(root, absolute).split(sep).join('/');
+      // Root-relative, as `loadApp` tests it: an absolute path under `my.test.app/` is no test.
+      if (hasPathSegment(absolute, 'node_modules') || isTest(file)) continue;
       if (seen.has(absolute)) continue;
       seen.add(absolute);
-      const file = relative(root, absolute).split(sep).join('/');
       let module: Record<string, unknown>;
       try {
         module = (await import(absolute)) as Record<string, unknown>;

package/src/dev-dashboard.ts

@@ -22,14 +22,14 @@ import { json as jsonResponse } from '@ultimat3/http';
 import type { MemoryMailDriver } from '@ultimat3/mail';
 import { isMemoryDriver } from '@ultimat3/mail';
 import type { Manifest } from '@ultimat3/manifest';
-import { checkAppBoundaries } from './app-boundaries';
 import { appManifest, readAppManifest } from './app-manifest';
+import { appBoundaryFindings } from './boundary-findings';
 import type { StatementLedger } from './dev-n-plus-one';
 import { devPolicyMatrix } from './dev-policy';
-import type { RunningServices } from './dev-runtime';
-import type { DevServices } from './dev-services';
 import type { TraceRecorder } from './dev-traces';
 import type { Finding } from './output';
+import type { DevServices } from './runtime-bindings';
+import type { RunningServices } from './runtime-services';
 import { loopFacts } from './statement-loop';
 
 export interface DevStatus {
@@ -195,7 +195,7 @@ const boundariesPanel = (input: DevDashboardInput): DevPanel<BoundariesPanelData
   titleKey: 'dev.panel.boundaries.title',
   questionKey: 'dev.panel.boundaries.question',
   async data(): Promise<BoundariesPanelData> {
-    return { findings: await checkAppBoundaries(input.root) };
+    return { findings: await appBoundaryFindings(input.root) };
   },
 });
 

package/src/dev-lock.ts

@@ -14,7 +14,7 @@
 // The lock file is what makes the second one nameable at all: nothing else in the process can tell
 // "another dev server owns this directory" from "the database is broken".
 
-import { closeSync, mkdirSync, openSync, unlinkSync, writeFileSync } from 'node:fs';
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { stringField, UltimateError } from '@ultimat3/core';
 import { exec, type Runner } from './exec';
@@ -75,11 +75,27 @@ export const isProcessAlive = (pid: number): boolean => {
   }
 };
 
+/**
+ * The lock a LIVE `x dev` holds on this state directory, or `undefined` — for a command that must
+ * not run beside one (`x db reset` deletes the data directory that process has open). A missing,
+ * unreadable or stale lock is no holder: only `preflight` may clear one.
+ */
+export const liveDevLock = (stateDir: string): DevLock | undefined => {
+  let raw: string;
+  try {
+    raw = readFileSync(lockPath(stateDir), 'utf-8');
+  } catch {
+    return undefined;
+  }
+  const lock = parseLock(raw);
+  return lock !== null && isProcessAlive(lock.pid) ? lock : undefined;
+};
+
 /**
  * Refused before boot, so the failure names the process holding the directory.
  *
  * The lock is on the CHECKOUT, not on the database, and the cause says so. `x dev` is one process
- * running every role (`dev-roles.ts`), so a second one is unsupported whatever the services are.
+ * running every role (`role-start.ts`), so a second one is unsupported whatever the services are.
  * The embedded-Postgres sentence is appended only when the database actually IS embedded — with an
  * external `DATABASE_URL` it would name a mechanism that is not in play, which is the same defect
  * as the message this whole module replaced.

package/src/dev-port.ts

@@ -0,0 +1,21 @@
+// Which port `x dev` binds: `--port`, else `PORT` from the environment, else 3000. The flag used to
+// declare `default: '3000'`, and a default is indistinguishable from a caller's value — so the
+// scaffold's own `.env.development` `PORT=` was read by nothing and every app booted on 3000.
+
+import { PORT_RANGE, readIntFlag } from './flag-number';
+import type { ParsedArgs } from './parse';
+import { portFromEnv } from './serve';
+
+export const DEFAULT_DEV_PORT = 3000;
+
+/** The `metricsPortFor` shape: an explicit value, then the env, then the constant. */
+export const devPortFor = (
+  args: ParsedArgs,
+  env: Readonly<Record<string, string | undefined>>,
+): number =>
+  readIntFlag(args, {
+    name: 'port',
+    command: 'dev',
+    ...PORT_RANGE,
+    example: `x dev --port ${DEFAULT_DEV_PORT}`,
+  }) ?? portFromEnv(env);

package/src/dev-route-table.ts

@@ -0,0 +1,119 @@
+// The route table `x dev` serves, in mount order: the dashboard, the API, the assets a document
+// names, the island and sync-worker scripts, and the app's pages last. Split from `cmd-dev.ts` at its
+// 500-line ceiling; `serve.ts` composes the production table from the same builders.
+
+import type { Route } from '@ultimat3/http';
+import { describeRoutes } from '@ultimat3/render';
+import type { Storage } from '@ultimat3/storage';
+import { apiRoutes } from './api-routes';
+import { mountAppMcp } from './app-mcp';
+import type { DevDashboardInput } from './dev-dashboard';
+import { devDashboardRoutes } from './dev-dashboard';
+import { errorPageStyleSources } from './error-page-csp';
+import type { IslandBundle } from './island-bundle';
+import { islandHarnessRoutes } from './island-harness-route';
+import { islandRoutes } from './island-routes';
+import { loadIslandStates } from './island-states-load';
+import { pageSync } from './page-sync';
+import { loadPwaArtifacts } from './pwa-artifacts';
+import { assetRoutes } from './runtime-assets';
+import { appRoutes } from './runtime-render';
+import { storageRoutes } from './runtime-storage';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
+import { serviceWorkerArtifacts } from './sw-artifacts';
+import { serviceWorkerRoutes } from './sw-routes';
+import type { ThemeBoot } from './theme-boot';
+import { loadThemeMode, themeBoot } from './theme-boot';
+
+export interface DevRouteTableInput {
+  readonly root: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly buildId: string;
+  readonly storage: Storage;
+  readonly dashboard: DevDashboardInput;
+  /** A getter: the watcher tick rebuilds the islands, and a captured bundle would serve the first. */
+  readonly islands: () => IslandBundle;
+}
+
+export interface DevRouteTable {
+  readonly routes: readonly Route[];
+  /** The theme boot, whose `cspSource` the web role admits. */
+  readonly theme: ThemeBoot;
+  /** The app's own error pages' inline styles, admitted the same way. */
+  readonly errorStyles: readonly string[];
+  /** Where the app's MCP endpoint was mounted, or `undefined`. */
+  readonly mcpPath: string | null;
+}
+
+export async function devRouteTable(input: DevRouteTableInput): Promise<DevRouteTable> {
+  // Resolved once, before the first route. `undefined` for an app that is not installable: nothing
+  // is mounted, and the 0kb baseline is not spent on a `<link>` to a file that does not exist.
+  const pwa = await loadPwaArtifacts(input.root);
+  const theme = themeBoot(await loadThemeMode(input.root));
+  // The same call `serve.ts` makes, so the two boots cannot serve different sync targets.
+  const sync = await pageSync(input.root, input.env, input.buildId);
+  const errorStyles = await errorPageStyleSources(input.root);
+  // Built once at boot and NOT rebuilt with the islands on a watcher tick: a service worker that
+  // changes under a page it controls is the update path, and one per keystroke exercises it per save.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId: input.buildId,
+          routes: describeRoutes(),
+          islands: input.islands(),
+          styles: styleBundle(),
+          scripts: sync.scripts,
+        });
+
+  // The app's own MCP endpoint, discovered from `apps/<app>/mcp.ts` and mounted through the SAME
+  // call `runRole` makes — `POST /mcp` answered 404 in every process the framework booted until
+  // one of them asked. Warned once here when `expose` is true and nothing can be mounted.
+  const mcpMount = await mountAppMcp(input.root);
+  const routes: readonly Route[] = [
+    ...devDashboardRoutes(input.dashboard),
+    // The same API table the container serves: a read that answers here and 404s in production
+    // is exactly the drift one composition exists to prevent.
+    ...apiRoutes(),
+    ...mcpMount.routes,
+    // The image pipeline's only HTTP surface: the icons the web manifest declares, and the
+    // variants every `srcset` promises. Mounted before the app's own routes so a page route can
+    // never shadow `/icons` or `/media`.
+    ...assetRoutes({
+      root: input.root,
+      storage: input.storage,
+      ...(pwa === undefined ? {} : { pwa }),
+    }),
+    ...storageRoutes({ storage: input.storage }),
+    // The chunks the documents below name. Mounted before the app's routes for the reason
+    // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
+    ...islandRoutes(() => input.islands()),
+    // And the stylesheet every one of those documents links. Read through the getter for the
+    // reason the islands are: a rebuilt island registers CSS, which mints a new URL, and a table
+    // captured at boot would answer 404 for the href the document now carries.
+    ...styleRoutes(() => styleBundle()),
+    // `x shot --island`'s harness, in the `/_x` dev namespace so no app route can shadow it. It
+    // lives here rather than in a second server because everything it needs is in THIS process:
+    // the built chunks, the app's stylesheet registry, and the one embedded Postgres a checkout
+    // may have. The states are read per REQUEST — an author editing a state and re-running the
+    // command must not need a restart to see it.
+    ...islandHarnessRoutes({
+      islands: () => input.islands(),
+      states: () => loadIslandStates(input.root),
+    }),
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
+    ...sync.routes,
+    ...appRoutes({
+      buildId: input.buildId,
+      resolveIsland: (file) => input.islands().resolverFor(file),
+      sync: sync.head,
+      persisted: sync.persisted,
+      themeHead: theme.head,
+      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
+    }),
+  ];
+
+  return { routes, theme, errorStyles, mcpPath: mcpMount.path };
+}

package/src/dispatch.ts

@@ -16,6 +16,7 @@ import { exitCodeFor, findingFrom, render } from './output';
 import type { ParsedArgs } from './parse';
 import { parseArgs, wantsJson } from './parse';
 import { commandFor, SPECS } from './registry';
+import { rootEnvAdditions } from './root-env';
 
 export interface DispatchOptions {
   readonly argv: readonly string[];
@@ -120,14 +121,20 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     ? { ...args, command: 'help', positionals: [args.command] }
     : args;
 
+  const cwd = resolveCwd(
+    options.cwd,
+    typeof args.flags.get('cwd') === 'string' ? String(args.flags.get('cwd')) : undefined,
+  );
+  // The ROOT's `.env*`, not the cwd's: Bun loaded the cwd's at startup, and a command run from
+  // `apps/web` finds its root by walking up. Written into the process env too when that IS the env
+  // passed in, because a package reading `Bun.env` directly must see what the command sees.
+  const added = await rootEnvAdditions(cwd, options.env);
+  if (options.env === Bun.env) Object.assign(Bun.env, added);
   const ctx: CommandContext = {
     args: helpArgs,
-    cwd: resolveCwd(
-      options.cwd,
-      typeof args.flags.get('cwd') === 'string' ? String(args.flags.get('cwd')) : undefined,
-    ),
+    cwd,
     runner: options.runner ?? exec,
-    env: options.env,
+    env: options.env === Bun.env ? options.env : { ...added, ...options.env },
     bunVersion: options.bunVersion,
     ...(options.invocation === undefined ? {} : { invocation: options.invocation }),
   };

package/src/document-styles.ts

@@ -25,7 +25,7 @@ export const definesRootCustomProperties = (css: string): boolean => ROOT_CUSTOM
 
 export interface SurfaceDocument {
   readonly surface: Surface;
-  /** Exactly the CSS `dev-render.ts` would inline into a document on this surface. */
+  /** Exactly the CSS `runtime-render.ts` would inline into a document on this surface. */
   readonly css: string;
 }
 

package/src/drift.ts

@@ -11,7 +11,10 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { ERROR_DOCS_URL } from '@ultimat3/core';
+// `canonicalJson` is core's, the one serializer every content hash in the framework uses. A private
+// copy here wrote `"key":null` for an unset optional field where core drops the key, so the schema
+// hash agreed with nothing else (plan 101 slice 18 h; 22.0.0 re-stamps every sidecar once).
+import { canonicalJson, ERROR_DOCS_URL } from '@ultimat3/core';
 import { describeEntities } from '@ultimat3/entity';
 import { countDeclaredEntities } from './app-entities';
 import { loadApp } from './app-load';
@@ -23,23 +26,6 @@ import type { Finding } from './output';
 export const DB_PACKAGE = join('packages', 'db');
 const SCHEMA_GLOB = 'packages/db/src/**/*.ts';
 
-/**
- * Canonical JSON: object keys sorted, arrays in their own order. The registry's description is a
- * BUILD INPUT committed to disk as a hash, so a field reordered inside `describe()` upstream would
- * otherwise move every app's hash and report drift over a framework upgrade nobody made.
- */
-function canonicalJson(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
-  if (typeof value === 'object' && value !== null) {
-    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
-      a < b ? -1 : a > b ? 1 : 0,
-    );
-    return `{${entries.map(([key, held]) => `${JSON.stringify(key)}:${canonicalJson(held)}`).join(',')}}`;
-  }
-  // `undefined` has no JSON form and an optional field left unset must hash as absent, not throw.
-  return JSON.stringify(value) ?? 'null';
-}
-
 /**
  * What the app's entities declare, as the registry describes them — the half `SCHEMA_GLOB` cannot
  * see. `x new` puts an entity at `apps/web/app/<feature>/entity.ts` and `packages/db/src/schema.ts`

package/src/error-catalog.ts

@@ -46,22 +46,29 @@ export const CATALOG_PACKAGES = [
 ] 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.
+ * The packages the catalog may import WITHOUT `@ultimat3/cli` declaring them. `admin` and `ui`
+ * 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. `scraping` is an app's own
+ * choice since 22.0.0: `x shot` drives Chrome over raw CDP and imports nothing from it, so its codes
+ * answer where the app installed it and are reported `unavailable` where it did not. 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 const CATALOG_OPTIONAL_HOSTS: readonly string[] = [
+  '@ultimat3/admin',
+  '@ultimat3/scraping',
+  '@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: `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
+   * tolerated case is the optional host (`CATALOG_OPTIONAL_HOSTS`), which a bare CLI process may
+   * not have, 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

@@ -30,6 +30,9 @@ export const CLI_OWNED_ERROR_CODES = [
   // `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',
+  // The fourth: registered, presented as live, and constructed by nothing — the state a code is left
+  // in when its last thrower moves on. The reference row has to say so in words.
+  'X_ERROR_CODE_UNTHROWN',
   // 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
@@ -175,29 +178,26 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_SHOT_ISLAND_UNPHOTOGRAPHABLE',
   'X_SHOT_ISLAND_UNSTUBBED_REQUEST',
   'X_SHOT_ISLAND_MISSING',
-  // The browser-backed e2e driver — `e2e-driver.ts` and the three modules under it. Owned by the
-  // CLI because the ADAPTER is: `@ultimat3/testing` declares `PageLike` and may not import a
-  // browser, `@ultimat3/scraping` owns the browser and may not import the harness, and neither
-  // package can name a failure that only exists where the two meet.
-  'X_E2E_EVALUATE_UNSUPPORTED',
-  'X_E2E_EVALUATE_CAPTURED',
-  'X_E2E_EVALUATE_THREW',
-  'X_E2E_LOCATOR_EMPTY',
-  'X_E2E_LOCATOR_AMBIGUOUS',
-  'X_E2E_SERVICE_WORKER_ABSENT',
-  // The raw-CDP browser under that driver — `cdp-launch.ts`, `cdp-connection.ts`,
-  // `cdp-e2e-page.ts`, `cdp-browser.ts`. Four codes and not one, because the four repairs differ:
-  // install a browser, read the browser's own stderr, look at the page, raise a deadline.
-  'X_CDP_BROWSER_MISSING',
-  'X_CDP_LAUNCH_FAILED',
-  'X_CDP_CALL_FAILED',
-  'X_CDP_TIMEOUT',
+  // The raw-CDP shot page's own refusals (`cdp-shot-errors.ts` holds the classes): which host it
+  // may open, which element it was pointed at, and which key it was asked to press.
+  'X_SHOT_HOST_REFUSED',
+  'X_SHOT_ELEMENT_MISSING',
+  'X_SHOT_ELEMENT_UNREADY',
+  'X_SHOT_KEY_INVALID',
   'X_GH_UNAVAILABLE',
   'X_GH_NOT_AUTHENTICATED',
   'X_GH_COMMAND_FAILED',
   'X_GH_RESPONSE_INVALID',
   'X_PR_NOT_FOUND',
   'X_CI_RUN_NOT_FOUND',
+  'X_APP_NAME_EMPTY',
+  'X_APP_EMPTY',
+  'X_BOUNDARY_SURFACE_IMPORT',
+  'X_PERMISSION_UNGRANTED',
+  'X_JOB_UNREGISTERED',
+  'X_FEATURE_UNKNOWN',
+  'X_ROUTE_ASYNC_PAGE',
+  'X_BUDGET_PARAMS_UNDECLARED',
 ] as const;
 
 /**
@@ -262,6 +262,8 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   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_ERROR_CODE_UNTHROWN:
+    'a registered error code is constructed by nothing and its reference row does not say so',
   X_FRAMEWORK_SCHEMA_FAILED: 'a framework table could not be created at boot',
   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',
@@ -310,7 +312,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
   X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
   X_PACKAGE_DUPLICATED: 'two copies of one registry-holding framework package are installed',
-  X_SHOT_BROWSER_MISSING: 'x shot found no browser library in the app',
+  X_SHOT_BROWSER_MISSING: '`x shot` has no browser to launch',
   X_UI_SHOT_ROUTE_UNKNOWN: 'a ui.* tool was asked for a path no route answers',
   X_UI_SHOT_ROUTE_UNBUDGETED: 'a ui.* tool refused a route that declares no budget.js',
   X_UI_INTERACT_STEPS_INVALID: 'a ui.interact step list is over its bounds or malformed',
@@ -324,22 +326,25 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',
   X_SHOT_ISLAND_UNSTUBBED_REQUEST: 'the island requested something no state stub answers',
   X_SHOT_ISLAND_MISSING: 'a declared island picture is not on disk',
-  X_E2E_EVALUATE_UNSUPPORTED: 'a page.evaluate() closure cannot be sent into the browser',
-  X_E2E_EVALUATE_CAPTURED: 'a page.evaluate() closure named a binding the page does not have',
-  X_E2E_EVALUATE_THREW: 'an expression an e2e page ran threw inside the browser',
-  X_E2E_LOCATOR_EMPTY: 'an e2e locator matched no element',
-  X_E2E_LOCATOR_AMBIGUOUS: 'an e2e locator matched more than one element and was asked to click',
-  X_E2E_SERVICE_WORKER_ABSENT: 'no service worker took control of the page within the budget',
-  X_CDP_BROWSER_MISSING: 'no Chrome or Chromium is installed for the e2e driver to launch',
-  X_CDP_LAUNCH_FAILED: 'the browser started and never announced a DevTools endpoint',
-  X_CDP_CALL_FAILED: 'the browser refused a DevTools call',
-  X_CDP_TIMEOUT: 'a DevTools call did not answer inside its deadline',
+  X_SHOT_HOST_REFUSED: "x shot was asked to open a host outside the run's allow list",
+  X_SHOT_ELEMENT_MISSING: 'no element matched the selector before the deadline',
+  X_SHOT_ELEMENT_UNREADY: 'the element matched and never became ready to act on',
+  X_SHOT_KEY_INVALID: 'a key chord the browser cannot press',
   X_GH_UNAVAILABLE: 'the GitHub CLI is not runnable from here',
   X_GH_NOT_AUTHENTICATED: 'gh holds no credentials for this host',
   X_GH_COMMAND_FAILED: 'a gh invocation exited non-zero',
   X_GH_RESPONSE_INVALID: "gh's output is not the shape the command reads",
   X_PR_NOT_FOUND: 'no pull request for this checkout',
   X_CI_RUN_NOT_FOUND: 'no workflow run for this branch',
+  X_APP_NAME_EMPTY: 'the app name has no letters or digits',
+  X_APP_EMPTY: 'an app with an app.config.ts registered no primitive',
+  X_BOUNDARY_SURFACE_IMPORT: 'a surface imports one SURFACE_SPECS does not allow',
+  X_PERMISSION_UNGRANTED: 'an action, query or route requires a permission no role grants',
+  X_JOB_UNREGISTERED: 'a job reached the manifest under its positional anonymous name',
+  X_FEATURE_UNKNOWN: 'x g --feature names a slice that does not exist',
+  X_ROUTE_ASYNC_PAGE: 'a route exports an async Page',
+  X_BUDGET_PARAMS_UNDECLARED:
+    'a dynamic route with a budget declares no prerender() paths to weigh it by',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/error-pages.ts

@@ -34,9 +34,8 @@ const isStatus = (status: number): boolean =>
 /**
  * The app's page for one status, or `undefined`.
  *
- * Read per REQUEST, never cached at boot, for `favicon.ts`'s reason: `x dev` is a running process
- * an author drops a file into, and a reader that captured "there was none" at startup would keep
- * answering the framework's page until the server was restarted.
+ * One read. How often it is asked is `errorPageHook`'s decision: per request under `x dev`, for
+ * `favicon.ts`'s reason, and once per status in a container.
  */
 export async function errorPageOverride(root: string, status: number): Promise<string | undefined> {
   if (!isStatus(status)) return undefined;
@@ -48,11 +47,24 @@ export async function errorPageOverride(root: string, status: number): Promise<s
  * `ServerHooks.errorPage`, bound to one app root. Installed by `startWeb` so `x dev` and the
  * container cannot answer a browser differently — the rule `assetRoutes` already holds for
  * `/favicon.ico`.
+ *
+ * `perRequest` is `x dev`'s: an author drops a file into a running process. A container's image
+ * cannot change under it, so there each status is read ONCE and kept — per request, a burst of 500s
+ * during an outage paid a file read each, on the path that was already failing (plan 101, 12 g).
  */
-export const errorPageHook =
-  (root: string) =>
-  (status: number): Promise<string | undefined> =>
-    errorPageOverride(root, status);
+export const errorPageHook = (root: string, options: { readonly perRequest: boolean }) => {
+  if (options.perRequest) {
+    return (status: number): Promise<string | undefined> => errorPageOverride(root, status);
+  }
+  const read = new Map<number, Promise<string | undefined>>();
+  return (status: number): Promise<string | undefined> => {
+    const known = read.get(status);
+    if (known !== undefined) return known;
+    const once = errorPageOverride(root, status);
+    read.set(status, once);
+    return once;
+  };
+};
 
 /**
  * The document that goes into a static export: the app's file if it has one, the framework's page