@ultimat3/cli 19.2.0 → 19.3.2

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

@@ -27,6 +27,8 @@ import {
   renderHead,
   routeDataFor,
   routeEntries,
+  routeFor,
+  routeStatusOf,
   seoRenderers,
 } from '@ultimat3/render';
 import type { IsrController } from '@ultimat3/render/server';
@@ -212,12 +214,15 @@ async function resultFor(
   // ONCE per request, before the mode is chosen. Every branch below reads this same object, so a
   // route's `load` runs exactly once however its mode splits head from body.
   const data = await routeDataFor(entry.config, request);
+  // The status the loader answered through `withStatus`, 200 when it said nothing. Read once,
+  // here, and handed to every mode: this file mints the `Response`, render owns the seam.
+  const status = routeStatusOf(data);
   switch (entry.config.render) {
     case 'static': {
       // Not `renderStatic`: that enumerates every prerendered path for the build. A request
       // names exactly one, and it earns the same content-hashed headers.
       const body = await documentFrom(entry, request, data, options);
-      return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
+      return { status, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'isr': {
       // `isrKey(url, locale)`, never `url.pathname`: the query is part of what was rendered — this
@@ -227,9 +232,12 @@ async function resultFor(
       // The locale is the second dimension and it is `ctx.locale`, the answer the `locale` stage
       // already negotiated for THIS request — never `currentLocale()`, which would read the same
       // value through an ambient store the key does not need.
-      const served = await isr.serve(isrKey(url, ctx.locale), () =>
-        documentFrom(entry, request, data, options),
-      );
+      // `{ html, status }`, never the bare string: the entry stores the status beside the HTML
+      // and serves it on every hit, so a 404 under `isr` is a 404 for its whole TTL.
+      const served = await isr.serve(isrKey(url, ctx.locale), async () => ({
+        html: await documentFrom(entry, request, data, options),
+        status,
+      }));
       return served.result;
     }
     case 'stream': {
@@ -253,13 +261,14 @@ async function resultFor(
           holes: [],
         },
         { buildId: options.buildId },
+        status,
       );
     }
     default:
       return renderSsr(
         { entry, params: request.params, url, ctx },
         () => documentFrom(entry, request, data, options),
-        { buildId: options.buildId },
+        { buildId: options.buildId, status },
       );
   }
 }
@@ -281,15 +290,32 @@ const metaOf = (entry: RouteEntry): HttpRouteMeta => ({
   ...(entry.config.policy === undefined ? {} : { policy: entry.config.policy.permission }),
 });
 
-/** One HTTP route per registered `route` primitive, in the table's own order. */
+/**
+ * One HTTP route per registered `route` primitive, in the table's own order.
+ *
+ * The URL and the method are the table's at the time this is called; the ENTRY — the component the
+ * handler renders AND the `meta` the pipeline enforces — is read back from the table on every
+ * request. `x dev` re-registers a route module when its source changes (`app-load.ts`), and a
+ * handler closing over the entry it was built from kept serving the first component after every
+ * save — the table had moved and this closure had not. `meta` was the same defect one stage
+ * earlier: a snapshot taken here, so a `policy` added in a save was not enforced until a restart
+ * while the page behind it was already the new one — the pipeline's `auth` and `authz` stages read
+ * `route.meta` per request, and this getter is what makes that read the table's. The path cannot
+ * move under a reload (the table derives it from the file, and the file is the reload's key), so
+ * the entry captured here is only the fallback for a table cleared under a running server, which
+ * only a test does — and then guard and page fall back together.
+ */
 export function appRoutes(options: DevRenderOptions): readonly Route[] {
   const isr = options.isr ?? createIsrController({ buildId: options.buildId });
-  return routeEntries().map((entry) => ({
+  return routeEntries().map((registered) => ({
     method: 'GET' as const,
-    path: entry.path,
-    meta: metaOf(entry),
+    path: registered.path,
+    get meta(): HttpRouteMeta {
+      return metaOf(routeFor(registered.path) ?? registered);
+    },
     // `ctx.params` is the router's own match — the CLI never re-parses a path it did not match.
     handler: async (request, ctx): Promise<Response> => {
+      const entry = routeFor(registered.path) ?? registered;
       const data: DevRouteData = { url: request.url.href, params: ctx.params };
       return responseOf(await resultFor(entry, data, options, isr, asCtx(ctx)));
     },

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();
+  }
+}

package/src/dev-watch.ts

@@ -1,53 +1,75 @@
-// Which writes under the app root are a source change, and which are noise. Split out of
-// `cmd-dev.ts` because it is a rule with cases rather than four lines of glue, and because the
-// answer needs a test of its own: a watcher that reloads on the wrong write is invisible — the
-// dev server stays correct and merely does the most expensive thing it can do, repeatedly.
+// Which paths under the app root `x dev` must not watch, and the rule is REGISTRATION rather than
+// filtering: `watch(root, { recursive: true })` takes one inotify descriptor per directory before
+// any filter runs, so an answer given after the event has already cost the kernel queue, a JS
+// callback and a slot out of `max_user_watches`. Measured on a monorepo root: 1901 descriptors,
+// 1490 of them under `.git/` and `node_modules/`, and one `git status` delivering 5 events.
 //
-// What it was: `filename.includes('.x/') || filename.includes('node_modules')`. Measured against
-// ai-maxxing, whose checkout carries `.git/`, `.personal/`, `.claude/worktrees/` (two FULL copies
-// of the app) and `coverage/`, every write under any of them ran a whole `appManifest()` plus a
-// `buildIslands()` over ten islands. `git status`, an agent's scratch file and a coverage run each
-// cost a full rebuild, and each rebuild re-minted every island chunk.
-//
-// `includes` was also the wrong operator, not just the wrong list: a directory legitimately named
-// `my-node_modules-notes/` was excluded from the dev loop for a substring, and `notes/.xyz/` for
-// another. The match is on a PATH SEGMENT, so only the directory itself is ever ignored.
+// The ignore set is the app's own `.gitignore`, read with git's own anchoring (`gitignore.ts`),
+// plus a floor of directory names an ignore file need not name. It was seven hand-listed names,
+// and both halves of that were wrong: nothing read `.gitignore`, so `tsconfig.tsbuildinfo` —
+// rewritten by every `bun run typecheck` — ran a full `appManifest()` plus `buildIslands()`; and
+// `dist` and `coverage` were matched at ANY depth, so an app's own `/dist` or `/coverage` route
+// never reloaded at all, silently.
+
+// why: Bun exposes no path-join primitive. The same necessity `fix-path.ts` already records.
+import { join } from 'node:path';
+import type { IgnoreScope } from './gitignore';
+import { ignoreScopes, isGitIgnored } from './gitignore';
+import { pathSegments } from './path-segments';
 
 /**
- * Directories whose writes are never an app source change.
+ * Directory names no `.gitignore` can be relied on to carry, matched as a path SEGMENT at any
+ * depth. Every entry earns its line, and every one is either dotted or `node_modules` — which is
+ * what makes the any-depth match safe: a `site/` subtree is a URL tree, and neither a dot-directory
+ * nor an install is ever a route.
  *
- * Every entry earns its line and none is a guess:
- * - `.x` — the framework's own state directory: PGlite's data, the dev lock, the static export,
- *   `build-stats.json`. `x build` writes here, which made a build trigger reloads of the process
- *   that was running it.
- * - `node_modules` — an install, not an edit. `x dev` does not reload for a dependency change
- *   because it cannot: the modules are already in this process's cache.
- * - `.git` — the reason this list exists. `git status`, `git fetch` and every commit rewrite index
- *   and ref files continuously, and none of them is a source edit; a checkout of a branch IS one,
- *   but it also writes the source files themselves, which this list does not touch.
- * - `.personal` — an app's uncommitted local state (ai-maxxing's fleet file, its inventory, its
- *   credentials). Written by scripts while the dev server runs.
+ * - `.git` — git never names its own directory in an ignore file, and `git status`, `git fetch` and
+ *   every commit rewrite index and ref files continuously. The reason this list exists.
+ * - `.x` — the framework's own state: PGlite's data directory (which THIS process writes
+ *   continuously), the dev lock, the static export, `build-stats.json`.
+ * - `node_modules` — an install, not an edit. `x dev` cannot reload for a dependency change: the
+ *   modules are already in this process's cache.
+ * - `.personal` — an app's uncommitted local state, written by scripts while the dev server runs.
  * - `.claude` — agent scratch, session logs and worktrees. ai-maxxing keeps two entire copies of
  *   the app under `.claude/worktrees/`, so a second agent's edit rebuilt the first agent's islands.
- * - `dist`, `coverage` — build and test output. Both are written by commands an author runs
- *   BESIDE `x dev`, which is exactly when a spurious rebuild costs the most.
+ *
+ * `dist` and `coverage` were here and are deliberately not: both are ordinary build output that
+ * every ignore file already names, and hand-listing them cost an app its own routes.
  */
-export const IGNORED_DIRECTORIES: readonly string[] = [
+export const ALWAYS_IGNORED_DIRECTORIES: readonly string[] = [
+  '.git',
   '.x',
   'node_modules',
-  '.git',
   '.personal',
   '.claude',
-  'dist',
-  'coverage',
 ];
 
+/** The ignore set as one question, so the walk and the event filter cannot disagree. */
+export interface DevIgnore {
+  /** `path` is app-root-relative; `isDirectory` decides every trailing-slash rule git holds. */
+  ignores(path: string, isDirectory: boolean): boolean;
+  /** The `.gitignore` files this set was built from, outermost first — what `--json` can report. */
+  readonly scopes: readonly IgnoreScope[];
+}
+
 /**
- * A path segment, never a substring. `filename` arrives from `node:fs`'s watcher root-relative and
- * with the platform's separator, so both are normalised before the split — a rule that reads
- * `foo/node_modules/bar` and not `foo\\node_modules\\bar` is a rule that does not exist on Windows.
+ * Read once, at boot and again on every write that names `.gitignore`. A snapshot rather than a
+ * live reader: the watcher rebuilds the whole set and re-walks, so a directory the author just
+ * ignored drops its descriptor instead of keeping one nothing will ever read an event from.
+ *
+ * Two limits, both deliberate. An ANCESTOR ignore file is read at boot and is not watched — it sits
+ * outside the app root, so `x dev` has no descriptor there and a restart is the way to pick up an
+ * edit to it. A NESTED one (`apps/web/.gitignore`) is not read at all: `ignoreScopes` walks upward
+ * only, and watching for one would mean a scope per directory in the tree.
  */
-export function isIgnoredPath(filename: string): boolean {
-  const segments = filename.replaceAll('\\', '/').split('/');
-  return segments.some((segment) => IGNORED_DIRECTORIES.includes(segment));
+export function devIgnore(root: string): DevIgnore {
+  const scopes = ignoreScopes(root);
+  return {
+    scopes,
+    ignores(path: string, isDirectory: boolean): boolean {
+      const segments = pathSegments(path);
+      if (segments.some((segment) => ALWAYS_IGNORED_DIRECTORIES.includes(segment))) return true;
+      return isGitIgnored(scopes, join(root, ...segments), isDirectory);
+    },
+  };
 }