@ultimat3/cli 25.1.0 → 26.0.0

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/doctor-guards.ts

@@ -1,12 +1,14 @@
-// `x doctor`'s guard listing: the guards the framework ships that this app's `guards/` does not
-// hold, each with the command that adds it. A LISTING, never a finding: every shipped guard says
-// "delete this file to drop the rule", so an app without one may have decided — and a red
-// `x doctor` over a decision would be the framework overruling the convention it handed over.
+// `x doctor`'s guard listing: the shipped guards this app's `guards/` does not hold, and the ones
+// it holds in a form that is not the current template — each with the command that writes it. A
+// LISTING, never a finding: every shipped guard is the app's copy ("delete this file to drop the
+// rule"), so a missing or edited one may be a decision the framework must not overrule.
 
+// why: Bun exposes no path-join primitive; Bun.file takes one already joined.
+import { join } from 'node:path';
 import { GUARD_DIR, guardPaths } from './guards';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
-import { SHIPPED_GUARD_NAMES } from './templates/scaffold-guards';
+import { SHIPPED_GUARD_NAMES, shippedGuardSource } from './templates/scaffold-guards';
 
 export interface MissingGuard {
   readonly name: string;
@@ -23,9 +25,51 @@ export function missingShippedGuards(present: readonly string[]): readonly Missi
   }));
 }
 
+export interface DifferingGuard {
+  readonly name: string;
+  /** Rewrites the guard and its test from the current template. Review the diff, then keep it. */
+  readonly refresh: string;
+}
+
+/** One line of the listing: a shipped guard the app lacks, or holds in another form. */
+export type GuardListingEntry = MissingGuard | DifferingGuard;
+
+/** A guard file as the app holds it, path relative to the app root. */
+export interface HeldGuard {
+  readonly path: string;
+  readonly source: string;
+}
+
+/** A checkout on Windows may write CRLF; the rule is the same text either way. */
+const sameText = (a: string, b: string): boolean =>
+  a.replaceAll('\r\n', '\n') === b.replaceAll('\r\n', '\n');
+
+/**
+ * The rule, pure: which held guards carry a shipped name and are not that guard's current
+ * template. A guard with a name the framework never shipped is the app's own, and has no template.
+ */
+export function differingShippedGuards(held: readonly HeldGuard[]): readonly DifferingGuard[] {
+  const differing: DifferingGuard[] = [];
+  for (const { path, source } of held) {
+    const name = path.slice(`${GUARD_DIR}/`.length).replace(/\.tsx?$/, '');
+    const template = shippedGuardSource(name);
+    if (template === undefined || sameText(source, template)) continue;
+    differing.push({ name, refresh: `x g guard ${name} --force` });
+  }
+  return differing;
+}
+
 /** The I/O half: the same enumeration the `boundaries` step runs, so the two cannot disagree. */
