@ultimat3/cli 2.0.0 → 4.0.0

package/src/flag-reads.ts

@@ -0,0 +1,114 @@
+// A flag a command declares and nothing reads. The parser accepts every declared flag, so a flag
+// with no reader is not a parse error and not a type error — it is a promise in the help text with
+// no code behind it, and only a rule over the two halves together can see that.
+//
+// The bound of this rule, stated where it is enforced: it sees the flag NAME reaching a reader,
+// not the value reaching an effect. `x deploy --critical` satisfied it by being written into the
+// plan JSON, where nothing read the field; that flag is deleted rather than wired, and a second
+// one of its shape would pass here too.
+
+// `join`/`relative` are `node:`-only by necessity: Bun exposes no path-join primitive.
+import { join, relative } from 'node:path';
+import { docsFor } from './error-codes';
+import type { Finding } from './output';
+import type { CommandSpec, FlagSpec } from './parse';
+import { GLOBAL_FLAGS } from './parse';
+import { stripComments } from './ts-scan';
+
+/** A flag as declared, with the command that declares it. */
+export interface DeclaredFlag {
+  readonly command: string;
+  readonly flag: FlagSpec;
+}
+
+/**
+ * Every flag a command declares. The global four are excluded: `--json`, `--help`, `--cwd` and
+ * `--verbose` are the parser's and the dispatcher's, read once for every command rather than by
+ * the command that lists them, and a per-command rule would report all 30 of them as unread.
+ */
+export function declaredFlags(specs: readonly CommandSpec[]): readonly DeclaredFlag[] {
+  const global = new Set(GLOBAL_FLAGS.map((flag) => flag.name));
+  return specs.flatMap((spec) =>
+    (spec.flags ?? [])
+      .filter((flag) => !global.has(flag.name))
+      .map((flag) => ({ command: spec.name, flag })),
+  );
+}
+
+/** A flag name is `[a-z][a-z-]*`, so nothing in it is a regex metacharacter to escape. */
+const literalOf = (name: string): RegExp => new RegExp(`(['"\`])${name}\\1`, 'g');
+
+/**
+ * The declaration itself, which is never a read. `{ name: 'critical', … }` and its `short:` twin
+ * are the two places the name appears as a spec field; every other occurrence of the bare literal
+ * is a reader — `flagBool(ctx.args, 'critical')`, a table key, a constant the reader indexes with.
+ */
+const declarationOf = (name: string): RegExp =>
+  new RegExp(`(?:name|short)\\s*:\\s*(['"\`])${name}\\1`, 'g');
+
+const countIn = (text: string, pattern: RegExp): number => [...text.matchAll(pattern)].length;
+
+/**
+ * Whether this file reads the flag, as against merely declaring it. Deliberately generous: a flag
+ * consumed only by being echoed into `--json`, or read through a shared constant rather than by
+ * name at the call site, is still read — the rule exists to catch a flag NOTHING mentions, and a
+ * gate that guessed at intent would report findings about working commands.
+ */
+export const readsFlag = (text: string, name: string): boolean =>
+  countIn(text, literalOf(name)) > countIn(text, declarationOf(name));
+
+const declaresFlag = (text: string, name: string): boolean =>
+  countIn(text, declarationOf(name)) > 0;
+
+const unreadFinding = (declared: DeclaredFlag, at: string): Finding => ({
+  code: 'X_CLI_FLAG_UNREAD',
+  cause: `x ${declared.command} declares --${declared.flag.name} ("${declared.flag.summary}") and no file in the CLI's source reads it, so the flag parses and changes nothing`,
+  fix: `read it in ${at} with flag${declared.flag.type === 'boolean' ? 'Bool' : 'String'}(ctx.args, '${declared.flag.name}'), or delete it from the spec's flags`,
+  docs: docsFor('X_CLI_FLAG_UNREAD'),
+  at,
+});
+
+/**
+ * Every declared flag held to one rule: something reads it.
+ *
+ * Scans source rather than the runtime, because "is this value ever consumed?" is not a question
+ * a `run` can be asked without running it — and running every command is not a check, it is the
+ * program. Comments are stripped first: a flag named only in the prose above the spec is not read,
+ * and a scanner that counted it would pass exactly the flags most likely to be dead.
+ */
+export async function checkFlagReads(
+  specs: readonly CommandSpec[],
+  srcDir: string,
+): Promise<readonly Finding[]> {
+  const paths: string[] = [];
+  try {
+    for await (const path of new Bun.Glob('**/*.ts').scan({ cwd: srcDir, absolute: false })) {
+      if (!/\.test\.tsx?$/.test(path)) paths.push(path);
+    }
+  } catch {
+    // The directory is not there. `Bun.Glob.scan` raises rather than yielding nothing, so the
+    // absent case has to be caught here — see the `texts.size` guard below for why it answers [].
+    // The scan is ALL that is inside the `try`, deliberately: a file the scan found and this
+    // cannot read must propagate, or an unreadable source answers "no findings" and the rule
+    // reports green over the half it could not see.
+    return [];
+  }
+  const texts = new Map<string, string>();
+  for (const path of paths) {
+    texts.set(path, stripComments(await Bun.file(join(srcDir, path)).text()));
+  }
+  // No CLI source under this root: the rule holds two halves against each other and only one is
+  // here, so there is nothing it can decide. Derived, not "is this the framework repo" — the same
+  // condition `scripts/release-workflow.ts` uses for a tree with no publishable workspace. Scanning
+  // on would report EVERY declared flag as unread, which is the false-positive direction and the
+  // one that trains a reader to ignore the check.
+  if (texts.size === 0) return [];
+  const findings: Finding[] = [];
+  for (const declared of declaredFlags(specs)) {
+    const name = declared.flag.name;
+    if ([...texts.values()].some((text) => readsFlag(text, name))) continue;
+    const declaringFile = [...texts].find(([, text]) => declaresFlag(text, name))?.[0];
+    findings.push(unreadFinding(declared, join(relative('', srcDir), declaringFile ?? '')));
+  }
+  return findings;
+}

