@hienlh/ppm 0.21.0 → 0.22.0

package/src/services/event-loop-lag.ts

@@ -0,0 +1,208 @@
+/**
+ * Event-loop lag, and — the part that decides what to do about it — whether the
+ * time was ours.
+ *
+ * PPM serves every HTTP request, every WebSocket frame and all of the chat work
+ * from one Bun process with one event loop, so anything synchronous holds up
+ * everything else for exactly as long as it runs. That is measurable from
+ * outside (`/api/health`, which returns a literal, has been seen taking 18.9s on
+ * a busy instance against 0.12-0.65ms on an idle one of the same binary), but
+ * from outside it names no culprit.
+ *
+ * A late tick means one of two things, and they are fixed in different places:
+ *
+ *   - **self** — the loop was busy with our own synchronous work, or with GC.
+ *     Worth hunting: a blocking call, a whole-file read, a synchronous DB write.
+ *   - **starved** — the OS gave the CPU to something else. PPM shares a machine,
+ *     and when a chat session spawns them a *cgroup*, with compilers, browsers
+ *     and one `claude` process per session. Nothing in this repository fixes
+ *     that; moving work to another thread least of all, since the CPU was never
+ *     ours to move it to.
+ *
+ * Sampling `process.cpuUsage()` across the same gap tells them apart: time we
+ * burned is ours, time we did not is somebody else's. Without that, "the server
+ * stalled" is a fact with two opposite conclusions.
+ *
+ * The monitor costs one timer and two counter reads per tick. It holds its
+ * samples in memory and writes nothing to disk — `~/.ppm/ppm.log` is already
+ * 261 MB with 54% of its lines duplicated, and a diagnostic that makes the
+ * problem it diagnoses worse is not one.
+ */
+
+/** How often the monitor checks in. */
+export const TICK_MS = 250;
+
+/** A tick at least this late is recorded. One whole interval of slip. */
+export const REPORT_THRESHOLD_MS = 250;
+
+/** Samples kept. At one stall per tick this is ~50s of solid stalling. */
+export const MAX_SAMPLES = 240;
+
+/** CPU/wall at or above this during the gap: the loop was busy with our work. */
+export const SELF_RATIO = 0.7;
+
+/** CPU/wall at or below this: the process was not running for most of the gap. */
+export const STARVED_RATIO = 0.25;
+
+export type LagCause = "self" | "starved" | "mixed";
+
+export interface LagSample {
+  /** Epoch ms at which the late tick finally ran. */
+  at: number;
+  /** How much later than scheduled it ran. */
+  lagMs: number;
+  /** Process CPU (user + system) consumed across the same gap. */
+  cpuMs: number;
+  /** Resident set at that moment, to spot a stall that is really GC pressure. */
+  rssMb: number;
+  cause: LagCause;
+}
+
+export interface LagReport {
+  /** Whether the monitor is running. */
+  running: boolean;
+  /** Ticks observed since it started. */
+  ticks: number;
+  /** Ticks that slipped past the threshold. */
+  stalls: number;
+  /** Total slip across those, in ms. */
+  blockedMs: number;
+  /** The single worst slip seen, in ms. */
+  worstMs: number;
+  /** Wall time the monitor has been running, in ms. */
+  uptimeMs: number;
+  /** Share of wall time the loop was unavailable, 0-1. */
+  blockedFraction: number;
+  /** How the stalls broke down. */
+  byCause: Record<LagCause, number>;
+  /** Most recent stalls, newest last. */
+  samples: LagSample[];
+}
+
+/**
+ * Which of the two stories the numbers tell.
+ *
+ * The ratio can exceed 1: `cpuUsage` counts every thread, and Bun runs file
+ * system work on a pool, so a gap spent in parallel IO bills more CPU than wall
+ * time passed. That is still our own work, which is what the answer says.
+ */
+export function classifyLag(lagMs: number, cpuMs: number): LagCause {
+  if (lagMs <= 0) return "self";
+  const ratio = cpuMs / lagMs;
+  if (ratio >= SELF_RATIO) return "self";
+  if (ratio <= STARVED_RATIO) return "starved";
+  return "mixed";
+}
+
+/**
+ * Fold one observation into a sample, or return null when the tick was on time.
+ *
+ * Split out from the timer so the arithmetic — which is the whole of the
+ * measurement — can be tested without waiting for real stalls to happen.
+ */
+export function sampleFromTick(args: {
+  now: number;
+  elapsedMs: number;
+  cpuMicros: number;
+  rssBytes: number;
+  thresholdMs?: number;
+}): LagSample | null {
+  const lagMs = args.elapsedMs - TICK_MS;
+  if (lagMs < (args.thresholdMs ?? REPORT_THRESHOLD_MS)) return null;
+  const cpuMs = args.cpuMicros / 1000;
+  return {
+    at: args.now,
+    lagMs: Math.round(lagMs),
+    cpuMs: Math.round(cpuMs),
+    rssMb: Math.round(args.rssBytes / 1048576),
+    cause: classifyLag(lagMs, cpuMs),
+  };
+}
+
+// ─── Monitor ───────────────────────────────────────────────────────────
+
+let timer: ReturnType<typeof setInterval> | null = null;
+let samples: LagSample[] = [];
+let startedAt = 0;
+let lastAt = 0;
+let lastCpu: { user: number; system: number } | null = null;
+let ticks = 0;
+let stalls = 0;
+let blockedMs = 0;
+let worstMs = 0;
+
+function tick(): void {
+  const now = Date.now();
+  const cpu = process.cpuUsage();
+  const elapsedMs = now - lastAt;
+  const cpuMicros = lastCpu
+    ? cpu.user - lastCpu.user + (cpu.system - lastCpu.system)
+    : 0;
+  lastAt = now;
+  lastCpu = cpu;
+  ticks++;
+
+  const sample = sampleFromTick({
+    now,
+    elapsedMs,
+    cpuMicros,
+    rssBytes: process.memoryUsage.rss(),
+  });
+  if (!sample) return;
+
+  stalls++;
+  blockedMs += sample.lagMs;
+  if (sample.lagMs > worstMs) worstMs = sample.lagMs;
+  samples.push(sample);
+  if (samples.length > MAX_SAMPLES) samples.shift();
+}
+
+/** Idempotent: calling it twice does not start a second timer. */
+export function startLagMonitor(): void {
+  if (timer) return;
+  startedAt = Date.now();
+  lastAt = startedAt;
+  lastCpu = process.cpuUsage();
+  ticks = 0;
+  stalls = 0;
+  blockedMs = 0;
+  worstMs = 0;
+  samples = [];
+  timer = setInterval(tick, TICK_MS);
+  // The monitor must never be the reason the process stays alive.
+  (timer as unknown as { unref?: () => void }).unref?.();
+}
+
+export function stopLagMonitor(): void {
+  if (!timer) return;
+  clearInterval(timer);
+  timer = null;
+  lastCpu = null;
+}
+
+export function lagReport(): LagReport {
+  const uptimeMs = startedAt ? Date.now() - startedAt : 0;
+  const byCause: Record<LagCause, number> = { self: 0, starved: 0, mixed: 0 };
+  for (const s of samples) byCause[s.cause]++;
+  return {
+    running: timer !== null,
+    ticks,
+    stalls,
+    blockedMs,
+    worstMs,
+    uptimeMs,
+    blockedFraction: uptimeMs > 0 ? blockedMs / uptimeMs : 0,
+    byCause,
+    samples: [...samples],
+  };
+}
+
+/** Test seam: drop every counter and sample without touching the timer. */
+export function resetLagMonitorForTest(): void {
+  samples = [];
+  ticks = 0;
+  stalls = 0;
+  blockedMs = 0;
+  worstMs = 0;
+  startedAt = 0;
+}

