@ultimat3/cli 19.1.3 → 19.3.1

package/src/cmd-dev.ts

@@ -4,7 +4,6 @@
 // alongside it — mounted, never re-implemented — so an agent can introspect the running app.
 // No Docker, no env setup: an unset variable means the embedded default.
 
-import { watch } from 'node:fs';
 import { join } from 'node:path';
 import { devShellStyle } from '@ultimat3/admin/dev';
 import type { Role } from '@ultimat3/core';
@@ -29,6 +28,7 @@ import { devDashboardRoutes, devPanels } from './dev-dashboard';
 import { liveFeedLabel } from './dev-live-feed';
 import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
+import { coalesceReloads } from './dev-reload';
 import { appRoutes } from './dev-render';
 import { replicaOverrides } from './dev-replica';
 import type { RunningRoles } from './dev-roles';
@@ -39,10 +39,12 @@ import type { DevServices } from './dev-services';
 import { describeServices, reportedUrls, resolveServices } from './dev-services';
 import { storageRoutes } from './dev-storage';
 import { createTraceRecorder } from './dev-traces';
+import { watchTree } from './dev-watch-tree';
 import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands } from './island-bundle';
+import { FRAME_STYLE } from './island-harness';
 import { islandHarnessRoutes } from './island-harness-route';
 import { islandRoutes } from './island-routes';
 import { loadIslandStates } from './island-states-load';
@@ -53,6 +55,8 @@ import { flagString } from './parse';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { metricsPortFor } from './serve';
 import { loopFacts, loopFinding, loopNotice } from './statement-loop';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
 
@@ -92,22 +96,6 @@ interface DevState {
   islands: IslandBundle;
 }
 
-/** Debounced: a save that touches five files is one reload, not five. */
-function watchApp(root: string, onChange: (file: string) => void): () => void {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let last = '';
-  const watcher = watch(root, { recursive: true }, (_event, filename) => {
-    if (filename === null || filename.includes('.x/') || filename.includes('node_modules')) return;
-    last = filename;
-    if (timer !== undefined) clearTimeout(timer);
-    timer = setTimeout(() => onChange(last), 30);
-  });
-  return () => {
-    if (timer !== undefined) clearTimeout(timer);
-    watcher.close();
-  };
-}
-
 export interface StartDevOptions {
   readonly root: string;
   readonly port: number;
@@ -191,7 +179,13 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   const serviceWorker =
     pwa === undefined
       ? undefined
-      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands: state.islands });
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands: state.islands,
+          styles: styleBundle(),
+        });
 
   // The app's own MCP endpoint, discovered from `apps/<app>/mcp.ts` and mounted through the SAME
   // call `runRole` makes — `POST /mcp` answered 404 in every process the framework booted until
@@ -215,6 +209,10 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // The chunks the documents below name. Mounted before the app's routes for the reason
     // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
     ...islandRoutes(() => state.islands),
+    // And the stylesheet every one of those documents links. Read through the getter for the
+    // reason the islands are: a rebuilt island registers CSS, which mints a new URL, and a table
+    // captured at boot would answer 404 for the href the document now carries.
+    ...styleRoutes(() => styleBundle()),
     // `x shot --island`'s harness, in the `/_x` dev namespace so no app route can shadow it. It
     // lives here rather than in a second server because everything it needs is in THIS process:
     // the built chunks, the app's stylesheet registry, and the one embedded Postgres a checkout
@@ -258,10 +256,12 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // The same seam `serve.ts` passes: the app's own error page is a FILE, so the root is what
     // `startWeb` needs to find one.
     root: options.root,
-    // The one document this process serves that the app did not write; `startRoles` covers the
-    // app's own surfaces itself. `x dev` sends the policy report-only, so an uncovered `<style>`
-    // here is a console report rather than a blank page — which is how this reached production.
-    inlineStyles: [await devShellStyle()],
+    // The documents this process serves that the app did not write — the `/_x` shell and the
+    // screenshot harness's frame. The app's OWN surfaces need no entry any more: their CSS is a
+    // content-hashed file `'self'` already admits (`style-bundle.ts`). `x dev` sends the policy
+    // report-only, so an uncovered `<style>` here is a console report rather than a blank page —
+    // which is how this reached production.
+    inlineStyles: [await devShellStyle(), FRAME_STYLE],
     // The fourth surface, and the only one an author sees without leaving the page they broke:
     // 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, so production has no