-export async function shippedGuardsProbe(root: string): Promise<readonly MissingGuard[]> {
-  return missingShippedGuards(await guardPaths(root));
+export async function shippedGuardsProbe(root: string): Promise<readonly GuardListingEntry[]> {
+  const paths = await guardPaths(root);
+  const held = await Promise.all(
+    paths.map(async (path) => ({ path, source: await Bun.file(join(root, path)).text() })),
+  );
+  const entries: GuardListingEntry[] = [
+    ...missingShippedGuards(paths),
+    ...differingShippedGuards(held),
+  ];
+  return entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
 
 /**
@@ -34,21 +78,32 @@ export async function shippedGuardsProbe(root: string): Promise<readonly Missing
  */
 export function withGuardListing(
   result: CommandResult,
-  missing: readonly MissingGuard[],
+  entries: readonly GuardListingEntry[],
 ): CommandResult {
   const data = typeof result.data === 'object' && result.data !== null ? result.data : {};
-  const listed: JsonValue = missing.map(({ name, add }) => ({ name, add }));
+  const missing = entries.filter((entry): entry is MissingGuard => 'add' in entry);
+  const differs = entries.filter((entry): entry is DifferingGuard => 'refresh' in entry);
+  const lines = [
+    ...(missing.length === 0
+      ? []
+      : [
+          msg('cli.doctor.guards', { count: missing.length }),
+          ...missing.map(({ add }) => `  ${add}`),
+        ]),
+    ...(differs.length === 0
+      ? []
+      : [
+          msg('cli.doctor.guardsDiffer', { count: differs.length }),
+          ...differs.map(({ refresh }) => `  ${refresh}`),
+        ]),
+  ];
+  const guards: JsonValue = {
+    missing: missing.map(({ name, add }) => ({ name, add })),
+    differs: differs.map(({ name, refresh }) => ({ name, refresh })),
+  };
   return {
     ...result,
-    data: { ...(data as Record<string, JsonValue>), guards: { missing: listed } },
-    ...(missing.length === 0
-      ? {}
-      : {
-          lines: [
-            ...(result.lines ?? []),
-            msg('cli.doctor.guards', { count: missing.length }),
-            ...missing.map(({ add }) => `  ${add}`),
-          ],
-        }),
+    data: { ...(data as Record<string, JsonValue>), guards },
+    ...(lines.length === 0 ? {} : { lines: [...(result.lines ?? []), ...lines] }),
   };
 }

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/index.ts

@@ -31,12 +31,6 @@ export { GENERATORS, generate, writeFiles } from './cmd-generate';
 export { JOBS_SUBCOMMANDS } from './cmd-jobs';
 export { newCommand, planNewApp, writeNewApp } from './cmd-new';
 export { PLANNED_COMMANDS, PLANNED_SUBCOMMANDS, plannedSubcommand } from './cmd-planned';
-// `shotCommand`, `prCommand` and `ciCommand` are deliberately NOT re-exported here. They reach
-// `x` through `registry.ts`, which is the only thing that makes a command exist — and the barrel
-// is the surface an APP imports. Exporting them would put the browser driver and the GitHub client
-// in the module graph of every app that imports `@ultimat3/cli`, for tools it never calls. The app
-// path does not pay for the tool path.
-export { renderRouteTable } from './cmd-routes';
 export { runVerify, VERIFY_STEPS, verifyCommand, verifyStepNames } from './cmd-verify';
 export type { CliCommand } from './command';
 export { failed, ok } from './command';
@@ -130,6 +124,12 @@ export { loadPwaArtifacts } from './pwa-artifacts';
 export { COMMANDS, cliVersion, SPECS } from './registry';
 export type { RunningRoles, WebBinding } from './role-start';
 export { DEV_BINDING, DEV_ROLES, startRoles } from './role-start';
+// `shotCommand`, `prCommand` and `ciCommand` are deliberately NOT re-exported here. They reach
+// `x` through `registry.ts`, which is the only thing that makes a command exist — and the barrel
+// is the surface an APP imports. Exporting them would put the browser driver and the GitHub client
+// in the module graph of every app that imports `@ultimat3/cli`, for tools it never calls. The app
+// path does not pay for the tool path.
+export { renderRouteTable } from './route-table';
 export { assetRoutes, MEDIA_BASE_PATH } from './runtime-assets';
 export { resolveServices } from './runtime-bindings';
 export { devHooks } from './runtime-hooks';

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/mcp-host.ts

@@ -36,7 +36,6 @@ import type {
   VerifyStep,
 } from '@ultimat3/mcp';
 import { DEV_SCOPES, devHost, devMcpServer, frameworkIntrospection } from '@ultimat3/mcp';
-import { describePages } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { appManifest, policyFacts } from './app-manifest';
 import { runVerify, VERIFY_STEPS } from './cmd-verify';
@@ -50,6 +49,7 @@ import { testRunOf } from './mcp-test-run';
 import { type UiCapabilities, uiCapabilities } from './mcp-ui';
 import { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
+import { plainAppRoutes, routeRows } from './route-table';
 import type { DevServices, Env } from './runtime-bindings';
 import { resolveServices } from './runtime-bindings';
 import type { RunningServices } from './runtime-services';
@@ -346,10 +346,12 @@ export async function createDevMcpServer(input: DevHostInput): Promise<CliMcpSer
   // scratch boot re-imported the app after declaring — rendered. Idempotent; a set key stays.
   declareDevEnvironment(input.env);
   await Promise.all([loadApp(input.root), loadCodeFixes()]);
+  // The plain `runtime.ts` routes, read once: `routes.list` answers the table `x routes` prints.
+  const plain = await plainAppRoutes(input.root);
   const lazy = lazyServices(input);
   const ui = uiCapabilities({ root: input.root, env: input.env });
   const introspection = frameworkIntrospection({
-    routes: () => describePages(),
+    routes: () => routeRows(plain).map((row) => row.json),
     policies: () => policyFacts(),
   });
   const server = devMcpServer({ host: devHost(introspection, capabilities(input, lazy, ui)) });

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',
@@ -102,6 +102,8 @@ const CATALOG = {
   'cli.doctor.findings': '{count} finding(s)',
   'cli.doctor.guards':
     '{count} shipped guard(s) this app does not hold — each line adds one, then x verify reports what it finds:',
+  'cli.doctor.guardsDiffer':
+    '{count} shipped guard(s) differ from the current template — an older copy or your own edit; each line rewrites one and its test, review the diff before keeping it:',
   // `x doctor`'s other listing: what the coverage floor in x.verify.json does not see, and why.
   'cli.doctor.coverageExclude':
     '{count} path(s) x.verify.json excludes from the coverage floor — each with the reason it gives:',
@@ -147,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/route-table.ts

@@ -0,0 +1,113 @@
+// The served route table, as rows: the pages (`describePages()`), then every API route — the
+// action and query projections `apiRoutes()` builds for `x dev` and the container, and the plain
+// routes of `apps/<app>/runtime.ts`. `x routes` and the MCP dev tool `routes.list` both read it.
+
+import type { Route } from '@ultimat3/http';
+import type { RouteDescriptor, Surface } from '@ultimat3/render';
+import { describePages } from '@ultimat3/render';
+import { apiRoutes } from './api-routes';
+import { loadAppRuntime } from './app-runtime';
+import type { JsonValue } from './output';
+
+/** One printed and one JSON row per served route: a page, a mounted page, or an API route. */
+export interface RouteRow {
+  readonly surface: Surface;
+  readonly path: string;
+  readonly cells: readonly string[];
+  readonly json: JsonValue;
+}
+
+/**
+ * Where a route comes from. A file route names its file; a MOUNTED one names the call that
+ * mounted it and every permission that gates it — there is no `page.tsx` to name, and printing the
+ * package would send a reader looking for a route file inside `node_modules`.
+ */
+const declaredBy = (route: RouteDescriptor): string =>
+  route.mount === undefined
+    ? route.file
+    : `${route.mount.by}() · ${route.mount.permissions.join(' + ')}`;
+
+const pageRow = (route: RouteDescriptor): RouteRow => ({
+  surface: route.surface,
+  path: route.path,
+  cells: [
+    'GET',
+    route.path,
+    route.surface,
+    route.mode,
+    route.hydrate,
+    route.offline,
+    declaredBy(route),
+  ],
+  json: {
+    method: 'GET',
+    path: route.path,
+    surface: route.surface,
+    file: route.file,
+    render: route.mode,
+    hydrate: route.hydrate,
+    offline: route.offline,
+    budget: { js: route.budgetJs },
+    // Absent on a file route, never `null`: only a mounted route has the fact.
+    ...(route.mount === undefined
+      ? {}
+      : { mount: { by: route.mount.by, permissions: [...route.mount.permissions] } }),
+  },
+});
+
+/**
+ * An action or query projection, or a plain `runtime.ts` route (`primitive: null`). It renders
+ * nothing, so the page columns read `-`; where a page names its file this names what declared it
+ * and the permission its policy asks for.
+ */
+const apiRow = (route: Route): RouteRow => {
+  const primitive = route.meta.primitive ?? null;
+  const policy = route.meta.policy ?? null;
+  const from = primitive === null ? 'runtime.ts routes' : primitive;
+  const by = `${from} ${route.meta.name}${policy === null ? '' : ` · ${policy}`}`;
+  return {
+    surface: 'api',
+    path: route.path,
+    cells: [route.method, route.path, 'api', '-', '-', '-', by],
+    json: {
+      method: route.method,
+      path: route.path,
+      surface: 'api',
+      primitive,
+      name: route.meta.name,
+      auth: route.meta.auth,
+      policy,
+    },
+  };
+};
+
+const byPath = (a: RouteRow, b: RouteRow): number =>
+  a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+
+/** Pages first, in the page table's order; then the API, by path, so the listing diffs cleanly. */
+export function routeRows(plain: readonly Route[] = []): readonly RouteRow[] {
+  return [...describePages().map(pageRow), ...[...apiRoutes(), ...plain].map(apiRow).sort(byPath)];
+}
+
+/**
+ * The plain HTTP routes `apps/<app>/runtime.ts` declares — the ones `X_BODY_INVALID` is about,
+ * since an action or query validates its own input. Loaded as `x dev` loads them.
+ */
+export async function plainAppRoutes(root: string): Promise<readonly Route[]> {
+  return (await loadAppRuntime(root))?.routes ?? [];
+}
+
+/** Fixed-width columns so the output diffs cleanly between runs and between machines. */
+export function renderRouteTable(routes: readonly RouteDescriptor[]): readonly string[] {
+  return renderRouteRows(routes.map(pageRow));
+}
+
+export function renderRouteRows(rows: readonly RouteRow[]): readonly string[] {
+  const header = ['method', 'path', 'surface', 'render', 'hydrate', 'offline', 'declared by'];
+  const widths = header.map((title, index) =>
+    Math.max(title.length, ...rows.map((row) => (row.cells[index] ?? '').length)),
+  );
+  const line = (cells: readonly string[]): string =>
+    cells.map((value, index) => value.padEnd(widths[index] ?? 0)).join('  ');
+  return [line(header), ...rows.map((row) => line(row.cells))];
+}

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,