@ultimat3/cli 19.2.0 → 19.3.1

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-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.

package/src/dev-reload.ts

@@ -0,0 +1,46 @@
+// One rebuild at a time. A reload is a full `appManifest()` plus a `buildIslands()` over every
+// island, and the watcher had no in-flight guard: a 45ms drip of writes — a slow `git checkout`, a
+// formatter walking the tree, `x db gen` — started one per file, 40 for 40 files, each assigning
+// the same two state slots in COMPLETION order. So a slower earlier rebuild could land on top of a
+// newer one, and the dev server then served a manifest built from source that had already changed.
+
+/** What a tick does while a rebuild is already running: nothing, except become the next one. */
+export type ReloadTrigger = (file: string) => void;
+
+/**
+ * Serialise `run`, keeping only the LAST tick that arrived while it was busy. N ticks during one
+ * rebuild are exactly one more rebuild, for the newest file — never N queued ones, and never a
+ * dropped tick, which would leave the process serving the state before the author's last save.
+ *
+ * `onError` defaults to swallowing, because the caller that cares reports its own failure as a
+ * finding; a rejection escaping here would be an unhandled rejection that takes `x dev` down.
+ */
+export function coalesceReloads(
+  run: (file: string) => Promise<void> | void,
+  onError: (error: unknown, file: string) => void = () => undefined,
+): ReloadTrigger {
+  let running = false;
+  let pending: string | undefined;
+
+  const start = (file: string): void => {
+    running = true;
+    // `Promise.resolve().then` rather than a bare call: a SYNCHRONOUS throw from `run` would
+    // otherwise escape the fs callback that triggered it, where nothing is listening.
+    void (async () => await run(file))()
+      .catch((error: unknown) => onError(error, file))
+      .finally(() => {
+        running = false;
+        const next = pending;
+        pending = undefined;
+        if (next !== undefined) start(next);
+      });
+  };
+
+  return (file: string): void => {
+    if (running) {
+      pending = file;
+      return;
+    }
+    start(file);
+  };
+}

package/src/dev-runtime.ts