package/src/i18n-audit.ts

@@ -8,6 +8,7 @@
 // root-relative POSIX shape every CLI-reported path is keyed by.
 import { existsSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
+import { renderThrowable } from '@ultimat3/core';
 import type { Catalog, Extraction, ExtractReport, Locale } from '@ultimat3/i18n';
 import {
   auditCatalogs,
@@ -51,7 +52,7 @@ function parseCatalogJson(path: string, raw: string): unknown {
   try {
     return JSON.parse(raw);
   } catch (error) {
-    throw catalogInvalid(path, error instanceof Error ? error.message : String(error));
+    throw catalogInvalid(path, renderThrowable(error));
   }
 }
 

package/src/index.ts

@@ -75,7 +75,7 @@ export {
   pgliteBranchName,
   previewUrl,
 } from './db-branch';
-export type { GeneratedFiles, GenerateMigrationOptions } from './db-generate';
+export type { GeneratedFiles, GenerateMigrationOptions, GenerateOutcome } from './db-generate';
 export { generateAppMigration, migrationSql } from './db-generate';
 export type { AssetRoutesOptions } from './dev-assets';
 export {
@@ -99,8 +99,14 @@ export type { DevServices, ServiceBinding } from './dev-services';
 export { describeServices, resolveServices } from './dev-services';
 export type { DispatchOptions } from './dispatch';
 export { dispatch } from './dispatch';
-export type { DeclaredEntityCount } from './drift';
-export { checkSourceDrift, recordedHashes, schemaHash, writeSchemaHash } from './drift';
+export type { DeclaredEntityCount, HashReconciliation } from './drift';
+export {
+  checkSourceDrift,
+  reconcileSchemaHash,
+  recordedHashes,
+  schemaHash,
+  writeSchemaHash,
+} from './drift';
 export type { ErrorCatalog } from './error-catalog';
 export {
   buildErrorCatalog,
@@ -111,12 +117,14 @@ export {
 } from './error-catalog';
 export type { CliErrorCode } from './error-codes';
 export { CLI_ERROR_CODES, CLI_ERROR_TITLES } from './error-codes';
+export type { ErrorFixReport } from './error-contract';
 export {
   BANNED_PHRASES,
   COMMAND_TOKENS,
   checkErrorCodeDocs,
   checkErrorCodeRegistry,
   checkErrorFixes,
+  checkErrorFixReport,
   collectDeclaredCodes,
   documentedCodes,
   fixProblem,
@@ -161,6 +169,12 @@ export {
   fixCitations,
   loadCommandCatalog,
 } from './fix-command';
+export type { HelperResolver } from './fix-imports';
+export { candidatePaths, createHelperResolver, scanImports } from './fix-imports';
+export type { FixHelper, FixScan } from './fix-scan';
+export { scanFixes, scanFixHelpers, scanFixSites } from './fix-scan';
+export type { DeclaredFlag } from './flag-reads';
+export { checkFlagReads, declaredFlags, readsFlag } from './flag-reads';
 export type { Guard } from './guards';
 export { findingProblem, GUARD_DIR, guardFindings, guardPaths } from './guards';
 export type { DrainFailure, DrainOutcome, DrainSkip } from './jobs-drain';
@@ -213,6 +227,7 @@ export {
   runRole,
   serveApp,
 } from './serve';
+export { quoteArg } from './shell-quote';
 export {
   eachSourceFile,
   isGenerated,
@@ -225,7 +240,7 @@ export { countsOf } from './test-counts';
 export type { TestFile } from './test-select';
 export { belongsToType, discoverTests, sampleFiles } from './test-select';
 export type { ReproduceOptions, RunShardsOptions, Shard } from './test-shards';
-export { planShards, quoteArg, reproduceFor, runShards, shardArgs } from './test-shards';
+export { planShards, reproduceFor, runShards, shardArgs } from './test-shards';
 export { availableCpus, defaultWorkers, WORKER_CEILING } from './test-workers';
 export type { CodeFixSite, CodeSite, FixSite, SourceSite } from './ts-scan';
 export {
@@ -234,7 +249,6 @@ export {
   scanBorrowedCodes,
   scanCodeFixSites,
   scanCodes,
-  scanFixes,
   stripComments,
 } from './ts-scan';
 // The one spelling rule for a `references` entry. Exported because the two gate scripts ask the

package/src/jobs-drain.ts

@@ -75,7 +75,12 @@ async function copySteps(source: JobDriver, target: JobDriver, runId: string): P
 /**
  * Hand a leased job back exactly as the drain found it. `countsAsAttempt: false` is the point:
  * a transfer that failed is not a failed attempt, and burning one per `x jobs drain` retry would
- * dead-letter a job nobody ever ran. It parks as `suspended`, which every driver claims.
+ * dead-letter a job nobody ever ran.
+ *
+ * It returns to `ready`, which is what "as the drain found it" means — the drain leased a ready
+ * job and could not move it. It used to land in `suspended`, not by intent but because
+ * `countsAsAttempt: false` was the only bit the drivers had and `step.sleep` had claimed it;
+ * `NackOptions.park` now carries the suspension, so the two callers no longer share one meaning.
  */
 async function releaseLease(source: JobDriver, id: string): Promise<void> {
   try {

package/src/mcp-errors.ts

@@ -22,6 +22,11 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // Runnable first, the narrowing behind a `#`: `x help <command> --json` pasted into a shell
   // is a redirect, not a command, and this table is copied verbatim by whoever reads it.
   X_CLI_BAD_FLAG: 'x help --json   # then narrow to the command the cause names',
+  // Not an `x` command: this rule is about the CLI's OWN declarations, it can only fire in this
+  // repo, and the suite that applies it is what reproduces the finding. A placeholder command
+  // would fail this table's own no-`<placeholder>` rule, and rightly — it would not run.
+  X_CLI_FLAG_UNREAD:
+    'bun test packages/cli/src/flag-reads.test.ts   # the finding names the flag and the file to read it in',
   X_VERIFY_FAILED: 'x verify --json',
   X_NOT_IN_APP: 'x new myapp --json && cd myapp',
   X_BUN_VERSION: 'bun upgrade',
@@ -93,6 +98,14 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
   X_DB_BRANCH_FAILED: 'x db branch ls --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
+  // know — a bare `x db seed --tier dev` would seed every dev fixture in production to answer a
+  // refusal about one. The dry run is what lists them, and the raised error's own `fix:` already
+  // carries the fully named invocation. `ULTIMATE_SEED_TIER=<tier>` is the other half of the
+  // consent and stays in the cause: it is the answer only for a container with a fixed argv.
+  X_SEED_ENVIRONMENT:
+    'x db seed --dry-run --json   # then name the tier: x db seed <name> --tier dev --json',
   X_BOUNDARY_SITE_TO_APP:
     'x verify --json   # then: x fix boundary <the file the finding names> --json',
   X_BOUNDARY_SHARED_LEAF:

package/src/mcp-host.ts

@@ -4,7 +4,7 @@
 // is a second catalog of routes, entities, actions, queries or jobs.
 
 import { join } from 'node:path';
-import { agentActor, isUltimateError, UltimateError } from '@ultimat3/core';
+import { agentActor, isUltimateError, renderThrowable, UltimateError } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
 import {
   ensureReadOnlyRole,
@@ -199,7 +199,9 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
         if (isUltimateError(error)) throw error;
         throw new UltimateError({
           code: 'X_DB_MIGRATE_FAILED',
-          cause: error instanceof Error ? error.message : String(error),
+          // The blessed total renderer: `String(error)` runs the value's own `toString`, and
+          // this is the last hop before an agent is handed the three-line result.
+          cause: renderThrowable(error),
           fix: 'x db reset',
         });
       }

package/src/messages.ts

@@ -46,10 +46,22 @@ const CATALOG = {
   'cli.db.branch.unknown': '-',
   'cli.db.gen.failed': 'migration not generated',
   'cli.db.gen.unchanged': 'entities and migrations agree — nothing to generate',
+  // A THIRD outcome, and it is neither of the other two: nothing to generate, but the sidecar the
+  // `drift` step reads did move — an edit under `packages/db/src` that implies no DDL. Rendering it
+  // as `written` would name a migration nobody can apply; as `unchanged`, it would hide a file this
+  // command wrote. `GeneratedFiles.outcome` is what `--json` carries the same distinction on.
+  'cli.db.gen.recorded': 'no migration needed — schema hash re-recorded in {file}',
   'cli.db.gen.written': 'migration {id} generated',
   'cli.db.migrate.applied': 'migrations applied',
   'cli.db.migrate.failed': 'migration failed',
   'cli.db.reset.done': 'database reset and migrated',
+  // Every seed counted per outcome, exactly as the backfill summary is: a replayed seed writes
+  // nothing and skips everything, and a total that hid that would make the second run look idle.
+  'cli.db.seed.done':
+    '{count} seed(s): {inserted} inserted, {updated} updated, {skipped} already stored',
+  'cli.db.seed.dryRun': '{count} seed(s) would run — nothing written while --dry-run is set',
+  'cli.db.seed.failed': '{failed} of {count} seed(s) failed',
+  'cli.db.seed.none': 'no seed matched — nothing to run',
   'cli.dev.ready': 'dev ready on {url} — /_x mounted ({panels} panels), {services}',
   // The mail and CDN halves of that boot line. Rendered text, so it lives here — while
   // `describeMail`/`describeCdn` keep the same wording as the fixed vocabulary `x dev --json`
@@ -158,6 +170,9 @@ const CATALOG = {
   '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}',
+  // The `errors` step's own coverage, in `output`: a scan without a parser reads most fix lines
+  // and not all of them, and a step that reports findings alone claims a completeness it lacks.
+  'cli.verify.fixCoverage': 'checked {checked} fix line(s), could not read {unreadable}',
   'cli.verify.serial': 'serial',
   'cli.verify.workers': '{workers} workers',
   'cli.env.checked': '{count} declared variable(s), all present and valid',

package/src/metrics-endpoint.ts

@@ -8,7 +8,11 @@ import {
   METRICS_PATH,
   markListening,
   metricsText,
+  stringField,
+  UltimateError,
 } from '@ultimat3/core';
+import { docsFor } from './error-codes';
+import { neighbouringPort } from './flag-number';
 
 /**
  * A port of its own, and NOT the role's HTTP port, for one reason the chart makes concrete:
@@ -25,6 +29,37 @@ import {
  */
 export const DEFAULT_METRICS_PORT = 9090;
 
+/**
+ * `X_PORT_IN_USE` is the code the CLI already registers for "this dev port is taken", and the
+ * scrape port is one — a synonym here would be a second code for one condition. The fix moves the
+ * port rather than naming a process to kill, because `METRICS_PORT` is the one knob both `x dev`
+ * and the container read (`serve.ts`'s `metricsPortFromEnv`).
+ *
+ * The port it names comes from `neighbouringPort`, never `port + 1`: at the top of the range
+ * that is 65536, and an instruction that cannot run is the failure this code exists to end.
+ */
+export class MetricsPortInUseError extends UltimateError {
+  constructor(input: { port: number }) {
+    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`,
+      docs: docsFor('X_PORT_IN_USE'),
+    });
+  }
+}
+
+/**
+ * Bun surfaces the bind failure as an `Error` carrying the libc code; nothing else is ours. Read
+ * through `stringField`, never `error instanceof Error` plus a property access: both run on a value
+ * this process did not build, and either can throw one line before the guard that was meant to make
+ * the path safe. Exported because whether the kernel refuses a second bind is the OS's business,
+ * not this package's — the contract worth pinning is that an EADDRINUSE-shaped throw becomes a
+ * coded refusal, and that is testable without racing a socket.
+ */
+export const isAddressInUse = (error: unknown): boolean =>
+  stringField(error, 'code') === 'EADDRINUSE';
+
 export interface MetricsEndpointOptions {
   /** 0 asks the kernel for an ephemeral port, which is what a test wants. */
   readonly port?: number;
@@ -45,20 +80,32 @@ export interface MetricsEndpoint {
  * signal at the moment of load is worse than no autoscaler.
  */
 export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): MetricsEndpoint {
-  const server = Bun.serve({
-    port: options.port ?? DEFAULT_METRICS_PORT,
-    hostname: options.hostname ?? 'localhost',
-    fetch(request: Request): Response {
-      if (new URL(request.url).pathname !== METRICS_PATH) {
-        return new Response('not found', { status: 404 });
-      }
-      // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot steal
-      // each other's samples — but a cache would hand the second one a stale window.
-      return new Response(metricsText(), {
-        headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+  const port = options.port ?? DEFAULT_METRICS_PORT;
+  // `startRoles` opens this FIRST, before any role, so `Bun.serve`'s own bare `Error` was what a
+  // second `x dev` on one machine reported: no code, no fix, at the boot path this package owns.
+  // The return type is inferred, keeping `Bun.serve`'s own shape stated once.
+  function listen() {
+    try {
+      return Bun.serve({
+        port,
+        hostname: options.hostname ?? 'localhost',
+        fetch(request: Request): Response {
+          if (new URL(request.url).pathname !== METRICS_PATH) {
+            return new Response('not found', { status: 404 });
+          }
+          // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot
+          // steal each other's samples — but a cache would hand the second one a stale window.
+          return new Response(metricsText(), {
+            headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+          });
+        },
       });
-    },
-  });
+    } catch (error) {
+      if (!isAddressInUse(error)) throw error;
+      throw new MetricsPortInUseError({ port });
+    }
+  }
+  const server = listen();
   // Same rule as every other socket the framework opens: announce it, so a request back to it is
   // recognisably this process calling itself rather than egress the test seal must refuse.
   const stopListening = markListening(server.url.origin);

package/src/otlp-export.ts

@@ -7,6 +7,8 @@ import {
   configureMetrics,
   configureTelemetry,
   logger,
+  noopExporter,
+  noopMetricExporter,
   onShutdown,
   otlpMetricExporter,
   otlpSpanExporter,
@@ -29,6 +31,14 @@ export const METRIC_EXPORT_INTERVAL_MS = 60_000;
  * Both are registered with `onShutdown(..., { phase: 'close' })`: the last spans of a drain are
  * the ones that explain the drain, and a process that exits with a full queue loses exactly the
  * window an operator went looking for.
+ *
+ * The release UNINSTALLS what it installed, per signal. `configureTelemetry`/`configureMetrics`
+ * 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
+ * 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.
  */
 export function startOtlpExport(env: Env = process.env): () => void {
   const releases: (() => void)[] = [];
@@ -41,6 +51,9 @@ export function startOtlpExport(env: Env = process.env): () => void {
   if (traces !== undefined) {
     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.
+    releases.push(() => configureTelemetry({ exporter: noopExporter }));
     releases.push(onShutdown('otlp-traces', () => exporter.shutdown(), { phase: 'close' }));
     logger.info('ultimate otlp traces', { endpoint: traces });
   }
@@ -49,6 +62,7 @@ export function startOtlpExport(env: Env = process.env): () => void {
   if (metrics !== undefined) {
     const exporter = otlpMetricExporter({ endpoint: metrics });
     configureMetrics({ exporter });
+    releases.push(() => configureMetrics({ exporter: noopMetricExporter }));
     // The push loop, and not only the exporter: `configureMetrics` names where a snapshot goes
     // and nothing decides when one is taken, so without this the collector receives one export —
     // the drain's — for the whole life of the process.

package/src/parse.ts

@@ -47,7 +47,12 @@ export interface CommandSpec {
    */
   readonly subcommandPositionals?: Readonly<Record<string, readonly string[]>>;
   readonly flags?: readonly FlagSpec[];
-  /** Command needs an app root (`app.config.ts`) — the dispatcher enforces it. */
+  /**
+   * Command needs an app root (`app.config.ts`). The dispatcher enforces it — `dispatch.ts`, before
+   * `target.run` — and until 2026-08 nothing read this field at all: the guarantee was kept only by
+   * each of the 17 declaring commands remembering to call `requireAppRoot` itself, so a new command
+   * that declared it and forgot the call ran outside an app with no refusal.
+   */
   readonly requiresApp?: boolean;
 }
 

package/src/seo-meta.ts

@@ -0,0 +1,105 @@
+// Single responsibility: the app's `site/` routes as `@ultimat3/seo` reads them.
+//
+// The two shapes only meet here. `RouteRecord.meta` is a STATIC object, and `defineRoute({ meta })`
+// is an async function of the route's own data — so somebody has to call one to get the other, and
+// this is the only tier that can see both: `@ultimat3/seo` is tier 1 and may not import the route
+// registry, which is tier 4.
+
+import { metaContextFor, type RouteEntry, routeDataFor, routeEntries } from '@ultimat3/render';
+import type { RouteRecord } from '@ultimat3/seo';
+import { loadApp } from './app-load';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/**
+ * Why a `site/` route's metadata cannot be read without running the app.
+ *
+ * Neither is a defect — both are routes whose `<head>` is a function of data that does not exist
+ * until a request does. They are reported rather than dropped, because a gate that silently checks
+ * two of five routes and says "ok" is worse than one that says which three it could not reach.
+ */
+export type UnresolvedReason = 'declares-load' | 'dynamic';
+
+export interface UnresolvedRoute {
+  readonly path: string;
+  readonly file: string;
+  readonly reason: UnresolvedReason;
+}
+
+export interface SiteMetaScan {
+  /** Routes whose meta resolved, in the shape `validateMeta` takes. */
+  readonly records: readonly RouteRecord[];
+  readonly unresolved: readonly UnresolvedRoute[];
+  /** A route whose `meta()` THREW — a page that cannot render its own head. */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * The origin `meta` is called with. Reserved by RFC 6761 and resolvable by nothing, deliberately:
+ * an app has no configured base URL (`packages/core/src/config.ts` declares none), so any real
+ * origin here would be this file inventing one — and a `canonical` compared against an invented
+ * origin is a finding nobody can act on. `validateMeta` is therefore called with no `baseUrl` and
+ * skips canonical checks; `absoluteUrl` never sees this string.
+ */
+const PROBE_ORIGIN = 'https://verify.invalid';
+
+const reasonFor = (entry: RouteEntry): UnresolvedReason | undefined => {
+  if (entry.pattern.keys.length > 0) return 'dynamic';
+  // A `load` is a database read. Running one inside `x verify` would make the gate need a live
+  // database to answer a question about text, and would run app queries nobody asked for.
+  if (entry.config.load !== undefined) return 'declares-load';
+  return undefined;
+};
+
+/**
+ * Read every `site/` route's metadata, without rendering and without touching a database.
+ *
+ * `routeDataFor` hands a no-`load` route its own context back as the data — that is exactly what
+ * `defineRoute`'s `LoadRequirement` guarantees — so `meta` gets the same argument here that it gets
+ * in `x dev` and in the prerenderer, from the same two builders both of those use.
+ */
+export async function scanSiteMeta(root: string): Promise<SiteMetaScan> {
+  await loadApp(root);
+  return await readSiteMeta();
+}
+
+/**
+ * The same scan over the registry as it stands, without loading anything.
+ *
+ * Split from `scanSiteMeta` so the resolution rules are testable against routes registered by hand:
+ * the half worth pinning is which routes are reachable and what happens when one throws, and
+ * neither of those is a fact about globbing a directory.
+ */
+export async function readSiteMeta(): Promise<SiteMetaScan> {
+  const records: RouteRecord[] = [];
+  const unresolved: UnresolvedRoute[] = [];
+  const findings: Finding[] = [];
+
+  for (const entry of routeEntries()) {
+    if (entry.surface !== 'site') continue;
+    const reason = reasonFor(entry);
+    if (reason !== undefined) {
+      unresolved.push({ path: entry.path, file: entry.file, reason });
+      continue;
+    }
+    const ctx = { url: `${PROBE_ORIGIN}${entry.path}`, params: {} };
+    try {
+      const meta = await entry.config.meta(
+        metaContextFor(ctx, await routeDataFor(entry.config, ctx)),
+      );
+      records.push({
+        path: entry.path,
+        file: entry.file,
+        surface: 'site',
+        render: entry.config.render,
+        meta,
+      });
+    } catch (error) {
+      // `findingFrom`, not a code of this file's own: a `meta` that throws an `UltimateError` has
+      // already said what broke and how to fix it, and a wrapper would bury both. Anything else
+      // becomes `X_CLI_UNEXPECTED` through core's total renderer.
+      findings.push({ ...findingFrom(error), at: entry.file });
+    }
+  }
+  return { records, unresolved, findings };
+}

package/src/serve.ts

@@ -86,6 +86,20 @@ export function metricsPortFromEnv(env: Env): number {
   return portValue(env, 'METRICS_PORT', DEFAULT_METRICS_PORT);
 }
 
+/**
+ * The scrape port a boot uses, given the app port it already resolved. One expression, and it is
+ * exported because `x dev` is the second caller: `cmd-dev.ts` passed no `metricsPort` at all, so
+ * `METRICS_PORT` was honoured in the container and ignored on a laptop — the dev/prod parity break
+ * `dev-roles.ts`'s own header forbids, and a second copy of this rule would be the same break
+ * one edit later.
+ *
+ * An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+ * fixed 9090 would fail the next suite to boot beside it. An environment that names the port still
+ * wins — that is the deploy talking.
+ */
+export const metricsPortFor = (env: Env, port: number, override?: number): number =>
+  override ?? (port === 0 && env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(env));
+
 /**
  * The one env var that turns error monitoring on, and the only vendor-shaped name in the boot
  * path. Not a platform primitive (axiom 7): the value is a URL to whatever the operator runs, the
@@ -302,9 +316,7 @@ async function bootRoles(boot: {
   // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
   // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
   // still wins — that is the deploy talking.
-  const metricsPort =
-    options.metricsPort ??
-    (port === 0 && options.env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(options.env));
+  const metricsPort = metricsPortFor(options.env, port, options.metricsPort);
   const running = await startRoles({
     roles: [role],
     port,

package/src/shell-quote.ts

@@ -0,0 +1,15 @@
+// POSIX single-quoting for a value the CLI pastes into a line a reader runs — a `fix:`, a
+// reproduce command. Its own module, and not `test-shards.ts` where it started, because the
+// subprocess boundary needs it too and `test-shards.ts` imports `exec.ts`: one leaf both can
+// reach is the alternative to an import cycle or a second quoter.
+
+const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
+
+/**
+ * A program name, a `--filter` or a path holding a space, a `$` or a `;` pastes back as two
+ * arguments or as a second command, so an unquoted line runs something other than what it claims.
+ * `'\''` is the only escape a single-quoted string has. A shell-safe value is left alone, so the
+ * common case stays readable.
+ */
+export const quoteArg = (value: string): string =>
+  SHELL_SAFE.test(value) ? value : `'${value.split("'").join("'\\''")}'`;