package/src/services/file-lines.ts

@@ -0,0 +1,114 @@
+/**
+ * Line-oriented reads of a file that may be enormous, without holding it.
+ *
+ * Both functions here replace a `readFileSync(path, "utf-8")` that was correct
+ * when the files were small and became a stall when they were not. Measured on
+ * this machine:
+ *
+ *   - `~/.ppm/ppm.log` at 276 MB: 264 ms to read + 92 ms to `split("\n")` =
+ *     **356 ms** of blocked event loop and a 644 MB resident spike, to answer
+ *     with the last 30 lines. The route doing it (`/api/logs/recent`) is
+ *     registered *before* `authMiddleware`.
+ *   - A 35 MB transcript: 34 ms to read as a string + 18 ms to walk it with
+ *     `charCodeAt`, to arrive at a line count.
+ *
+ * Neither cost was bounded: both grow with the file, and both were paid on the
+ * one thread that also serves every other request.
+ */
+
+/** How much of the end of a file is read to find the last few lines. */
+export const DEFAULT_TAIL_BYTES = 64 * 1024;
+
+/**
+ * The last `count` lines out of a slice taken from the end of a file.
+ *
+ * `startedMidFile` is what makes this safe to call on a slice: the first line
+ * of one is the tail of a line whose beginning was never read, so a report
+ * would open mid-sentence. It is dropped. That also absorbs the other hazard
+ * of slicing at an arbitrary byte — a cut through a multi-byte character
+ * decodes to U+FFFD, and the replacement character is inside the line being
+ * discarded.
+ */
+export function lastLinesFromTail(tail: string, count: number, startedMidFile: boolean): string {
+  const lines = tail.split("\n");
+  if (startedMidFile && lines.length > 0) lines.shift();
+  // A file that ends in a newline splits to a trailing empty string, and it
+  // counts against `count` like any other element — asking for the last 1 line
+  // of a well-formed log returned that empty string and nothing else. The
+  // previous `readFileSync` spelling had the same flaw and got away with it
+  // only because it always asked for 30 and then trimmed, quietly answering
+  // with 29.
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines.slice(-count).join("\n").trim();
+}
+
+/** The last `count` lines of a file, at a cost that does not grow with it. */
+export async function tailLines(
+  filePath: string,
+  count: number,
+  tailBytes: number = DEFAULT_TAIL_BYTES,
+): Promise<string> {
+  const file = Bun.file(filePath);
+  const size = file.size;
+  if (size <= 0) return "";
+  const start = Math.max(0, size - tailBytes);
+  const tail = await file.slice(start).text();
+  return lastLinesFromTail(tail, count, start > 0);
+}
+
+/** Bytes counted between two yields back to the event loop. */
+export const YIELD_EVERY_BYTES = 2 * 1024 * 1024;
+
+/**
+ * How many lines a file has, read as a stream of bytes.
+ *
+ * Counting `0x0A` over raw bytes rather than characters is not an
+ * approximation: UTF-8 gives every byte of a multi-byte sequence the high bit,
+ * so no byte of any non-ASCII character can collide with a newline. It also
+ * builds no string at all, so nothing the size of the file is held.
+ *
+ * This is **not faster** than the `readFileSync` walk it replaces — both are
+ * 53 ms on a 35 MB transcript. What changes is that the event loop gets the
+ * thread back during it, and that is the entire point.
+ *
+ * The explicit yield is the part that is easy to get wrong, and was. Awaiting
+ * the stream is *not* enough: its chunks resolve as **microtasks**, and a
+ * microtask queue drains without ever letting a timer or a socket run, so a
+ * `for await` over an already-buffered file blocks exactly as hard as the
+ * synchronous version. Measured with a 5 ms interval running alongside, over
+ * the same file:
+ *
+ *     readFileSync + charCodeAt   53 ms wall,  0 timer fires
+ *     stream, no explicit yield   37 ms wall,  0 timer fires
+ *     stream + setTimeout yield   53 ms wall,  9 timer fires, worst gap 11.8 ms
+ *
+ * (control: an equivalent `Bun.sleep` allows 12.) Only a macrotask hands the
+ * thread back, hence the `setTimeout`.
+ */
+export async function countLines(filePath: string): Promise<number> {
+  let count = 0;
+  let lastByte = -1;
+  let sinceYield = 0;
+  // `getReader()` rather than `for await`: Bun's ReadableStream is async
+  // iterable at runtime, but the DOM typings it is declared against do not say
+  // so, and a cast to paper over that would outlive the reason for it.
+  const reader = Bun.file(filePath).stream().getReader();
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done || !value) break;
+      for (let i = 0; i < value.length; i++) if (value[i] === 0x0a) count++;
+      if (value.length > 0) lastByte = value[value.length - 1]!;
+      sinceYield += value.length;
+      if (sinceYield >= YIELD_EVERY_BYTES) {
+        sinceYield = 0;
+        await new Promise<void>((r) => setTimeout(r, 0));
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  if (lastByte === -1) return 0;              // empty file
+  if (lastByte !== 0x0a) count++;             // last line carries no newline
+  return count;
+}