@@ -274,22 +274,32 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
   });
 
-  const stopWatching = watchApp(options.root, (file) => {
-    const started = performance.now();
-    void Promise.all([appManifest(options.root), buildIslands(options.root)])
-      .then(([{ manifest }, islands]) => {
-        state.manifest = manifest;
-        state.islands = islands;
-        state.reloads += 1;
-        state.reloadFinding = undefined;
-        options.onReload?.(file, Math.round(performance.now() - started));
-      })
-      // Same rule as a module that will not import: a save the manifest cannot be rebuilt from is
-      // a finding on `/_x`, never an unhandled rejection that takes the dev server down.
-      .catch((error: unknown) => {
-        state.reloadFinding = { ...findingFrom(error), at: file };
-      });
-  });
+  // One rebuild at a time, and the last save wins: a tick arriving mid-build coalesces into ONE
+  // trailing rebuild instead of racing the one in flight for `state.manifest` and `state.islands`.
+  const rebuild = coalesceReloads(
+    async (file) => {
+      const started = performance.now();
+      const [{ manifest }, islands] = await Promise.all([
+        appManifest(options.root),
+        buildIslands(options.root),
+      ]);
+      state.manifest = manifest;
+      state.islands = islands;
+      state.reloads += 1;
+      state.reloadFinding = undefined;
+      options.onReload?.(file, Math.round(performance.now() - started));
+    },
+    // Same rule as a module that will not import: a save the manifest cannot be rebuilt from is
+    // a finding on `/_x`, never an unhandled rejection that takes the dev server down.
+    (error: unknown, file: string) => {
+      state.reloadFinding = { ...findingFrom(error), at: file };
+    },
+  );
+  // 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}`,
@@ -313,7 +323,7 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     runtime,
     panels,
     async stop() {
-      stopWatching();
+      watcher.close();
       await running.stop();
       await runtime.stop();
       // Released after the roles: a span opened by an in-flight request still has an exporter to

package/src/cmd-doctor.ts

@@ -4,16 +4,25 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { ERROR_DOCS_URL, tryResolveEnvironment, usesDevCursorSecret } from '@ultimat3/core';
+import {
+  ENV_EXAMPLE_PATH,
+  ERROR_DOCS_URL,
+  tryResolveEnvironment,
+  usesDevCursorSecret,
+} from '@ultimat3/core';
 import { checkDb, createPostgresClient } from '@ultimat3/db';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
-import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
+import { syncPortFor } from './dev-sync';
+import type { OfflineFallbackFact } from './doctor-offline';
+import { offlineFallbackFinding, offlineFallbackProbe } from './doctor-offline';
+import { intFlagOr, PORT_RANGE, portPairAfter } from './flag-number';
 import { ICON_SOURCE } from './icon-assets';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
+import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
 import { portFree } from './port-probe';
 import { checkMigrationDrift } from './schema-drift';
@@ -59,6 +68,12 @@ export interface DoctorProbe {
    * separate remedies — one is "generate a migration", the other is "this migration is incomplete".
    */
   snapshots(): Promise<readonly Finding[]>;
+  /**
+   * What the app declared as its offline fallback, and which routes it really serves. A FACT and
+   * not a finding, because deciding is `offlineFallbackFinding`'s and this seam's whole job is
+   * reaching the disk — the same split `drift()` makes one question over.
+   */
+  offlineFallback(): Promise<OfflineFallbackFact>;
 }
 
 const finding = (code: string, cause: string, fix: string, at?: string): Finding =>
@@ -66,7 +81,8 @@ const finding = (code: string, cause: string, fix: string, at?: string): Finding
     ? { code, cause, fix, docs: ERROR_DOCS_URL }
     : { code, cause, fix, docs: ERROR_DOCS_URL, at };
 
-export const OFFLINE_FALLBACK = 'apps/web/app/offline.tsx';
+/** The file `x doctor` reports missing, and the one the reader creates. */
+export const ENV_DEVELOPMENT = '.env.development';
 
 /** The port `x dev` binds by default, so the probe answers about the port the developer will use. */
 const DEFAULT_DOCTOR_PORT = 3000;
@@ -80,12 +96,30 @@ const DEFAULT_DOCTOR_PORT = 3000;
  * derives `PORT = .port - 1` from it, so it is part of the contract `x dev` runs by.
  *
  * The suggested port moves BOTH: `x dev --port N` occupies N and N+1, so a free N beside a taken
- * N+1 is still not a runnable command.
+ * N+1 is still not a runnable command. It did not move both until 2026-09 — the line was
+ * `neighbouringPort(probe.port)`, which for the sync finding IS the port the finding is about, and
+ * a docblock claiming otherwise is how it survived. `portPairAfter` is the one reader of that rule
+ * and `dev-sync.ts`'s own refusal shares it.
+ *
+ * The sync port is `syncPortFor`, never `neighbouringPort` again: that helper answers 65534 for a
+ * web port of 65535 — BELOW the web port, and a port `x dev` never binds — where the boot refuses
+ * the run outright with `X_PORT_INVALID`. A probe that reports on a socket the command would never
+ * open is answering a question nobody asked, so the boot's own rule decides, and its refusal is
+ * reported instead of a probe. Alone, and ahead of the web port: there is no runnable `x dev` at
+ * this port whatever the other one answers, and a second finding about it is noise over the cause.
  */
 async function portFindings(probe: DoctorProbe): Promise<readonly Finding[]> {
+  let syncPort: number;
+  try {
+    syncPort = syncPortFor(probe.port);
+  } catch (error) {
+    // The boot's own error, carried whole — `findingFrom` reads its code, cause and fix off the
+    // value rather than rendering it, which is what `scripts/catch-render.ts` requires.
+    return [findingFrom(error)];
+  }
   const wanted = [
     { port: probe.port, role: 'web' },
-    { port: neighbouringPort(probe.port), role: 'sync' },
+    { port: syncPort, role: 'sync' },
   ] as const;
   const findings: Finding[] = [];
   for (const entry of wanted) {
@@ -94,10 +128,7 @@ async function portFindings(probe: DoctorProbe): Promise<readonly Finding[]> {
       finding(
         'X_PORT_IN_USE',
         `port ${entry.port} is already listening, and \`x dev --port ${probe.port}\` binds it for the ${entry.role} role`,
-        // Unchanged, and deliberately: the neighbour below the top of the range is the one port
-        // `x dev` is guaranteed to accept (`X_CLI_BAD_FLAG` otherwise), which is what
-        // `cmd-doctor.test.ts` pins by parsing this line with `x dev`'s own flag reader.
-        `x dev --port ${neighbouringPort(probe.port)}`,
+        `x dev --port ${portPairAfter(probe.port)}`,
       ),
     );
   }
@@ -125,13 +156,20 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
     );
     return findings;
   }
-  if (!probe.exists('.env.development')) {
+  if (!probe.exists(ENV_DEVELOPMENT)) {
     findings.push(
       finding(
         'X_ENV_MISSING',
-        '.env.development is missing, so committed defaults cannot be read',
-        'x new --force to restore the committed defaults, or create .env.development',
-        '.env.development',
+        `${ENV_DEVELOPMENT} is missing, so committed defaults cannot be read`,
+        // The file write, named — `X_PWA_ICON_MISSING`'s shape below, and for its reason. This
+        // said `x new --force`, which cannot run where the reader is standing: `x new` takes a
+        // <name> positional (reproduced: `x new --force --json` inside an app answers
+        // `X_CLI_BAD_FLAG`), and with one it scaffolds a SECOND app beside the broken one.
+        // `.env.example` is the committed projection of `envSchema`, so the copy lands every
+        // declared key with its default and blank secrets; `x env example` writes it where an app
+        // has none, and `X_ENV_EXAMPLE_DRIFT` is what reports that.
+        `cp ${ENV_EXAMPLE_PATH} ${ENV_DEVELOPMENT}`,
+        ENV_DEVELOPMENT,
       ),
     );
   }
@@ -183,16 +221,12 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
       ),
     );
   }
-  if (!probe.exists(OFFLINE_FALLBACK)) {
-    findings.push(
-      finding(
-        'X_PWA_NO_OFFLINE_FALLBACK',
-        `${OFFLINE_FALLBACK} is missing, so an offline navigation falls back to the browser error page`,
-        'x g route offline --surface app',
-        OFFLINE_FALLBACK,
-      ),
-    );
-  }
+  // The DECLARED fallback against the ROUTE TABLE, never a filename: this probed
+  // `apps/web/app/offline.tsx`, which is not a route file at all (`assertRouteFilename` refuses
+  // it), so no app could clear the finding and its own `fix:` did not either. `doctor-offline.ts`
+  // holds the rule and the reasons.
+  const offline = offlineFallbackFinding(await probe.offlineFallback());
+  if (offline !== undefined) findings.push(offline);
   const database = await probe.database();
   if (database !== null) findings.push(database);
   findings.push(...(await probe.drift()));
@@ -264,6 +298,10 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     database: () => probeDatabase(process.env['DATABASE_URL']),
     drift: async () => (root === undefined ? [] : checkMigrationDrift(root)),
     snapshots: async () => (root === undefined ? [] : checkMigrationSnapshots(root)),
+    // `routes: undefined` outside an app is "not judged", which is what the caller already is:
+    // `runDoctor` returns on `X_NOT_IN_APP` before this can be asked.
+    offlineFallback: async () =>
+      root === undefined ? { fallback: null, routes: undefined } : offlineFallbackProbe(root),
   };
 }
 

package/src/cmd-generate.ts

@@ -8,7 +8,7 @@ import { appManifest, writeAppManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { generate } from './generate-files';
-import { GENERATORS, readKind, readName, readSurface } from './generate-kinds';
+import { GENERATORS, readKind, readName, readPermission, readSurface } from './generate-kinds';
 import { containedPath, writeFiles } from './generate-write';
 import { resolveCatalogModule } from './i18n-audit';
 import { syncI18nIndex } from './i18n-index';
@@ -63,7 +63,10 @@ export const generateCommand: CliCommand = {
     const surface = readSurface(flagString(ctx.args, 'surface'), kind, name);
     const locales = resolveLocales(flagList(ctx.args, 'locales'));
     const at = flagString(ctx.args, 'at');
-    const permission = flagString(ctx.args, 'permission');
+    // Read with the two above, and refused here for their reason: the value is spliced into the
+    // emitted source three times, and a value that is not a `<resource>:<verb>` is a page the app
+    // cannot compile — found after the files are on disk, which is the worst place to find it.
+    const permission = readPermission(flagString(ctx.args, 'permission'), kind);
     // Read before a file is planned, like the flags above: which module a generated component
     // imports `useT()` from is a fact about THIS app, and `generate` is a pure function.
     const catalogModule = await resolveCatalogModule(root);

package/src/cmd-i18n.ts

@@ -8,6 +8,7 @@
 // would, and `node:path` because Bun exposes no path API to build what either of them takes.
 import { type FileHandle, mkdir, open } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { stringField } from '@ultimat3/core';
 import type { Catalog } from '@ultimat3/i18n';
 import { auditCatalogs, catalogKeys } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
@@ -40,9 +41,15 @@ export const I18N_SUBCOMMANDS = ['check', 'add', 'sync'] as const;
 /** `ExtractReport` is plain JSON by construction — same idiom as `cmd-registries.ts`'s `asJson`. */
 const asJson = (value: object): Record<string, JsonValue> => value as Record<string, JsonValue>;
 
-/** `open`'s failure when the file is already there — the one errno this command translates. */
-const isAlreadyExists = (error: unknown): boolean =>
-  typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST';
+/**
+ * `open`'s failure when the file is already there — the one errno this command translates.
+ *
+ * `stringField`, never `'code' in error && error.code`: `in` narrows for the COMPILER and promises
+ * the runtime nothing, so the read still happens on a value this process did not build and a
+ * throwing getter takes the command down one line after the guard written to make it safe. The
+ * same repair `dev-lock.ts` took for the cast spelling of the identical read.
+ */
+const isAlreadyExists = (error: unknown): boolean => stringField(error, 'code') === 'EEXIST';
 
 /**
  * The exclusive half of the create: `wx` fails rather than truncates, so an existing catalog is

package/src/cmd-jobs.ts

@@ -5,10 +5,11 @@
 // `jobs-table.ts`, and getting hold of the queue at all is `jobs-driver.ts` — shared with `x db`.
 
 import type { JobDriver } from '@ultimat3/jobs';
-import { cancelJob, createMemoryDriver, createNatsDriver, createRedisDriver } from '@ultimat3/jobs';
+import { cancelJob, createNatsDriver, createRedisDriver } from '@ultimat3/jobs';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, JobUnknownError, MissingPositionalError } from './errors';
+import type { DrainOutcome } from './jobs-drain';
 import { drainJobs } from './jobs-drain';
 import { withJobDriver } from './jobs-driver';
 import {
@@ -28,7 +29,32 @@ import { flagBool, flagString } from './parse';
 
 export const JOBS_SUBCOMMANDS = ['ls', 'show', 'retry', 'cancel', 'drain'] as const;
 
-const DRAIN_TARGETS = ['memory', 'redis', 'nats'] as const;
+/**
+ * The drivers a drain may move work ONTO — every one of them durable, and that is the whole rule.
+ * Closed, and read three ways: the flag summary, the refusal, and the `memory` case below.
+ */
+export const DRAIN_TARGETS = ['redis', 'nats'] as const;
+
+/**
+ * `memory` was on that list until 2026-09 and could not be: `createMemoryDriver()` is a `Map` in
+ * THIS process, so `x jobs drain --to memory` enqueued each job into it and then `ack`ed the
+ * durable row off the source. Reproduced against two real drivers — source ready 1 -> 0, target
+ * ready 1, `ok: true` — and the target dies with the command. `wiki/CLI-Reference.md` said the
+ * crash window "duplicates a job … instead of losing it"; this target lost every one of them.
+ *
+ * Refused by NAME rather than folded into the unknown-value message, for `cmd-deploy.ts`'s
+ * `readMethod` reason: `--to memory` is a spelling that used to work, so a reader who types it is
+ * owed the fact that it moved work into a process that is about to exit, not a list of words.
+ */
+function refuseMemoryTarget(): never {
+  throw new BadFlagError({
+    flag: 'to',
+    command: 'jobs',
+    reason:
+      'memory is a Map inside this process — the drain would ack every durable row and lose the copy when the command exits',
+    fix: 'x jobs drain --to redis --json   # or --to nats; --dry-run reports the plan and moves nothing',
+  });
+}
 
 function requireIdPositional(ctx: CommandContext, sub: string): string {
   const id = ctx.args.positionals[0];
@@ -57,10 +83,13 @@ function requireEnvUrl(env: CommandContext['env'], name: string, target: string)
 
 /**
  * `redis`/`nats` are honest `X_NOT_IMPLEMENTED` stubs in `@ultimat3/jobs` — building one here is
- * fine even though every `enqueue` on it will fail; `drainJobs` reports that per record.
+ * fine even though every `enqueue` on it will fail; `drainJobs` reports that per record. What is
+ * NOT fine is a target that accepts every enqueue and then vanishes, which is why `memory` is
+ * refused first and by name rather than falling into the closed-set message below.
  * Exported so a test can drive the `--to`/env-var validation without a driver or a boot.
  */
 export function buildDrainTarget(to: string | undefined, env: CommandContext['env']): JobDriver {
+  if (to === 'memory') refuseMemoryTarget();
   if (to === undefined || !(DRAIN_TARGETS as readonly string[]).includes(to)) {
     throw new BadFlagError({
       flag: 'to',
@@ -68,7 +97,6 @@ export function buildDrainTarget(to: string | undefined, env: CommandContext['en
       reason: `expects one of: ${DRAIN_TARGETS.join(', ')}`,
     });
   }
-  if (to === 'memory') return createMemoryDriver();
   if (to === 'redis') return createRedisDriver({ url: requireEnvUrl(env, 'REDIS_URL', 'redis') });
   return createNatsDriver({ servers: [requireEnvUrl(env, 'NATS_URL', 'nats')] });
 }
@@ -174,11 +202,13 @@ async function runCancel(driver: JobDriver, ctx: CommandContext): Promise<Comman
  * A skipped candidate is not an error — a job whose `runAt` has not arrived is unclaimable by
  * design — so it carries no `X_*` finding. It still fails the command: `x jobs drain` is run to
  * empty a driver, and a partial move that exited 0 would read as "the queue is clear".
+ *
+ * Exported, and separate from the flag reading above it, because every target the flag now accepts
+ * needs a server: a test can produce a real outcome from two drivers and render THAT, where
+ * driving the whole command would need a redis or a nats to move anything at all.
  */
-async function runDrain(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const target = buildDrainTarget(flagString(ctx.args, 'to'), ctx.env);
-  const dryRun = flagBool(ctx.args, 'dry-run');
-  const outcome = await drainJobs(driver, target, dryRun);
+export function drainResult(outcome: DrainOutcome): CommandResult {
+  const dryRun = outcome.dryRun;
   const findings = outcome.failures.map((failure) => failure.finding);
   const lines: string[] = [];
   if (outcome.skipped.length > 0) {
@@ -212,6 +242,15 @@ async function runDrain(driver: JobDriver, ctx: CommandContext): Promise<Command
   };
 }
 
+/** The move, then the render. The target is built ABOVE `withJobDriver` — see `run` below. */
+async function runDrain(
+  driver: JobDriver,
+  target: JobDriver,
+  ctx: CommandContext,
+): Promise<CommandResult> {
+  return drainResult(await drainJobs(driver, target, flagBool(ctx.args, 'dry-run')));
+}
+
 export const jobsCommand: CliCommand = {
   spec: {
     name: 'jobs',
@@ -245,7 +284,7 @@ export const jobsCommand: CliCommand = {
       {
         name: 'to',
         type: 'string',
-        summary: 'drain: target driver — memory, redis, nats',
+        summary: `drain: target driver — ${DRAIN_TARGETS.join(', ')}`,
         subcommands: ['drain'],
       },
       {
@@ -259,11 +298,18 @@ export const jobsCommand: CliCommand = {
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('jobs', ctx.cwd).dir;
     const sub = ctx.args.subcommand ?? 'ls';
+    // BEFORE `withJobDriver`, which boots the SOURCE queue and pings it. `--to` is a flag, so
+    // whether it names a durable driver is answerable with no server at all — and reading it
+    // inside meant `x jobs drain --to memory` on a box whose database is down reported the boot
+    // failure instead of `X_CLI_BAD_FLAG`, i.e. the operator repaired Postgres to be told the
+    // word they typed was refused by name. It also opens a connection to a target the command
+    // then refuses, which is a socket nothing closes.
+    const target = sub === 'drain' ? buildDrainTarget(flagString(ctx.args, 'to'), ctx.env) : null;
     return withJobDriver(root, ctx, (driver) => {
       if (sub === 'show') return runShow(driver, ctx);
       if (sub === 'retry') return runRetry(driver, ctx);
       if (sub === 'cancel') return runCancel(driver, ctx);
-      if (sub === 'drain') return runDrain(driver, ctx);
+      if (target !== null) return runDrain(driver, target, ctx);
       return runLs(driver, ctx);
     });
   },

package/src/cmd-shot.ts

@@ -322,7 +322,9 @@ export const shotCommand: CliCommand = {
     const timeoutMs = intFlag(ctx.args, 'timeout', 1, DEFAULT_PAGE_TIMEOUT_MS);
     // Which browser this run gets — start one here, or attach to one somebody else is running.
     // Decided by `shot-browser.ts` over plain inputs, and decided HERE, before a dev server or a
-    // provider session exists to pay for a typo.
+    // provider session exists to pay for a typo. It also PROBES for an installed Chrome and refuses
+    // when there is none: `puppeteer-core` bundles no browser, so a missing one used to surface as
+    // a library throw one embedded Postgres later.
     const { cdpUrl, executablePath } = shotBrowserChoice({
       cdpFlag: flagString(ctx.args, 'cdp-url'),
       browserFlag: flagString(ctx.args, 'browser'),

package/src/cmd-test.ts

@@ -104,8 +104,12 @@ export const testCommand: CliCommand = {
     name: 'test',
     summary:
       'run one test type — or the whole suite — across N workers, one isolated database per worker',
-    usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--json]`,
+    usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--json] [-- <bun test flags>]`,
     positionalChoices: TEST_TYPES,
+    // The one command that hands a tail to another tool — `bun test` — and the reason
+    // `CommandSpec.passthrough` exists: `x test unit -- --coverage --bail` parsed both flags and
+    // dropped both, so a run that measured no coverage reported exactly what a coverage run does.
+    passthrough: true,
     flags: [
       {
         name: 'workers',
@@ -173,15 +177,13 @@ export const testCommand: CliCommand = {
     }
     const files = sample === undefined ? selected : sampleFiles(selected, sample);
     const requested = readIndex(ctx.args, 'workers', 1) ?? defaultWorkers();
-    // A serial type is serial HERE TOO, `As of 2026-08-27`. `verify-tests.ts` routes `live` and
-    // `e2e` through `runSerial` and this command never read the same list, so `x verify` ran one
-    // process over the very files `x test live --workers 8` ran eight over — two answers to one
-    // question, which is axiom 1, and the dangerous one is the command a human types while
-    // debugging. What makes them serial is not a preference: a logical replication slot is named
-    // at the Postgres CLUSTER level, so a per-worker database does not isolate it and two workers
-    // race `pg_create_logical_replication_slot`; `e2e` shares one built `dist/` and one browser
-    // profile. Neither is visible without a real `TEST_DATABASE_URL`, which is why the split
-    // measured green for as long as it did.
+    // 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.
     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);
@@ -208,6 +210,9 @@ export const testCommand: CliCommand = {
       // corpus, so its shard 2 is a different shard 2 — reproducing nothing, which is the one
       // thing `reproduceFor` exists to prevent.
       ...(scope === undefined ? {} : { affected: scope.selection }),
+      // The fifth input to the split, and the one a rerun most obviously needs: `--coverage`
+      // changes what a run measures, and the reproduce line carries it back out.
+      ...(ctx.args.passthrough.length === 0 ? {} : { passthrough: ctx.args.passthrough }),
     });
     return scope === undefined ? result : withScope(result, scope);
   },

package/src/db-seed.ts

@@ -15,6 +15,7 @@ import { isSeed, SEED_TIERS, seedTiersFor } from '@ultimat3/entity';
 import { BadFlagError } from './errors';
 import type { Finding, JsonValue } from './output';
 import { findingFrom } from './output';
+import { hasPathSegment } from './path-segments';
 import { renderTable } from './table';
 
 /**
@@ -101,7 +102,7 @@ export async function discoverSeeds(root: string): Promise<SeedDiscovery> {
   const seen = new Set<string>();
   for (const pattern of SEED_GLOBS) {
     for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
-      if (absolute.includes('node_modules') || absolute.includes('.test.')) continue;
+      if (hasPathSegment(absolute, 'node_modules') || absolute.includes('.test.')) continue;
       if (seen.has(absolute)) continue;
       seen.add(absolute);
       const file = relative(root, absolute).split(sep).join('/');

package/src/dev-queue.ts

@@ -78,8 +78,16 @@ export interface RunningQueue {
  * Before this, `defaultClient()` was the only composer of a replicated pair in the framework and
  * it runs only from `baseClient()` — the client an app installed NONE for. This line installs one,
  * so `DATABASE_REPLICA_URL` was read by no booted process at all.
+ *
+ * `env` is REQUIRED, and that is the repair: it defaulted to `process.env` and `startQueue` passed
+ * nothing, so the standby was decided from the process while the middleware that opens the
+ * `withReplicaReads` scope was decided from the boot's own `options.env` (`cmd-dev.ts`,
+ * `serve.ts`). Two sources for one question answer differently the moment a boot is handed an
+ * environment it did not inherit — a routed client with no scope, or a scope with no standby, and
+ * neither reports anything. A default here is what let the caller forget; the type is what stops
+ * the next one. Exported for the test that proves which environment decides.
  */
-function startDb(services: DevServices, env: ReplicaEnv = process.env): StartedDb {
+export function startDb(services: DevServices, env: ReplicaEnv): StartedDb {
   const binding = services.db;
   const client =
     binding.mode === 'embedded'
@@ -218,8 +226,14 @@ async function releaseQueue(
 export async function startQueue(
   services: DevServices,
   overrides?: RuntimeOverrides,
+  /**
+   * The boot's own environment — `x dev`'s, the container role's, the CLI command's `ctx.env`.
+   * `process.env` is the default for a caller that has no other answer, and it is the ONLY place
+   * this file reads it: see `startDb` for what two readers of one question cost.
+   */
+  env: ReplicaEnv = process.env,
 ): Promise<RunningQueue> {
-  const { client: db, replica } = startDb(services);
+  const { client: db, replica } = startDb(services, env);
   try {
     // Pay the Postgres boot here, so the first request is not the slow one and a broken database
     // fails at boot rather than on some later query.