@ultimat3/cli 25.2.0 → 26.1.0

package/src/parse.ts

@@ -44,7 +44,7 @@ export interface CommandSpec {
    * than a misspelt one. Declared per command, never inferred, because only some commands can say
    * it truthfully: `x errors X_PERMISSION_UNKNOWN` can only be a code, and `x jobs 4f2a` is
    * genuinely ambiguous with `show`, so an unconditional fallback would turn `x jobs <id>` into a
-   * silent `x jobs ls` that ignores the id.
+   * silent `x jobs list` that ignores the id.
    *
    * `x errors X_PERMISSION_UNKNOWN --json` answered `X_CLI_UNKNOWN_COMMAND … fix: x help`, and
    * `x help` prints `errors  an X_* code, explained` — which reads as exactly the form that was
@@ -304,6 +304,27 @@ function splitInline(raw: string): [string, string | undefined] {
   return [raw.slice(0, eq), raw.slice(eq + 1)];
 }
 
+/**
+ * The verbs 26.0.0 retired (#709): one verb each across every `x` registry — `list`, `show <one>`,
+ * `delete` — and no alias, because two spellings of one verb is the ambiguity axiom 1 forbids. A
+ * retired verb is REFUSED, never accepted; this table only lets the refusal name its replacement.
+ */
+export const RETIRED_VERBS = Object.freeze<Record<string, string>>({
+  ls: 'list',
+  rm: 'delete',
+  describe: 'show',
+  drop: 'delete',
+});
+
+/** The verb that replaced `word`, when `word` was retired and its replacement is in `allowed`. */
+export function retiredVerbReplacement(
+  word: string,
+  allowed: readonly string[],
+): string | undefined {
+  const replacement = Object.hasOwn(RETIRED_VERBS, word) ? RETIRED_VERBS[word] : undefined;
+  return replacement !== undefined && allowed.includes(replacement) ? replacement : undefined;
+}
+
 /** Which subcommand ran, and whether the caller's first positional is what named it. */
 interface ResolvedSubcommand {
   readonly name: string | undefined;
@@ -323,7 +344,7 @@ function readSubcommand(spec: CommandSpec, positionals: readonly string[]): Reso
     throw new MissingSubcommandError({ command: spec.name, known: allowed });
   }
   if (allowed.includes(token)) return { name: token, consumed: true };
-  const suggestion = nearestName(token, allowed);
+  const suggestion = retiredVerbReplacement(token, allowed) ?? nearestName(token, allowed);
   // The declared fallback, and only past the near-miss guard: a word within `nearestName`'s edit
   // budget of a real subcommand is a typo, and reading it as the default subcommand's argument
   // would answer a question nobody asked.

package/src/pwa-artifacts.ts

@@ -18,7 +18,7 @@
 // why: Bun exposes no path-join primitive, and the export writes each icon under an out directory.
 import { join } from 'node:path';
 import type { PwaColors, PwaOfflineConfig } from '@ultimat3/core';
-import { escapeHtml, localeSegment } from '@ultimat3/core';
+import { escapeHtml, localeSegment, pushWired } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
@@ -117,7 +117,7 @@ async function loadInstallable(root: string): Promise<InstallableApp | undefined
     locales: appLocales(await appLocaleSet(root)),
     offline: pwa.offline,
     backgroundSync: pwa.backgroundSync,
-    push: pwa.push,
+    push: pushWired(pwa),
   };
 }
 

package/src/registry.ts

@@ -37,6 +37,7 @@ import { secretsSpec } from './cmd-secrets-spec';
 import { shotSpec } from './cmd-shot-spec';
 import { tasksSpec } from './cmd-tasks-spec';
 import { testSpec } from './cmd-test-spec';
+import { vapidSpec } from './cmd-vapid-spec';
 import { verifySpec } from './cmd-verify-spec';
 import type { CliCommand } from './command';
 import type { CommandSpec } from './parse';
