@ultimat3/cli 23.0.0 → 25.0.0

package/src/cmd-test.ts

@@ -5,6 +5,7 @@
 // there, because it is a fact about a git diff and not about a path: what the diff touches is
 // `affected.ts`, and this file only maps that answer onto the paths discovery yields.
 
+import { TEST_TYPES } from '@ultimat3/testing';
 import type { AffectedScope } from './affected';
 import { affectedScope, affectedScopeJson, DEFAULT_BASE, inScope } from './affected';
 import { testSpec } from './cmd-test-spec';
@@ -37,25 +38,22 @@ import {
 } from './test-workers';
 import { readVerifyFloor } from './verify-floor';
 import type { TestType } from './verify-tests';
-import { TEST_TYPES } from './verify-tests';
 
 /**
- * `--workers` and `--shard`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while
- * `cmd-verify.ts`'s own comment claimed `x test --workers` refused the same values `x verify`
- * does — so the two commands disagreed about the same flag. One reader now answers for both.
+ * `--workers`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while `cmd-verify.ts`'s
+ * own comment claimed `x test --workers` refused the same values `x verify` does — so the two
+ * commands disagreed about the same flag. One reader now answers for both.
  */
-const readIndex = (args: ParsedArgs, name: string, min: number): number | undefined =>
+const readWorkers = (args: ParsedArgs): number | undefined =>
   readIntFlag(args, {
-    name,
+    name: 'workers',
     command: 'test',
-    min,
+    min: 1,
     // The ceiling the summary already claimed and the reader never enforced: `--workers 5000` was
     // accepted and the run clamps only to the file count, which is one Bun worker per test FILE,
-    // each with the framework module graph and a cloned database. `--worker` is an index into an
-    // N-way split, so the same bound holds it (the exact upper index is `workers - 1`, refused a
-    // line below by the check that knows the real width).
+    // each with the framework module graph and a cloned database.
     max: WORKER_CEILING,
-    example: `x test --${name} ${Math.max(min, 1)}`,
+    example: 'x test --workers 1',
   });
 
 /**
@@ -168,29 +166,17 @@ export const testCommand: CliCommand = {
       });
     }
     const files = sample === undefined ? selected : sampleFiles(selected, sample);
-    const explicit = readIndex(ctx.args, 'workers', 1);
+    const explicit = readWorkers(ctx.args);
     const plan =
       explicit === undefined ? workerPlan(availableCpus(), totalMemory(), ctx.env) : undefined;
     const requested = explicit ?? (plan as WorkerPlan).workers;
     const floor = await readVerifyFloor(ctx.cwd);
     const isolate = flagBool(ctx.args, 'isolate') || floor?.isolate === true;
-    // The width a `--worker` index is judged against, and nothing else: which files really run one
-    // at a time is `test-passes.ts`, off the FILES rather than off the positional. This line read
-    // the positional alone until 2026-09 and the comment here claimed it made a serial type serial
-    // — true for `x test live`, false for the bare `x test --workers 8` that selects every type,
-    // which ran the same `live` and `e2e` files eight at a time. It stays because a `--worker` run
-    // is one process per CI JOB: sharding a serial type across N of them is the cluster-wide race
-    // in a second disguise, and refusing the index is where that is caught.
+    // A serial type is one worker whatever `--workers` says. `test-passes.ts` makes the same call
+    // off the FILES, which is what decides which files really run one at a time; this keeps the
+    // width the run reports and reproduces with the one it ran at.
     const ceiling = type !== undefined && SERIAL_TYPES.includes(type) ? 1 : files.length;
     const workers = Math.max(1, Math.min(requested, ceiling));
-    const only = readIndex(ctx.args, 'worker', 0);
-    if (only !== undefined && only >= workers) {
-      throw new BadFlagError({
-        flag: 'worker',
-        command: 'test',
-        reason: `shard ${only} does not exist in a ${workers}-worker split (0..${workers - 1})`,
-      });
-    }
     const result = await runShards({
       root: ctx.cwd,
       runner: ctx.runner,
@@ -201,11 +187,9 @@ export const testCommand: CliCommand = {
       // A default-width run leases its workers from the machine pool, so a second `x test` or
       // gate on the same box runs narrower instead of doubling its memory.
       ...(plan === undefined ? {} : withLease(machineLease(plan.workers, ctx.env))),
-      ...(only === undefined ? {} : { only }),
       ...(filter === undefined ? {} : { filter }),
       ...(type === undefined ? {} : { type }),
-      // `kept` is the corpus the split saw; a `--worker` rerun must name it, not its own shard.
-      // `selected`, not `discovered`: with `--affected` the sample was taken from the narrowed
+      // `kept` is the corpus the run saw. `selected`, not `discovered`: with `--affected` the sample was taken from the narrowed
       // set, and reporting the whole tree as its total would name a corpus no run ever had.
       ...(sample === undefined ? {} : { sample: { kept: files.length, total: selected.length } }),
       // The fourth input to the split. Without it a failing shard's `fix:` re-splits the whole

package/src/cmd-verify.ts

@@ -20,14 +20,13 @@ import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
 import { WORKER_CEILING, WORKER_FLOOR } from './test-workers';
 import { VERIFY_STEPS } from './verify-checks';
-import { VerifyMergeInputError, VerifyShardInvalidError } from './verify-errors';
 import { readVerifyFloor } from './verify-floor';
 import type { VerifyPart } from './verify-merge';
-import { coverageRiders, mergeParts, parsePart } from './verify-merge';
+import { coverageRiders, mergeParts, parsePart, VerifyMergeInputError } from './verify-merge';
 import { stepStream } from './verify-progress';
 import { runVerify } from './verify-run';
 import type { ShardSpec, Timings } from './verify-shard';
-import { assertShardable, parseShard, readTimings } from './verify-shard';
+import { assertShardable, parseShard, readTimings, VerifyShardInvalidError } from './verify-shard';
 import type { VerifyStepName } from './verify-step';
 import { VERIFY_STEP_NAMES } from './verify-step';
 import { writeErrorLine } from './write-line';
@@ -150,8 +149,9 @@ export const readOnlySteps = (args: ParsedArgs): readonly VerifyStepName[] | und
   if (unknown.length === 0) {
     return VERIFY_STEP_NAMES.filter((name) => items.includes(name));
   }
+  // An empty item corrects to nothing — never to whichever step is nearest to ''.
   const corrected = items.map((item) =>
-    isStepName(item) ? item : nearestName(item, VERIFY_STEP_NAMES),
+    isStepName(item) ? item : item === '' ? undefined : nearestName(item, VERIFY_STEP_NAMES),
   );
   const fix = corrected.every((item) => item !== undefined)
     ? `x verify --only ${renderFixShellArg([...new Set(corrected)].join(','), '<step,step>')} --json`

package/src/coverage-lcov.ts

@@ -4,7 +4,7 @@
 
 /** One `SF:` record, as written: its own totals and every `DA:` line. */
 export interface LcovRecord {
-  /** The `SF:` path, verbatim — Bun writes it relative to the directory the run started in. */
+  /** The `SF:` path with `/` separators — Bun writes it relative to the directory the run started in. */
   readonly file: string;
   /** `LF` / `LH` / `FNF` / `FNH`. Bun's lcov carries no `FN:` lines, so functions are counts only. */
   readonly linesFound: number;
@@ -25,7 +25,9 @@ export function parseLcov(text: string): readonly LcovRecord[] {
   let lines = new Map<number, number>();
   for (const line of text.split('\n')) {
     if (line.startsWith('SF:')) {
-      file = line.slice(3);
+      // `/` on every OS: Bun on Windows writes `apps\web\…`, and the app's source walk keys its
+      // files with `/`, so no record matched and the floor read 0% of a fully tested app.
+      file = line.slice(3).replaceAll('\\', '/');
       lf = 0;
       lh = 0;
       fnf = 0;

package/src/db-backfill.ts

@@ -10,7 +10,7 @@
 // which names were asked for, whether `--write` was passed, and what `x_migrations` says.
 
 import type { Environment } from '@ultimat3/core';
-import { createContext } from '@ultimat3/core';
+import { ctxOf } from '@ultimat3/core';
 import { db, isLedgerMissing, readLedger } from '@ultimat3/db';
 import type {
   BackfillDeclaration,
@@ -218,7 +218,7 @@ async function remainingFor(declaration: BackfillDeclaration): Promise<number |
   const count = handle === undefined ? undefined : backfillOrigin(handle)?.count;
   if (count === undefined) return null;
   try {
-    return await count({ ctx: createContext({ role: 'migrate' }) });
+    return await count({ ctx: ctxOf({ role: 'migrate' }) });
   } catch {
     return null;
   }

package/src/db-replay-engine.ts

@@ -6,13 +6,7 @@
 // why: Bun ships no path joiner.
 import { join } from 'node:path';
 import type { DbClient, LinkedExtensions, Migration } from '@ultimat3/db';
-import {
-  createPgliteClient,
-  createPostgresClient,
-  DbError,
-  linkPgliteExtensions,
-  raw,
-} from '@ultimat3/db';
+import { DbError, linkPgliteExtensions, pgliteClient, postgresClient, raw } from '@ultimat3/db';
 import { migrationExtensions } from './migration-extensions';
 
 type Env = Readonly<Record<string, string | undefined>>;
@@ -73,14 +67,14 @@ async function withPostgresScratch<T>(
   work: (client: DbClient) => Promise<T>,
 ): Promise<T> {
   const database = scratchName();
-  const admin = createPostgresClient({ url: adminUrl });
+  const admin = postgresClient({ url: adminUrl });
   try {
     // `template0`: the server's `template1` may carry objects an operator put there, and they
     // would be dumped as the app's.
     await admin.execute(raw(`create database ${database} template template0`));
     const target = new URL(adminUrl);
     target.pathname = `/${database}`;
-    const client = createPostgresClient({ url: target.toString() });
+    const client = postgresClient({ url: target.toString() });
     try {
       return await work(client);
     } finally {
@@ -103,7 +97,7 @@ export async function withScratchDatabase<T>(
   work: (client: DbClient) => Promise<T>,
 ): Promise<T> {
   if (engine.kind === 'postgres') return withPostgresScratch(engine.adminUrl, work);
-  const client = createPgliteClient({
+  const client = pgliteClient({
     extensions: engine.extensions,
     ...(stateDir === undefined ? {} : { snapshotDir: join(stateDir, 'cache') }),
   });

package/src/db-subscribes.ts

@@ -1,8 +1,9 @@
-// Single responsibility: which tables `x db gen` must grant `REPLICA IDENTITY FULL`, read off the
-// live queries' DECLARED `subscribes:` — and the refusal for a declared name no entity's table
-// matches. This tier is the only one holding both registries, so it is the only one that can ask.
+// Single responsibility: which tables `x db gen` must grant `REPLICA IDENTITY FULL` — the `records`
+// tables of every channel with params, and since #518 never a live query's `subscribes:` — and the
+// refusal for a declared `subscribes:` name no entity's table matches. Only this tier holds both.
 
 import { UltimateError } from '@ultimat3/core';
+import { paramsChannelTables } from '@ultimat3/realtime/server';
 
 /**
  * The two fields this reads, and nothing else. Structurally satisfied by `QueryDescriptor` (whose
@@ -28,11 +29,10 @@ function offer(tables: ReadonlySet<string>): string {
 /**
  * A live read declares a relation this app has no entity for.
  *
- * Refused rather than dropped, and that is the whole point of the check: `@ultimat3/db` keeps only
- * the declared names an entity's table matches (`replica-identity.ts`), so an EXTRA name is
- * discarded in silence — and `@ultimat3/query` has no table catalog, so its own `subscribes:`
- * assertions cannot see one either. A typo therefore granted `REPLICA IDENTITY FULL` to nothing
- * while its author read the declaration as granted, which is the failure #357 exists to end.
+ * Refused rather than dropped: `@ultimat3/query` has no table catalog, so its own `subscribes:`
+ * assertions cannot see a name no table has — and a typo there is a declaration its author reads
+ * as true. Until #518 the list also chose which tables got `REPLICA IDENTITY FULL`, so the typo
+ * granted it to nothing (#357); the grant is gone, the declaration's honesty still matters.
  *
  * The name goes in the `cause` and never into a command: it is a string from the app's own source,
  * and the remedy is an edit to a field rather than anything to paste at a shell.
@@ -46,8 +46,8 @@ export class QuerySubscribesUnknownError extends UltimateError {
         'declares a table with that name',
       fix:
         `edit subscribes: on the query "${input.query}" to name a table this app declares ` +
-        `(${offer(input.tables)}), or drop the name — x db gen grants REPLICA IDENTITY FULL to ` +
-        'exactly the tables it lists, and would have granted it to nothing',
+        `(${offer(input.tables)}), or drop the name, then x db gen "fix subscribes" --json — a ` +
+        'name no table has can never match what the read selects from (X_QUERY_SUBSCRIBES_DRIFT)',
       meta: { query: input.query, table: input.table },
     });
   }
@@ -56,26 +56,37 @@ export class QuerySubscribesUnknownError extends UltimateError {
 /**
  * The tables to hand `GenerateOptions.replicaIdentityFull`, deduped and sorted.
  *
+ * A live query's `subscribes:` is VALIDATED here and never granted (#518, owner decision O-518):
+ * every entity has a primary key — `entity()` refuses one without — and a live query over a keyed
+ * table is correct on DEFAULT identity, because the shared window holds the whole row the
+ * in/out/delete decision needs (`realtime/src/pg-identity-window.live.test.ts`, on real WAL). FULL
+ * there only made every UPDATE and DELETE log the whole old row. A table already on FULL keeps it:
+ * `replica-identity.ts` never reverts, and the drift step reads a recorded FULL as agreement.
+ *
  * Sorted so the same app generates the same bytes whatever order its modules registered in — the
  * rule `@ultimat3/db`'s own `pending()` states one layer down, kept here too because a caller that
  * ordered by registration would put a diff in a file for nothing.
  *
- * Every name is checked against `tables` BEFORE any of them is returned: a run that emitted the
- * good half and refused afterwards would leave an author with a migration that is right for one
- * table and silently absent for the other.
+ * Every `subscribes:` name is checked against `tables` BEFORE anything is returned, so a refused
+ * declaration never leaves a migration half-written behind it.
+ *
+ * `channelTables` defaults to what the declared channels need (`paramsChannelTables()`): a channel
+ * with params routes a DELETE to the topic the OLD row names, and under the default identity that
+ * image is the key alone — no topic, no `remove`, and members keep the deleted record. They are
+ * derived from entity projections rather than typed by an author, so one outside `tables` is
+ * dropped, not refused: there is no declaration to send anyone back to.
  */
 export function replicaIdentityTables(
   queries: readonly SubscribingQuery[],
   tables: ReadonlySet<string>,
+  channelTables: readonly string[] = paramsChannelTables(),
 ): readonly string[] {
-  const wanted = new Set<string>();
   for (const query of queries) {
     for (const table of query.subscribes ?? []) {
       if (!tables.has(table)) {
         throw new QuerySubscribesUnknownError({ query: query.name, table, tables });
       }
-      wanted.add(table);
     }
   }
-  return [...wanted].sort();
+  return [...new Set(channelTables.filter((table) => tables.has(table)))].sort();
 }

package/src/dev-boot.ts

@@ -0,0 +1,290 @@
+// `x dev`'s boot: every role in one Bun process, embedded Postgres/events/storage started for real,
+// the app's own modules loaded into the framework's registries, the route table they hold served
+// over HTTP with `/_x` beside it, and the watcher that rebuilds on save (`dev-rebuild.ts`). The
+// command that prints it and holds the process is `cmd-dev.ts`.
+
+import { devShellStyle } from '@ultimat3/admin/dev';
+import type { Role } from '@ultimat3/core';
+import { configureTelemetry, noopExporter } from '@ultimat3/core';
+import { setStatementObserver } from '@ultimat3/db';
+import type { OverlayNotice, RequestContext } from '@ultimat3/http';
+import { asCtx } from '@ultimat3/http';
+import { loadSignInPath } from './app-auth';
+import { appManifest } from './app-manifest';
+import type { StalePin } from './app-reload-graph';
+import { enableReloadTracking } from './app-reload-graph';
+import { loadAppRuntime } from './app-runtime';
+import type { DevDashboardInput, DevStatus } from './dev-dashboard';
+import { devPanels } from './dev-dashboard';
+import { declareDevEnvironment, needsDevEnvironmentDeclaration } from './dev-environment';
+import { createStatementLedger } from './dev-n-plus-one';
+import type { DevState } from './dev-rebuild';
+import { devRebuilder } from './dev-rebuild';
+import { devRouteTable } from './dev-route-table';
+import { createTraceRecorder } from './dev-traces';
+import { watchTree } from './dev-watch-tree';
+import { buildIslands } from './island-bundle';
+import { FRAME_STYLE } from './island-harness';
+import type { Finding } from './output';
+import type { RunningRoles } from './role-start';
+import { DEV_ROLES, startRoles } from './role-start';
+import type { DevServices } from './runtime-bindings';
+import { resolveServices, withRealtimeEvents } from './runtime-bindings';
+import { attachedIsr } from './runtime-isr';
+import type { RuntimeOverrides } from './runtime-overrides';
+import { replicaOverrides } from './runtime-replica';
+import type { RunningServices } from './runtime-services';
+import { releaseOrThrow, startServices } from './runtime-services';
+import { metricsPortFor, releaseBoot } from './serve';
+import { loopFacts, loopFinding, loopNotice } from './statement-loop';
+
+export interface DevServer {
+  readonly url: string;
+  readonly services: DevServices;
+  readonly roles: readonly Role[];
+  /**
+   * `BUILD_ID` when stamped — the id every response carries. Otherwise the manifest as it stands
+   * now, so a reload that registers a new route moves it.
+   */
+  readonly buildId: string;
+  /**
+   * Modules that would not import, primitives that would not register, reloads that would not
+   * build — and the statement loops this process has counted so far, which is what puts an N+1 in
+   * `x dev`'s own output and in `--json` without a channel of its own.
+   */
+  readonly findings: readonly Finding[];
+  readonly running: RunningRoles;
+  readonly runtime: RunningServices;
+  /** Panel keys `/_x` mounted, in tab order. Reported so `--json` names what is reachable. */
+  readonly panels: readonly string[];
+  /** `POST <path>` of the app's default MCP endpoint, or `null` when nothing was mounted. */
+  readonly mcp: string | null;
+  /** `POST <path>` of every mounted MCP endpoint, default first — `[]` when none was. */
+  readonly mcpPaths: readonly string[];
+  stop(): Promise<void>;
+}
+
+export interface StartDevOptions {
+  readonly root: string;
+  readonly port: number;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly roles?: readonly Role[];
+  readonly onReload?: (file: string, durationMs: number) => void;
+  /**
+   * A save reached a module that defines a primitive, so this process cannot serve it
+   * (`takeStalePins`). Given, it is called INSTEAD of `onReload` — `x dev`'s child drains and exits
+   * for its supervisor to boot a fresh one. Absent, the save is `X_DEV_RESTART_REQUIRED` on `/_x`.
+   */
+  readonly onRestart?: (pins: readonly StalePin[]) => void;
+}
+
+/**
+ * The environment `devDashboard` refuses to mount in. Spread conditionally rather than passed as
+ * `undefined`: `exactOptionalPropertyTypes` makes "absent" and "explicitly undefined" different
+ * answers, and only the absent one lets the dashboard read the process environment itself.
+ */
+const envOf = (env: StartDevOptions['env']): { env?: string } => {
+  const value = env['NODE_ENV'] ?? env['X_ENV'];
+  return value === undefined ? {} : { env: value };
+};
+
+/**
+ * Boot order is the production order: services first, then the app's modules (importing them IS
+ * the registration), then the roles that serve what those modules registered. A module that
+ * fails to import becomes a finding rather than a dead process — the point of the dev loop is to
+ * still be reachable while something is broken.
+ */
+export async function startDev(options: StartDevOptions): Promise<DevServer> {
+  // EVERY boot: a scratch server (`x shot`, `ui.shot`) boots here too, and without this a
+  // fail-closed dev actor installs nothing — the picture is of a 401. Idempotent.
+  declareDevEnvironment(options.env);
+  // Before the first scan: the watcher's rescans evict a saved module AND everything importing it,
+  // and that needs the import graph recorded as each module is first loaded (`app-reload-graph.ts`).
+  enableReloadTracking(true);
+  // The declaration lands on `process.env`; the env this boot passes on must carry it too, or every
+  // service resolved from `options.env` still reads no `ULTIMATE_ENV`.
+  const env = needsDevEnvironmentDeclaration(options.env)
+    ? { ...options.env, ULTIMATE_ENV: 'development' }
+    : options.env;
+  const resolved = resolveServices(options.root, env);
+  // The app's `apps/<app>/runtime.ts`, read ONCE and handed to `startServices` exactly as
+  // `serve.ts`'s `withAppRuntime` does — so the disks (`storage`), the queue, the mail driver and
+  // every other override a deployment declares are the ones development runs too. Until 22.4 this
+  // boot passed nothing here and built its own embedded disk, so an app's `/_storage` routes and its
+  // actions wrote to two different places in `x dev` and to one in production.
+  const appRuntime = await loadAppRuntime(options.root);
+  const runtime: RunningServices = await startServices(resolved, env, appRuntime);
+  // The events binding the boot line reports is the bus the runtime chose, read off it.
+  const services = withRealtimeEvents(resolved, env, runtime.realtime);
+  // `serve.ts`'s `releaseBoot` shape: everything acquired from here on is released, newest first,
+  // if the boot throws — a failed `x dev` left PGlite holding `.x/pgdata` for the retry to meet.
+  const acquired: (() => void | Promise<void>)[] = [() => runtime.stop()];
+  try {
+    return await bootDev(options, services, runtime, acquired, appRuntime);
+  } catch (error) {
+    await releaseBoot(acquired);
+    throw error;
+  }
+}
+
+async function bootDev(
+  options: StartDevOptions,
+  services: ReturnType<typeof resolveServices>,
+  runtime: RunningServices,
+  acquired: (() => void | Promise<void>)[],
+  appRuntime: RuntimeOverrides | undefined,
+): Promise<DevServer> {
+  // Installed before the app loads, so a span opened during registration is already recorded.
+  // Tracing is always on in the framework and free until an exporter is configured; `x dev` is
+  // what configures one, which is the whole reason `/_x/timeline` has anything to draw.
+  const traces = createTraceRecorder();
+  configureTelemetry({ exporter: traces.exporter });
+  acquired.push(() => {
+    configureTelemetry({ exporter: noopExporter });
+    traces.reset();
+  });
+  // Installed at the same moment and for the same reason: an observer is the single switch that
+  // turns statement instrumentation on at all (`@ultimat3/db`'s `observe.ts`), so the timeline's
+  // SQL rows and the repeat counts arrive together rather than through two toggles. `serve.ts`
+  // installs neither — a production process pays the one `undefined` branch the seam costs
+  // uninstalled, and nothing more (axiom 6).
+  const statements = createStatementLedger();
+  setStatementObserver(statements.observer);
+  acquired.push(() => {
+    setStatementObserver(undefined);
+    statements.reset();
+  });
+  // ONE load at boot, the same call the rebuild below makes: the manifest and the findings are
+  // two projections of one scan. Until 2026-09-07 this was `loadApp` for the findings and then
+  // `appManifest` — which loads again — for the manifest, so a save landing between the two put
+  // `/_x`'s findings and its manifest on different registration states.
+  const app = await appManifest(options.root);
+  const state: DevState = {
+    manifest: app.manifest,
+    reloads: 0,
+    reloadFinding: undefined,
+    appFindings: app.findings,
+    islands: await buildIslands(options.root),
+  };
+  // The manifest's build id is a content hash of every fact below it, so a dev document's
+  // `x-ultimate-build` header names the exact shape the client was served against. Pinned at
+  // boot on purpose: the header is handed to the HTTP config and the render modes once, and a
+  // reload cannot re-pin it — `state.manifest.buildId` is what `/_x` and `--json` report, so a
+  // divergence between the two is visible rather than silent, and a restart closes it.
+  // `BUILD_ID` wins when set — `serve.ts`'s rule, so an e2e `deploy.newBuild()` can restart `x dev`
+  // as a new build with the same sources.
+  // Stamped, it is ALSO what `server.buildId` answers below: the process serves no other build.
+  const rawStamp = options.env['BUILD_ID'];
+  const stamped = rawStamp !== undefined && rawStamp !== '' ? rawStamp : undefined;
+  const buildId = stamped ?? state.manifest.buildId;
+
+  let server: DevServer;
+  // Read at request time, never captured at boot: `/_x/services` must report the reload counter
+  // and the findings as they are now, not as they were when the route table was built.
+  const dashboard: DevDashboardInput = {
+    root: options.root,
+    runtime,
+    status: (): DevStatus => ({
+      url: server.url,
+      services: server.services,
+      roles: server.roles,
+      findings: server.findings,
+      reloads: state.reloads,
+    }),
+    traces,
+    statements,
+    ...envOf(options.env),
+  };
+  const panels = devPanels(dashboard).map((panel) => panel.key);
+
+  // `x dev`'s own, so a reload can empty it (a save otherwise kept a page's first render for its
+  // ttl); attached, so a tag bust reaches it too. Released with the roles.
+  const { isr, release: releaseIsr } = attachedIsr({ buildId });
+  acquired.push(releaseIsr);
+  const { routes, theme, speculation, inlineStyles, mcpPath, mcpPaths } = await devRouteTable({
+    isr,
+    root: options.root,
+    env: options.env,
+    buildId,
+    storage: runtime.storage,
+    dashboard,
+    islands: () => state.islands,
+    realtime: runtime.realtime,
+    rateLimitStore: appRuntime?.rateLimitStore ?? runtime.rateLimitStore,
+    appRoutes: appRuntime?.routes,
+    images: appRuntime?.images,
+  });
+
+  // The app's `apps/<app>/runtime.ts`, composed exactly as `runRole` composes a caller's
+  // `runtime`: the replica scope in front, the app's own middleware behind it. Before this the
+  // first argument was `undefined` here and an app's middleware reached no development process.
+  const replicaOverride = replicaOverrides(appRuntime, services.db, options.env);
+  const running = await startRoles({
+    roles: options.roles ?? DEV_ROLES,
+    port: options.port,
+    // `serve.ts`'s expression, called rather than restated: `METRICS_PORT` was read in the
+    // container and ignored here, so the scrape port an operator moved was the one port `x dev`
+    // could not move — and the second `x dev` on a box died binding the hardcoded 9090.
+    metricsPort: metricsPortFor(options.env, options.port),
+    buildId,
+    runtime,
+    routes,
+    env: options.env,
+    // Read from `app.config.ts` rather than threaded through `DevOptions`: `x dev` and `serve.ts`
+    // must not be able to disagree about where the app's sign-in page is.
+    signInPath: await loadSignInPath(options.root),
+    // The same seam `serve.ts` passes: the app's own error page is a FILE under this root.
+    root: options.root,
+    // The `/_x` shell, the harness's frame, the app's own error pages and its brand — the inline
+    // bodies this process serves; the app's surfaces are content-hashed files `'self'` admits.
+    inlineStyles: [await devShellStyle(), FRAME_STYLE, ...inlineStyles],
+    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
+    // The overlay renders this request's own loops under the error it is already showing.
+    // `serve.ts` boots through the same `startRoles` and passes nothing (axiom 6).
+    devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>
+      statements.repeatsFor(asCtx(ctx)).map(loopFacts).map(loopNotice),
+    // The read-replica scope, opened per request. Absent for every app that names no
+    // `DATABASE_REPLICA_URL` — which is every embedded boot by construction, since PGlite has no
+    // standby — so this key does not exist on a homework app's boot at all.
+    ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
+  });
+  acquired.push(() => running.stop());
+
+  const rebuild = devRebuilder(options, state, isr);
+  // Watched one directory at a time, so an ignored one costs no descriptor at all — `dev-watch.ts`
+  // decides which, from the app's own `.gitignore`. A recursive watch on the root registered one
+  // inotify descriptor per directory in the tree, `.git/`, `node_modules/` and the `.x/` this
+  // process writes to included, and filtered the events afterwards.
+  const watcher = watchTree({ root: options.root, onChange: rebuild });
+
+  server = {
+    url: running.url ?? `http://localhost:${options.port}`,
+    services,
+    roles: running.roles,
+    mcp: mcpPath,
+    mcpPaths,
+    get buildId(): string {
+      return stamped ?? state.manifest.buildId;
+    },
+    // A getter, not a snapshot: `/_x` and `--json` must show the reload that just failed and the
+    // loop the last request tripped, not the findings as they were when the route table was built.
+    // The loops come last and carry their request id, so a boot report reads as a boot report and
+    // a diagnostic that arrived a minute later reads as one too.
+    get findings(): readonly Finding[] {
+      const loops = statements.repeats().map(loopFacts).map(loopFinding);
+      return state.reloadFinding === undefined
+        ? [...state.appFindings, ...loops]
+        : [...state.appFindings, state.reloadFinding, ...loops];
+    },
+    running,
+    runtime,
+    panels,
+    // The boot's own unwind list IS the stop list — one list, so the two cannot drift — plus the
+    // watcher. Every step runs and the first failure is rethrown (`releaseOrThrow`): one refused
+    // role stop used to leave PGlite's lock held for the next `x dev`. Newest first: the watcher,
+    // the roles, ISR, the statement ledger and the exporter (after the roles, so an in-flight
+    // request still has both), then the services.
+    stop: () => releaseOrThrow([...acquired, () => watcher.close()]),
+  };
+  return server;
+}