@hienlh/ppm 0.23.11 → 0.23.12

package/src/services/file-list-index.service.ts

@@ -2,46 +2,120 @@
  * file-list-index.service.ts
  * Lazy-load file tree listing and flat index building for palette/search.
  * Implements listDir() (1-level) and buildIndex() (recursive) with filter support.
- * Index results are cached per project path and invalidated on file changes.
+ * Index results are cached per project path; a file change marks them stale (see IndexEntry).
+ * The walk itself runs on the file index worker (file-index/), off the thread serving requests.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { resolve, relative, join, sep } from "node:path";
-import ignore, { type Ignore } from "ignore";
-import type { FileEntry, FileDirEntry } from "../types/project.ts";
+import { existsSync, readdirSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import type { Ignore } from "ignore";
+import type { FileDirEntry, FileEntry } from "../types/project.ts";
 import { matchesGlob, resolveFilter } from "./file-filter.service.ts";
 import { SecurityError, NotFoundError } from "./file.service.ts";
+import { loadGitignore, type IndexBuild } from "./file-index/index-walk.ts";
+import { fileIndexRunner } from "./file-index/file-index-runner.ts";
+import type { SearchKind } from "./file-index/index-search.ts";
 
 // ---------------------------------------------------------------------------
 // Index cache keyed by absolute project path
 // ---------------------------------------------------------------------------
 
-const indexCache = new Map<string, FileEntry[]>();
+/**
+ * One project's index. A file change marks it `stale` instead of dropping it, and the list is
+ * walked again in the background a second later (see `refreshDelay`), so the palette opens on a
+ * list that is already current. A request that finds it stale is answered with the rebuild if
+ * that lands within `REBUILD_GRACE_MS`, and with the list already held otherwise. It used to be
+ * dropped, so the explorer's refetch after every change walked the project on the request
+ * itself — nxsys-workspace (181k entries) took 6.2 s per walk, and a session writing test
+ * artefacts into it kept the server frozen until the supervisor killed it.
+ */
+interface IndexEntry {
+  build: IndexBuild | null;
+  /** Something under the project changed since `build` was walked. */
+  stale: boolean;
+  /** The walk under way, shared by every request that arrives while it runs. */
+  building: Promise<IndexBuild> | null;
+  /**
+   * A request found a change that landed after the running walk began, which that walk may
+   * have passed by — so walk once more as soon as it ends, instead of after `refreshDelay`.
+   * Only for a project quick to walk (`QUICK_WALK_MS`); a slow one keeps to its schedule.
+   */
+  rewalk: boolean;
+  /** The background walk a change scheduled. */
+  refreshTimer: ReturnType<typeof setTimeout> | null;
+  /** When the last walk ended, and how long it took: what spaces background walks out. */
+  lastWalkEndedAt: number;
+  lastWalkMs: number;
+}
+
+const indexCache = new Map<string, IndexEntry>();
+
+type RebuiltListener = (projectPath: string, changed: boolean) => void;
+const rebuiltListeners = new Set<RebuiltListener>();
+
+/**
+ * Called after each background rebuild — one that replaced a list already being served — with
+ * whether its paths differ. Content-only churn (a log being appended to) rebuilds to the same
+ * list, and nothing downstream needs to hear about that.
+ */
+export function onIndexRebuilt(listener: RebuiltListener): () => void {
+  rebuiltListeners.add(listener);
+  return () => { rebuiltListeners.delete(listener); };
+}
 
-/** Invalidate cached flat index for a project (called on file change events) */
+/**
+ * Drop a project's index, so the next request waits for a fresh walk. For filter changes: the
+ * list held was built with the old filters, so it is wrong rather than merely old.
+ */
 export function invalidateIndexCache(projectPath: string): void {
+  const entry = indexCache.get(projectPath);
+  if (entry?.refreshTimer) clearTimeout(entry.refreshTimer);
   indexCache.delete(projectPath);
 }
 
+/** A file changed: keep serving the index held, and walk it again in the background. */
+export function markIndexStale(projectPath: string): void {
+  const entry = indexCache.get(projectPath);
+  if (!entry) return;
+  entry.stale = true;
+  scheduleRefresh(projectPath, entry);
+}
+
+/**
+ * Walk a project nobody has asked about yet, so its first palette opens on a ready list. The
+ * walk runs on the index worker; a failure is left to the first request to report.
+ */
+export function warmIndex(projectPath: string): void {
+  if (indexCache.has(projectPath)) return;
+  buildIndex(projectPath).catch(() => {});
+}
+
 /** Clear all cached indexes (e.g. for tests) */
 export function clearIndexCache(): void {
+  for (const entry of indexCache.values()) {
+    if (entry.refreshTimer) clearTimeout(entry.refreshTimer);
+  }
   indexCache.clear();
 }
 
-// ---------------------------------------------------------------------------
-// Gitignore loader (shared utility)
-// ---------------------------------------------------------------------------
+/**
+ * How long after a change to walk again. A second, so a burst of writes costs one walk — but no
+ * sooner after the last walk ended than that walk took, so a project as slow as nxsys-workspace
+ * (~7 s) keeps the worker busy at most half the time while a session writes into it without end.
+ */
+export function refreshDelay(now: number, lastWalkEndedAt: number, lastWalkMs: number): number {
+  return Math.max(REFRESH_AFTER_CHANGE_MS, lastWalkEndedAt + lastWalkMs - now);
+}
 
-function loadGitignore(projectPath: string): Ignore {
-  const ig = ignore();
-  const gitignorePath = join(projectPath, ".gitignore");
-  if (existsSync(gitignorePath)) {
-    try {
-      const content = readFileSync(gitignorePath, "utf-8");
-      ig.add(content);
-    } catch { /* unreadable — skip */ }
-  }
-  return ig;
+function scheduleRefresh(projectPath: string, entry: IndexEntry): void {
+  // With no list yet the first request walks, and a walk under way reschedules when it ends.
+  // Starting a walk and dropping the entry both clear the timer, so one that fires has work to do.
+  if (entry.refreshTimer || !entry.build || entry.building) return;
+  entry.refreshTimer = setTimeout(() => {
+    entry.refreshTimer = null;
+    startBuild(projectPath, entry);
+  }, refreshDelay(Date.now(), entry.lastWalkEndedAt, entry.lastWalkMs));
+  entry.refreshTimer.unref?.();
 }
 
 // ---------------------------------------------------------------------------
@@ -146,59 +220,104 @@ function listDirWithContext(projectPath: string, relPath: string, { filter, ig }
 // ---------------------------------------------------------------------------
 
 /**
- * Build flat index of all files in project for palette/search.
+ * How long a request for a stale index waits for the rebuild before it is answered with the
+ * list already held. Most projects are walked well inside it — PPM's own 3.2k entries take
+ * ~80 ms — so a file just created is in the palette the first time it opens. nxsys-workspace
+ * (181k entries, ~7 s) is answered with the list it had, and `files:index-changed` follows.
+ */
+const REBUILD_GRACE_MS = 1000;
+
+/** See `refreshDelay`. */
+const REFRESH_AFTER_CHANGE_MS = 1000;
+
+/**
+ * The slowest walk a request waits for. A slower project is answered with the list it has at
+ * once and rebuilt on its own schedule, and whatever is showing the list gets the rebuild when
+ * `files:index-changed` says it landed. Measured on a 186k-entry project written into every
+ * 50 ms: waiting for its ~1 s walks made every palette open take 969 ms (p50), and walking again
+ * straight after each walk that a request found stale kept the worker walking without a break.
+ */
+const QUICK_WALK_MS = 250;
+
+/**
+ * Flat index of all files in the project for palette/search, as the `/files/index` response.
  * Applies filesExclude + searchExclude + optional gitignore.
- * Result is cached; call invalidateIndexCache(projectPath) to bust.
+ *
+ * Only a project with no list yet waits for the whole walk. A stale list of a project that is
+ * quick to walk is replaced if its rebuild lands within `graceMs`; any other stale list is
+ * returned as it is, the rebuild carrying on behind it — see `IndexEntry`. `graceMs` 0 answers
+ * with the held list at once.
  */
-export function buildIndex(projectPath: string): FileEntry[] {
-  const cached = indexCache.get(projectPath);
-  if (cached) return cached;
+export function buildIndex(projectPath: string, graceMs = REBUILD_GRACE_MS): Promise<IndexBuild> {
+  let entry = indexCache.get(projectPath);
+  if (!entry) {
+    entry = { build: null, stale: true, building: null, rewalk: false, refreshTimer: null, lastWalkEndedAt: 0, lastWalkMs: 0 };
+    indexCache.set(projectPath, entry);
+  }
+  const held = entry.build;
+  const waits = !held || entry.lastWalkMs <= QUICK_WALK_MS;
+  if (entry.stale) {
+    // A slow list is refreshed on its schedule; this only re-arms one a failed walk left unset.
+    if (!waits) scheduleRefresh(projectPath, entry);
+    else if (entry.building) entry.rewalk = true;
+    else startBuild(projectPath, entry);
+  }
+  const building = entry.building;
+  if (!building) return Promise.resolve(held!);
+  if (!held) return building;
+  if (graceMs <= 0 || !waits) return Promise.resolve(held);
+  const graceOver = new Promise<IndexBuild>((resolve) => setTimeout(() => resolve(held), graceMs));
+  return Promise.race([building.catch(() => held), graceOver]);
+}
 
-  const filter = resolveFilter(projectPath);
-  const ig = filter.useIgnoreFiles ? loadGitignore(projectPath) : null;
-  const allExclude = [...filter.filesExclude, ...filter.searchExclude];
-
-  const entries: FileEntry[] = [];
-  walkForIndex(projectPath, projectPath, allExclude, ig, entries);
-
-  indexCache.set(projectPath, entries);
-  return entries;
-}
-
-function walkForIndex(
-  rootPath: string,
-  dirPath: string,
-  allExclude: string[],
-  ig: Ignore | null,
-  results: FileEntry[],
-): void {
-  let dirEntries;
-  try { dirEntries = readdirSync(dirPath, { withFileTypes: true }); }
-  catch { return; }
-
-  for (const entry of dirEntries) {
-    const fullPath = join(dirPath, entry.name);
-    const relPath = relative(rootPath, fullPath);
-    const relPosix = relPath.split("\\").join("/");
-
-    // Apply glob exclusion (check full relative path and bare entry name)
-    // These are HARD excludes — .git, node_modules, dist, etc.
-    if (matchesGlob(relPosix, allExclude)) continue;
-    if (matchesGlob(entry.name, allExclude)) continue;
-
-    // Apply gitignore rules — SOFT exclude only (mark with isIgnored flag).
-    // Huge dirs like node_modules/dist/build are already hard-excluded by glob above.
-    let isIgnored = false;
-    if (ig) {
-      const checkPath = entry.isDirectory() ? `${relPosix}/` : relPosix;
-      isIgnored = ig.ignores(checkPath) || ig.ignores(relPosix);
-    }
+/**
+ * The best `limit` entries of the project's list for `query`, best first, searched where the list
+ * is held (see `index-search.ts`) — for a project whose list is too long to send to a browser.
+ * Searches the list `buildIndex` would answer with, and never waits for a rebuild: this is asked
+ * once per keystroke.
+ */
+export async function searchFileIndex(projectPath: string, query: string, kind: SearchKind, limit: number): Promise<FileEntry[]> {
+  const build = await buildIndex(projectPath, 0);
+  return fileIndexRunner.search(projectPath, build, query, kind, limit);
+}
 
-    if (entry.isDirectory()) {
-      results.push({ path: relPosix, name: entry.name, type: "directory" });
-      walkForIndex(rootPath, fullPath, allExclude, ig, results);
-    } else {
-      results.push({ path: relPosix, name: entry.name, type: "file", ...(isIgnored && { isIgnored: true }) });
-    }
+function startBuild(projectPath: string, entry: IndexEntry): Promise<IndexBuild> {
+  const previous = entry.build;
+  if (entry.refreshTimer) {
+    clearTimeout(entry.refreshTimer);
+    entry.refreshTimer = null;
+  }
+  // A change from here on may land behind the walk, so it has to leave the list stale again.
+  entry.stale = false;
+  entry.rewalk = false;
+  const filter = resolveFilter(projectPath);
+  const build = fileIndexRunner.run(projectPath, {
+    exclude: [...filter.filesExclude, ...filter.searchExclude],
+    useIgnoreFiles: filter.useIgnoreFiles,
+  }).then(
+    (next) => {
+      entry.building = null;
+      entry.build = next;
+      entry.lastWalkEndedAt = Date.now();
+      entry.lastWalkMs = next.walkMs;
+      if (previous) {
+        const changed = previous.hash !== next.hash;
+        for (const listener of rebuiltListeners) listener(projectPath, changed);
+      }
+      if (entry.rewalk) startBuild(projectPath, entry);
+      else if (entry.stale) scheduleRefresh(projectPath, entry);
+      return next;
+    },
+    (e) => {
+      entry.building = null;
+      entry.stale = true;
+      throw e;
+    },
+  );
+  entry.building = build;
+  // Nobody awaits a background rebuild, so its failure is only logged; the old list stays.
+  if (previous) {
+    build.catch((e) => console.warn(`[file-index] rebuilding ${projectPath} failed: ${(e as Error).message}`));
   }
+  return build;
 }

package/src/services/file-watcher/linux-inotify.ts

@@ -0,0 +1,238 @@
+/**
+ * Directory watches on Linux through one raw inotify instance, called over bun:ffi.
+ *
+ * Bun's `fs.watch` on Linux opens a descriptor for every *file* in a watched directory as well
+ * as for the directory itself (4 directories holding 600 files come to 604). The live server
+ * held 76,565 of them for its projects — 63k files, 13k directories — and every `Bun.spawn`
+ * then took ~5.6 ms instead of 0.08 ms, so each git call, terminal and Claude session stopped
+ * the event loop that long. An inotify watch on a directory already reports every entry in it:
+ * here the whole process holds one descriptor, whatever it watches.
+ *
+ * It also sidesteps Bun's registry being keyed by path, which makes a re-watch of a deleted and
+ * recreated directory silent forever (see recreated-dir-poller.ts): a recreated directory is a
+ * new inode, and adding a watch for it simply returns a new watch descriptor.
+ *
+ * The descriptor is read on a timer. `Bun.file(fd).stream()` over it ends at once with no events
+ * (measured), and a read that blocks would hold the loop; a non-blocking read that finds nothing
+ * is one syscall. The file watcher batches what it reports into 500 ms windows anyway.
+ */
+import { dlopen, FFIType, ptr, type Pointer } from "bun:ffi";
+
+const IN_NONBLOCK = 0o4000;
+const IN_CLOEXEC = 0o2000000;
+
+const IN_MODIFY = 0x2;
+const IN_ATTRIB = 0x4;
+const IN_MOVED_FROM = 0x40;
+const IN_MOVED_TO = 0x80;
+const IN_CREATE = 0x100;
+const IN_DELETE = 0x200;
+const IN_Q_OVERFLOW = 0x4000;
+/** The kernel dropped the watch: the directory is gone, its filesystem unmounted, or we removed it. */
+const IN_IGNORED = 0x8000;
+const IN_ONLYDIR = 0x01000000;
+const IN_DONT_FOLLOW = 0x02000000;
+
+/** The split libuv (and so Node's `fs.watch`) makes: entries appearing or vanishing vs. content. */
+const RENAME_EVENTS = IN_MOVED_FROM | IN_MOVED_TO | IN_CREATE | IN_DELETE;
+const CHANGE_EVENTS = IN_MODIFY | IN_ATTRIB;
+const WATCH_MASK = RENAME_EVENTS | CHANGE_EVENTS | IN_ONLYDIR | IN_DONT_FOLLOW;
+
+/** `struct inotify_event`: int wd; uint32 mask, cookie, len; then `len` bytes of NUL-padded name. */
+const EVENT_HEADER_BYTES = 16;
+const READ_BUFFER_BYTES = 64 * 1024;
+const POLL_MS = 50;
+
+export type DirEventKind = "rename" | "change";
+export type DirEventListener = (kind: DirEventKind, name: string) => void;
+
+export interface DirWatch {
+  close(): void;
+}
+
+interface Inotify {
+  fd: number;
+  addWatch: (fd: number, path: Uint8Array, mask: number) => number;
+  rmWatch: (fd: number, wd: number) => number;
+  read: (fd: number, buf: Pointer, size: number) => number | bigint;
+  buf: Uint8Array;
+  bufPtr: Pointer;
+}
+
+/** `undefined` until first asked for; `null` where inotify cannot be reached. */
+let inotify: Inotify | null | undefined;
+
+/**
+ * Listeners per watch descriptor. Two trees watching one directory — a project nested inside
+ * another — are handed the same descriptor by the kernel, so the watch is removed only once the
+ * last of them lets go. The wrapper object keeps each registration distinct.
+ */
+const listeners = new Map<number, Set<{ listener: DirEventListener }>>();
+const overflowListeners = new Set<() => void>();
+let timer: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Watches removed between two reads of the queue.
+ *
+ * Every `inotify_rm_watch` queues an IN_IGNORED, and a tree takes all of its watches down in one
+ * synchronous loop, so closing more directories than `max_queued_events` (16,384 by default)
+ * overflowed the queue by itself. The rebuild that answers an overflow takes the tree's watches
+ * down first, so a watched tree that size overflowed it again on every rebuild, for as long as
+ * it stayed open: 1.6 overflows a second and a third of a core on 20,000 directories. Reading as
+ * the watches go keeps the queue short. What is read waits in `pending` for the next drain, so
+ * no listener runs inside a `close()`.
+ */
+const READ_EVERY_REMOVALS = 1024;
+let removedSinceRead = 0;
+
+/**
+ * Read and not yet delivered. `kind: null` marks the kernel dropping a watch, kept in sequence so
+ * what came before it is still delivered.
+ */
+const pending: { wd: number; kind: DirEventKind | null; name: string }[] = [];
+const pendingKeys = new Set<string>();
+let pendingOverflow = false;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function open(): Inotify | null {
+  if (inotify !== undefined) return inotify;
+  inotify = null;
+  if (process.platform !== "linux") return null;
+  try {
+    const { symbols } = dlopen("libc.so.6", {
+      inotify_init1: { args: [FFIType.i32], returns: FFIType.i32 },
+      inotify_add_watch: { args: [FFIType.i32, FFIType.ptr, FFIType.u32], returns: FFIType.i32 },
+      inotify_rm_watch: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+      read: { args: [FFIType.i32, FFIType.ptr, FFIType.u64], returns: FFIType.i64 },
+    });
+    const fd = symbols.inotify_init1(IN_NONBLOCK | IN_CLOEXEC);
+    if (fd < 0) return null; // out of inotify instances: the caller falls back to fs.watch
+    const buf = new Uint8Array(READ_BUFFER_BYTES);
+    inotify = {
+      fd,
+      addWatch: (f, path, mask) => symbols.inotify_add_watch(f, ptr(path), mask),
+      rmWatch: symbols.inotify_rm_watch,
+      read: symbols.read,
+      buf,
+      bufPtr: ptr(buf),
+    };
+  } catch {
+    // No glibc (a musl build): the caller falls back to fs.watch.
+  }
+  return inotify;
+}
+
+/** Whether `watchDirectory` can be used on this host. */
+export function inotifyAvailable(): boolean {
+  return open() !== null;
+}
+
+/**
+ * Watch one directory's entries — not its subdirectories' — and report each change by entry
+ * name. Null when the directory cannot be watched (gone, not a directory, a symlink, or the
+ * machine's watch limit is spent), which is where `fs.watch` would have thrown.
+ */
+export function watchDirectory(dir: string, listener: DirEventListener): DirWatch | null {
+  const lib = open();
+  if (!lib) return null;
+  const wd = lib.addWatch(lib.fd, encoder.encode(`${dir}\0`), WATCH_MASK);
+  if (wd < 0) return null;
+  const registrations = listeners.get(wd) ?? new Set();
+  listeners.set(wd, registrations);
+  const registration = { listener };
+  registrations.add(registration);
+  timer ??= setInterval(drain, POLL_MS);
+  timer.unref?.();
+
+  let closed = false;
+  return {
+    close() {
+      if (closed) return;
+      closed = true;
+      // The set is gone when the kernel already dropped the watch — and its number may since
+      // have been handed to another directory, which must not lose its watch.
+      if (listeners.get(wd) === registrations && registrations.delete(registration) && registrations.size === 0) {
+        listeners.delete(wd);
+        lib.rmWatch(lib.fd, wd);
+        if (++removedSinceRead >= READ_EVERY_REMOVALS) readQueue(lib);
+      }
+      if (listeners.size === 0 && timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+  };
+}
+
+/**
+ * Called when the kernel's event queue overflowed (`max_queued_events`) and events were lost,
+ * so a watcher has to rebuild what it covers rather than trust it.
+ */
+export function onInotifyOverflow(listener: () => void): () => void {
+  overflowListeners.add(listener);
+  return () => { overflowListeners.delete(listener); };
+}
+
+/** Move everything queued into `pending`, one entry per distinct event, in the order they happened. */
+function readQueue(lib: Inotify): void {
+  removedSinceRead = 0;
+  for (;;) {
+    // -1 with EAGAIN when nothing is queued; any other failure is retried on the next tick.
+    const n = Number(lib.read(lib.fd, lib.bufPtr, READ_BUFFER_BYTES));
+    if (n <= 0) break;
+    const view = new DataView(lib.buf.buffer, 0, n);
+    for (let offset = 0; offset + EVENT_HEADER_BYTES <= n;) {
+      const wd = view.getInt32(offset, true);
+      const mask = view.getUint32(offset + 4, true);
+      const nameBytes = view.getUint32(offset + 12, true);
+      const raw = lib.buf.subarray(offset + EVENT_HEADER_BYTES, offset + EVENT_HEADER_BYTES + nameBytes);
+      offset += EVENT_HEADER_BYTES + nameBytes;
+      if (mask & IN_Q_OVERFLOW) {
+        pendingOverflow = true;
+        continue;
+      }
+      if (mask & IN_IGNORED) {
+        pending.push({ wd, kind: null, name: "" });
+        continue;
+      }
+      const end = raw.indexOf(0);
+      const name = decoder.decode(end < 0 ? raw : raw.subarray(0, end));
+      // Events about the watched directory itself carry no name; its parent reports those.
+      if (!name) continue;
+      const kind: DirEventKind = mask & RENAME_EVENTS ? "rename" : "change";
+      // A file written in a thousand chunks is a thousand IN_MODIFY; one report does.
+      const key = `${wd}\0${kind}\0${name}`;
+      if (pendingKeys.has(key)) continue;
+      pendingKeys.add(key);
+      pending.push({ wd, kind, name });
+    }
+  }
+}
+
+/** Read everything queued, then report each distinct event once, in the order they happened. */
+function drain(): void {
+  const lib = inotify;
+  if (!lib) return;
+  readQueue(lib);
+  const events = pending.splice(0);
+  pendingKeys.clear();
+  const overflowed = pendingOverflow;
+  pendingOverflow = false;
+  for (const { wd, kind, name } of events) {
+    if (kind === null) {
+      listeners.delete(wd);
+      continue;
+    }
+    const registrations = listeners.get(wd);
+    if (!registrations) continue;
+    for (const { listener } of [...registrations]) {
+      try { listener(kind, name); }
+      catch (e) { console.error(`[file-watcher] listener failed: ${(e as Error).message}`); }
+    }
+  }
+  if (overflowed) {
+    console.warn("[file-watcher] inotify queue overflowed, rebuilding coverage");
+    for (const listener of [...overflowListeners]) listener();
+  }
+}

package/src/services/file-watcher/watch-tree.ts

@@ -1,6 +1,7 @@
-import { lstatSync, readdirSync, watch, type FSWatcher } from "node:fs";
+import { lstatSync, readdirSync, watch } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { hasIgnoredDirSegment, isIgnoredDirName, isIgnoredPath } from "./ignore-rules.ts";
+import { inotifyAvailable, onInotifyOverflow, watchDirectory } from "./linux-inotify.ts";
 import { RecreatedDirPoller } from "./recreated-dir-poller.ts";
 
 /**
@@ -36,6 +37,11 @@ import { RecreatedDirPoller } from "./recreated-dir-poller.ts";
  * whole store watched, one open descriptor per file, which exhausted the process at
  * ~724k descriptors.
  *
+ * Linux no longer goes through `fs.watch` at all where glibc is present: each directory is
+ * one watch on a single inotify descriptor the whole process shares (`linux-inotify.ts`),
+ * because the per-file descriptors above still came to 76k on an ordinary set of projects.
+ * `fs.watch` remains the fallback there, and the recreated-directory poller with it.
+ *
  * Either way the walk below is what prunes ~92% of the directories in a typical repo,
  * and an ignored branch is never handed to the runtime.
  */
@@ -85,6 +91,11 @@ export interface WatchTreeOptions {
   maxDirs: number;
   /** Called with a root-relative POSIX path for every change worth reporting. */
   onChange: (relPath: string) => void;
+  /**
+   * Watch through raw inotify rather than `fs.watch`. Defaults to whether this host can, which
+   * only a Linux host with glibc can; tests pass false to keep the fallback covered.
+   */
+  inotify?: boolean;
 }
 
 interface ScanNode {
@@ -97,7 +108,7 @@ interface ScanNode {
 }
 
 interface AttachedWatcher {
-  watcher: FSWatcher;
+  watcher: { close(): void };
   /** Directories this watcher accounts for: the subtree when recursive, else itself. */
   covers: number;
   recursive: boolean;
@@ -106,7 +117,7 @@ interface AttachedWatcher {
 export interface WatchTreeStats {
   /** Directories covered ≈ inotify watches held on Linux. */
   dirs: number;
-  /** `fs.watch` handles held. */
+  /** Watch handles held: `fs.watch` watchers, or inotify watches on Linux. */
   watchers: number;
   /** Coverage was cut short by a budget, so part of the tree is unwatched. */
   truncated: boolean;
@@ -127,6 +138,8 @@ export class WatchTree {
    */
   private readonly everAttached = new Set<string>();
   private readonly poller: RecreatedDirPoller | null;
+  private readonly inotify: boolean;
+  private readonly stopOverflowListener: () => void;
   private covered = 0;
   private truncated = false;
   private closed = false;
@@ -142,14 +155,20 @@ export class WatchTree {
   private coverChain: Promise<void> = Promise.resolve();
 
   constructor(private readonly options: WatchTreeOptions) {
-    // Only Bun on Linux has the stale-watch defect; elsewhere re-watching works
-    // and paying for polling would be pure waste.
+    this.inotify = !NATIVE_RECURSIVE && (options.inotify ?? inotifyAvailable());
+    // Only Bun's `fs.watch` on Linux has the stale-watch defect; elsewhere re-watching works
+    // and paying for polling would be pure waste — raw inotify included, since a recreated
+    // directory is a new inode it simply watches.
     // Tied to NATIVE_RECURSIVE rather than re-testing the platform: the poller stands in
     // for a defect of the same emulation, and `attach()` relies on exactly one of the two
     // being in play. Deriving it here keeps that from drifting apart.
-    this.poller = !NATIVE_RECURSIVE
+    this.poller = !NATIVE_RECURSIVE && !this.inotify
       ? new RecreatedDirPoller({ onChange: (abs) => this.reportAbs(abs) })
       : null;
+    // Events were lost, so what is covered may have moved on: cover it again from the root.
+    this.stopOverflowListener = this.inotify
+      ? onInotifyOverflow(() => this.scheduleRebuild(this.options.root))
+      : () => {};
   }
 
   async start(): Promise<void> {
@@ -159,6 +178,7 @@ export class WatchTree {
 
   close(): void {
     this.closed = true;
+    this.stopOverflowListener();
     for (const timer of this.rebuildTimers.values()) clearTimeout(timer);
     this.rebuildTimers.clear();
     for (const { watcher } of this.attached.values()) {
@@ -347,6 +367,17 @@ export class WatchTree {
     // `close()` has already emptied the map it would have been recorded in.
     if (this.closed) return false;
     if (this.attached.has(absDir)) return true;
+    if (this.inotify) {
+      const watcher = watchDirectory(absDir, (event, filename) => this.handleEvent(absDir, false, event, filename));
+      if (!watcher) {
+        this.truncated = true; // the same failures `fs.watch` throws for below
+        return false;
+      }
+      this.attached.set(absDir, { watcher, covers, recursive: false });
+      this.everAttached.add(absDir);
+      this.covered += covers;
+      return true;
+    }
     try {
       const watcher = watch(absDir, { recursive }, (event, filename) => {
         this.handleEvent(absDir, recursive, event, typeof filename === "string" ? filename : null);