@@ -87,6 +88,7 @@ export const LAZY_COMMANDS: readonly LazyCommand[] = [
   lazy(envSpec, async () => (await import('./cmd-env')).envCommand),
   lazy(secretsSpec, async () => (await import('./cmd-secrets')).secretsCommand),
   lazy(authSpec, async () => (await import('./cmd-auth')).authCommand),
+  lazy(vapidSpec, async () => (await import('./cmd-vapid')).vapidCommand),
   lazy(manifestSpec, async () => (await import('./cmd-manifest')).manifestCommand),
   lazy(routesSpec, async () => (await import('./cmd-routes')).routesCommand),
   lazy(actionsSpec, async () => (await import('./cmd-registries')).actionsCommand),

package/src/role-replicator.ts

@@ -73,7 +73,7 @@ const embeddedRefusal = (dev: boolean): BadFlagError | ConfigInvalidError =>
  * Both readers of this list are catalog readers. `PgReplicationStream` keeps a change only when
  * `#entities.has(relation.name)`, and a pgoutput Relation message names the table; `warnPartialIdentity`
  * matches the same list against `pg_class.relname`. An entity NAME is the framework's own registry
- * key — what a cache tag, a policy and `x entities describe` are keyed by — and `entity('user',
+ * key — what a cache tag, a policy and `x entities show` are keyed by — and `entity('user',
  * { table: 'users' })` makes the two different strings. Passing the name meant a renamed table
  * matched nothing on either side: every change SKIPPED, and a replica-identity warning that could
  * never fire. Latent wherever the two agree, which is every entity in `examples/dummy`.

package/src/runtime-jobs.ts

@@ -93,7 +93,7 @@ function reportUnserved(served: readonly string[], registered: readonly string[]
   logger.warn('jobs.worker.queue-unserved', {
     queues,
     served,
-    fix: `x jobs ls --json — every queue listed with no worker needs one: WORKER_QUEUES=<queue>,<queue> on another worker Deployment, or add it to this one's`,
+    fix: `x jobs list --json — every queue listed with no worker needs one: WORKER_QUEUES=<queue>,<queue> on another worker Deployment, or add it to this one's`,
   });
 }
 

package/src/runtime-push.ts

@@ -0,0 +1,80 @@
+// Web Push at boot: `pwa.push` read off the one config, the VAPID pair resolved from the boot's
+// environment (refused before any service starts), and the runtime installed over the boot's own
+// executor — so `pushSubscribe()`, `pushUnsubscribe()` and `webPush()` work in every role with no
+// line of app wiring, and a deploy with no keys never boots.
+//
+// `@ultimat3/pwa` behind `await import()`: an app with push off — most of them — loads none of it
+// into a worker or a migrate pod (`serve-graph.test.ts`), exactly as the nats client is opened.
+
+import type { AppConfig, PgExecutor } from '@ultimat3/core';
+import { logger, PWA_PUSH_FIX, pushWired } from '@ultimat3/core';
+import type { ResolvedVapidKeys } from '@ultimat3/pwa';
+import type { Env } from './runtime-bindings';
+
+/** `pwa.vapid.subject` when this app's boot owes a push runtime, else `undefined`. */
+export function pushSubjectOf(config: AppConfig | undefined): string | undefined {
+  const pwa = config?.pwa;
+  if (pwa === undefined || !pushWired(pwa)) return undefined;
+  // `pushWired` checked the block is there; `defineConfig` checked its subject is one a push
+  // service takes (`pwaPushIssues`).
+  return pwa.vapid?.subject;
+}
+
+export interface PushSelection {
+  readonly subject: string;
+  readonly resolved: ResolvedVapidKeys;
+  /** `pwa.vapid.pushHosts`: push services beyond the built-in list. */
+  readonly pushHosts: readonly string[];
+}
+
+/**
+ * Pure apart from the key check — reads env, dials nothing — so it runs BEFORE the queue, beside
+ * the mail driver's selection: a deploy missing `ULTIMATE_VAPID_PRIVATE_KEY` fails on the spot
+ * with `X_PWA_VAPID_KEY_MISSING`, not after PGlite started, and never on the first push nobody got.
+ */
+export async function selectWebPush(
+  config: AppConfig | undefined,
+  env: Env,
+): Promise<PushSelection | undefined> {
+  const subject = pushSubjectOf(config);
+  if (subject === undefined) {
+    const pwa = config?.pwa;
+    // Accepted for 26.0.0's sake, and never silent: the app asked for push and gets none.
+    if (pwa?.enabled === true && pwa.push) {
+      logger.warn('pwa.push unwired', {
+        cause:
+          'pwa.push is true and pwa.vapid is unset, so no push runtime, handler or key is wired',
+        fix: PWA_PUSH_FIX,
+      });
+    }
+    return undefined;
+  }
+  const { resolveVapidKeys } = await import('@ultimat3/pwa');
+  return {
+    subject,
+    resolved: await resolveVapidKeys(env),
+    pushHosts: config?.pwa.vapid?.pushHosts ?? [],
+  };
+}
+
+/** Install the runtime over the boot's executor; answers its release. */
+export async function installAppWebPush(
+  selection: PushSelection,
+  executor: PgExecutor,
+): Promise<() => void> {
+  const { installWebPush, postgresPushSubscriptionStore } = await import('@ultimat3/pwa');
+  if (selection.resolved.source === 'development') {
+    // Said once per boot: a reader seeing pushes arrive locally must know they are signed with a
+    // pair printed in the framework's source, which no deploy accepts.
+    logger.info('pwa.push development keys', {
+      cause: 'ULTIMATE_VAPID_PUBLIC_KEY and ULTIMATE_VAPID_PRIVATE_KEY are unset',
+      fix: 'x vapid create   # before the first deploy; a deployed boot refuses the development pair',
+    });
+  }
+  return installWebPush({
+    store: postgresPushSubscriptionStore({ executor }),
+    keys: selection.resolved.keys,
+    subject: selection.subject,
+    pushHosts: selection.pushHosts,
+  });
+}

