@ultimat3/cli 24.0.0 → 25.0.0

package/src/runtime-services.ts

@@ -16,14 +16,13 @@ import {
   systemClock,
 } from '@ultimat3/core';
 import type { RateLimitStore } from '@ultimat3/http';
-import { postgresRateLimitStore } from '@ultimat3/http';
+import { adoptRateLimitStore, postgresRateLimitStore } from '@ultimat3/http';
 import type { EventBus, JobDriver, OutboxStore } from '@ultimat3/jobs';
 import type { MailDriver } from '@ultimat3/mail';
 import {
   isMemoryDriver,
   isUnconfiguredDriver,
   resetMailDriver,
-  selectMailDriver,
   setMailDriver,
 } from '@ultimat3/mail';
 import type { Transport, TransportSelection } from '@ultimat3/realtime/server';
@@ -36,6 +35,7 @@ import { msg } from './messages';
 import type { DevServices, Env } from './runtime-bindings';
 import { cacheTiersOf, startCacheTiers } from './runtime-cache';
 import { type WorkerConfig, workerConfigOf } from './runtime-jobs';
+import { selectAppMailDriver } from './runtime-mail';
 import { inboxRetentionOf } from './runtime-notify-retention';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { installRetentionSweep } from './runtime-purge';
@@ -57,7 +57,8 @@ export interface RunningServices {
    */
   readonly realtime: RealtimeConfig;
   /**
-   * `app.config.ts`'s `jobs.queues` / `concurrency` / `visibilityTimeoutMs`, for the `worker` role.
+   * `app.config.ts`'s `jobs.queues` / `concurrency` / `visibilityTimeoutMs`, for the `worker` role —
+   * the queues replaced by the boot env's `WORKER_QUEUES` when it is set (`runtime-jobs.ts`).
    * Optional because a `RunningServices` can be hand-built, and a test runtime with none keeps the
    * worker's own defaults — the answer it always got. `startServices` always sets it.
    */
@@ -87,7 +88,7 @@ export interface RunningServices {
    * `roles.web.replicas: 3` and `x new` scaffolds two.
    *
    * OPTIONAL because a `RunningServices` can be hand-built: a test's fixture runtime has a stub
-   * client and no shared store, which is `createServer`'s memory store and `scope: 'process'` —
+   * client and no shared store, which is `httpServer`'s memory store and `scope: 'process'` —
    * the honest answer for it, and the one `startWeb` derives.
    */
   readonly rateLimitStore?: RateLimitStore;
@@ -301,6 +302,20 @@ async function release(steps: readonly (() => void | Promise<void>)[]): Promise<
   return failures;
 }
 
+/**
+ * Every STOP path's form of `release`: every step runs, newest first, and the FIRST failure is
+ * rethrown — it is the cause, the rest its consequences. The one helper for this process's stops
+ * (`startServices`, `startRoles`, `bootServing`, `x dev`): a chain of `await`s with no `try`
+ * skipped every step after one rejection, and the replicator rejects a refused close on purpose.
+ * Steps are listed in BOOT order, as an unwind list is.
+ */
+export async function releaseOrThrow(
+  steps: readonly (() => void | Promise<void>)[],
+): Promise<void> {
+  const failures = await release(steps);
+  if (failures.length > 0) throw failures[0];
+}
+
 export async function startServices(
   services: DevServices,
   env: Env,
@@ -308,10 +323,14 @@ export async function startServices(
   /** `'verify'` for a serving role on an external database — `runtime-queue.ts`'s `SchemaMode`. */
   schema: SchemaMode = 'apply',
 ): Promise<RunningServices> {
+  // The app's config is loaded ONCE, here, first, and every section below is read out of that one
+  // validated object — mail's `retainMime` is the first reader, so it is loaded before mail.
+  const config = await loadAppConfig(services.root);
   // Before the queue: selection is pure — it parses `SMTP_URL` and builds a transport, it does
   // not dial. A typo'd credential must fail on the spot rather than after PGlite has started and
   // been unwound again, and it must fail at boot rather than on the first mail nobody receives.
-  const selection = selectMailDriver(env);
+  // `mail.retainMime` rides along (`runtime-mail.ts`), refused here the same way.
+  const selection = selectAppMailDriver(env, config);
   // Same reason, same place: building a purge driver reads env and dials nothing, so a half-set
   // `FASTLY_API_TOKEN` without its service id fails here rather than on the first stale page.
   const cdn = selectPurgeDriver(env);
@@ -320,11 +339,9 @@ export async function startServices(
   // service starts, rather than quietly keeping the in-process bus. Which transport, which KV
   // bucket and which presence TTL is `@ultimat3/realtime`'s decision, and it is the same call a
   // `ROLE=sync` container makes, so this process cannot resolve the bus differently from the
-  // container it stands in for. The app's config is loaded ONCE, here, and every section below is
-  // read out of that one validated object.
-  const config = await loadAppConfig(services.root);
+  // container it stands in for.
   const realtime = realtimeConfigOf(config);
-  const workerConfig = workerConfigOf(config);
+  const workerConfig = workerConfigOf(config, env);
   const bus: TransportSelection = selectTransport(env, realtime);
   // `env`, not the ambient one: this function is HANDED the boot's environment and every other
   // reader here already uses it, so a queue that asked `process.env` would decide the standby from
@@ -358,6 +375,10 @@ export async function startServices(
       postgresAuthLimiter({ executor, clock: systemClock, policy }),
     );
     started.push(() => resetAuthLimiters());
+    // Where an action's or a query's declared `rateLimit:` is counted — on every surface, so a
+    // task or a one-off command spends from the fleet's table too, not one process' memory. Before
+    // `loadApp` for the auth limiters' reason; `startRoles` stacks a deployment's override over it.
+    started.push(adoptRateLimitStore(rateLimitStore));
     // The hourly sweep over the framework tables this boot is responsible for. Every one of them
     // ships a `purgeExpired()` that nothing called, so every row written was a row kept —
     // `x_rate_limit` takes one upsert per request the web role serves, assets included.
@@ -407,8 +428,8 @@ export async function startServices(
     started.push(() => resetMailDriver());
     const purge = overrides?.purge ?? cdn.driver;
     // Every tier this process reads through, plus the cross-instance invalidation hop, in one
-    // call. The CDN tier used to be the only one registered here — so `createRedisTier`,
-    // `createLruTier` and `createMemoTier` shipped with no caller at all and every replica
+    // call. The CDN tier used to be the only one registered here — so `redisTier`,
+    // `lruTier` and `memoTier` shipped with no caller at all and every replica
     // recomputed every cached read. Released with `resetTiers()`, which drops the whole registry:
     // this boot is the only thing that registers one, and a tier left behind would purge for a
     // process that has stopped.
@@ -446,8 +467,7 @@ export async function startServices(
       // the FIRST failure is rethrown because it is the cause and the rest are its consequences,
       // and every step still runs, so a refused shutdown never leaks into the next boot.
       async stop() {
-        const failures = await release(started);
-        if (failures.length > 0) throw failures[0];
+        await releaseOrThrow(started);
       },
     };
   } catch (error) {

package/src/runtime-storage-upload.ts

@@ -5,7 +5,7 @@
 
 import { finiteCount, readWithinLimit } from '@ultimat3/core';
 import type { RequestContext, Route, UltimateRequest } from '@ultimat3/http';
-import { json, NO_STORE } from '@ultimat3/http';
+import { jsonResponse, NO_STORE } from '@ultimat3/http';
 import type { Storage } from '@ultimat3/storage';
 import {
   acceptSignedUpload,
@@ -74,7 +74,7 @@ async function acceptUpload(
         : { allowedContentTypes: [constraints.contentType] }),
     }),
   });
-  return json({ key: stored.key }, { status: 201 });
+  return jsonResponse({ key: stored.key }, { status: 201 });
 }
 
 /**

package/src/runtime-storage.ts

@@ -7,12 +7,12 @@
 // `localDriver` SIGNS `/_storage/<disk>/<key>`, so a local `'/_storage'` here is a second statement
 // of one constant — and a signer and a reader that disagree serve 404 for every signed URL.
 
-import { actorOf } from '@ultimat3/action';
 import type { Actor } from '@ultimat3/core';
+import { actorOf } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { asCtx, unauthenticated } from '@ultimat3/http';
 import type { KnownPermission } from '@ultimat3/policy';
-import { can, codeOf, evaluate, forbidden, reasonOf } from '@ultimat3/policy';
+import { can, codeOf, evaluate, policyForbidden, reasonOf } from '@ultimat3/policy';
 import type { Storage, StorageRead } from '@ultimat3/storage';
 import {
   assertSafeKey,
@@ -88,7 +88,7 @@ export function authorizeStorageRead(input: StorageReadInput, ctx: RequestContex
   const reason = reasonOf(evaluation.decision) ?? 'denied';
   throw codeOf(evaluation.decision) === 'X_UNAUTHENTICATED'
     ? unauthenticated(ctx.url.pathname)
-    : forbidden(policy.label, reason);
+    : policyForbidden(policy.label, reason);
 }
 
 /**

package/src/schema-diff.ts

@@ -43,7 +43,7 @@ const RECORDED_ONLY = 'was recorded by the newest migration and no entity declar
 /** The difference's name — what `x db gen "record …"` is told to write down. */
 const REPLICA_IDENTITY_FULL = 'replica identity full';
 const REPLICA_IDENTITY_UNRECORDED =
-  'needs REPLICA IDENTITY FULL — a channel with params or a live query subscribes to it — and no ' +
+  'needs REPLICA IDENTITY FULL — a channel with params routes deletes by its old row — and no ' +
   'migration recorded it';
 
 const columns = (names: readonly string[]): string => names.join(', ');

package/src/secrets-rotation.ts

@@ -1,18 +1,19 @@
 // A master-key rotation in an order a crash cannot turn into data loss. The new key is STAGED at
-// `<key>.next` (0600) before anything is sealed with it, the committed file is sealed second, and
+// `<key>.next` (owner-only: 0600, and an ACL on Windows) before anything is sealed with it, the committed file is sealed second, and
 // the rename that makes the new key live is last. Interrupted anywhere, some key on disk opens the
 // committed file — and `recoverRotation`, which every `x secrets` command runs first, finishes or
 // abandons the move by asking the file which key it answers to.
 
-import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'; // why: the staged key is written and renamed synchronously at 0600, and Bun has no mode-setting write or rename.
+import { existsSync, readFileSync, rmSync } from 'node:fs'; // why: Bun has no sync exists/remove; the key is WRITTEN and RENAMED only by core's owner-only writers.
 import type { MasterKeyRef, SecretValues } from '@ultimat3/core';
 import {
   generateMasterKey,
   isUltimateError,
   masterKeyPath,
+  promoteStagedMasterKey,
   readSecretsFile,
-  SECRETS_KEY_MODE,
   stagedMasterKeyPath,
+  stageMasterKeyFile,
   writeSecretsFile,
 } from '@ultimat3/core';
 
@@ -24,14 +25,12 @@ const fileKey = (root: string, hex: string): MasterKeyRef => ({
 
 /** Stage, seal, then make live. Returns the key now in force. */
 export async function rotateMasterKey(root: string, values: SecretValues): Promise<MasterKeyRef> {
-  const staged = stagedMasterKeyPath(root);
   const hex = generateMasterKey();
-  rmSync(staged, { force: true });
-  // `wx`: the mode applies only when a write CREATES the file, and a leftover could be 0644.
-  writeFileSync(staged, `${hex}\n`, { encoding: 'utf-8', mode: SECRETS_KEY_MODE, flag: 'wx' });
+  // A fresh temp file renamed over any leftover: a staged key left 0644 is replaced, never reused.
+  stageMasterKeyFile(root, hex);
   const next = fileKey(root, hex);
   await writeSecretsFile(root, values, next);
-  renameSync(staged, masterKeyPath(root));
+  promoteStagedMasterKey(root);
   return next;
 }
 
@@ -53,7 +52,7 @@ export async function recoverRotation(root: string, key: MasterKeyRef): Promise<
     // Throws the staged key's own mismatch when neither opens it — the committed file's problem,
     // which `X_SECRETS_KEY_MISMATCH`'s fix (restore it from git) answers.
     await readSecretsFile(root, candidate);
-    renameSync(staged, masterKeyPath(root));
+    promoteStagedMasterKey(root);
     return candidate;
   }
 }

package/src/seo-routes.ts

@@ -4,7 +4,7 @@
 
 import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, json, NO_STORE } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
 import { SITEMAP_PARTS_DIR } from '@ultimat3/seo';
 import { quoteArg } from './shell-quote';
 import { NO_SITE_SETTINGS, publicOrigin, type SiteSettings } from './site-config';
@@ -125,7 +125,7 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
           );
         }
         const index = new URL(SITEMAP_PATH, originOf(options, request)).href;
-        const missing = json(
+        const missing = jsonResponse(
           {
             ok: false,
             error: {

package/src/serve-boot.ts

@@ -16,7 +16,7 @@ import { warnIfIdempotencyProcessScoped } from './runtime-idempotency-scope';
 import { warnUnsealedMfaSecrets } from './runtime-mfa-warning';
 import { replicaOverrides } from './runtime-replica';
 import type { RunningServices } from './runtime-services';
-import { startServices } from './runtime-services';
+import { releaseOrThrow, startServices } from './runtime-services';
 import { loadDrainConfig, loadHealthConfig } from './serve-drain';
 import { configureReporting, containerBinding, metricsPortFor, portFromEnv } from './serve-env';
 import { adoptPrebuiltStyles, reportBootBuilds, watchBootBuilds } from './serve-prebuilt';
@@ -49,16 +49,22 @@ const LISTENING_ROLES: readonly Role[] = ['web', 'sync'];
 
 /**
  * `app.config.ts`'s `drain`, applied to the WHOLE process rather than only to the web server that
- * `createServer` hands it to. A role nothing routes to gets no readiness grace at all: the grace
+ * `httpServer` hands it to. A role nothing routes to gets no readiness grace at all: the grace
  * holds `/readyz` at 503 with the listener open so the endpoints catch up, and a worker has neither
  * — it only went on claiming jobs for those seconds, then aborted them at the drain (s1-con #7).
+ *
+ * The budget (`deadlineMs`) is every role's: it is the time a worker's running job has to finish
+ * on a deploy, so it is the one key here a non-listening role needs MOST.
  */
 export function lifecycleForRole(
   role: Role,
   drain: Partial<DrainConfig> | undefined,
 ): LifecycleOptions {
-  if (!LISTENING_ROLES.includes(role)) return { readinessGraceMs: 0 };
-  return drain?.readinessGraceMs === undefined ? {} : { readinessGraceMs: drain.readinessGraceMs };
+  const budget = drain?.deadlineMs === undefined ? {} : { deadlineMs: drain.deadlineMs };
+  if (!LISTENING_ROLES.includes(role)) return { readinessGraceMs: 0, ...budget };
+  return drain?.readinessGraceMs === undefined
+    ? budget
+    : { readinessGraceMs: drain.readinessGraceMs, ...budget };
 }
 
 /**
@@ -181,13 +187,18 @@ async function bootRoles(boot: {
     running,
     runtime,
     async stop() {
-      await running.stop();
-      // After the server drained: a bust landing mid-drain still marks the pages it is serving.
-      web?.release();
-      await runtime.stop();
-      // Last: the exporters outlive the roles they were recording, so the drain's own spans and
-      // the final counter snapshot still have somewhere to go.
-      stopOtlp();
+      // Every step runs and the first failure is rethrown (`releaseOrThrow`): a refused role stop
+      // used to leave the services, the PGlite lock and the exporter behind it. Listed in boot
+      // order, released newest first — the roles; then the web surface, after the server drained
+      // (a bust landing mid-drain still marks the pages it is serving); then the services; LAST
+      // the exporter, so the drain's own spans and the final counter snapshot still have
+      // somewhere to go.
+      await releaseOrThrow([
+        stopOtlp,
+        () => runtime.stop(),
+        () => web?.release(),
+        () => running.stop(),
+      ]);
     },
   };
 }

package/src/serve-drain.ts

@@ -7,7 +7,9 @@ import { loadAppConfig } from './app-config-load';
 /** The declared section, or `undefined` for a root with no config file — core keeps its default. */
 export async function loadDrainConfig(root: string): Promise<Partial<DrainConfig> | undefined> {
   const drain = (await loadAppConfig(root))?.drain;
-  return drain === undefined ? undefined : { readinessGraceMs: drain.readinessGraceMs };
+  return drain === undefined
+    ? undefined
+    : { readinessGraceMs: drain.readinessGraceMs, deadlineMs: drain.deadlineMs };
 }
 
 /** `health.readiness`, or `undefined` for a root with no config file (core keeps its default). */

package/src/serve-retire.ts

@@ -0,0 +1,95 @@
+// `ROLE=worker`'s retire, on SIGUSR2 (issue #669): stop claiming, finish every held job however
+// long it takes, abort nothing — then the ordinary drain, so the process exits 0. It is what a
+// Kubernetes `preStop` sends before the SIGTERM a rollout ends in, for a job whose side effect may
+// happen at most once and may outlast `drain.deadlineMs`. Framework-owned: no port, no app code.
+
+import { drain, logger, renderThrowable } from '@ultimat3/core';
+import type { Worker } from '@ultimat3/jobs';
+
+/** The signal a worker retires on. Free in Bun and Node (SIGUSR1 is the inspector's). */
+export const RETIRE_SIGNAL = 'SIGUSR2';
+
+/** The two calls a retire makes on the worker. */
+export type RetiringWorker = Pick<Worker, 'stats' | 'stop'>;
+
+/** Where the signal is heard — `process` by default, a hand-raised source in a test. */
+export interface RetireSignals {
+  on(signal: typeof RETIRE_SIGNAL, listener: () => void): void;
+  off(signal: typeof RETIRE_SIGNAL, listener: () => void): void;
+}
+
+export interface WorkerRetireOptions {
+  /** Default `process.platform`. `win32` installs nothing: Windows has no SIGUSR2. */
+  readonly platform?: string;
+  readonly signals?: RetireSignals;
+  /** What the retire ends in. Default core's `drain` — the hold then releases and exits 0. */
+  readonly drain?: (signal: string) => Promise<void>;
+}
+
+export interface WorkerRetire {
+  /** The worker the boot started (`null` when it started none) — a signal before this waits. */
+  adopt(worker: RetiringWorker | null): void;
+  /** Give the listener back: a boot that failed, or a hold that is over. */
+  disarm(): void;
+}
+
+const NOTHING: WorkerRetire = Object.freeze({ adopt: () => undefined, disarm: () => undefined });
+
+/**
+ * Listen for `RETIRE_SIGNAL` NOW, before the boot: Bun's default for an unhandled SIGUSR2 ends the
+ * process, so a `preStop` that lands while the pod still boots must meet this listener, which waits
+ * for the worker and then retires it. One retire per process; a second signal joins it.
+ *
+ * Exits rather than holds, decided 2026-10-07: the `preStop` has no channel back but PID 1 itself,
+ * so "retired" has to be observable as "PID 1 is gone" — and a pod that has stopped claiming serves
+ * nothing it could keep holding for. A SIGTERM landing mid-retire is the ordinary drain: it binds
+ * the retire to `drain.deadlineMs` and cuts off at the margin (`packages/jobs/src/worker.ts`).
+ */
+export function armWorkerRetire(options: WorkerRetireOptions = {}): WorkerRetire {
+  if ((options.platform ?? process.platform) === 'win32') return NOTHING;
+  const signals: RetireSignals = options.signals ?? process;
+  const finish = options.drain ?? drain;
+  let adopt: (worker: RetiringWorker | null) => void = () => undefined;
+  const adopted = new Promise<RetiringWorker | null>((resolve) => {
+    adopt = resolve;
+  });
+  let retiring = false;
+
+  const retire = async (): Promise<void> => {
+    const worker = await adopted;
+    try {
+      if (worker !== null) {
+        const before = await worker.stats();
+        logger.info('jobs.worker.retiring', {
+          signal: RETIRE_SIGNAL,
+          workerId: before.workerId,
+          inFlight: before.inFlight,
+        });
+        await worker.stop(RETIRE_SIGNAL);
+        const after = await worker.stats();
+        logger.info('jobs.worker.retired', {
+          signal: RETIRE_SIGNAL,
+          workerId: after.workerId,
+          state: after.state,
+          inFlight: after.inFlight,
+        });
+      }
+    } catch (error) {
+      logger.warn('jobs.worker.retire-failed', { error: renderThrowable(error) });
+    } finally {
+      await finish(RETIRE_SIGNAL);
+    }
+  };
+
+  const listener = (): void => {
+    if (retiring) return;
+    retiring = true;
+    // Never rejects: `retire` catches its own failure and always reaches the drain.
+    void retire();
+  };
+  signals.on(RETIRE_SIGNAL, listener);
+  return {
+    adopt: (worker) => adopt(worker),
+    disarm: () => signals.off(RETIRE_SIGNAL, listener),
+  };
+}

package/src/serve-web.ts

@@ -4,16 +4,18 @@
 // spared: render's server half, the PWA, SEO, MCP and island subsystems.
 
 import type { Route } from '@ultimat3/http';
-import { describeRoutes } from '@ultimat3/render';
+import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
+
+import { describePages } from '@ultimat3/render';
 import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { mountAppMcp } from './app-mcp';
-import { errorPageStyleSources } from './error-page-csp';
+import { errorPageStyleBodies } from './error-page-csp';
 import { islandRoutes } from './island-routes';
 import type { LoadedIslands } from './island-store';
 import { loadOrBuildIslands } from './island-store';
 import { loadNavigation, pageNavigation } from './page-navigation';
-import { loadSpeculation, pageSpeculation } from './page-speculation';
+import { loadSpeculation, otherLocaleSegments, pageSpeculation } from './page-speculation';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { adminMountRoutes } from './runtime-admin';
@@ -30,13 +32,14 @@ import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
 import { loadThemeMode, themeBoot } from './theme-boot';
+import { loadThemeBrand } from './theme-brand';
 
 /** Everything `startRoles` is handed that only a process serving documents has. */
 export interface WebSurface {
   readonly routes: readonly Route[];
   /** The theme boot and the speculation rules: the two inline bodies every document may carry. */
   readonly inlineScripts: readonly string[];
-  /** The app's own error pages' `<style>` bodies, which the enforced policy must admit. */
+  /** The app's error pages' and its brand's `<style>` bodies, which the enforced policy admits. */
   readonly inlineStyles: readonly string[];
   /** Where a browser that opened a guarded page is sent — the declaration `x dev` reads. */
   readonly signInPath: string | null;
@@ -60,6 +63,8 @@ export async function webSurface(
   // prevent, and it is the one an operator cannot see without installing the app.
   const pwa = await loadPwaArtifacts(options.root);
   const theme = themeBoot(await loadThemeMode(options.root));
+  // The app's brand (`apps/web/shared/theme.ts`), or nothing: the same reader `x dev` calls.
+  const brand = await loadThemeBrand(options.root);
   // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
   const site = await loadSiteSettings(options.root);
   const origin = publicOrigin(options.env, site);
@@ -73,8 +78,9 @@ export async function webSurface(
   const speculation = pageSpeculation({
     config: await loadSpeculation(options.root),
     client: declared.surfaces,
+    localeSegments: otherLocaleSegments(await appLocaleSet(options.root)),
   });
-  // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
+  // The worker, from the SAME route table this process is about to serve — `describePages()` is
   // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
   // route added here cannot be missing from the precache manifest.
   const serviceWorker =
@@ -83,7 +89,7 @@ export async function webSurface(
       : serviceWorkerArtifacts({
           pwa,
           buildId,
-          routes: describeRoutes(),
+          routes: describePages(),
           islands,
           styles: styleBundle(),
           scripts: [
@@ -135,6 +141,7 @@ export async function webSurface(
     ...adminMountRoutes({
       buildId: buildId,
       themeHead: theme.head,
+      ...(brand === undefined ? {} : { brandHead: brand.head }),
       ...(origin === undefined ? {} : { origin }),
     }),
     ...appRoutes({
@@ -144,6 +151,7 @@ export async function webSurface(
       persisted: sync.persisted,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       themeHead: theme.head,
+      ...(brand === undefined ? {} : { brandHead: brand.head }),
       ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
       // A `static` page is the same bytes for every request of this process: rendered once.
       memoStatic: true,
@@ -158,8 +166,11 @@ export async function webSurface(
     routes,
     inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
     // The enforced policy this process sends must admit the app's own error pages' `<style>` and
-    // the theme boot the documents carry; `x dev` is report-only, so only here was it a blank page.
-    inlineStyles: await errorPageStyleSources(options.root),
+    // the brand's; `x dev` is report-only, so only here was a missing hash an unstyled page.
+    inlineStyles: [
+      ...(await errorPageStyleBodies(options.root)),
+      ...(brand === undefined ? [] : [brand.style]),
+    ],
     // Same declaration `x dev` reads. Without it a container answers a browser that opened a
     // guarded page with the problem document, rendered as raw JSON in the viewport.
     signInPath: await loadSignInPath(options.root),

package/src/serve.ts

@@ -5,10 +5,10 @@
 // interface — every one by default, because a container is reached through a port mapping.
 
 import { assertNoDevSecretsOutsideLocal, logger } from '@ultimat3/core';
-import { assertNoDrift, checkDrift, migrate } from '@ultimat3/db';
+import { assertNoSchemaDrift, checkDrift, migrate } from '@ultimat3/db';
 import { loadAppRuntime } from './app-runtime';
 import { acceptCreatedTables } from './db-accept-created';
-import { holdUntilShutdown } from './hold';
+import { type BootedHold, holdWhileBooting } from './hold';
 import { startMetricsEndpoint } from './metrics-endpoint';
 import { readMigrations } from './migrations';
 import { resolveServices } from './runtime-bindings';
@@ -174,19 +174,36 @@ export async function runRole(input: ServeOptions): Promise<StartedApp> {
     // returned. `x db migrate` calls the same `runMigrations` and renders every difference as a
     // finding before exiting non-zero; a container that logged one and exited 0 would let the
     // deploy roll on over a schema nobody can reconstruct, which is the failure drift exists for.
-    assertNoDrift(migrated.drift);
+    assertNoSchemaDrift(migrated.drift);
     return migrated;
   }
-  const app = await serveApp({ ...options, role });
-  logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
+  // The drain's handlers BEFORE the boot (`holdWhileBooting`): the worker claims inside
+  // `startRoles`, so a SIGTERM during boot has to be a drain of what started, never Bun's kill.
   // `exit` because this is the one entry point with nothing above it: `bin.ts` ends in
   // `process.exit(code)` and `apps/web/server.ts` — which is what awaits this — does not. One
   // non-unref'd interval anywhere in the app then holds an event loop that has nothing left to do,
   // until `terminationGracePeriodSeconds` runs out and the kubelet SIGKILLs a drained process.
-  await holdUntilShutdown('serve', () => app.stop(), {
-    exit: (code) => {
-      process.exit(code);
-    },
-  })();
+  //
+  // A worker also retires on SIGUSR2 (`serve-retire.ts`) — armed before the boot for the same
+  // reason: Bun's default for an unhandled SIGUSR2 ends the process, and a `preStop` may land
+  // while the pod still boots. The retire ends in the same drain, so the same hold exits 0.
+  // Behind `await import()`, as the serving graph is: `ROLE=migrate` never loads it.
+  const retire = role === 'worker' ? (await import('./serve-retire')).armWorkerRetire() : undefined;
+  let booted: BootedHold<ServedApp>;
+  try {
+    booted = await holdWhileBooting('serve', () => serveApp({ ...options, role }), {
+      exit: (code) => {
+        retire?.disarm();
+        process.exit(code);
+      },
+    });
+  } catch (error) {
+    retire?.disarm();
+    throw error;
+  }
+  const { app, hold } = booted;
+  retire?.adopt(app.running.worker);
+  logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
+  await hold();
   return app;
 }

package/src/server-barrels.ts

@@ -27,9 +27,12 @@ export interface BarrelImport {
   readonly entry: string;
 }
 
-/** `import` / `export … from` / `import()` of a VALUE from the barrel. `import type` runs nothing. */
+/**
+ * `import` / `export … from` / `import()` of a VALUE from the barrel, and the side-effect
+ * `import '…'` that binds nothing yet evaluates the whole module. `import type` runs nothing.
+ */
 const IMPORTS =
-  /\b(?:import|export)\s+(?!type\s)[^;'"]*?\bfrom\s*(['"])([^'"]+)\1|\bimport\s*\(\s*(['"])([^'"]+)\3\s*\)/g;
+  /\b(?:import|export)\s+(?!type\s)[^;'"]*?\bfrom\s*(['"])([^'"]+)\1|\bimport\s*\(\s*(['"])([^'"]+)\3\s*\)|\bimport\s*(['"])([^'"]+)\5/g;
 
 export function barrelImports(
   source: string,
@@ -41,7 +44,7 @@ export function barrelImports(
   const lineAt = lineIndex(code);
   const found: BarrelImport[] = [];
   for (const match of code.matchAll(IMPORTS)) {
-    const spec = match[2] ?? match[4] ?? '';
+    const spec = match[2] ?? match[4] ?? match[6] ?? '';
     const entry = barrels.get(spec);
     if (entry === undefined) continue;
     // `import { type A, type B } from …` binds nothing at runtime either.

package/src/shot-browser.ts

@@ -96,7 +96,7 @@ export function shotBrowserChoice(input: ShotBrowserInput): ShotBrowserChoice {
       flag: 'browser',
       command: 'shot',
       reason: `no executable at "${executablePath}"`,
-      fix: 'x shot / --browser /usr/bin/chromium',
+      fix: 'x shot / --browser /usr/bin/chromium   # macOS: --browser "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"; Windows: --browser "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"',
     });
   }
   return { executablePath };

package/src/shot-locale.ts

@@ -3,23 +3,14 @@
 // on the language of the machine's Chrome. A non-default locale is also a URL prefix (`/en/…`),
 // because on a `site/` route the unprefixed path is always the default locale whatever the header.
 
-import { loadAppConfig } from './app-config-load';
+import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import { BadFlagError } from './errors';
 
-export interface ShotLocales {
-  readonly locales: readonly string[];
-  readonly defaultLocale: string;
-}
-
-/** An app that declares nothing is `en` only — the framework's own default. */
-export const FALLBACK_SHOT_LOCALES: ShotLocales = { locales: ['en'], defaultLocale: 'en' };
-
-/** `app.config.ts`'s `locales` and `defaultLocale`, off the one loader (`app-config-load.ts`). */
-export async function loadShotLocales(root: string): Promise<ShotLocales> {
-  const config = await loadAppConfig(root);
-  if (config === undefined) return FALLBACK_SHOT_LOCALES;
-  return { locales: config.locales, defaultLocale: config.defaultLocale };
-}
+/**
+ * `@ultimat3/i18n/app-catalogs`'s `appLocaleSet(root)` — the one reader, and its one answer for an
+ * app that declares nothing (`UNDECLARED_LOCALES`, the framework default alone).
+ */
+export type ShotLocales = AppLocaleSet;
 
 /** `--locale <l>`, refused by name when the app does not declare it — a typo costs no browser. */
 export function readLocaleFlag(value: string | undefined, app: ShotLocales): string | undefined {