@@ -299,7 +299,10 @@ export async function startServices(
   // `@ultimat3/realtime`'s decision, and it is the same call a `ROLE=sync` container makes, so this
   // process cannot resolve the bus differently from the container it stands in for.
   const bus: TransportSelection = selectTransport(env);
-  const queue = await startQueue(services, overrides);
+  // `env`, not the ambient one: this function is HANDED the boot's environment and every other
+  // reader here already uses it, so a queue that asked `process.env` would decide the standby from
+  // a different answer than the middleware that routes to it.
+  const queue = await startQueue(services, overrides, env);
   const { db, jobs, outbox, events } = queue;
   // The same executor the jobs driver, the outbox, the event bus and the idempotency store run
   // on — one pool, one `Bun.sql` that does NOT satisfy `PgExecutor` (`Bun.sql.query` is

package/src/dev-sync.ts

@@ -15,7 +15,7 @@ import {
   SocketRegistry,
 } from '@ultimat3/realtime/server';
 import type { StartRolesOptions } from './dev-roles';
-import { neighbouringPort, PORT_RANGE } from './flag-number';
+import { neighbouringPort, PORT_RANGE, portPairAfter } from './flag-number';
 import { portFree } from './port-probe';
 import { syncAuthenticator } from './sync-authenticator';
 import { DEV_BINDING } from './web-binding';
@@ -53,7 +53,11 @@ class SyncPortInUseError extends UltimateError {
     super({
       code: 'X_PORT_IN_USE',
       cause: `the sync role binds PORT + 1, so \`x dev --port ${input.webPort}\` needs port ${input.port} and something is already listening on it`,
-      fix: `x dev --port ${neighbouringPort(input.webPort)}   # or free port ${input.port}: lsof -nP -iTCP:${input.port} -sTCP:LISTEN`,
+      // `portPairAfter`, never `neighbouringPort`: `x dev` binds a PAIR, so the neighbour of the
+      // web port IS the sync port this refusal is about — the fix said `x dev --port 4000` for a
+      // run that had just died on 4000, and a test named "its fix is a command that ends the
+      // failure" pinned it.
+      fix: `x dev --port ${portPairAfter(input.webPort)}   # or free port ${input.port}: lsof -nP -iTCP:${input.port} -sTCP:LISTEN`,
       meta: { port: input.port, webPort: input.webPort },
     });
   }
@@ -183,7 +187,11 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     // so the one socket that streams live database patches was the one socket on every
     // interface — and `WebBinding`'s own docstring is about not serving a laptop's app to a café.
     const binding = options.http ?? DEV_BINDING;
-    const listener = listenSyncNode(node, { port, hostname: binding.hostname });
+    // No drain grace: there is one node here and it is the one going away. Its clients reconnect
+    // to it when `x dev` is back, and a grace that kept their patches flowing meanwhile was five
+    // seconds of every Ctrl-C (measured 2026-09-06, 5.0s of 5.1s) spent on a reconnect frame
+    // whose target does not exist yet.
+    const listener = listenSyncNode(node, { port, hostname: binding.hostname, drainGraceMs: 0 });
     return {
       url: listener.url,
       registry,

package/src/dev-watch-tree.ts

@@ -0,0 +1,226 @@
+// The app root watched one directory at a time, because the watch SET is a registration decision
+// and not a filter. `watch(root, { recursive: true })` takes an inotify descriptor per directory
+// in the tree — including every directory the dev loop then discards events from — so `.git/`,
+// `node_modules/` and `.x/` (which this very process writes to, continuously) each cost a
+// descriptor, a kernel queue entry and a JS callback per write, against a per-user descriptor
+// budget of 8192 on many distributions. Bun 1.4.0's `fs.watch` takes no ignore option, so the
+// only place the answer can be given early is at registration.
+
+// why: Bun exposes no filesystem watcher, no directory listing and no synchronous stat —
+// `Bun.file().exists()` is async and answers false for a DIRECTORY, which is the one thing this
+// module has to decide. Delete each when Bun ships an equivalent.
+import type { Dirent } from 'node:fs';
+import { readdirSync, statSync, watch } from 'node:fs';
+// why: Bun exposes no path-join primitive.
+import { join } from 'node:path';
+import { finiteCount, logger } from '@ultimat3/core';
+import type { DevIgnore } from './dev-watch';
+import { devIgnore } from './dev-watch';
+import { pathSegments } from './path-segments';
+
+/** What `node:fs`'s watcher hands a listener — `filename` is optional in fact, not only in type. */
+export type WatchListener = (event: string, filename: string | Buffer | null | undefined) => void;
+
+/** The one thing this module needs of a watcher, so a test can stand one up in four lines. */
+export interface DirectoryWatcher {
+  close(): void;
+}
+
+export type WatchDirectory = (directory: string, listener: WatchListener) => DirectoryWatcher;
+
+export interface WatchTreeOptions {
+  readonly root: string;
+  /** A source change, app-root-relative and POSIX-separated. Debounced. */
+  readonly onChange: (file: string) => void;
+  /** Trailing debounce. A save touching five files is one reload, not five. Default 30ms. */
+  readonly debounceMs?: number;
+  /** Test seam: the default is `node:fs`'s `watch(dir, { recursive: false })`. */
+  readonly watchDirectory?: WatchDirectory;
+}
+
+export interface WatchTree {
+  /** Directories holding a descriptor right now, app-root-relative; `''` is the app root. */
+  directories(): readonly string[];
+  close(): void;
+}
+
+const DEFAULT_DEBOUNCE_MS = 30;
+
+/**
+ * Every directory under `root` an event could be a source change in, `''` first. Ignored
+ * directories are not descended, so a `node_modules` tree costs one `readdir` and nothing else.
+ * A symlinked directory is deliberately not followed: `Dirent.isDirectory()` is false for one, and
+ * a workspace symlink pointing back into the checkout would otherwise be walked twice.
+ */
+export function admittedDirectories(root: string, ignore: DevIgnore): readonly string[] {
+  const admitted: string[] = [''];
+  const pending: string[] = [''];
+  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+    for (const entry of childrenOf(join(root, next))) {
+      if (!entry.isDirectory()) continue;
+      const child = next === '' ? entry.name : `${next}/${entry.name}`;
+      if (ignore.ignores(child, true)) continue;
+      admitted.push(child);
+      pending.push(child);
+    }
+  }
+  return admitted.sort();
+}
+
+/**
+ * One directory's entries, or none. A directory removed between the listing above and this read, or
+ * one this user may not open, is neither a source change nor a finding anyone can act on.
+ */
+function childrenOf(path: string): readonly Dirent[] {
+  try {
+    return readdirSync(path, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+const nodeWatch: WatchDirectory = (directory, listener) =>
+  watch(directory, { recursive: false }, listener);
+
+/** Whether the path is a directory right now — the question a `rename` event does not answer. */
+function isDirectoryAt(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function watchTree(options: WatchTreeOptions): WatchTree {
+  const { root, onChange } = options;
+  // Screened before a single descriptor is taken. `??` guards NULLISH and `NaN` is not nullish, so
+  // an unparsed value walks past the default into `setTimeout(fn, NaN)`, which coerces to **0**:
+  // the debounce reads as installed and every keystroke runs a full `appManifest()` plus
+  // `buildIslands()`. `0` is admitted — "rebuild on the next tick" is a decision — and `Infinity`
+  // is not, because a reload that never fires is the same defect facing the other way.
+  const debounceMs = finiteCount(
+    'watchTree',
+    'debounceMs',
+    options.debounceMs ?? DEFAULT_DEBOUNCE_MS,
+  );
+  const open = new WatchDirectoryMap(options.watchDirectory ?? nodeWatch, root);
+  let ignore = devIgnore(root);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let last = '';
+  let warned = false;
+
+  const schedule = (file: string): void => {
+    last = file;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(() => onChange(last), debounceMs);
+  };
+
+  const listen = (directory: string): void => {
+    open.add(directory, (event, filename) => {
+      if (typeof filename !== 'string' && !(filename instanceof Buffer)) {
+        // Bun's watcher delivers no filename when the WATCHED directory itself moves or is removed
+        // — `mv myapp myapp2`, a re-clone, a volume remount. Once, because the same rename can
+        // arrive on every descriptor at the same instant.
+        if (!warned) logger.warn('dev.watch.unnamed_event', { directory: directory || '.' });
+        warned = true;
+        return;
+      }
+      const name = pathSegments(filename.toString()).join('/');
+      const file = directory === '' ? name : `${directory}/${name}`;
+      // Asked of the DISK, once, because every trailing-slash rule in a `.gitignore` turns on it
+      // and a `rename` says only that something moved. One stat against a whole rebuild.
+      const isDirectory = open.has(file) || isDirectoryAt(join(root, file));
+      if (event === 'rename') follow(file, isDirectory);
+      if (file === '.gitignore') {
+        // The ignore set is the app's own, so an edit to it changes which directories are watched
+        // at all. Not a source change: rebuilding the manifest for it would be a reload the author
+        // did not ask for on the one file whose whole job is saying what to leave alone.
+        ignore = devIgnore(root);
+        reconcile();
+        return;
+      }
+      if (ignore.ignores(file, isDirectory)) return;
+      schedule(file);
+    });
+  };
+
+  /** A `rename` created or removed something: keep the descriptor set honest either way. */
+  const follow = (file: string, isDirectory: boolean): void => {
+    if (isDirectory && isDirectoryAt(join(root, file))) {
+      if (ignore.ignores(file, true)) return;
+      if (!open.has(file)) for (const found of subtree(file)) listen(found);
+      return;
+    }
+    if (open.has(file)) open.remove(file);
+  };
+
+  /** The admitted directories at or under `directory`, discovered rather than assumed. */
+  const subtree = (directory: string): readonly string[] =>
+    admittedDirectories(join(root, directory), ignore).map((found) =>
+      found === '' ? directory : `${directory}/${found}`,
+    );
+
+  /** The whole set, re-derived: a directory the author just ignored gives its descriptor back. */
+  const reconcile = (): void => {
+    const admitted = new Set(admittedDirectories(root, ignore));
+    for (const held of open.directories()) if (!admitted.has(held)) open.remove(held);
+    for (const directory of admitted) if (!open.has(directory)) listen(directory);
+  };
+
+  for (const directory of admittedDirectories(root, ignore)) listen(directory);
+
+  return {
+    directories: () => open.directories(),
+    close(): void {
+      if (timer !== undefined) clearTimeout(timer);
+      open.closeAll();
+    },
+  };
+}
+
+/**
+ * The descriptors this watcher holds, keyed by app-root-relative directory. Its own type because
+ * removing one means removing everything under it: a deleted directory takes its children's
+ * descriptors with it, and a `Map` iterated by the caller would leak every one of them.
+ */
+class WatchDirectoryMap {
+  readonly #watchers = new Map<string, DirectoryWatcher>();
+  readonly #watch: WatchDirectory;
+  readonly #root: string;
+
+  constructor(watchDirectory: WatchDirectory, root: string) {
+    this.#watch = watchDirectory;
+    this.#root = root;
+  }
+
+  add(directory: string, listener: WatchListener): void {
+    if (this.#watchers.has(directory)) return;
+    try {
+      this.#watchers.set(directory, this.#watch(join(this.#root, directory), listener));
+    } catch {
+      // A directory that vanished between the walk and the registration. The parent's own
+      // descriptor still reports anything that reappears there.
+    }
+  }
+
+  has(directory: string): boolean {
+    return this.#watchers.has(directory);
+  }
+
+  directories(): readonly string[] {
+    return [...this.#watchers.keys()].sort();
+  }
+
+  remove(directory: string): void {
+    for (const held of this.#watchers.keys()) {
+      if (held !== directory && !held.startsWith(`${directory}/`)) continue;
+      this.#watchers.get(held)?.close();
+      this.#watchers.delete(held);
+    }
+  }
+
+  closeAll(): void {
+    for (const watcher of this.#watchers.values()) watcher.close();
+    this.#watchers.clear();
+  }
+}