package/src/runtime-services.ts

@@ -40,6 +40,7 @@ import { selectAppMailDriver } from './runtime-mail';
 import { inboxRetentionOf } from './runtime-notify-retention';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { installRetentionSweep } from './runtime-purge';
+import { installAppWebPush, selectWebPush } from './runtime-push';
 import type { DevDbClient, SchemaMode } from './runtime-queue';
 import { startQueue } from './runtime-queue';
 import { realtimeConfigOf } from './runtime-realtime';
@@ -342,6 +343,9 @@ export async function startServices(
   // `ROLE=sync` container makes, so this process cannot resolve the bus differently from the
   // container it stands in for.
   const realtime = realtimeConfigOf(config);
+  // Fourth: `pwa.push` and its VAPID pair (`runtime-push.ts`). Resolving the pair reads env and
+  // signs one probe — a deploy with no keys, or two halves of different pairs, refuses here.
+  const push = await selectWebPush(config, env);
   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
@@ -419,6 +423,9 @@ export async function startServices(
       const connectable = transport;
       started.push(registerReadinessCheck('transport', () => connectable.connected));
     }
+    // Before `loadApp` for the auth limiters' reason: `pushSubscribe()` is declared when the app's
+    // modules import, and reads this runtime per call.
+    if (push !== undefined) started.push(await installAppWebPush(push, executor));
     const storage = startStorage(services, env, overrides?.storage);
     // With no credential this is the memory driver: caught, not sent, so the `/_x` mail panel can
     // show what a template renders in every locale without a mailbox or a message escaping to a

package/src/serve-boot.ts

@@ -54,13 +54,19 @@ const LISTENING_ROLES: readonly Role[] = ['web', 'sync'];
  * — 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.
+ * on a deploy, so it is the one key here a non-listening role needs MOST. The worker's alone is
+ * `workerDeadlineMs` when declared — the hour `deadlineMs` is capped at is too short for a job
+ * that must not run twice, and a web role has no business waiting two hours on a request.
  */
 export function lifecycleForRole(
   role: Role,
   drain: Partial<DrainConfig> | undefined,
 ): LifecycleOptions {
-  const budget = drain?.deadlineMs === undefined ? {} : { deadlineMs: drain.deadlineMs };
+  const declared =
+    role === 'worker' && drain?.workerDeadlineMs !== undefined
+      ? drain.workerDeadlineMs
+      : drain?.deadlineMs;
+  const budget = declared === undefined ? {} : { deadlineMs: declared };
   if (!LISTENING_ROLES.includes(role)) return { readinessGraceMs: 0, ...budget };
   return drain?.readinessGraceMs === undefined
     ? budget

package/src/serve-drain.ts

@@ -9,7 +9,11 @@ export async function loadDrainConfig(root: string): Promise<Partial<DrainConfig
   const drain = (await loadAppConfig(root))?.drain;
   return drain === undefined
     ? undefined
-    : { readinessGraceMs: drain.readinessGraceMs, deadlineMs: drain.deadlineMs };
+    : {
+        readinessGraceMs: drain.readinessGraceMs,
+        deadlineMs: drain.deadlineMs,
+        workerDeadlineMs: drain.workerDeadlineMs,
+      };
 }
 
 /** `health.readiness`, or `undefined` for a root with no config file (core keeps its default). */

package/src/serve-retire.ts

@@ -1,9 +1,9 @@
 // `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.
+// happen at most once and may outlast the drain budget. Framework-owned: no port, no app code.
 
-import { drain, logger, renderThrowable } from '@ultimat3/core';
+import { drain, logger, markRetiring, 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). */
@@ -43,7 +43,8 @@ const NOTHING: WorkerRetire = Object.freeze({ adopt: () => undefined, disarm: ()
  * 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`).
+ * the retire to the worker's budget — `drain.workerDeadlineMs`, else `drain.deadlineMs` — and cuts
+ * off at the margin (`packages/jobs/src/worker.ts`). `isRetiring()` is true from the signal on.
  */
 export function armWorkerRetire(options: WorkerRetireOptions = {}): WorkerRetire {
   if ((options.platform ?? process.platform) === 'win32') return NOTHING;
@@ -84,6 +85,9 @@ export function armWorkerRetire(options: WorkerRetireOptions = {}): WorkerRetire
   const listener = (): void => {
     if (retiring) return;
     retiring = true;
+    // At the signal, before the worker is awaited or stopped: the app's `isRetiring()` is how its
+    // own code (a heartbeat, a status row) sees a retire that `isDraining()` only shows at the end.
+    markRetiring();
     // Never rejects: `retire` catches its own failure and always reaches the drain.
     void retire();
   };

package/src/serve-web.ts

@@ -6,6 +6,7 @@
 import type { Route } from '@ultimat3/http';
 import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
 
+import { installedVapid } from '@ultimat3/pwa';
 import { describePages } from '@ultimat3/render';
 import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
@@ -96,6 +97,9 @@ export async function webSurface(
             ...sync.scripts,
             ...(navigation.script === undefined ? [] : [navigation.script]),
           ],
+          // The runtime `startServices` installed when `pwa.push` is on: the worker's push
+          // handler and the page's `x-push-key` come from the pair this process signs with.
+          vapid: installedVapid(),
         });
   // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
   const mcpMount = await mountAppMcp(options.root);

package/src/site-seo.ts

@@ -110,7 +110,7 @@ type Stamp = (file: string) => { readonly lastmod?: string };
 /**
  * The app's `seo.sitemap.extra` paths as records, each resolved to the route that answers it — the
  * most specific match, the router's own tie-break. REFUSED, never skipped, when it names no route,
- * an `api/` route, a gated one or a `site/` page (listed already): a sitemap missing a page its
+ * a gated one or a `site/` page (listed already): a sitemap missing a page its
  * author listed is the silent drop, and a gated page in it is a URL a crawler cannot open.
  */
 function extraRoutes(extra: readonly string[], stamp: Stamp): readonly RouteRecord[] {
@@ -121,9 +121,6 @@ function extraRoutes(extra: readonly string[], stamp: Stamp): readonly RouteReco
       .sort((a, b) => b.pattern.specificity - a.pattern.specificity)[0];
     if (entry === undefined)
       throw new SitemapExtraInvalidError(path, 'no registered route answers');
-    if (entry.surface === 'api') {
-      throw new SitemapExtraInvalidError(path, `is the api/ route ${entry.file}, not a page`);
-    }
     if (entry.surface === 'site') {
       throw new SitemapExtraInvalidError(
         path,

package/src/sw-artifacts.ts

@@ -3,8 +3,9 @@
 // until #390. Beside `pwa-artifacts.ts` and not inside it: that file needs a root and a config
 // file, this one needs a booted app and a finished build.
 
-import type { PrecacheManifest } from '@ultimat3/pwa';
-import { generateServiceWorker } from '@ultimat3/pwa';
+import { escapeHtml } from '@ultimat3/core';
+import type { PrecacheManifest, VapidConfig } from '@ultimat3/pwa';
+import { generateServiceWorker, PUSH_KEY_META } from '@ultimat3/pwa';
 import type { RouteDescriptor } from '@ultimat3/render';
 import type { IslandBundle } from './island-bundle';
 import { ISLAND_BASE_PATH } from './island-bundle';
@@ -72,6 +73,12 @@ export interface ServiceWorkerInput {
    * offline reload that cannot load the boot restores no record and shows the old count.
    */
   readonly scripts?: readonly { readonly url: string; readonly bytes: number }[];
+  /**
+   * The installed Web Push runtime's public key and subject (`@ultimat3/pwa`'s `installedVapid()`),
+   * which the boot put there from `pwa.push` and the VAPID pair — or absent where no runtime runs:
+   * a static export serves no subscribe action, so its worker carries no push handler.
+   */
+  readonly vapid?: VapidConfig | undefined;
 }
 
 /**
@@ -175,6 +182,7 @@ export function serviceWorkerArtifacts(
         personalPages: pwa.offline.personalPages,
       },
       capabilities: { backgroundSync: pwa.backgroundSync, push: pwa.push },
+      ...(pwa.push && input.vapid !== undefined ? { vapid: input.vapid } : {}),
       assets: precacheAssets({
         routes: input.routes,
         documents,
@@ -194,15 +202,14 @@ export function serviceWorkerArtifacts(
   return {
     source: output.source,
     register: serviceWorkerRegistration(),
-    head,
+    head: head + pushKeyMeta(pwa, input.vapid),
     precache: output.precache,
     // `output.warnings` IS `output.precache.warnings` — the generator returns the manifest's list
     // verbatim — so it is read once, not twice. The push line is this module's own, and it is the
     // one thing the generator cannot say: `generateServiceWorker` emits a push handler only when a
-    // VAPID key comes with the capability, and drops it in SILENCE otherwise. `pwa.push: true` in
-    // an `app.config.ts` therefore wires nothing and reports nothing, which is `jobs.driver`'s
-    // shape one package over.
-    warnings: [...output.warnings, ...pushWarning(pwa)],
+    // VAPID key comes with the capability, and drops it in SILENCE otherwise — which, since the
+    // boot installs the runtime whenever `pwa.push` is on, is a build with no runtime behind it.
+    warnings: [...output.warnings, ...pushWarning(pwa, input.vapid)],
   };
 }
 
@@ -219,10 +226,20 @@ export const serviceWorkerHead = (pwa: PwaArtifacts): string | undefined =>
   pwa.offline.fallback === null ? undefined : `<script src="${SW_REGISTER_PATH}" defer></script>`;
 
 /**
- * `pwa.push: true` with nothing to sign a subscription with. There is no `pwa.vapid` config key
- * yet, so today this fires for EVERY app that sets the flag — deliberately: a switch that silently
- * does nothing is the defect this framework keeps re-shipping, and a warning naming the missing
- * half is the smallest honest answer until the key exists.
+ * `pwa.push: true` in a build no Web Push runtime stands behind. A served boot installs one whenever
+ * the flag is on (`runtime-push.ts`, and it refuses to boot without the keys), so this fires for a
+ * static export alone — which serves no subscribe action, so a push handler there would be a
+ * capability the deploy cannot use. Said, never dropped in silence.
+ */
+const pushWarning = (pwa: PwaArtifacts, vapid: VapidConfig | undefined): readonly string[] =>
+  pwa.push && vapid === undefined ? [msg('cli.build.pushUnwired')] : [];
+
+/**
+ * `<meta name="x-push-key">`: the public key `@ultimat3/pwa/client`'s `subscribeToPush` hands the
+ * browser. In the document rather than fetched, so subscribing is one click and no round trip, and
+ * a key rotation reaches every page on its next render. Public by definition; escaped regardless.
  */
-const pushWarning = (pwa: PwaArtifacts): readonly string[] =>
-  pwa.push ? [msg('cli.build.pushUnwired')] : [];
+const pushKeyMeta = (pwa: PwaArtifacts, vapid: VapidConfig | undefined): string =>
+  pwa.push && vapid !== undefined
+    ? `<meta name="${PUSH_KEY_META}" content="${escapeHtml(vapid.publicKey)}">`
+    : '';

package/src/sync-url.ts

@@ -11,6 +11,15 @@ import { ConfigInvalidError } from '@ultimat3/core';
  */
 export const SYNC_PATH = '/_x/sync';
 
+/**
+ * Exactly what a proxy routes to the `sync` role: the socket's path, and anything under it. No
+ * other framework route matches it — scripts live under `FRAMEWORK_ASSET_BASE_PATH`
+ * (`/_x/assets/…`) — so an operator's ordinary prefix rule can never swallow a page's asset.
+ * `wiki/Deployment.md` prints this pattern; `worker-bundle.test.ts` holds every framework route
+ * outside it.
+ */
+export const SYNC_PROXY_PATTERN = /^\/_x\/sync(\/.*)?$/;
+
 /**
  * `SYNC_URL` verbatim when the deployment states one — the Compose rung publishes `sync` on its
  * own port with no proxy in front, so only the deployment knows that URL — else `SYNC_PATH`,

package/src/templates/scaffold-claude-agents.ts

@@ -40,7 +40,7 @@ stop; that answer is worth more than a plan built on a shape the app cannot hold
 |---|---|
 | \`apps/web/site/<path>/page.tsx\` | public, SEO-critical, 0kb JS |
 | \`apps/web/app/<slice>/\` | the feature slice: entity, repo, policy, actions, queries, jobs, UI |
-| \`apps/web/api/<name>/route.ts\` | HTTP surface for actions |
+| \`apps/web/api/index.ts\` | the one \`defineApi()\` collecting every action and query — no route file lives under \`api/\` |
 | \`apps/web/shared/\` | tokens, primitives, the actor type — a leaf, imports nothing of yours |
 | \`packages/db/\` | schema, migrations, seed |
 | \`packages/ui/\` | components with no feature knowledge |
@@ -79,7 +79,7 @@ feature slice. Nothing else. A change outside that set is a collision — report
 | Money | \`{ minor, currency }\` — integer minor units and an ISO code, both, always. Never a float |
 | Time | store UTC; a formatted date always names an explicit IANA time zone |
 
-Inspect before you change: \`x entities list\`, \`x entities describe <name>\`, both with \`--json\`.
+Inspect before you change: \`x entities list\`, \`x entities show <name>\`, both with \`--json\`.
 
 Checks: \`bun test <path>/entity.test.ts\`, \`bunx biome check --write <paths>\`, and \`bun run typecheck\`
 once when you are otherwise done. Never \`x verify\` — that belongs to whoever coordinates you.
@@ -105,7 +105,7 @@ renders. A change outside that set is a collision — report it, do not make it.
 | Tasks name a time zone | a cron schedule with an ambient zone is a different time twice a year |
 | No \`any\` | \`unknown\` plus a schema parse |
 
-Inspect before you change: \`x actions describe <name>\`, \`x queries describe <name>\`, \`x jobs ls\`,
+Inspect before you change: \`x actions show <name>\`, \`x queries show <name>\`, \`x jobs list\`,
 \`x tasks list\`, \`x policy explain <subject>\` — every one takes \`--json\`.
 
 Checks: \`bun test <path>/<file>.test.ts\`, \`bunx biome check --write <paths>\`, and \`bun run typecheck\`
@@ -126,7 +126,7 @@ calls. A change outside that set is a collision — report it, do not make it.
 |---|---|
 | \`site/\` is 0kb JS | and may not import from \`app/\`. One interactive control on a static page is an island: \`x g island <name> --at <dir>\` |
 | \`shared/\` is a leaf | tokens, primitives, the actor type. It imports nothing of yours |
-| The directory is the URL | \`page.tsx\` under \`site/\`/\`app/\`, \`route.ts\` under \`api/\`. The filename is never the path |
+| The directory is the URL | \`page.tsx\` under \`site/\`/\`app/\`; \`api/\` holds no route file, only \`defineApi()\`'s actions and queries. The filename is never the path |
 | Every string through \`t()\` | a literal in a component is a string no locale can ever translate |
 | Semantic tokens only | never a raw hex, in a component or a stylesheet |
 | Dates name a zone | explicit IANA time zone at every call site, no ambient default |

package/src/templates/scaffold-claude-commands.ts

@@ -66,12 +66,12 @@ SQL into \`packages/db/migrations/\`.
 |---|---|---|
 | \`apps/web/site/\` | 0kb JS, may not import \`apps/web/app/\` | the static path pays the app's bundle |
 | \`apps/web/app/\` | authed, streaming, hydrated | — |
-| \`apps/web/api/\` | actions only, \`route.ts\` | a second HTTP surface |
+| \`apps/web/api/\` | actions and queries only, collected by \`defineApi()\` — no route file | a second HTTP surface |
 | \`apps/web/shared/\` | a leaf: imports nothing of yours | an import cycle across surfaces |
 | \`repo.ts\` | the only file that touches the database | authz bypassed by a raw read |
 | routes | call actions and queries, never a repo | policy skipped |
 
-Route files: \`page.tsx\` under \`site/\`/\`app/\`, \`route.ts\` under \`api/\`. **The directory is the URL** —
+Route files: \`page.tsx\` under \`site/\`/\`app/\`, and none under \`api/\`. **The directory is the URL** —
 the filename never is. One interactive control on a 0kb page is an island: \`x g island <name> --at <dir>\`.
 
 ## 4. Gate it

package/src/templates/scaffold-claude.ts

@@ -32,7 +32,7 @@ const settings = (): string => `{
       "Bash(x actions:*)",
       "Bash(x queries:*)",
       "Bash(x entities:*)",
-      "Bash(x jobs ls:*)",
+      "Bash(x jobs list:*)",
       "Bash(x jobs show:*)",
       "Bash(x tasks:*)",
       "Bash(x policy:*)",

package/src/templates/scaffold-helm-templates.ts

@@ -195,14 +195,18 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
 {{/*
 A role's terminationGracePeriodSeconds, in the order the kubelet's budget is spent: the preStop
 sleep (web and sync, 1.30+), the worker's opt-in retire (roles.worker.retireSeconds), the
-readiness grace (web and sync — every other role drains with none), the drain budget (app.config.ts drain.deadlineMs, every role) and the teardown margin.
+readiness grace (web and sync — every other role drains with none), the drain budget (app.config.ts drain.deadlineMs, every role;
+the worker's is drain.workerDeadlineSeconds instead when > 0, from drain.workerDeadlineMs) and the teardown margin.
 Defaults: 45s web/sync (40s below 1.30), 35s the rest. x deploy --method helm sets
-drain.deadlineSeconds and drain.readinessGraceSeconds from app.config.ts.
+drain.deadlineSeconds, drain.workerDeadlineSeconds and drain.readinessGraceSeconds from app.config.ts.
 */}}
 {{- define "${app.kebab}.terminationGracePeriodSeconds" -}}
 {{- $drain := .root.Values.drain -}}
 {{- $total := add (int $drain.deadlineSeconds) (int $drain.teardownMarginSeconds) -}}
 {{- if eq .role "worker" -}}
+{{- if gt (int $drain.workerDeadlineSeconds) 0 -}}
+{{- $total = add (int $drain.workerDeadlineSeconds) (int $drain.teardownMarginSeconds) -}}
+{{- end -}}
 {{- $total = add $total (int .cfg.retireSeconds) -}}
 {{- end -}}
 {{- if .cfg.port -}}

package/src/templates/scaffold-helm.ts

@@ -99,11 +99,14 @@ securityContext:
 #   readinessGraceSeconds  app.config.ts drain.readinessGraceMs / 1000 (web and sync only)
 #   deadlineSeconds        app.config.ts drain.deadlineMs / 1000 — x deploy --method helm sets
 #                          both from app.config.ts, so a raised budget raises the grace with it
+#   workerDeadlineSeconds  app.config.ts drain.workerDeadlineMs / 1000 — the worker's budget in place
+#                          of deadlineSeconds, up to a day; 0 means the worker uses deadlineSeconds
 #   teardownMarginSeconds  the release after the drain, the telemetry flush, the pool close
 drain:
   preStopSleepSeconds: 5
   readinessGraceSeconds: 5
   deadlineSeconds: 25
+  workerDeadlineSeconds: 0
   teardownMarginSeconds: 10
 
 # How long a new pod must stay Ready before a rollout counts it and stops an old one.
@@ -166,7 +169,7 @@ roles:
     replicas: 2
     # The retire, OFF at 0. Set to the longest a held job may run, in seconds, and the worker's
     # preStop sends its PID 1 SIGUSR2: stop claiming, finish every held job, abort nothing, exit 0
-    # — for a job whose side effect must happen at most once and may outlast drain.deadlineSeconds.
+    # — for a job whose side effect must happen at most once and may outlast its drain budget.
     # Added to this role's terminationGracePeriodSeconds, which the kubelet counts the preStop against.
     retireSeconds: 0
     resources:

package/src/worker-bundle.ts

@@ -7,24 +7,34 @@
 // why: Bun ships no path API; the entry is resolved to a file and named in the cause.
 import { dirname, join, relative } from 'node:path';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, jsonResponse } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
 import { FrameworkScriptBuildFailedError, type FrameworkScriptKind } from './errors';
 import { describeBuildError, graphHash, stripDebugId } from './island-identity';
 
-/** Under the dev namespace `/_x` — where the socket it opens (`/_x/sync`) already lives. */
-export const SYNC_WORKER_BASE_PATH = '/_x/sync-worker';
+/**
+ * The ONE prefix every framework-served, content-addressed script lives under — the sync worker,
+ * the page boot, the client router — the way Rails serves `/assets/<name>-<sha>`. No live endpoint
+ * shares it: the worker lived at `/_x/sync-worker/…`, and an operator's ordinary prefix rule for
+ * the socket (`^/_x/sync` → the sync role) sent it to a process that serves only the socket, so
+ * no page got its worker and the CDN kept the 404 for hours. `SYNC_PROXY_PATTERN` (`sync-url.ts`)
+ * is the socket's whole claim, and `worker-bundle.test.ts` holds the two apart.
+ */
+export const FRAMEWORK_ASSET_BASE_PATH = '/_x/assets';
+
+/** The sync worker: `<FRAMEWORK_ASSET_BASE_PATH>/sync-worker/<hash>.js`. */
+export const SYNC_WORKER_BASE_PATH = `${FRAMEWORK_ASSET_BASE_PATH}/sync-worker`;
 
 /** What an app resolves: realtime's worker entry, from the APP's install, never the CLI's own. */
 export const SYNC_WORKER_SPECIFIER = '@ultimat3/realtime/sync-worker';
 
-/** Under the dev namespace too; one per document that carries a principal scope. */
-export const PAGE_BOOT_BASE_PATH = '/_x/page-boot';
+/** The page boot, one per document that carries a principal scope. */
+export const PAGE_BOOT_BASE_PATH = `${FRAMEWORK_ASSET_BASE_PATH}/page-boot`;
 
 /** Realtime's page boot, from the APP's install. */
 export const PAGE_BOOT_SPECIFIER = '@ultimat3/realtime/boot';
 
-/** Under the dev namespace too; one per document whose surface opted into client navigation. */
-export const NAVIGATION_BASE_PATH = '/_x/navigation';
+/** The client router, one per document whose surface opted into client navigation. */
+export const NAVIGATION_BASE_PATH = `${FRAMEWORK_ASSET_BASE_PATH}/navigation`;
 
 /** Render's client router, from the APP's install — the copy its documents were rendered by. */
 export const NAVIGATION_SPECIFIER = '@ultimat3/render/navigation';
@@ -198,7 +208,7 @@ function scriptRoute(
     handler: (request: UltimateRequest): Response => {
       const script = source();
       if (script === undefined || script.url !== request.pathname) {
-        return jsonResponse(
+        const missing = jsonResponse(
           {
             ok: false,
             error: {
@@ -209,6 +219,9 @@ function scriptRoute(
           },
           { status: 404 },
         );
+        // `no-store`, said here and not left to the pipeline: a miss on a content-addressed URL
+        // must never be pinned by a CDN or a proxy (`island-routes.ts`' rule).
+        return applyCacheHeaders(missing, NO_STORE);
       }
       return applyCacheHeaders(
         new Response(script.code, { headers: { 'content-type': 'text/javascript' } }),