@ultimat3/cli 23.0.0 → 25.0.0

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 ──────────────────────────────────────────────────────────────────
@@ -127,10 +143,10 @@ export async function showJob(driver: JobDriver, id: string): Promise<JobTrace>
 // ── retry ─────────────────────────────────────────────────────────────────
 
 /**
- * Existence is checked up front so an unknown id always surfaces as `X_JOB_UNKNOWN`: the
- * concrete drivers (pg, memory) throw their own error from inside `requeue()` for a missing
- * row, and that error is not this command's contract — `retryFromStep`'s documented `undefined`
- * return is, and the driver never reaches it once the row is already known absent.
+ * Existence is checked up front so an unknown id always surfaces as `X_JOB_UNKNOWN`: both
+ * drivers answer `X_JOB_NOT_FOUND` from inside `requeue()` for a missing row, and that code is
+ * the driver's contract, not this command's — `retryFromStep`'s documented `undefined` return
+ * is, and the driver never reaches it once the row is already known absent.
  */
 export async function retryJob(
   driver: JobDriver,

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

@@ -0,0 +1,13 @@
+// Whether a hostname is this machine: `localhost`, a `*.localhost` name (RFC 6761 reserves both
+// to loopback) or a loopback address literal. One answer for `x dev`'s Host check and `x doctor`'s
+// APP_URL rule, which ask the same question about two different headers.
+
+import { classifyAddress } from '@ultimat3/core';
+
+/** `hostname` as `URL` spells it — `[::1]` bracketed, no port. */
+export const isLoopbackHostname = (hostname: string): boolean => {
+  const name = hostname.toLowerCase();
+  return (
+    name === 'localhost' || name.endsWith('.localhost') || classifyAddress(name) === 'loopback'
+  );
+};

package/src/manifest-staleness.ts

@@ -0,0 +1,62 @@
+// Do the committed generated files still describe the code? ONE check, asked by `x manifest
+// --check` and by the gate's `manifest` step through this function — two commands answering
+// differently about one file is itself the drift these files exist to prevent.
+
+// why: Bun has no synchronous existence probe, and `hasCommittedContract` guards an app load.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join primitive; Bun.file takes a path already joined.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Manifest } from '@ultimat3/manifest';
+import { assertNoDrift, MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { OPENAPI_FILE, openApiStaleness } from './app-openapi';
+import { APP_CONFIG_FILE } from './app-root';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/** Whether there is any committed contract here to judge — the cheap question, asked first. */
+export const hasCommittedContract = (root: string): boolean =>
+  existsSync(join(root, MANIFEST_FILENAME)) || existsSync(join(root, OPENAPI_FILE));
+
+/**
+ * `x.manifest.json` was never written. An app root only: the framework monorepo emits
+ * `framework.manifest.json` and has no `x.manifest.json` to be missing. `AGENTS.md` tells an agent
+ * that facts live in this file, and after `x new` and every generator nothing had run the one
+ * command that writes it while the gate reported green (#F7).
+ */
+export function manifestMissingFindings(root: string): readonly Finding[] {
+  if (!existsSync(join(root, APP_CONFIG_FILE))) return [];
+  if (existsSync(join(root, MANIFEST_FILENAME))) return [];
+  return [
+    {
+      code: 'X_MANIFEST_MISSING',
+      cause: `${MANIFEST_FILENAME} does not exist, so every fact an agent reads about this app — route table, action schemas, policies, error codes — is unavailable`,
+      fix: 'x manifest',
+      docs: ERROR_DOCS_URL,
+      at: MANIFEST_FILENAME,
+    },
+  ];
+}
+
+/**
+ * Every way the committed files disagree with `manifest`, the app as the code declares it now:
+ * `x.manifest.json` missing (`X_MANIFEST_MISSING`) or drifted (`X_MANIFEST_DRIFT` — a body that no
+ * longer hashes to its own `buildId` included), and `openapi.json` or a bearer mount's document
+ * stale (`X_MANIFEST_STALE`). The spec is judged whether or not the manifest is there: it is a
+ * published contract on its own, and the typed client is generated from it.
+ */
+export async function manifestStaleness(
+  root: string,
+  manifest: Manifest,
+): Promise<readonly Finding[]> {
+  const path = join(root, MANIFEST_FILENAME);
+  const findings: Finding[] = [...manifestMissingFindings(root)];
+  if (existsSync(path)) {
+    try {
+      await assertNoDrift({ manifest, path });
+    } catch (error) {
+      findings.push({ ...findingFrom(error), at: MANIFEST_FILENAME });
+    }
+  }
+  return [...findings, ...(await openApiStaleness(root, manifest))];
+}

package/src/mcp-errors.ts

@@ -51,7 +51,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --only unit --json   # the finding carries the measured numbers and the "coverage" line to add to x.verify.json',
   X_COVERAGE_FLOOR_STALE:
     'x verify --only unit --json   # the finding carries the measured numbers; raise "coverage" in x.verify.json to them',
-  X_TEST_SHARD_FAILED: 'x test --workers 1 --json',
+  // Unthrown since `--worker` was deleted, and kept only because this record is typed over every
+  // registered code: `--shard i/n` is the one way to rerun a slice.
+  X_TEST_SHARD_FAILED: 'x verify --only unit --shard 1/2 --json',
   X_SCAFFOLD_PATH_ESCAPE: 'x g route posts --json   # a path with no ".." segment',
   X_GENERATE_JSON_INVALID:
     'bun test packages/cli/src/cmd-generate.test.ts   # the error names the template to fix',
@@ -67,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:
@@ -118,8 +121,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',
   X_ERROR_CODE_UNRESOLVED:
     'x verify --json   # the finding names the file, the line and the name it could not resolve',
-  X_ERROR_CODE_UNTHROWN:
-    'x errors explain X_ERROR_CODE_UNTHROWN --json   # then mark the row "registered, thrown by nothing since <version>"',
+  X_ERROR_CODE_UNTHROWN: 'x errors explain X_ERROR_CODE_UNTHROWN --json',
   X_CLI_UNEXPECTED: 'x doctor --json',
   // `-p .`: an app root has no `references`, so the gate's own step runs this form (#450).
   X_TYPECHECK_FAILED: 'bunx tsc -p . --pretty false',
@@ -284,6 +286,20 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'edit docker/Dockerfile: add RUN bun node_modules/@ultimat3/cli/src/bin.ts build --target prebuilt after COPY . . in the runtime stage, then rebuild the image',
   X_ADMIN_UNSCANNED:
     'git mv apps/admin/src/index.ts apps/admin/app/admin/admin.ts   # then repoint its relative imports and x verify --only manifest --json',
+  X_FRAMEWORK_TABLE_ORPHANED: 'x doctor --json',
+  X_BUILD_OUT_UNSAFE: 'x build --target static --out .x/static --json',
+  X_FRAMEWORK_SCHEMA_UNAPPLIED: 'x db migrate --json',
+  X_APP_URL_PORT_MISMATCH: 'export APP_URL=http://localhost:3000',
+  X_DEV_HOST_REFUSED: "curl -sS -H 'accept: application/json' http://localhost:3000/_x",
+  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

@@ -7,7 +7,14 @@
 // or prints inside a `fix:` an operator runs — the dev log, a per-role log, the committed
 // manifest — and string concatenation would answer a different path on a Windows checkout.
 import { join } from 'node:path';
-import { agentActor, isUltimateError, renderThrowable, UltimateError } from '@ultimat3/core';
+import {
+  agentActor,
+  isUltimateError,
+  NotImplementedError,
+  renderFixShellArg,
+  renderThrowable,
+  UltimateError,
+} from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
 import {
   ensureReadOnlyRole,
@@ -28,19 +35,18 @@ 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';
 import { declareDevEnvironment } from './dev-environment';
 import { loadCodeFixes } from './error-fixes';
-import { BadFlagError, CliNotImplementedError } from './errors';
+import { BadFlagError } from './errors';
 import type { Runner } from './exec';
-import { execOutput } from './exec';
 import { databaseTarget } from './mcp-db-target';
 import { explainErrorCode } from './mcp-errors';
-import { parseBunTest } from './mcp-test-output';
+import { testRunOf } from './mcp-test-run';
 import { type UiCapabilities, uiCapabilities } from './mcp-ui';
 import { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
@@ -107,8 +113,9 @@ export function lazyServices(input: DevHostInput): LazyServices {
       // A boot started after close() would hold the PGlite data directory for the life of the
       // process with nobody left to stop it — the host is closed, so the call is the bug.
       if (closed) {
-        throw new CliNotImplementedError({
-          feature: 'an MCP tool that needs the database after the host closed',
+        throw new NotImplementedError({
+          cause:
+            'an MCP tool that needs the database after the host closed is not implemented in this build',
           fix: 'x mcp serve --transport stdio   # keep the host open for the whole session',
         });
       }
@@ -271,7 +278,8 @@ function capabilities(
         cwd: root,
         ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
       });
-      return parseBunTest(execOutput(result), result.durationMs);
+      // The whole result, exit code included: `0 fail` beside `1 error` is a red run.
+      return testRunOf(result);
     },
 
     async tailLogs(lines: number, role: string | undefined) {
@@ -281,12 +289,12 @@ function capabilities(
       if (!(await file.exists())) {
         // `@ultimat3/core`'s `logger` is a module const with no sink seam, so there is nothing to
         // intercept in-process — a log on disk is the only honest source, and the fix creates one.
-        throw new CliNotImplementedError({
-          feature: `logs.tail without ${path}`,
+        throw new NotImplementedError({
+          cause: `logs.tail without ${path} is not implemented in this build`,
           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);
@@ -341,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-test-run.ts

@@ -0,0 +1,38 @@
+// `test.run`'s answer from the whole `bun test` result, not from its pass/fail lines alone: bun
+// counts an error raised OUTSIDE any test on a line of its own (`1 error`) beside `0 fail`, and
+// says the run failed only through its exit code.
+
+import type { TestRun } from '@ultimat3/mcp';
+import type { ExecResult } from './exec';
+import { execOutput } from './exec';
+import { parseBunTest } from './mcp-test-output';
+
+/** Bun's own `N error` / `N errors` summary line: the last one, as `parseBunTest` reads the rest. */
+export const errorsIn = (output: string): number => {
+  const last = [...output.matchAll(/^\s*(\d+)\s+errors?\s*$/gm)].at(-1);
+  return last === undefined ? 0 : Number.parseInt(last[1] ?? '0', 10);
+};
+
+/**
+ * Every error outside a test is one failure, carried with the run's own message; a non-zero exit
+ * with nothing else counted is one more, so a red process can never answer `failed: 0`.
+ */
+export function testRunOf(result: ExecResult): TestRun {
+  const output = execOutput(result);
+  const run = parseBunTest(output, result.durationMs);
+  const errors = errorsIn(output);
+  const outside = Array.from({ length: errors }, () => ({
+    test: 'bun test',
+    message: 'an error outside any test — a file that threw while loading, or a failed hook',
+  }));
+  const counted = run.failed + errors;
+  const exitOnly =
+    result.code !== 0 && counted === 0
+      ? [{ test: 'bun test', message: `bun test exited ${String(result.code)} with no failure` }]
+      : [];
+  return {
+    ...run,
+    failed: counted + exitOnly.length,
+    failures: [...run.failures, ...outside, ...exitOnly],
+  };
+}

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})`;
+}