@ultimat3/cli 25.2.0 → 26.0.0

package/README.md

@@ -19,9 +19,9 @@ Commands and the `x verify` step count, `As of 2026-08`:
 | `x doctor` | environment, ports, drift, PWA prerequisites, `APP_URL` | every finding carries a fix command; probes the port `x dev` binds ([which one](../../wiki/CLI-Reference.md#x-doctor)); the framework's deploy secrets only where the machine names `staging`/`production` |
 | `x deploy` | container deploy plan | compose or helm; zero platform primitives |
 | `x manifest` / `x routes` | generated facts | `x.manifest.json`, `openapi.json`, route table |
-| `x actions` / `x queries` / `x entities` | the declaration registries | `list` and `describe <name>`, straight off the registries |
+| `x actions` / `x queries` / `x entities` | the declaration registries | `list` and `show <name>`, straight off the registries |
 | `x tasks list\|show` | cron tasks | timezone and next run, off `registeredTasks()` |
-| `x jobs ls\|show\|retry\|cancel\|rm\|promote\|pause\|resume` | the queue | depth, dead letters, step traces, `retry --from-step`, `cancel --reason`; `ls --json` pages as `rows`/`nextCursor`/`hasMore`; `drain` is planned (`X_NOT_IMPLEMENTED`) |
+| `x jobs list\|show\|retry\|cancel\|delete\|promote\|pause\|resume` | the queue | depth, dead letters, step traces, `retry --from-step`, `cancel --reason`; `list --json` pages as `rows`/`nextCursor`/`hasMore`; `drain` is planned (`X_NOT_IMPLEMENTED`) |
 | `x test [type]` | one of the six test types, or all | same type rule as the gate; `--filter`, `--sample N` |
 | `x env check\|example` | the typed environment `envSchema` declares | and the `.env.example` rendered from it, plus the framework's deploy-required secrets (`ULTIMATE_CURSOR_SECRET`, `STORAGE_SIGNING_SECRET` unless `S3_ENDPOINT` is set), which `check` asks for wherever the boot refuses them — outside `development`/`test`, or with no environment named |
 | `x auth seal-mfa` | one-shot auth maintenance | seals every `x_users.mfa_secret` still in the clear; idempotent, `{ sealed, alreadySealed, skipped }` |
@@ -171,7 +171,7 @@ that name where there is one (`x new` writes all seventeen), the blank template
 | `app-boundaries.ts` | app import boundaries, over `@ultimat3/render`'s surface check |
 | `app-transport.ts` / `browser-transport.ts` | one browser transport, on `boundaries` in every app: a raw `fetch(`, `new WebSocket(` or `new XMLHttpRequest(` in an island's closure is `X_BROWSER_TRANSPORT_BYPASS`; a server barrel there is `X_BROWSER_SERVER_BARREL` |
 | `app-agents-md.ts` | `AGENTS.md` exists and stays short, over `@ultimat3/manifest`'s check |
-| `serve.ts` | **what a container starts** — `runRole(options)`, the same boot `x dev` runs minus the watcher, `/_x` and `dev: true`. `x new`'s `apps/web/server.ts` is three lines that call it. `ROLE`, `PORT` and `HOST` are read from `env`; `role`, `port` and `hostname` on `ServeOptions` override each. `ROLE=worker` also retires on SIGUSR2 (`serve-retire.ts`, 25.0.0): stop claiming, finish every held job, abort nothing, drain, exit 0 — what the chart's opt-in `roles.worker.retireSeconds` `preStop` sends; a no-op on Windows ([Deployment](../../wiki/Deployment.md#retiring-a-worker-before-sigterm)) |
+| `serve.ts` | **what a container starts** — `runRole(options)`, the same boot `x dev` runs minus the watcher, `/_x` and `dev: true`. `x new`'s `apps/web/server.ts` is three lines that call it. `ROLE`, `PORT` and `HOST` are read from `env`; `role`, `port` and `hostname` on `ServeOptions` override each. `ROLE=worker` also retires on SIGUSR2 (`serve-retire.ts`, 25.0.0): stop claiming, finish every held job, abort nothing, drain, exit 0 — what the chart's opt-in `roles.worker.retireSeconds` `preStop` sends; core's `isRetiring()` is true from the signal on, and a SIGTERM mid-retire drains on `drain.workerDeadlineMs` when declared (`lifecycleForRole`); a no-op on Windows ([Deployment](../../wiki/Deployment.md#retiring-a-worker-before-sigterm)) |
 | `prerender.ts` | `x build --target static`: which `site/` routes qualify, and where the bytes land |
 | `metrics-endpoint.ts` | the `METRICS_PATH` scrape listener every role opens, on `METRICS_PORT`; opening it starts the `process_*` series, labelled by `startMetricsEndpoint({ role })` |
 | `role-load.ts` / `document-graph.ts` / `serve-web.ts` | what each container role imports: `web`, `sync` and `replicator` every app module; `worker` and `scheduler` the API index plus every module that reaches no component or stylesheet |

package/package.json

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

package/src/cmd-db-branch.ts

@@ -1,6 +1,7 @@
-// `x db branch ls|create|drop` — the wiring alone: which verb, which database, which refusal.
+// `x db branch list|create|delete` — the wiring alone: which verb, which database, which refusal.
 // A VERB is required and comes from a closed set, so a branch name can never be read as one:
-// `x db branch ls` used to clone a database called `ls`, because the argument was the name.
+// `x db branch ls` used to clone a database called `ls`, because the argument was the name. One
+// verb each across every `x` registry (#709): `list` and `delete`, no `ls`/`drop` alias.
 // The facts (what a branch is, per mode) are `db-branch.ts`; the client lifetime is here.
 
 import { ERROR_DOCS_URL, nearestName } from '@ultimat3/core';
@@ -26,7 +27,7 @@ import { stepFinding } from './db-finding';
 import { MissingPositionalError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
-import { flagString } from './parse';
+import { flagString, retiredVerbReplacement } from './parse';
 import type { DevServices } from './runtime-bindings';
 import { resolveServices } from './runtime-bindings';
 import { portFromEnv } from './serve';
@@ -35,9 +36,9 @@ import { renderTable } from './table';
 /**
  * Always runnable, always the next thing a caller needs: what branches there are. Spelled twice
  * because `UnknownCommandError` prefixes its `suggestion` with `x ` and `MissingPositionalError`
- * takes a whole invocation — one of them handed back `x x db branch ls --json`.
+ * takes a whole invocation — one of them handed back `x x db branch list --json`.
  */
-const LIST_ARGV = 'db branch ls --json';
+const LIST_ARGV = 'db branch list --json';
 const LIST_FIX = `x ${LIST_ARGV}`;
 
 /**
@@ -47,7 +48,10 @@ const LIST_FIX = `x ${LIST_ARGV}`;
  * `x` excluded — the error class adds it.
  */
 function branchRetry(word: string, name: string | undefined): string {
-  const near = nearestName(word, [...BRANCH_SUBCOMMANDS]);
+  // A retired verb (`ls`, `drop`) is a legal branch NAME too, so without this `drop feat` would be
+  // answered with `create drop` — the exact confusion the closed verb set exists to end.
+  const near =
+    retiredVerbReplacement(word, BRANCH_SUBCOMMANDS) ?? nearestName(word, [...BRANCH_SUBCOMMANDS]);
   if (near !== undefined) return name === undefined ? LIST_ARGV : `db branch ${near} ${name}`;
   return isBranchName(word) ? `db branch create ${word}` : LIST_ARGV;
 }
@@ -101,7 +105,7 @@ export async function runBranchCommand(ctx: CommandContext, root: string): Promi
     });
   }
   const services = resolveServices(root, ctx.env);
-  if (verb === 'ls') return runList(services);
+  if (verb === 'list') return runList(services);
   if (name === undefined) {
     throw new MissingPositionalError({
       command: `db branch ${verb}`,
@@ -109,7 +113,7 @@ export async function runBranchCommand(ctx: CommandContext, root: string): Promi
       example: `x db branch ${verb} feature-x`,
     });
   }
-  return verb === 'create' ? runCreate(ctx, services, name) : runDrop(services, name);
+  return verb === 'create' ? runCreate(ctx, services, name) : runDelete(services, name);
 }
 
 const row = (branch: BranchRow): readonly string[] => [
@@ -174,12 +178,12 @@ async function runCreate(
 }
 
 /**
- * You may only drop what `ls` shows, and that is the whole guard — stronger than a confirmation
+ * You may only delete what `list` shows, and that is the whole guard — stronger than a confirmation
  * flag, because it is the typo that is impossible rather than the keystroke that is tedious. An
  * external branch is a database carrying `createBranch`'s marker comment AND this database's own
  * prefix, so neither the shared database this session is connected to nor another app's clone on
  * the same server is in the set; an embedded one is a `pgdata-<name>` directory, so `pgdata` itself
- * is not either. `@ultimat3/db`'s own `X_BRANCH_EXISTS` fix line is `x db branch drop <name>` with
+ * is not either. `@ultimat3/db`'s own `X_BRANCH_EXISTS` fix line is `x db branch delete <name>` with
  * no flag on it, so a flag here would break a shipped instruction.
  *
  * The check is not made here, and that is the point: `false` from either drop means "there was no
@@ -187,7 +191,7 @@ async function runCreate(
  * earlier. A listing taken here and acted on below is two connections and a window wide enough to
  * hold a whole `create` — and the wiring layer is exactly where a guard must not live.
  */
-async function runDrop(services: DevServices, name: string): Promise<CommandResult> {
+async function runDelete(services: DevServices, name: string): Promise<CommandResult> {
   try {
     const dropped =
       services.db.mode === 'embedded'

package/src/cmd-db-spec.ts

@@ -18,11 +18,11 @@ export const dbSpec: CommandSpec = {
   name: 'db',
   summary: 'gen, migrate, reset, seed, studio, branch, backfill',
   usage:
-    'x db gen "add publish_at" | migrate | reset | seed [<name>] [--tier reference|dev] [--dry-run] | studio | branch ls | branch create <name> | branch drop <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
+    'x db gen "add publish_at" | migrate | reset | seed [<name>] [--tier reference|dev] [--dry-run] | studio | branch list | branch create <name> | branch delete <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
   requiresApp: true,
   subcommands: DB_SUBCOMMANDS,
   // Declared from the constant `runBranchCommand` validates against, never a second literal: it
-  // is what lets the `errors` step resolve `x db branch ls` — a fix line three shipped errors
+  // is what lets the `errors` step resolve `x db branch list` — a fix line three shipped errors
   // hand out, which read `ls` as a branch name and cloned a database until 1.2.x.
   subcommandPositionals: { branch: BRANCH_SUBCOMMANDS },
   // Each flag whose summary begins `<subcommand>:` declares that scope, and the parser refuses

package/src/cmd-deploy-drain.ts

@@ -12,7 +12,8 @@ const seconds = (ms: number): number => Math.ceil(ms / 1000);
 /**
  * The `--set` pairs, or none when the app declares no budget (the chart's defaults are core's).
  * The chart's `drain.deadlineSeconds` is ONE budget for every role, and so is `drain.deadlineMs`:
- * the web role drains on it too. The margins stay the chart's.
+ * the web role drains on it too — the worker on `drain.workerDeadlineSeconds` instead, when the app
+ * declares `drain.workerDeadlineMs`. The margins stay the chart's.
  *
  * The grace is budgeted at no less than core's production default: the value read here is resolved
  * in THIS process's environment, and an `x deploy` run under `NODE_ENV=development` resolves the
@@ -24,6 +25,10 @@ export function helmDrainOverrides(drain: Partial<DrainConfig> | undefined): rea
   if (drain?.deadlineMs !== undefined) {
     out.push('--set', `drain.deadlineSeconds=${seconds(drain.deadlineMs)}`);
   }
+  // The worker role's own budget: the chart sizes only the worker's grace period from it.
+  if (drain?.workerDeadlineMs !== undefined) {
+    out.push('--set', `drain.workerDeadlineSeconds=${seconds(drain.workerDeadlineMs)}`);
+  }
   if (drain === undefined) return out;
   const grace = Math.max(drain.readinessGraceMs ?? 0, READINESS_GRACE_DEFAULT_MS);
   out.push('--set', `drain.readinessGraceSeconds=${seconds(grace)}`);

package/src/cmd-docs.ts

@@ -144,7 +144,7 @@ export const docsCommand: CliCommand = {
     }
 
     const entries = await scanInstalledDocs(scope);
-    // `x jobs ls --limit`'s reader, and its `command` parameter exists for exactly this second
+    // `x jobs list --limit`'s reader, and its `command` parameter exists for exactly this second
     // caller. A local `Number.parseInt` accepted `--limit 1e9` as 1 and answered with one match,
     // and fell silently through to the default for `abc`, `0` and `-3` — a bound other than the one
     // typed, from the same binary that refuses all four one command over.

package/src/cmd-jobs-spec.ts

@@ -3,12 +3,16 @@
 
 import type { CommandSpec } from './parse';
 
+/**
+ * One verb each, the same across every `x` registry (#709): `list`, `show <one>`, `delete`. No
+ * `ls`/`rm` aliases — two spellings of one verb is the ambiguity axiom 1 forbids.
+ */
 export const JOBS_SUBCOMMANDS = [
-  'ls',
+  'list',
   'show',
   'retry',
   'cancel',
-  'rm',
+  'delete',
   'promote',
   'pause',
   'resume',
@@ -20,13 +24,13 @@ export const jobsSpec: CommandSpec = {
   // Never ENDING in "(planned)": that suffix is how `x help` and the planned-table tests tell a
   // planned COMMAND from a shipped one, and `x jobs` ships — only its `drain` does not.
   summary:
-    'list, show, retry, cancel, remove and promote jobs; pause and resume a queue (drain is planned)',
+    'list, show, retry, cancel, delete and promote jobs; pause and resume a queue (drain is planned)',
   usage:
-    'x jobs [ls|show <id>|retry <id>|cancel <id>|rm <id>|promote <id>|pause <queue>|resume <queue>|drain] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--json]',
+    'x jobs [list|show <id>|retry <id>|cancel <id>|delete <id>|promote <id>|pause <queue>|resume <queue>|drain] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--json]',
   requiresApp: true,
   subcommands: JOBS_SUBCOMMANDS,
   // The bare `x jobs` lists; it never retries, cancels or drains anything.
-  defaultSubcommand: 'ls',
+  defaultSubcommand: 'list',
   flags: [
     { name: 'queue', type: 'string', summary: 'filter by queue name' },
     { name: 'state', type: 'string', summary: 'filter by job state' },
@@ -35,8 +39,8 @@ export const jobsSpec: CommandSpec = {
     {
       name: 'after',
       type: 'string',
-      summary: 'ls: the next page — the cursor the previous page printed',
-      subcommands: ['ls'],
+      summary: 'list: the next page — the cursor the previous page printed',
+      subcommands: ['list'],
     },
     // Each of these is read by ONE subcommand — `retryJob`, `cancelJob` — and says so in its own
     // summary. The scope is what makes the parser refuse it anywhere else instead

package/src/cmd-jobs.ts

@@ -1,4 +1,4 @@
-// `x jobs ls|show|retry|cancel|rm|promote|pause|resume` — introspect and recover the job queue,
+// `x jobs list|show|retry|cancel|delete|promote|pause|resume` — introspect and recover the job queue,
 // bound to `@ultimat3/jobs`'s own introspection so the CLI, `/_x` and MCP report identically;
 // `drain` is planned (`cmd-planned.ts`): Postgres is the one durable driver. CLI wiring only:
 // the driver-injected logic is `jobs-report.ts`, the `--json` shapes `jobs-json.ts`, the table
@@ -56,7 +56,7 @@ function requireIdPositional(ctx: CommandContext, sub: string, driver: JobDriver
     throw new MissingPositionalError({
       command: `jobs ${sub}`,
       positional: 'id',
-      example: 'x jobs ls --json',
+      example: 'x jobs list --json',
     });
   }
   if (!JOB_ID.test(id)) throw new JobUnknownError({ id, driver: driver.name });
@@ -86,11 +86,11 @@ function refuseOversizedPage(limit: string | undefined): void {
     command: 'jobs',
     reason: `one page holds at most ${MAX_JOB_PAGE} jobs`,
     // The bound is the queue's own constant, screened like any value spliced into a command.
-    fix: `x jobs ls --limit ${renderFixShellArg(String(MAX_JOB_PAGE), '200')} --json   # then pass its data.nextCursor as --after while data.hasMore is true`,
+    fix: `x jobs list --limit ${renderFixShellArg(String(MAX_JOB_PAGE), '200')} --json   # then pass its data.nextCursor as --after while data.hasMore is true`,
   });
 }
 
-async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+async function runList(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
   const limit = flagString(ctx.args, 'limit');
   refuseOversizedPage(limit);
   const result = await listJobs(driver, {
@@ -208,8 +208,8 @@ async function runCancel(driver: JobDriver, ctx: CommandContext): Promise<Comman
 }
 
 /** Exit 0 means the row is gone. An id nobody queued is `X_JOB_UNKNOWN`; a running one refuses. */
-async function runRm(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const id = requireIdPositional(ctx, 'rm', driver);
+async function runDelete(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+  const id = requireIdPositional(ctx, 'delete', driver);
   const removed = await removeJob(driver, id);
   if (removed === undefined) throw new JobUnknownError({ id, driver: driver.name });
   return {
@@ -249,14 +249,14 @@ async function runPause(
   };
 }
 
-/** The subcommands that answer a `JobTrace`. `ls`, `rm`, `promote` and the rest read rows only. */
+/** The subcommands that answer a `JobTrace`. `list`, `delete`, `promote` and the rest read rows only. */
 const TRACE_SUBCOMMANDS: ReadonlySet<string> = new Set(['show', 'retry', 'cancel']);
 
 export const jobsCommand: CliCommand = {
   spec: jobsSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('jobs', ctx.cwd).dir;
-    const sub = ctx.args.subcommand ?? 'ls';
+    const sub = ctx.args.subcommand ?? 'list';
     // BEFORE `withJobDriver`, which boots the source queue: the answer needs no server, so a box
     // whose database is down gets it rather than the boot failure of a queue never to be used —
     // and nothing is leased. 24.x's `--to`/`--dry-run` are deleted, so the parser refuses them
@@ -272,10 +272,10 @@ export const jobsCommand: CliCommand = {
       if (sub === 'show') return runShow(driver, ctx);
       if (sub === 'retry') return runRetry(driver, ctx);
       if (sub === 'cancel') return runCancel(driver, ctx);
-      if (sub === 'rm') return runRm(driver, ctx);
+      if (sub === 'delete') return runDelete(driver, ctx);
       if (sub === 'promote') return runPromote(driver, ctx);
       if (sub === 'pause' || sub === 'resume') return runPause(driver, ctx, sub);
-      return runLs(driver, ctx);
+      return runList(driver, ctx);
     });
   },
 };

package/src/cmd-planned.ts

@@ -33,8 +33,8 @@ export const PLANNED_COMMANDS: readonly PlannedCommand[] = [
   {
     name: 'branch',
     summary: 'copy-on-write branch environments with a preview URL',
-    usage: 'x branch [<name>|rm <name>] [--json]',
-    fix: 'x db branch ls --json   # the database half: ls, create <name>, drop <name>',
+    usage: 'x branch [<name>|delete <name>] [--json]',
+    fix: 'x db branch list --json   # the database half: list, create <name>, delete <name>',
   },
   {
     name: 'status',
@@ -134,7 +134,7 @@ export const PLANNED_SUBCOMMANDS: readonly PlannedSubcommand[] = [
   {
     command: 'jobs',
     subcommand: 'drain',
-    fix: 'x jobs ls --json   # the queue as it stands; Postgres is the only durable driver, so there is nowhere to drain to',
+    fix: 'x jobs list --json   # the queue as it stands; Postgres is the only durable driver, so there is nowhere to drain to',
   },
 ];
 

package/src/cmd-registries-spec.ts

@@ -7,8 +7,8 @@ import type { CommandSpec } from './parse';
 export const actionsSpec: CommandSpec = {
   name: 'actions',
   summary: 'the action registry: input/output schema, policy, tags, MCP exposure',
-  usage: 'x actions [list|describe <name>] [--json]',
-  subcommands: ['list', 'describe'],
+  usage: 'x actions [list|show <name>] [--json]',
+  subcommands: ['list', 'show'],
   defaultSubcommand: 'list',
   requiresApp: true,
 };
@@ -16,8 +16,8 @@ export const actionsSpec: CommandSpec = {
 export const queriesSpec: CommandSpec = {
   name: 'queries',
   summary: 'the query registry: schema, policy, live, cache tags',
-  usage: 'x queries [list|describe <name>] [--json]',
-  subcommands: ['list', 'describe'],
+  usage: 'x queries [list|show <name>] [--json]',
+  subcommands: ['list', 'show'],
   defaultSubcommand: 'list',
   requiresApp: true,
 };
@@ -25,8 +25,8 @@ export const queriesSpec: CommandSpec = {
 export const entitiesSpec: CommandSpec = {
   name: 'entities',
   summary: 'the entity registry: columns, invariants, indexes, tenancy',
-  usage: 'x entities [list|describe <name>] [--json]',
-  subcommands: ['list', 'describe'],
+  usage: 'x entities [list|show <name>] [--json]',
+  subcommands: ['list', 'show'],
   defaultSubcommand: 'list',
   requiresApp: true,
 };

package/src/cmd-registries.ts

@@ -2,7 +2,7 @@
 // Replaces grepping a source tree, which is what an agent does when the framework has no answer
 // to "what actions/queries/entities exist". One table, one generic command body: the three
 // commands differ only in which registry they read, a row's columns, and (for a query only) the
-// one extra field `describe` surfaces that its descriptor does not already carry.
+// one extra field `show` surfaces that its descriptor does not already carry.
 
 import type { ActionDescriptor, AnyAction } from '@ultimat3/action';
 import { describeActions, getAction, jsonSchemaOf } from '@ultimat3/action';
@@ -35,7 +35,7 @@ const detailLines = (payload: Readonly<Record<string, JsonValue>>): readonly str
   Object.entries(payload).map(([key, value]) => `  ${key}: ${formatValue(value)}`);
 
 /**
- * One config per registry: how `list` renders a row, and what `describe` adds beyond the
+ * One config per registry: how `list` renders a row, and what `show` adds beyond the
  * descriptor itself — only a query's input schema does (`QUERIES.extra`); `ActionDescriptor`
  * already carries `input`/`output`, and an entity has no invocation shape to surface.
  */
@@ -116,7 +116,7 @@ function listResult<D extends { readonly name: string }, Raw extends { describe(
   };
 }
 
-function describeResult<D extends { readonly name: string }, Raw extends { describe(): D }>(
+function showResult<D extends { readonly name: string }, Raw extends { describe(): D }>(
   kind: RegistryKind<D, Raw>,
   ctx: CommandContext,
   findings: readonly Finding[],
@@ -126,7 +126,7 @@ function describeResult<D extends { readonly name: string }, Raw extends { descr
     // A positional, so `MissingPositionalError` — `--name on "x actions"` named a flag no registry
     // command declares, and reading it as one is a second refusal for the first one's advice.
     throw new MissingPositionalError({
-      command: `${kind.kind} describe`,
+      command: `${kind.kind} show`,
       positional: 'name',
       example: `x ${kind.kind} list --json`,
     });
@@ -158,8 +158,8 @@ async function runRegistryCommand<
 >(kind: RegistryKind<D, Raw>, ctx: CommandContext): Promise<CommandResult> {
   const root = requireAppRoot(kind.kind, ctx.cwd).dir;
   const { findings } = await loadApp(root);
-  return ctx.args.subcommand === 'describe'
-    ? describeResult(kind, ctx, findings)
+  return ctx.args.subcommand === 'show'
+    ? showResult(kind, ctx, findings)
     : listResult(kind, findings);
 }
 

package/src/cmd-tasks.ts

@@ -141,8 +141,8 @@ function requireHandle(ctx: CommandContext): TaskHandle {
   const suggestion = nearestName(name, known);
   throw new DeclarationUnknownError(
     suggestion === undefined
-      ? { kind: 'tasks', singular: 'task', name, known, verb: 'show' }
-      : { kind: 'tasks', singular: 'task', name, known, suggestion, verb: 'show' },
+      ? { kind: 'tasks', singular: 'task', name, known }
+      : { kind: 'tasks', singular: 'task', name, known, suggestion },
   );
 }
 

package/src/db-branch.ts

@@ -27,7 +27,7 @@ import {
  * `reap` is deliberately absent: a nightly sweep is a `task` (`reapBranches` from `@ultimat3/db`),
  * and a CLI verb for it would be a second path to one job with a max-age nobody can default.
  */
-export const BRANCH_SUBCOMMANDS = ['ls', 'create', 'drop'] as const;
+export const BRANCH_SUBCOMMANDS = ['list', 'create', 'delete'] as const;
 
 export type BranchSubcommand = (typeof BRANCH_SUBCOMMANDS)[number];
 
@@ -91,7 +91,7 @@ export function branchDatabaseName(source: string, branch: string): string {
  * `db.migrate` is aimed at a private database from a URL alone, with no connection to ask
  * `current_database()` — so "a branch of somebody" is the only question it can pose, and the
  * answer it wants for `analytics_branch_feat` is still "not the shared database". Anything holding
- * a client asks `branchNameIn` instead, which is the question `ls` and `drop` need.
+ * a client asks `branchNameIn` instead, which is the question `list` and `delete` need.
  */
 export const branchNameOf = (database: string): string | null =>
   /_branch_(.+)$/.exec(database)?.[1] ?? null;
@@ -112,7 +112,7 @@ export function branchNameIn(source: string, database: string): string | null {
 /**
  * The embedded peer: `branchPglite` copies `<dir>` to `<dir>-<name>`, so the branch name is the
  * suffix. `pgliteBranchDir` is the forward rule and this is its inverse — written once, because
- * `x db branch ls` and the MCP host's branch check must agree about what a branch directory is.
+ * `x db branch list` and the MCP host's branch check must agree about what a branch directory is.
  */
 export function pgliteBranchName(dir: string, source: string): string | null {
   return dir.startsWith(`${source}-`) ? dir.slice(source.length + 1) : null;
@@ -213,7 +213,7 @@ async function branchesOf(client: DbClient, source: string): Promise<readonly Br
 /**
  * Only databases carrying `createBranch`'s own marker comment, and only branches of the database
  * this session is connected to. A database this listing does not name is one `drop` may not touch,
- * which is what makes "you may only drop what `ls` shows" a guard rather than a courtesy — and a
+ * which is what makes "you may only delete what `list` shows" a guard rather than a courtesy — and a
  * row belonging to another app on the same server made that guard answer for a database it had
  * never seen.
  */
@@ -224,7 +224,7 @@ export async function listExternalBranches(client: DbClient): Promise<readonly B
 /**
  * Through `createBranch`, never a hand-written `CREATE DATABASE`: it validates the name, refuses a
  * database that already exists with `X_BRANCH_EXISTS`, and writes the marker comment that makes
- * the clone visible to `ls`. The CLI shelled out to `psql` until now and wrote no marker at all,
+ * the clone visible to `list`. The CLI shelled out to `psql` until now and wrote no marker at all,
  * so every branch it made was invisible to the only lister the framework has.
  */
 export async function createExternalBranch(client: DbClient, branch: string): Promise<BranchRow> {
@@ -232,7 +232,7 @@ export async function createExternalBranch(client: DbClient, branch: string): Pr
   const database = branchDatabaseName(source, branch);
   const info = await createBranch(database, { client, base: source });
   return {
-    // The name `ls` will show for it, derived the way `ls` derives one — a create that reported a
+    // The name `list` will show for it, derived the way `list` derives one — a create that reported a
     // name the listing then spells differently is a `drop` the caller has to guess at.
     name: branchNameIn(source, database) ?? database,
     location: database,

package/src/db-finding.ts

@@ -10,7 +10,7 @@ import { findingFrom, isUltimateErrorShape } from './output';
 /**
  * The engine names its own failures — `X_MIGRATION_CONFLICT` carries the ledger row that disagrees,
  * `X_MIGRATION_IRREVERSIBLE` carries the exact `--allow-destructive` line to rerun, and
- * `X_BRANCH_EXISTS` carries the `x db branch drop` that clears it — so those reach the caller
+ * `X_BRANCH_EXISTS` carries the `x db branch delete` that clears it — so those reach the caller
  * verbatim. `X_DB_GEN_FAILED` / `X_DB_MIGRATE_FAILED` / `X_DB_BRANCH_FAILED` are what is left: the
  * step failed for a reason no framework error claimed, and the raw message is all there is.
  */

package/src/dev-restart-retire.ts

@@ -4,7 +4,7 @@
 // login) ran twice. The worker is retired first — `stop()` claims nothing and aborts nothing — and
 // only then is the drain asked to release the port, the lock and the embedded database.
 
-import { drain, logger, renderThrowable } from '@ultimat3/core';
+import { drain, logger, markRetiring, renderThrowable } from '@ultimat3/core';
 import type { Worker } from '@ultimat3/jobs';
 import { msg } from './messages';
 import { writeErrorLine } from './write-line';
@@ -32,6 +32,8 @@ export async function retireThenDrain(
   worker: RetiringWorker | null,
   deps: RetireDeps = DEFAULT_DEPS,
 ): Promise<void> {
+  // The same retire the production SIGUSR2 is (`serve-retire.ts`), so the app reads it the same way.
+  markRetiring();
   try {
     if (worker !== null) {
       const { inFlight } = await worker.stats();

package/src/document-styles.ts

@@ -30,14 +30,12 @@ export interface SurfaceDocument {
 }
 
 /**
- * Every surface that renders a document, with the CSS one would carry. `api/` is excluded because
- * it emits no document at all — a surface with nothing to style is not a surface missing its
- * tokens. Read from render's own registry, filled when the CLI loaded the app: a second walk of
+ * Every surface that renders a document, with the CSS one would carry — a route lives on `site/`
+ * or `app/` only, so `api/` (no document) never appears. Read from render's own registry, filled when the CLI loaded the app: a second walk of
  * the app's stylesheets here would be a second answer to "what does this document contain".
  */
 export function documentSurfaces(): readonly SurfaceDocument[] {
   const surfaces = new Set(routeEntries().map((entry) => entry.surface));
-  surfaces.delete('api');
   return [...surfaces]
     .sort()
     .map((surface) => ({ surface, css: stylesFor(surface) }) satisfies SurfaceDocument);

package/src/error-contract.ts

@@ -32,7 +32,7 @@ export const BANNED_PHRASES: readonly RegExp[] = [
 /**
  * What makes a fix actionable as written: the `x` CLI, a tool the machine already has, a call the
  * reader can paste, or a file they can open. A banned phrase is only a failure without one of
- * these — "check the gateway, then: x actions describe posts.publish --json" names the observation
+ * these — "check the gateway, then: x actions show posts.publish --json" names the observation
  * *and* the command, which is the shape the contract wants.
  */
 export const COMMAND_TOKENS: readonly RegExp[] = [

package/src/errors.ts

@@ -248,7 +248,7 @@ export class ErrorCodeUnknownError extends UltimateError {
 }
 
 /**
- * `x actions|queries|entities describe <name>` named a declaration the registries do not hold —
+ * `x actions|queries|entities|tasks show <name>` named a declaration the registries do not hold —
  * a typo, or a module that never imported. `known` is the count, not the list: a 200-action app
  * would bury the fix line under names nobody asked for, and `list` is one command away.
  */
@@ -259,7 +259,7 @@ export class DeclarationUnknownError extends UltimateError {
     name: string;
     known: readonly string[];
     suggestion?: string;
-    /** The subcommand that takes one name. `describe` for the registries, `show` for `x tasks`. */
+    /** The subcommand that takes one name: `show` (#709), or `explain` for `x policy` — the "why". */
     verb?: string;
   }) {
     super({
@@ -268,7 +268,7 @@ export class DeclarationUnknownError extends UltimateError {
       fix:
         input.suggestion === undefined
           ? `x ${input.kind} list --json`
-          : `x ${input.kind} ${input.verb ?? 'describe'} ${input.suggestion}`,
+          : `x ${input.kind} ${input.verb ?? 'show'} ${input.suggestion}`,
     });
   }
 }
@@ -279,7 +279,7 @@ export class JobUnknownError extends UltimateError {
     super({
       code: 'X_JOB_UNKNOWN',
       cause: `the "${input.driver}" queue holds no job with id "${input.id}"`,
-      fix: 'x jobs ls --json',
+      fix: 'x jobs list --json',
     });
   }
 }

package/src/fix-command.ts

@@ -27,7 +27,7 @@ import { GLOBAL_FLAGS } from './parse';
 // slot where the reader has nothing to substitute, so `x db branch <name>` — two shipped fix lines
 // in `@ultimat3/mcp` — is `X_CLI_UNKNOWN_COMMAND` when run and resolved clean while a placeholder
 // was invisible to the reader. Second and fourth slots are open positionals (`x new my-app`,
-// `x db branch drop <name>`), where a placeholder is exactly right.
+// `x db branch delete <name>`), where a placeholder is exactly right.
 // A `:` is part of a word only when a letter follows it, which is what separates the shipped
 // positional `admin:page` from prose that ends a citation with a colon (`x verify: the gate`).
 // Read without it, `x g admin:page` cites `x g admin` — a positional the CLI does not ship —

package/src/jobs-report.ts

@@ -1,4 +1,4 @@
-// Pure, driver-injected job operations behind `x jobs`: flag parsing, plus ls / show / retry. No
+// Pure, driver-injected job operations behind `x jobs`: flag parsing, plus list / show / retry. No
 // CLI parsing, no process I/O, no rendering — a test drives every path with `memoryJobDriver()`
 // alone. The `--json` shapes are `jobs-json.ts`, the table `jobs-table.ts`.
 
@@ -61,7 +61,7 @@ export function parseLimitFlag(value: string | undefined, command = 'jobs'): num
   return limit;
 }
 
-// ── ls ────────────────────────────────────────────────────────────────────
+// ── list ──────────────────────────────────────────────────────────────────
 
 export interface JobsListFilter {
   readonly queue?: string | undefined;
@@ -105,7 +105,7 @@ async function jobPage(driver: JobDriver, filter: JobFilter): Promise<Page<JobRe
  * `--state ready` filter (or the default 100-row cap) pushes out of view is the exact failure
  * mode this command exists to prevent.
  *
- * Backfills are read `running` only. `x jobs ls` is a LIVE view of the queue — a pass that
+ * Backfills are read `running` only. `x jobs list` is a LIVE view of the queue — a pass that
  * finished last week is history, and `x db backfill --list` is where that question is asked and
  * answered with the whole ledger. A driver with no ledger answers `[]` rather than throwing, so
  * the queue view never fails over a fact nobody asked about.

package/src/jobs-table.ts

@@ -1,4 +1,4 @@
-// The `x jobs ls` terminal table, and nothing else. Split out of `jobs-report.ts` so that
+// The `x jobs list` terminal table, and nothing else. Split out of `jobs-report.ts` so that
 // deciding how a value LOOKS lives apart from deciding what the queue DOES: a rendering rule
 // (column order, padding, the run-at unit) is reviewed here, once, with no queue logic around it.
 

package/src/live-routes.ts

@@ -183,7 +183,6 @@ export async function liveRouteGaps(
   const reported = new Set<string>();
   const gaps: LiveRouteGap[] = [];
   for (const entry of entries) {
-    if (entry.surface === 'api') continue;
     const never = entry.config.hydrate === 'never';
     for (const read of await browserOnlyReads(root, entry.file)) {
       if (reported.has(read.at) || (!never && inBrowser.has(read.at))) continue;

package/src/mcp-db-target.ts

@@ -56,7 +56,7 @@ const isProduction = (env: Env): boolean => {
 /**
  * `x db branch create <name>` names an external clone `<source>_branch_<name>`. Both readings come
  * from `db-branch.ts` — the module that also WRITES those names — because a target that disagrees
- * with `x db branch ls` about what a branch is would let `db.migrate` run against a shared
+ * with `x db branch list` about what a branch is would let `db.migrate` run against a shared
  * database on the strength of a naming rule one of the two had drifted away from.
  */
 function postgresBranch(url: string): string | null {

package/src/mcp-errors.ts

@@ -60,7 +60,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_APP_PACKAGE_INVALID: 'bun pm pkg set name=my-app version=0.1.0',
   X_ERROR_CODE_UNKNOWN: 'x errors list --json',
   X_DECLARATION_UNKNOWN: 'x actions list --json',
-  X_JOB_UNKNOWN: 'x jobs ls --json',
+  X_JOB_UNKNOWN: 'x jobs list --json',
   X_FIX_TARGET_UNKNOWN: 'x fix boundary apps/web/site/page.tsx --json',
   X_ERROR_FIX_INVALID: 'x verify --json   # the finding names the file, the line and the fix text',
   X_ERROR_FIX_PATH_MISSING:
@@ -213,7 +213,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_QUERY_SUBSCRIBES_UNKNOWN:
     'x db gen "retry after fixing subscribes" --json   # first edit subscribes: on the query the cause names',
   X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
-  X_DB_BRANCH_FAILED: 'x db branch ls --json',
+  X_DB_BRANCH_FAILED: 'x db branch list --json',
   X_DB_STUDIO_FAILED: 'x doctor --json',
   // Runnable first, the narrowing behind a `#`, exactly as X_CLI_UNKNOWN_COMMAND above: naming
   // the tier IS the consent, and which seed to consent to is the one thing this table cannot

package/src/messages.ts

@@ -46,7 +46,7 @@ const CATALOG = {
   'cli.db.branch.failed': 'branch command failed',
   'cli.db.branch.listed': '{count} branch(es) of this database',
   'cli.db.branch.none': 'this database has no branch',
-  /** The empty cell in an `x db branch ls` column — a value, not a column key. */
+  /** The empty cell in an `x db branch list` column — a value, not a column key. */
   'cli.db.branch.unknown': '-',
   'cli.db.gen.failed': 'migration not generated',
   'cli.db.gen.unchanged': 'entities and migrations agree — nothing to generate',
@@ -149,7 +149,7 @@ const CATALOG = {
   'cli.jobs.depth':
     '{ready} ready · {running} running · {delayed} delayed · {dead} dead across {queues} queue(s)',
   'cli.jobs.listed': '{count} job(s)',
-  'cli.jobs.nextPage': 'more — next page: x jobs ls --after {cursor}',
+  'cli.jobs.nextPage': 'more — next page: x jobs list --after {cursor}',
   'cli.jobs.noError': 'no error recorded',
   'cli.jobs.paused': 'queue {queue} paused — no worker claims from it; enqueues still land',
   'cli.jobs.pausedQueues': 'paused queue(s): {queues}',

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/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/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/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/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: