@ultimat3/cli 19.2.0 → 19.3.2

package/src/cmd-dev-fixture.ts

@@ -7,6 +7,8 @@
 //   app.config.ts               the root marker a real `x dev` cannot start without; `ai.mcp` by default
 //   apps/web/mcp.ts             the app's own MCP endpoint, mounted by the web role
 //   apps/web/runtime.ts         the app's middleware, reaching a development process
+//   .git/HEAD                   the fixture is its own repository — see the entry below
+//   apps/web/app/hello/*        an SSR page with a component, edited on disk while `x dev` runs
 //   apps/web/app/notes/*        a memory-backed entity and a live query, fed by the in-process bridge
 //   apps/web/app/posts/*        an action, a policy and a query, mounted as HTTP routes
 //   apps/web/site/pricing/*     a static page with its own stylesheet, under the CSP `x dev` sends
@@ -24,6 +26,12 @@ import { resetAppLoad } from './app-load';
 export const DEV_FIXTURE_FILES: Readonly<Record<string, string>> = {
   'package.json': JSON.stringify({ name: 'dev-fixture', version: '1.4.0' }),
 
+  // Its own repository, so the ignore walk stops HERE. The framework's root `.gitignore` lists
+  // `packages/cli/.dev-fixture/`, and `devIgnore` honours every ancestor up to a `.git` — without
+  // this marker the watcher admitted the fixture root and nothing under it, so no save in this
+  // tree ever reached `rebuild`, and the reload path was booted by every run and exercised by none.
+  '.git/HEAD': 'ref: refs/heads/main\n',
+
   // The root marker a real `x dev` cannot start without, and where `ai.mcp` is declared — by
   // default `{ expose: true, path: '/mcp' }`, which is what the MCP mount reads.
   'app.config.ts': `import { defineConfig } from '@ultimat3/core';
@@ -98,6 +106,23 @@ export const echoPost = action({
     return { word: input.word };
   },
 });
+`,
+
+  // A page with a body, on the surface an author edits all day. What the reload test rewrites: the
+  // module must be imported again for the new body to be served, which `import()` alone never does.
+  'apps/web/app/hello/page.tsx': `import { defineRoute } from '@ultimat3/render';
+
+export const config = defineRoute({
+  render: 'ssr',
+  hydrate: 'visible',
+  offline: 'runtime',
+  budget: { js: '60kb' },
+  meta: () => ({ title: 'Hello', description: 'A page that is edited while x dev runs' }),
+});
+
+export function Page() {
+  return <p>generation one</p>;
+}
 `,
 
   // A stylesheet the page imports, because that import is what registers it — and the document's

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';
@@ -17,7 +16,6 @@ import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { describeRoutes } from '@ultimat3/render';
 import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
-import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
 import { mountAppMcp } from './app-mcp';
 import { requireAppRoot } from './app-root';
@@ -29,6 +27,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,7 +38,7 @@ import type { DevServices } from './dev-services';
 import { describeServices, reportedUrls, resolveServices } from './dev-services';
 import { storageRoutes } from './dev-storage';
 import { createTraceRecorder } from './dev-traces';
-import { isIgnoredPath } from './dev-watch';
+import { watchTree } from './dev-watch-tree';
 import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { IslandBundle } from './island-bundle';
@@ -88,34 +87,21 @@ interface DevState {
   reloads: number;
   /** A save that will not build. Replaced on every attempt, so a fixed file clears it. */
   reloadFinding: Finding | undefined;
+  /**
+   * Modules that would not import and primitives that would not register, as of the LAST scan —
+   * the boot's, then each rebuild's. A page saved with a syntax error is a finding here until the
+   * save that fixes it, and the boot's list alone would never show it.
+   */
+  appFindings: readonly Finding[];
   /**
    * The client entries, rebuilt on the same tick as the manifest. An island is the one module this
-   * process never imports, so a fresh `Bun.build` is the whole of its reload — no module cache to
-   * invalidate, which is exactly why editing one takes effect where editing a route does not.
+   * process never imports, so a fresh `Bun.build` is the whole of its reload. The route module
+   * beside it is re-imported by that same scan (`app-load.ts`) — the two are one generation, or
+   * a save serves a new island under an old page, which is what it did until 2026-09-07.
    */
   islands: IslandBundle;
 }
 
-/**
- * Debounced: a save that touches five files is one reload, not five. What counts as a save at all
- * is `dev-watch.ts` — a reload is a full `appManifest()` plus a `buildIslands()` over every island,
- * so a write this cannot rule out is the most expensive no-op the dev loop has.
- */
-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 || isIgnoredPath(filename)) 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;
@@ -155,11 +141,16 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // uninstalled, and nothing more (axiom 6).
   const statements = createStatementLedger();
   setStatementObserver(statements.observer);
-  const app = await loadApp(options.root);
+  // 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: (await appManifest(options.root)).manifest,
+    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
@@ -294,22 +285,33 @@ 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, findings }, islands] = await Promise.all([
+        appManifest(options.root),
+        buildIslands(options.root),
+      ]);
+      state.manifest = manifest;
+      state.appFindings = findings;
+      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}`,
@@ -326,14 +328,14 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     get findings(): readonly Finding[] {
       const loops = statements.repeats().map(loopFacts).map(loopFinding);
       return state.reloadFinding === undefined
-        ? [...app.findings, ...loops]
-        : [...app.findings, state.reloadFinding, ...loops];
+        ? [...state.appFindings, ...loops]
+        : [...state.appFindings, state.reloadFinding, ...loops];
     },
     running,
     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

@@ -7,8 +7,9 @@ import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 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 { generate, sliceDir } from './generate-files';
+import type { Generator } 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,14 +64,20 @@ 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);
+    // Read for the same reason: which errors the slice declares is written on THIS app's disk.
+    const sliceErrors = await readSliceErrors(root, kind, sliceDir(surface, featureFlag ?? name));
     const files = generate({
       kind,
       name,
       ...(featureFlag === undefined ? {} : { feature: featureFlag }),
+      ...(sliceErrors === undefined ? {} : { sliceErrors }),
       ...(at === undefined ? {} : { at }),
       ...(permission === undefined ? {} : { permission }),
       surface,
@@ -135,3 +142,18 @@ export const generateCommand: CliCommand = {
     };
   },
 };
+
+/**
+ * The slice's `errors.ts`, for the two generators whose template throws from it. Only those two:
+ * a route or an island names no slice, and the "feature" the fallback derives for them is a path
+ * that exists nowhere — reading it would be answering a question nobody asked.
+ */
+async function readSliceErrors(
+  root: string,
+  kind: Generator,
+  slice: string,
+): Promise<string | undefined> {
+  if (kind !== 'action' && kind !== 'mutator') return undefined;
+  const file = containedPath(root, `${slice}/errors.ts`);
+  return existsSync(file) ? await Bun.file(file).text() : undefined;
+}

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-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('/');