@ultimat3/cli 24.0.0 → 25.0.0

package/src/jobs-json.ts

@@ -13,7 +13,6 @@ import type {
   StepTrace,
   WorkerRecord,
 } from '@ultimat3/jobs';
-import type { DrainFailure, DrainSkip } from './jobs-drain';
 import type { JsonValue } from './output';
 
 function stepTraceToJson(step: StepTrace): JsonValue {
@@ -181,28 +180,3 @@ export function deadLetterToJson(entry: DeadLetterEntry): JsonValue {
     retryCommand: entry.retryCommand,
   };
 }
-
-export function drainFailureToJson(failure: DrainFailure): JsonValue {
-  return {
-    id: failure.id,
-    name: failure.name,
-    finding: {
-      code: failure.finding.code,
-      cause: failure.finding.cause,
-      fix: failure.finding.fix,
-      docs: failure.finding.docs ?? null,
-      at: failure.finding.at ?? null,
-    },
-  };
-}
-
-/** A candidate the drain refused to touch, and why — the half of the outcome `moved` cannot show. */
-export function drainSkipToJson(skip: DrainSkip): JsonValue {
-  return {
-    id: skip.id,
-    name: skip.name,
-    queue: skip.queue,
-    state: skip.state,
-    reason: skip.reason,
-  };
-}

package/src/jobs-report.ts

@@ -1,7 +1,9 @@
 // Pure, driver-injected job operations behind `x jobs`: flag parsing, plus ls / show / retry. No
-// CLI parsing, no process I/O, no rendering — a test drives every path with `createMemoryDriver()`
-// alone. Drain is `jobs-drain.ts`, the `--json` shapes `jobs-json.ts`, the table `jobs-table.ts`.
+// 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`.
 