package/src/services/file-watcher/recreated-dir-poller.ts

@@ -22,6 +22,7 @@
  * there.
  */
 import { lstatSync, readdirSync } from "node:fs";
+import { lstat, readdir } from "node:fs/promises";
 import { join } from "node:path";
 
 /** Slow enough to be invisible next to inotify, fast enough for a save-and-see loop. */
@@ -33,6 +34,15 @@ const POLL_INTERVAL_MS = 1000;
  * blowup once.
  */
 const MAX_POLLED_DIRS = 64;
+/**
+ * Entries stat'ed per turn of the loop.
+ *
+ * A recreated `dist` or `node_modules` holds tens of thousands of files, and statting them in
+ * one go is the stall this whole release is about — once a second, forever, for as long as the
+ * directory stays polled. The reads are async so they run off the loop thread anyway; the batch
+ * is what stops their *completions* arriving as one unbroken run of callbacks.
+ */
+const STAT_BATCH = 256;
 
 export interface RecreatedDirPollerOptions {
   /** Absolute path of every entry that appeared, vanished or changed. */
@@ -50,6 +60,8 @@ export class RecreatedDirPoller {
   private readonly intervalMs: number;
   private readonly maxDirs: number;
   private droppedForBudget = false;
+  /** True while a sweep is in flight, so the interval cannot stack them. */
+  private sweeping = false;
 
   constructor(private readonly options: RecreatedDirPollerOptions) {
     this.intervalMs = options.intervalMs ?? POLL_INTERVAL_MS;
@@ -109,24 +121,114 @@ export class RecreatedDirPoller {
   }
 
   private tick(): void {
-    for (const [dir, previous] of this.snapshots) {
-      const current = this.readDir(dir);
+    // A sweep that outlasts the interval must not be joined by the next one: two sweeps over
+    // the same directories would double the syscalls and race each other's snapshot writes,
+    // and the slower the host the worse it would get — the opposite of what polling is for.
+    if (this.sweeping) return;
+    this.sweeping = true;
+    void this.sweep().finally(() => {
+      this.sweeping = false;
+    });
+  }
+
+  private async sweep(): Promise<void> {
+    // Copied, because a directory can be added or removed while this awaits.
+    let first = true;
+    for (const dir of [...this.snapshots.keys()]) {
+      if (!first) await new Promise((resolve) => setImmediate(resolve));
+      first = false;
+      const previous = this.snapshots.get(dir);
+      if (!previous) continue; // removed while we were reading something else
+      const current = await this.readDirAsync(dir);
+      // Identity, not presence. A directory can be removed *and added back* while this reads,
+      // which is the ordinary rebuild path on Linux — `scheduleRebuild` calls `closeSubtree`
+      // (which removes) and then `cover` (which adds), and the new `add` installs a fresh
+      // baseline synchronously. Diffing against the baseline that has since been replaced
+      // reports changes the new one already accounts for.
+      //
+      // Reasoned rather than measured: the window is inside the await above, and no test here
+      // reaches it. The severe half of the same hazard — storing the stale read over the new
+      // baseline, which makes the *next* sweep report the whole directory — is the check below,
+      // and that one is covered.
+      if (this.snapshots.get(dir) !== previous) continue;
 
       for (const [name, mtime] of current) {
         const before = previous.get(name);
         if (before === undefined || before !== mtime) {
-          this.options.onChange(join(dir, name));
+          this.report(join(dir, name));
         }
       }
       for (const name of previous.keys()) {
-        if (!current.has(name)) this.options.onChange(join(dir, name));
+        if (!current.has(name)) this.report(join(dir, name));
       }
 
-      this.snapshots.set(dir, current);
+      // Checked again: `onChange` runs synchronously between the two, and this class is
+      // exported with a caller-supplied callback that may close or re-register the directory.
+      if (this.snapshots.get(dir) === previous) this.snapshots.set(dir, current);
     }
   }
 
-  /** Direct entries of `absDir` with their mtimes. Empty when it is unreadable. */
+  /**
+   * One change, reported without letting a bad listener take the process down.
+   *
+   * The sweep runs from a `void`ed promise, so a throwing `onChange` becomes an unhandled
+   * rejection — and the server treats three of those in a minute as fatal, which a poller
+   * ticking once a second reaches in three. Swallowing is right here: the listener's failure
+   * is the listener's business, and the alternative is that one bad path stops the directory
+   * being watched at all.
+   */
+  private report(absPath: string): void {
+    try {
+      this.options.onChange(absPath);
+    } catch {
+      // The caller's problem, not a reason to stop polling.
+    }
+  }
+
+  /**
+   * Direct entries of `absDir` with their mtimes, without holding the loop.
+   *
+   * Empty when unreadable — deleted again, or permissions.
+   */
+  private async readDirAsync(absDir: string): Promise<DirSnapshot> {
+    const snapshot: DirSnapshot = new Map();
+    let names: string[];
+    try {
+      names = await readdir(absDir);
+    } catch {
+      return snapshot;
+    }
+    for (let i = 0; i < names.length; i += STAT_BATCH) {
+      // Measured, not assumed: on 10k entries, async reads alone took the worst loop gap from
+      // 341ms to 194ms, because the completions still arrived as one unbroken run. Handing the
+      // loop a turn between batches is what takes it to single digits.
+      if (i > 0) await new Promise((resolve) => setImmediate(resolve));
+      const batch = names.slice(i, i + STAT_BATCH);
+      const stats = await Promise.all(
+        batch.map(async (name) => {
+          try {
+            // lstat, not stat: a symlink's own mtime, never its target's, matching
+            // the scan that decides coverage.
+            return [name, (await lstat(join(absDir, name))).mtimeMs] as const;
+          } catch {
+            // Vanished between readdir and lstat; the next tick reports it.
+            return null;
+          }
+        }),
+      );
+      for (const entry of stats) if (entry) snapshot.set(entry[0], entry[1]);
+    }
+    return snapshot;
+  }
+
+  /**
+   * The same read, synchronously, for the baseline taken at registration.
+   *
+   * It stays sync so the baseline is the directory as it was at the moment `add` was called:
+   * a `git checkout` writes into a recreated directory immediately, and those writes are
+   * exactly what the poller exists to report. Taking the baseline a turn later would fold them
+   * into it and report nothing. It is one read per directory, not one per second.
+   */
   private readDir(absDir: string): DirSnapshot {
     const snapshot: DirSnapshot = new Map();
     let names: string[];

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

@@ -43,6 +43,32 @@ import { RecreatedDirPoller } from "./recreated-dir-poller.ts";
 /** Coalesce a burst of directory churn into a single subtree rebuild. */
 const REBUILD_DEBOUNCE_MS = 500;
 
+/**
+ * Directories walked between two hand-backs of the event loop.
+ *
+ * Covering a project used to be one synchronous burst: `readdirSync` down the
+ * whole tree, then `fs.watch` on every directory it kept. On a 12,000-directory
+ * project that held the loop for **2.95 seconds** at startup — measured, and
+ * billed to PPM by the lag monitor at ratio 1.38 across two independent
+ * restarts (the ratio is over 1 because Bun runs the `readdirSync` calls on its
+ * file system thread pool while the main thread walks). Nothing else in the
+ * process could run for any of it.
+ *
+ * Picked by measurement on a 13,321-directory tree, against a 5 ms timer whose
+ * fires are counted. The wall time is allowed to get worse — nothing waits on
+ * this walk any more — so the number to read is the worst single pause:
+ *
+ *   sync (before)   2361 ms wall     0 fires    gap = the whole 2361 ms
+ *   every 250 dirs  2653 ms wall    63 fires    worst gap 134 ms
+ *   every  64 dirs  2812 ms wall   183 fires    worst gap  41 ms
+ *   every  32 dirs  4624 ms wall   503 fires    worst gap  23 ms
+ *
+ * 64 is where the curve bends: halving it again buys 18 ms off the worst pause
+ * and costs 1.8 seconds of wall time. The residual ~41 ms is one batch, not
+ * scheduling overhead — it is the same with either yield primitive below.
+ */
+const YIELD_EVERY_DIRS = 64;
+
 /**
  * Whether `{ recursive: true }` is a real subtree watch rather than a per-directory walk.
  * Named platforms rather than `!== "linux"`, so a runtime nobody has measured here —
@@ -104,6 +130,16 @@ export class WatchTree {
   private covered = 0;
   private truncated = false;
   private closed = false;
+  private sinceYield = 0;
+  /**
+   * Covers run one at a time, as they did when they were synchronous.
+   *
+   * Each one reads `this.covered` to work out its remaining budget, so two
+   * interleaving would each believe the other's watchers were still unspent and
+   * together overshoot `maxDirs` — which on Linux is the inotify budget, the one
+   * number this class exists to respect.
+   */
+  private coverChain: Promise<void> = Promise.resolve();
 
   constructor(private readonly options: WatchTreeOptions) {
     // Only Bun on Linux has the stale-watch defect; elsewhere re-watching works
@@ -116,8 +152,9 @@ export class WatchTree {
       : null;
   }
 
-  start(): void {
-    this.cover(this.options.root);
+  async start(): Promise<void> {
+    await this.cover(this.options.root);
+    await this.reconcile();
   }
 
   close(): void {
@@ -144,18 +181,54 @@ export class WatchTree {
   }
 
   /** Walk `absDir` and attach the fewest watchers that cover it without touching ignored dirs. */
-  private cover(absDir: string): void {
+  private cover(absDir: string): Promise<void> {
+    const run = this.coverChain.then(() => this.coverNow(absDir));
+    // The chain must survive a failure — one unreadable subtree cannot stop
+    // every later cover — but the caller still has to be able to see it, so the
+    // swallowing copy and the returned promise are deliberately not the same one.
+    this.coverChain = run.catch(() => {});
+    return run;
+  }
+
+  private async coverNow(absDir: string): Promise<void> {
+    if (this.closed) return;
     const budget = { left: this.options.maxDirs - this.covered };
     if (budget.left <= 0) {
       this.truncated = true;
       return;
     }
-    this.attach(this.scan(absDir, budget));
+    this.sinceYield = 0;
+    await this.attach(await this.scan(absDir, budget));
+  }
+
+  /**
+   * Hand the event loop back every `YIELD_EVERY_DIRS` directories, and say
+   * whether the walk should carry on.
+   *
+   * A **macrotask**, not `await Promise.resolve()`. A microtask queue drains
+   * without ever letting a timer or a socket run, so awaiting one would leave
+   * the loop exactly as blocked while looking asynchronous — the same trap
+   * measured and documented in `file-lines.ts`.
+   *
+   * `close()` can now land in one of these pauses, which is why the answer is
+   * a boolean rather than void: a walk that carries on past it would attach
+   * watchers to a tree nobody is going to close.
+   *
+   * `setImmediate` rather than `setTimeout(…, 0)`: both let timers run, and
+   * both leave the same 41 ms worst pause, but a timer costs a real round trip
+   * per yield — at 208 yields that measured 3.4 s of wall time against 2.8 s.
+   */
+  private async yieldIfDue(): Promise<boolean> {
+    if (++this.sinceYield < YIELD_EVERY_DIRS) return !this.closed;
+    this.sinceYield = 0;
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    return !this.closed;
   }
 
-  private scan(absDir: string, budget: { left: number }): ScanNode {
+  private async scan(absDir: string, budget: { left: number }): Promise<ScanNode> {
     const node: ScanNode = { path: absDir, dirs: [], hasIgnored: false, size: 1 };
     budget.left--;
+    if (!(await this.yieldIfDue())) return node;
 
     let entries;
     try {
@@ -189,7 +262,7 @@ export class WatchTree {
         this.truncated = true;
         break;
       }
-      const child = this.scan(join(absDir, entry.name), budget);
+      const child = await this.scan(join(absDir, entry.name), budget);
       node.dirs.push(child);
       node.size += child.size;
       if (child.hasIgnored) node.hasIgnored = true;
@@ -198,7 +271,50 @@ export class WatchTree {
     return node;
   }
 
-  private attach(node: ScanNode): void {
+  /**
+   * Second pass: attach whatever appeared *during* the first one.
+   *
+   * `scan` takes a snapshot and `attach` then walks it, and both hand the event loop back
+   * every `YIELD_EVERY_DIRS` directories — so on a large project seconds pass between "X was
+   * read" and "X has a watcher". A directory created inside X in that window is in neither the
+   * snapshot nor under a live watcher, and nothing later finds it: `syncChildDir` only fires
+   * from a parent watcher that did not exist yet. That subtree would stay unwatched for the
+   * whole session — a file change that never arrives, which is the failure the budget comments
+   * in this file exist to avoid. Before the walk yielded at all the window was too small to
+   * matter; yielding is what opened it.
+   *
+   * Only non-recursive watchers are re-read, because a recursive handle covers what appears
+   * under it by definition. That is one extra `readdir` per *directory* on Linux and one per
+   * *subtree* on Windows and macOS.
+   */
+  private async reconcile(): Promise<void> {
+    if (this.closed) return;
+    this.sinceYield = 0;
+    for (const [dir, entry] of [...this.attached]) {
+      if (this.closed) return;
+      if (entry.recursive) continue;
+      let entries;
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        continue; // deleted since it was attached; its watcher will say so
+      }
+      for (const child of entries) {
+        // Same rules as the walk: symlinks are not directories here, which keeps link cycles
+        // and doubly-covered pnpm stores out of this pass too.
+        if (!child.isDirectory() || isIgnoredDirName(child.name)) continue;
+        const abs = join(dir, child.name);
+        if (this.attached.has(abs)) continue;
+        // The whole subtree under it, budget and truncation accounted for — the same call
+        // `syncChildDir` makes for a directory that appears under a live watcher.
+        await this.cover(abs);
+      }
+      if (!(await this.yieldIfDue())) return;
+    }
+  }
+
+  private async attach(node: ScanNode): Promise<void> {
+    if (this.closed) return;
     const fitsWholeSubtree = this.covered + node.size <= this.options.maxDirs;
 
     // A path we have watched before is being re-attached, so this directory was deleted
@@ -221,10 +337,15 @@ export class WatchTree {
       return;
     }
     this.addWatcher(node.path, false, 1);
-    for (const child of node.dirs) this.attach(child);
+    if (!(await this.yieldIfDue())) return;
+    for (const child of node.dirs) await this.attach(child);
   }
 
   private addWatcher(absDir: string, recursive: boolean, covers: number): boolean {
+    // The tightest guard against a walk that was still running when `close()`
+    // ran: a handle opened after it is one nothing will ever close, because
+    // `close()` has already emptied the map it would have been recorded in.
+    if (this.closed) return false;
     if (this.attached.has(absDir)) return true;
     try {
       const watcher = watch(absDir, { recursive }, (event, filename) => {
@@ -307,7 +428,7 @@ export class WatchTree {
     // A directory we already watch just got created again: the old handle is attached
     // to the deleted inode, so replace the whole subtree rather than trusting it.
     if (this.attached.has(abs)) this.scheduleRebuild(abs);
-    else this.cover(abs);
+    else void this.cover(abs);
   }
 
   private scheduleRebuild(absDir: string): void {
@@ -316,7 +437,7 @@ export class WatchTree {
       this.rebuildTimers.delete(absDir);
       if (this.closed) return;
       this.closeSubtree(absDir);
-      this.cover(absDir);
+      void this.cover(absDir);
     }, REBUILD_DEBOUNCE_MS));
   }