+import type { Page } from '@ultimat3/core';
+import { pageOf } from '@ultimat3/core';
 import type {
   BackfillProgress,
   DeadLetterEntry,
@@ -13,6 +15,7 @@ import type {
   QueueDepthReport,
 } from '@ultimat3/jobs';
 import {
+  DEFAULT_JOB_PAGE,
   inspectBackfills,
   inspectDeadLetters,
   inspectJob,
@@ -20,19 +23,12 @@ import {
   inspectQueues,
   isJobState,
   JOB_STATES,
+  jobCursor,
+  MAX_JOB_PAGE,
   retryFromStep,
 } from '@ultimat3/jobs';
 import { BadFlagError, JobUnknownError } from './errors';
 
-/**
- * The queue's own vocabulary, re-exported rather than restated — this file carried a copy of it,
- * and the copy was one member short. `cancelled` shipped in `@ultimat3/jobs` and never here, so
- * `x jobs cancel` created a state `x jobs ls --state cancelled` then refused to filter on: two
- * commands of one CLI disagreeing about what a job can be. Kept on this module's surface because
- * `index.ts` exports it from here.
- */
-export { JOB_STATES } from '@ultimat3/jobs';
-
 export function parseStateFlag(value: string | undefined): JobState | undefined {
   if (value === undefined) return undefined;
   if (isJobState(value)) return value;
@@ -76,12 +72,32 @@ export interface JobsListFilter {
   readonly after?: string | undefined;
 }
 
-export interface JobsListResult {
+/** ONE page of rows — core's `Page`, so `nextCursor` exists exactly when another row does. */
+export type JobsListResult = Page<JobRecord> & {
   readonly depth: QueueDepthReport;
-  readonly rows: readonly JobRecord[];
   readonly deadLetters: readonly DeadLetterEntry[];
   /** The sweeps still in flight — see below for why finished ones are not this command's answer. */
   readonly backfills: readonly BackfillProgress[];
+};
+
+/**
+ * One page, and whether a row exists past it — asked of the queue, never guessed from a count.
+ * `next = rows.length === limit ? cursor : null` handed a FULL last page a cursor to an empty one.
+ * The page reads one row past its limit; at `MAX_JOB_PAGE` there is no room for that row (the
+ * queue refuses a bigger page), so a full maximal page asks for the one row after its last.
+ */
+async function jobPage(driver: JobDriver, filter: JobFilter): Promise<Page<JobRecord>> {
+  const size = filter.limit ?? DEFAULT_JOB_PAGE;
+  const ask = size < MAX_JOB_PAGE ? size + 1 : size;
+  const fetched = await inspectJobList(driver, { ...filter, limit: ask });
+  const rows = fetched.slice(0, size);
+  const last = rows.at(-1);
+  if (last === undefined || fetched.length < size) return pageOf(rows, null);
+  if (fetched.length > size) return pageOf(rows, jobCursor(last));
+  if (ask > size) return pageOf(rows, null);
+  const after = jobCursor(last);
+  const beyond = await inspectJobList(driver, { ...filter, limit: 1, after });
+  return pageOf(rows, beyond.length > 0 ? after : null);
 }
 
 /**
@@ -107,13 +123,13 @@ export async function listJobs(
     ...(limit === undefined ? {} : { limit }),
     ...(filter.after === undefined ? {} : { after: filter.after }),
   };
-  const [depth, rows, deadLetters, backfills] = await Promise.all([
+  const [depth, page, deadLetters, backfills] = await Promise.all([
     inspectQueues(driver),
-    inspectJobList(driver, jobFilter),
+    jobPage(driver, jobFilter),
     inspectDeadLetters(driver),
     inspectBackfills(driver, { status: 'running' }),
   ]);
-  return { depth, rows, deadLetters, backfills };
+  return { ...page, depth, deadLetters, backfills };
 }
 
 // ── show ──────────────────────────────────────────────────────────────────

package/src/local-cli-handoff.ts

@@ -0,0 +1,90 @@
+// Running the app's own CLI in place of this one (`local-cli.ts` decides WHETHER). The parent only
+// waits, so every stop signal it receives is the child's to act on: a supervisor or a closing
+// terminal signals the pid it started, and that pid is this one. `bin.ts` exits with the answer.
+
+/**
+ * The stop signals forwarded to the child at once. SIGINT is NOT one of them: Ctrl-C reaches the
+ * whole foreground process group, so the child already has it, and a second one landed inside its
+ * cleanup — `x secrets edit` died mid-shred with its decrypted buffer still on disk (audit M1).
+ */
+export const HAND_OFF_SIGNALS = ['SIGTERM', 'SIGHUP'] as const;
+export type HandOffSignal = (typeof HAND_OFF_SIGNALS)[number] | 'SIGINT';
+
+/**
+ * How long a SIGINT is held before it is forwarded. A Ctrl-C the group delivered ends the child
+ * well inside it — a shred is milliseconds — so it is never sent twice; a SIGINT aimed at this pid
+ * alone (`kill -INT`, a runtime whose STOPSIGNAL is SIGINT) reaches the child a second later
+ * instead of never. A child still draining past it gets one more SIGINT, which every drain here
+ * already absorbs (`signal-shred.ts` ignores repeats; `x dev`'s stop is armed once).
+ */
+export const INTERRUPT_GRACE_MS = 1000;
+
+/** Arms `fire` after `ms`, answering its cancel. Injected by the test, so no verdict waits on a clock. */
+export type Schedule = (fire: () => void, ms: number) => () => void;
+
+/** The spawned CLI as the hand-off sees it — `Bun.spawn`'s answer, narrowed so a test can fake it. */
+export interface HandOffChild {
+  readonly exited: Promise<number>;
+  kill(signal: HandOffSignal): void;
+}
+
+// Untimed by design, and counted under `cli`'s pin in `scripts/lib/spawn-timeout-pins.ts`: the
+// child IS the command the user typed (`x dev` serves until Ctrl-C), so its lifetime is theirs, and
+// the forwarded stop signals below are what end it.
+const spawnInherited = (
+  command: readonly string[],
+  env: Readonly<Record<string, string | undefined>>,
+): HandOffChild =>
+  Bun.spawn([...command], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit', env });
+
+const scheduleTimer: Schedule = (fire, ms) => {
+  const timer = setTimeout(fire, ms);
+  return () => clearTimeout(timer);
+};
+
+export interface HandOffOptions {
+  readonly spawn?: typeof spawnInherited;
+  readonly schedule?: Schedule;
+}
+
+/**
+ * Spawns `command`, forwards SIGTERM and SIGHUP to it for as long as it runs — SIGINT only once the
+ * grace passes with the child still running — and answers its exit code: `128 + n` when a signal
+ * ended it, as `Bun.spawn`'s `exited` reports. `bin.ts` exits with that code.
+ *
+ * Without the listeners the default action ran: the parent died on the signal and the child —
+ * an `x dev` holding a port and an embedded Postgres, an `x db migrate` mid-transaction — ran on
+ * as an orphan nothing would stop. A listener is also what keeps the parent alive to report the
+ * child's own exit code, rather than 143 before the child had drained.
+ */
+export async function handOff(
+  command: readonly string[],
+  env: Readonly<Record<string, string | undefined>>,
+  options: HandOffOptions = {},
+): Promise<number> {
+  const child = (options.spawn ?? spawnInherited)(command, env);
+  const schedule = options.schedule ?? scheduleTimer;
+  const forwards = HAND_OFF_SIGNALS.map((signal) => {
+    const forward = (): void => child.kill(signal);
+    process.on(signal, forward);
+    return () => process.off(signal, forward);
+  });
+  // Whether the child already has this SIGINT is unknowable from here, so the grace decides: a
+  // repeat inside one window arms nothing new — one Ctrl-C never becomes two forwarded signals.
+  let cancelGrace: (() => void) | undefined;
+  const holdInterrupt = (): void => {
+    if (cancelGrace !== undefined) return;
+    cancelGrace = schedule(() => {
+      cancelGrace = undefined;
+      child.kill('SIGINT');
+    }, INTERRUPT_GRACE_MS);
+  };
+  process.on('SIGINT', holdInterrupt);
+  try {
+    return await child.exited;
+  } finally {
+    for (const release of forwards) release();
+    process.off('SIGINT', holdInterrupt);
+    cancelGrace?.();
+  }
+}

package/src/mcp-errors.ts

@@ -69,7 +69,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --json   # the package-shape finding carries the dependency line to add',
   X_PACKAGE_DUPLICATED:
     'x i18n check --json   # the finding names both copies and the package.json to pin',
-  X_SHOT_BROWSER_MISSING: 'export CHROME_PATH=/usr/bin/google-chrome',
+  X_SHOT_BROWSER_MISSING:
+    'export CHROME_PATH=/usr/bin/google-chrome   # macOS: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"; Windows PowerShell: $env:CHROME_PATH = "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"',
   X_UI_SHOT_ROUTE_UNKNOWN:
     'x routes --json   # then call the ui.* tool with one of its path values',
   X_UI_SHOT_ROUTE_UNBUDGETED:
@@ -293,6 +294,12 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_TRUSTED_PROXY_HOPS_INVALID: 'TRUSTED_PROXY_HOPS=1 ROLE=web bun apps/web/server.ts',
   X_PERMISSION_BORROWED: 'x verify --only policy --json',
   X_ERROR_CODE_UNTHROWN_STALE: 'x errors explain X_ERROR_CODE_UNTHROWN_STALE --json',
+  X_DEV_STATE_UNWRITABLE:
+    'ls -ld .x   # make it writable by this user, on a filesystem that supports hard links, then re-run x dev',
+  X_PACKAGE_TEST_ONLY_SHIPPED:
+    'bun run x -- verify --only package-shape --json   # then rename each listed module to <name>-fixture.ts and update its importers',
+  X_ISLAND_MODULE_DUPLICATED:
+    'gh issue create --repo developerz-ai/ultimate --title "X_ISLAND_MODULE_DUPLICATED"   # paste this error\'s --json as the body: the framework bundled one of its own modules twice',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/mcp-host.ts

@@ -11,6 +11,7 @@ import {
   agentActor,
   isUltimateError,
   NotImplementedError,
+  renderFixShellArg,
   renderThrowable,
   UltimateError,
 } from '@ultimat3/core';
@@ -34,8 +35,8 @@ import type {
   VerifyResult,
   VerifyStep,
 } from '@ultimat3/mcp';
-import { createDevServer, DEV_SCOPES, devHost, frameworkIntrospection } from '@ultimat3/mcp';
-import { describeRoutes } from '@ultimat3/render';
+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';
@@ -293,7 +294,7 @@ function capabilities(
           fix:
             role === undefined
               ? `x dev > ${path} 2>&1`
-              : `mkdir -p ${join(dir, 'logs')} && x dev --role ${role} > ${path} 2>&1`,
+              : `mkdir -p ${renderFixShellArg(join(dir, 'logs'), '<the logs dir of the path the cause names>')} && x dev --role ${role} > ${path} 2>&1`,
         });
       }
       return (await file.text()).trimEnd().split('\n').slice(-lines);
@@ -348,10 +349,10 @@ export async function createDevMcpServer(input: DevHostInput): Promise<CliMcpSer
   const lazy = lazyServices(input);
   const ui = uiCapabilities({ root: input.root, env: input.env });
   const introspection = frameworkIntrospection({
-    routes: () => describeRoutes(),
+    routes: () => describePages(),
     policies: () => policyFacts(),
   });
-  const server = createDevServer({ host: devHost(introspection, capabilities(input, lazy, ui)) });
+  const server = devMcpServer({ host: devHost(introspection, capabilities(input, lazy, ui)) });
   const caller = localCaller();
   return {
     server,

package/src/mcp-ui-inspect.ts

@@ -11,9 +11,10 @@
 import { join } from 'node:path';
 import type { UiInspectInput, UiInspectResult, UiInspectSelector } from '@ultimat3/mcp';
 import { UI_INSPECT_LIMITS } from '@ultimat3/mcp';
+import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
 import type { AxNode, ShotDriver, ShotPage } from './browser-launcher-port';
 import { DEFAULT_PAGE_TIMEOUT_MS } from './cdp-shot-clock';
-import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
+import { runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import type { ShotServer } from './shot-server';
 import type { ShotVerdict } from './shot-verdict';
 import type { InspectProbe } from './ui-inspect-probe';
@@ -144,7 +145,7 @@ export async function inspectRoute(
     outDir,
     driver,
     boot: deps.boot,
-    settleMs: DEFAULT_SETTLE_MS,
+    settleMs: IDLE_HYDRATE_TIMEOUT_MS,
     timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
     fullPage: true,
     colorScheme: input.colorScheme,

package/src/mcp-ui-interact.ts

@@ -14,9 +14,10 @@ import { join } from 'node:path';
 import { isUltimateError, toUltimateError, UltimateError } from '@ultimat3/core';
 import type { UiInteractInput, UiInteractResult, UiInteractStepResult } from '@ultimat3/mcp';
 import { UI_INTERACT_LIMITS } from '@ultimat3/mcp';
+import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
 import type { ShotPage } from './browser-launcher-port';
 import { DEFAULT_PAGE_TIMEOUT_MS } from './cdp-shot-clock';
-import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
+import { runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import type { InspectDeps, Seen } from './mcp-ui-inspect';
 import { readInspect, selectorsOf } from './mcp-ui-inspect';
 import { SETTLE_POLL_MS } from './shot-settle';
@@ -265,7 +266,7 @@ export async function interactRoute(
     outDir,
     driver,
     boot: deps.boot,
-    settleMs: DEFAULT_SETTLE_MS,
+    settleMs: IDLE_HYDRATE_TIMEOUT_MS,
     timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
     fullPage: input.fullPage,
     colorScheme: input.colorScheme,

package/src/mcp-ui.ts

@@ -10,7 +10,7 @@
 
 // why: Bun exposes no path-join primitive, and the picture's directory is a path an agent opens.
 import { join } from 'node:path';
-import { UltimateError } from '@ultimat3/core';
+import { finiteCount, UltimateError } from '@ultimat3/core';
 import type {
   UiDiffInput,
   UiDiffResult,
@@ -23,11 +23,11 @@ import type {
   UiShotInput,
   UiShotResult,
 } from '@ultimat3/mcp';
-import { describeRoutes } from '@ultimat3/render';
+import { describePages, IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
 import { appBrowser } from './browser-launcher';
 import type { ShotDriver } from './browser-launcher-port';
 import { DEFAULT_PAGE_TIMEOUT_MS } from './cdp-shot-clock';
-import { DEFAULT_SETTLE_MS, readRoute, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
+import { readRoute, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import { islandShot } from './cmd-shot-island';
 import { islandVerdictJson } from './island-verdict';
 import { diffShots } from './mcp-ui-diff';
@@ -95,7 +95,7 @@ export interface UiHostInput {
   readonly driver?: ((viewport: UiShotInput['viewport']) => Promise<ShotDriver>) | undefined;
   /** Injected by a test: the route table, in place of the registry. */
   readonly routes?: (() => readonly DeclaredRoute[]) | undefined;
-  /** Injected by a test: the settle wait, in place of `DEFAULT_SETTLE_MS` (a real sleep per call). */
+  /** Injected by a test: the settle wait, in place of `IDLE_HYDRATE_TIMEOUT_MS` (a real sleep per call). */
   readonly settleMs?: number | undefined;
 }
 
@@ -127,7 +127,7 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
   // The same choice `x shot` makes from the environment: `PUPPETEER_EXECUTABLE_PATH`, a
   // provider's CDP URL, or the launcher's own discovery.
   const browser = () => shotBrowserChoice({ cdpFlag: undefined, browserFlag: undefined, env });
-  const routes = input.routes ?? describeRoutes;
+  const routes = input.routes ?? describePages;
   // One browser per call, sized to the call: the injected driver in a test, `appBrowser` otherwise.
   const driverFor = async (viewport: UiShotInput['viewport']): Promise<ShotDriver> => {
     if (input.driver !== undefined) return input.driver(viewport);
@@ -165,7 +165,8 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
         outDir,
         driver,
         boot,
-        settleMs: input.settleMs ?? DEFAULT_SETTLE_MS,
+        // An agent's argument: a NaN or negative settle would wait forever or not at all.
+        settleMs: finiteCount('ui.shot', 'settleMs', input.settleMs ?? IDLE_HYDRATE_TIMEOUT_MS),
         timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
         fullPage: shot.fullPage,
         colorScheme: shot.colorScheme,
@@ -199,7 +200,7 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
         root,
         island: island.island,
         ...(island.state === undefined ? {} : { state: island.state }),
-        settleMs: input.settleMs ?? DEFAULT_SETTLE_MS,
+        settleMs: finiteCount('ui.island', 'settleMs', input.settleMs ?? IDLE_HYDRATE_TIMEOUT_MS),
         timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
         ...(executablePath === undefined ? {} : { executablePath }),
         ...(cdpUrl === undefined ? {} : { cdpUrl }),

package/src/measure-scope.ts

@@ -7,13 +7,8 @@
 // `withInProcessFetch`, because no server is listening during a build (plan 101 slice 11 m).
 
 import type { Actor, Ctx } from '@ultimat3/core';
-import { measurementActor, runWithContext, withInProcessFetch } from '@ultimat3/core';
-import {
-  createPipeline,
-  createRequestContext,
-  createRouter,
-  defineHttpConfig,
-} from '@ultimat3/http';
+import { actorLabel, measurementActor, runWithContext, withInProcessFetch } from '@ultimat3/core';
+import { defineHttpConfig, httpPipeline, httpRouter, requestContext } from '@ultimat3/http';
 import { apiRoutes } from './api-routes';
 
 /** One build's measurement scope: its actor, and a runner that renders inside it. */
@@ -35,15 +30,15 @@ export async function measureScope(input: {
   // No rate limit: every request here is this build's own render, and a limiter would need a
   // deployment scope a build does not have (`X_RATE_LIMIT_SCOPE_UNSET`).
   const config = defineHttpConfig({ buildId: input.buildId, rateLimit: { enabled: false } });
-  const ctx = createRequestContext({
+  const ctx = requestContext({
     url: new URL(input.origin),
     method: 'GET',
     role: 'web',
     config,
   });
   ctx.actor = actor;
-  const pipeline = createPipeline({
-    table: createRouter(apiRoutes()),
+  const pipeline = httpPipeline({
+    table: httpRouter(apiRoutes()),
     config,
     hooks: { authenticate: () => actor },
   });
@@ -72,3 +67,13 @@ export async function withAppUrl<T>(origin: string, fn: () => Promise<T>): Promi
     else process.env['APP_URL'] = before;
   }
 }
+
+/**
+ * The measurement actor as a refusal names it: core's `actorLabel` (kind, id, tenant) — the one
+ * actor format — plus the roles, which a role-gated page asks of it and `actorLabel` omits (#675).
+ * Never `facts`: this lands in a report and a gate finding.
+ */
+export function measurementActorLabel(actor: Actor): string {
+  const roles = actor.roles.length === 0 ? 'none' : actor.roles.join(', ');
+  return `${actorLabel(actor)} (roles: ${roles})`;
+}

package/src/messages.ts

@@ -86,6 +86,9 @@ const CATALOG = {
   'cli.dev.mail.refused': 'mail=refused({detail})',
   'cli.dev.hmr': 'reloaded {file} in {ms}ms',
   'cli.dev.restart': 'restarting: {reason} — a module that defines a primitive holds the old code',
+  // The restart's wait, said while it waits: a save never cancels a running job (issue #677).
+  'cli.dev.restartWaiting':
+    'restart waits for {count} running job(s) to finish — no new job is claimed; Ctrl-C stops now (a job still running is cut off at the drain deadline and requeued)',
   // A hard kill leaves the lock behind and that is normal, not a fault — worth one line so a
   // reader knows why the boot paused, and never a finding.
   'cli.dev.staleLock': 'cleared a stale dev.lock — the previous x dev did not shut down cleanly',
@@ -143,9 +146,6 @@ const CATALOG = {
   'cli.jobs.deadLetters': '{count} dead letter(s):',
   'cli.jobs.depth':
     '{ready} ready · {running} running · {delayed} delayed · {dead} dead across {queues} queue(s)',
-  'cli.jobs.drained': 'drained {count} job(s) from {from} to {to}',
-  'cli.jobs.drainedPartial':
-    'drained {count} job(s) from {from} to {to} — {skipped} left on {from}',
   'cli.jobs.listed': '{count} job(s)',
   'cli.jobs.nextPage': 'more — next page: x jobs ls --after {cursor}',
   'cli.jobs.noError': 'no error recorded',
@@ -156,24 +156,30 @@ const CATALOG = {
   'cli.jobs.resumed': 'queue {queue} resumed',
   'cli.jobs.retried': 'job {id} re-queued — {state}',
   'cli.jobs.shown': 'job {id} — {state}, attempt {attempt} of {attempts}',
-  'cli.jobs.skipped': '{count} job(s) left on {from} — re-run the drain once each is claimable:',
   'cli.manifest.blocked': 'manifest not written — {count} module(s) did not load',
   'cli.manifest.fresh': 'manifest is fresh',
   'cli.manifest.stale': 'manifest is stale',
   'cli.manifest.wrote': 'manifest written to {path} ({routes} routes, {actions} actions)',
   'cli.mcp.serving': 'mcp {transport} serving {tools} tools',
   'cli.mcp.scopes': '  scopes {scopes}',
-  // `bin/setup` and nothing else: the scaffold ships it, `README.md` and `bin/check` both name it,
-  // and it is the only spelling that is right on a fresh clone — it installs, writes
-  // `.env.development.local`, runs `x db gen "initial"` (the scaffold writes no migration, so the
-  // drift step is red until it has), migrates and seeds. The four-command line this replaced named
-  // `x dev` off a tree where nothing had installed the CLI yet, and skipped the seed entirely.
-  // `bin/dev`, never `x dev`: `bun install` links the binary into `./node_modules/.bin` and
-  // nowhere else, so the bare `x` this line printed is not on PATH in the shell it is pasted into
-  // (proved with `env -i PATH=… command -v x`). The scaffold's own `bin/` wrappers are the form
-  // that works from a fresh clone, and `bin/setup` already uses `bunx x` internally for this
-  // reason.
-  'cli.new.done': 'created {name} — next: cd {name} && bin/setup && bin/dev',
+  // `bun run setup` and nothing else: the scaffold ships it (`bin/setup.ts`), `README.md` and
+  // `bun run check` both name it, and it is the only spelling that is right on a fresh clone — it
+  // installs, writes `.env.development.local`, runs `x db gen "initial"` (the scaffold writes no
+  // migration, so the drift step is red until it has), migrates and seeds. The four-command line
+  // this replaced named `x dev` off a tree where nothing had installed the CLI yet, and skipped the
+  // seed entirely.
+  // `bun run dev`, never `x dev`: `bun install` links the binary into `./node_modules/.bin` and
+  // nowhere else, so a bare `x` is not on PATH in the shell it is pasted into (proved with
+  // `env -i PATH=… command -v x`); `bun run` puts that directory on PATH for the script. And
+  // `bun run`, never a `bin/` path: Bun runs the line identically in PowerShell, cmd and bash.
+  // `{cd}` is the resolved target as the caller's shell reaches it — `--dir` included, relative to
+  // the cwd when under it, shell-quoted (`cmd-new.ts`'s `cdTarget`). `cd {name}` entered the wrong
+  // directory, or none, whenever `--dir` put the app somewhere else.
+  'cli.new.done': 'created {name} — next: cd {cd} && bun run setup && bun run dev',
+  // `--dry-run`'s own summary: nothing landed, so "created" was a claim an agent branching on the
+  // summary would act on. `{dir}` is the resolved target, `--dir` included.
+  'cli.new.dryRun':
+    'would create {name} in {dir} — nothing written; after a real run: cd {cd} && bun run setup && bun run dev',
   // The two prose lines of `x new`'s report. The `run: cd … && git init …` line beneath the second
   // one stays inline in `cmd-new.ts`: it is an instruction to paste verbatim, and a translated
   // command is a broken one — the same split `Finding.fix` already makes.
@@ -235,6 +241,10 @@ const CATALOG = {
   'cli.shot.pageError': '  threw    {message}  {at}',
   'cli.shot.picture': '  picture  {path}',
   'cli.shot.verdict': '  verdict  {path}',
+  // `--viewport`: one route at several sizes. The summary is ONE size's verdict, so it says which
+  // size; each size line leads with its size and the per-size detail lines sit indented beneath.
+  'cli.shot.viewport.summary': '{size}: {summary}',
+  'cli.shot.viewport.line': '{size}  {summary}',
   // `--island`. A component capture reports per STATE, so the summary counts pictures and the
   // lines name one state each; nothing here restates a fact `--json` does not carry.
   'cli.shot.island.ok':
@@ -304,7 +314,7 @@ const CATALOG = {
   // A skipped step is not a passed one, so the two counts never share a sentence — and the skipped
   // ones are named, because "which suite has nothing to run here?" is the question a green gate
   // over a missing suite has to answer on its own line. Whole sentences per case rather than a
-  // clause the caller glues on, the same shape `cli.jobs.drained`/`drainedPartial` already uses.
+  // clause the caller glues on: a catalog clause cannot know the sentence it lands in.
   'cli.verify.passSkipped':
     '{passed} of {count} steps passed in {ms}ms — {skipped} skipped: {names}',
   'cli.verify.failSkipped': '{failed} of {count} steps failed — {skipped} skipped: {names}',
@@ -315,6 +325,7 @@ const CATALOG = {
   // tests ran. Each test's own name carries the reason it skipped, and `bun test` prints only the
   // counts — so the line says how many and `x test <type>` prints the names.
   'cli.verify.allSkipped': 'found {skipped} test(s) and every one skipped itself',
+  'cli.verify.warnings': '{count} warning(s) — --verbose or --json lists them',
   // The other shape the same counts can take: a suite that reported no test at all, skipped ones
   // included. Its own line and not `allSkipped` with a zero, because the repair differs — there is
   // no skipped test to read a reason off, so the files the step selected hold no test.

package/src/metrics-endpoint.ts

@@ -18,6 +18,7 @@ import {
   UltimateError,
 } from '@ultimat3/core';
 import { neighbouringPort } from './flag-number';
+import { quoteArg } from './shell-quote';
 
 /**
  * A port of its own, and NOT the role's HTTP port, for one reason the chart makes concrete:
@@ -48,7 +49,7 @@ export class MetricsPortInUseError extends UltimateError {
     super({
       code: 'X_PORT_IN_USE',
       cause: `the metrics port ${input.port} is already bound, so no role could open its scrape listener`,
-      fix: `METRICS_PORT=${neighbouringPort(input.port)} x dev --json`,
+      fix: `METRICS_PORT=${quoteArg(String(neighbouringPort(input.port)))} x dev --json`,
     });
   }
 }
@@ -114,7 +115,7 @@ export function bindScrapePort<T>(
     logger.warn('ultimate metrics port taken', {
       port,
       cause: `the metrics port ${String(port)} is already bound — another x dev, or a Prometheus — so this process listens on a free one`,
-      fix: `METRICS_PORT=${String(neighbouringPort(port))} x dev --json`,
+      fix: `METRICS_PORT=${quoteArg(String(neighbouringPort(port)))} x dev --json`,
     });
     return bind(0);
   }

package/src/migration-extensions.ts

@@ -24,6 +24,6 @@ export function migrationExtensions(migrations: readonly Migration[]): readonly
   return [...names].sort();
 }
 
-/** The same list for an app on disk — what an embedded boot hands `createPgliteClient`. */
+/** The same list for an app on disk — what an embedded boot hands `pgliteClient`. */
 export const appExtensions = async (root: string): Promise<readonly string[]> =>
   migrationExtensions(await readMigrations(root));

package/src/otlp-export.ts

@@ -36,7 +36,7 @@ export const METRIC_EXPORT_INTERVAL_MS = 60_000;
  * merge into process-global state, so stopping the timer and dropping the drain hooks left the
  * first boot's exporter configured: a second `serveApp` in the same process exported its spans
  * into a released exporter — queued against a collector nothing will flush to, on a timer nothing
- * clears. `cmd-dev.ts`'s `stop()` hands back `noopExporter` for exactly this reason. Per signal and
+ * clears. `dev-boot.ts`'s `stop()` hands back `noopExporter` for exactly this reason. Per signal and
  * never unconditionally: `x dev` configures a trace RECORDER before calling this, and a boot that
  * installed no exporter must not uninstall one it never owned.
  */
@@ -52,7 +52,7 @@ export function startOtlpExport(env: Env = process.env): () => void {
     const exporter = otlpSpanExporter({ endpoint: traces });
     configureTelemetry({ exporter });
     // Pushed first, so the reversed run below applies it LAST — after the drain hook is dropped,
-    // the same order `cmd-dev.ts` releases the recorder in.
+    // the same order `dev-boot.ts` releases the recorder in.
     releases.push(() => configureTelemetry({ exporter: noopExporter }));
     releases.push(onShutdown('otlp-traces', () => exporter.shutdown(), { phase: 'close' }));
     logger.info('ultimate otlp traces', { endpoint: traces });

package/src/output.ts

@@ -50,6 +50,12 @@ export interface StepResult {
    * coverage is `data.coverage.unit`), where `--json` and the terminal both always have it.
    */
   readonly output?: string;
+  /**
+   * Advice that does not fail the step — a file inside `filesize`'s band below the ceiling. Unlike
+   * `output`, carried by both renderers on a PASS too: advice a green run hides reaches nobody
+   * until it has become the failure it warns about. One line of text per warning.
+   */
+  readonly warnings?: readonly string[];
   /** Worker processes the step used; `1` means it ran serially. Absent for a non-test step. */
   readonly workers?: number;
   /** Why the width is what it is — `4 workers (budget 4.0 GB)`. */
@@ -230,6 +236,14 @@ export function renderHuman(result: CommandResult, verbose = false): string {
       `  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms${width(step)}${why(step)}`,
     );
     for (const finding of step.findings) out.push(renderFinding(finding, '      '));
+    // Escaped like every other line text reaches fd 1 through: a warning names a file path. A
+    // green terminal run shows the count, not the list: `filesize`'s band alone is ~150 lines,
+    // and a wall of advice on every run is read by nobody. `--json` always carries the list.
+    const warnings = step.warnings ?? [];
+    if (verbose) for (const warning of warnings) out.push(`      ! ${singleLine(warning)}`);
+    else if (warnings.length > 0) {
+      out.push(`      ! ${msg('cli.verify.warnings', { count: warnings.length })}`);
+    }
     // NOT escaped, and that is the one exception: `output` is this process's own captured
     // subprocess stdout — `bun test`'s colour is the reason a human reads it at all, and it is
     // already split on its real newlines rather than carrying them inside one entry.
@@ -256,6 +270,10 @@ export function renderJson(result: CommandResult, verbose = false): string {
     durationMs: step.durationMs,
     skipped: step.skipped === true,
     findings: step.findings,
+    // Never gated on `ok` or `--verbose`, unlike `output` below: see `StepResult.warnings`.
+    ...(step.warnings === undefined || step.warnings.length === 0
+      ? {}
+      : { warnings: [...step.warnings] }),
     ...(step.workers === undefined ? {} : { workers: step.workers }),
     ...(step.widthReason === undefined ? {} : { widthReason: step.widthReason }),
     ...(step.shard === undefined