@indigoai-us/hq-cloud 6.14.44 → 6.14.45

package/src/watch-roots.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Tests for the watch-root planner.
+ *
+ * The invariant under test is the one the whole change exists for: the watcher
+ * must only register OS watches over paths that can actually upload. Before
+ * this planner, macOS/Windows placed ONE recursive `fs.watch` on hqRoot, so the
+ * OS delivered every event in the tree — including `repos/` (~26k dirs on a
+ * real HQ) and `workspace/worktrees/` (~62k dirs) — and each one was filtered
+ * out only AFTER it had already cost a syscall and an allocation.
+ *
+ * The planner walks the exclusion filter up front and returns the minimum set
+ * of watch roots that covers exactly the in-scope tree:
+ *   - `recursive`: the dir's entire subtree is in scope → one recursive watch.
+ *   - `shallow`:   the dir contains an excluded child → watch the dir itself
+ *                  non-recursively and descend into its in-scope children.
+ */
+
+import { mkdtemp, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { isCoveredByRecursiveRoot, planWatchRoots } from "./watch-roots.js";
+import type { WatchPathFilter } from "./watcher.js";
+
+const ROOT = path.resolve("/hq");
+
+/** Build the `listChildDirs` seam over a literal `absDir -> childNames` map. */
+function treeLister(tree: Record<string, string[]>) {
+  return (dir: string): string[] =>
+    (tree[dir] ?? []).map((name) => path.join(dir, name));
+}
+
+/**
+ * Build a filter shaped like the real one: `prefixes` are exact vault-relative
+ * prefixes (`repos`, `workspace/worktrees` — position-sensitive), `anySegment`
+ * names are excluded at any depth (`node_modules`, `.git`).
+ */
+function makeFilter(opts: {
+  prefixes?: string[];
+  anySegment?: string[];
+}): WatchPathFilter {
+  const prefixes = opts.prefixes ?? [];
+  const anySegment = new Set(opts.anySegment ?? []);
+  return (absolutePath: string): boolean => {
+    const rel = path.relative(ROOT, absolutePath).split(path.sep).join("/");
+    if (rel === "" || rel.startsWith("..")) return false;
+    if (prefixes.some((p) => rel === p || rel.startsWith(p + "/"))) return false;
+    if (rel.split("/").some((seg) => anySegment.has(seg))) return false;
+    return true;
+  };
+}
+
+/** Every dir the plan asks the OS to watch, recursive roots and shallow alike. */
+function allWatched(plan: { recursive: string[]; shallow: string[] }): string[] {
+  return [...plan.recursive, ...plan.shallow];
+}
+
+describe("planWatchRoots — minimal cover of the in-scope tree", () => {
+  it("collapses a fully in-scope tree to ONE recursive watch at the root", () => {
+    const plan = planWatchRoots(ROOT, makeFilter({}), {
+      listChildDirs: treeLister({
+        [ROOT]: ["companies", "core"],
+        [path.join(ROOT, "companies")]: ["acme"],
+      }),
+    });
+
+    expect(plan.recursive).toEqual([ROOT]);
+    expect(plan.shallow).toEqual([]);
+  });
+
+  it("never registers a watch on an excluded dir, and never covers one from a recursive root", () => {
+    const filter = makeFilter({
+      prefixes: ["repos"],
+      anySegment: ["node_modules"],
+    });
+    const plan = planWatchRoots(ROOT, filter, {
+      listChildDirs: treeLister({
+        [ROOT]: ["companies", "repos", "node_modules"],
+        [path.join(ROOT, "companies")]: ["acme"],
+        [path.join(ROOT, "repos")]: ["hq-cloud"],
+      }),
+    });
+
+    // The root has excluded children, so it cannot be a recursive root.
+    expect(plan.shallow).toContain(ROOT);
+    expect(plan.recursive).not.toContain(ROOT);
+    // `companies/` is clean, so it collapses to one recursive watch.
+    expect(plan.recursive).toContain(path.join(ROOT, "companies"));
+
+    // The point of the whole change: excluded trees are never watched at all.
+    for (const watched of allWatched(plan)) {
+      expect(watched).not.toContain(`${path.sep}repos`);
+      expect(watched).not.toContain("node_modules");
+    }
+  });
+
+  it("descends through a partially-excluded dir to reach its in-scope children", () => {
+    // `workspace/` is in scope but `workspace/worktrees/` (the 62k-dir bucket)
+    // is not — so `workspace` must be shallow and its siblings recursive.
+    const filter = makeFilter({ prefixes: ["workspace/worktrees"] });
+    const plan = planWatchRoots(ROOT, filter, {
+      listChildDirs: treeLister({
+        [ROOT]: ["workspace"],
+        [path.join(ROOT, "workspace")]: ["agency", "threads", "worktrees"],
+        [path.join(ROOT, "workspace", "worktrees")]: ["feature-a"],
+      }),
+    });
+
+    expect(plan.shallow).toEqual(
+      expect.arrayContaining([ROOT, path.join(ROOT, "workspace")]),
+    );
+    expect(plan.recursive).toEqual(
+      expect.arrayContaining([
+        path.join(ROOT, "workspace", "agency"),
+        path.join(ROOT, "workspace", "threads"),
+      ]),
+    );
+    expect(allWatched(plan)).not.toContain(
+      path.join(ROOT, "workspace", "worktrees"),
+    );
+  });
+
+  it("holds the invariant: no excluded path lies under any recursive root", () => {
+    const filter = makeFilter({
+      prefixes: ["repos", "workspace/worktrees"],
+      anySegment: ["node_modules", ".git"],
+    });
+    const tree: Record<string, string[]> = {
+      [ROOT]: [
+        "companies",
+        "core",
+        "workspace",
+        "repos",
+        ".git",
+        "node_modules",
+      ],
+      [path.join(ROOT, "companies")]: ["acme", "indigo"],
+      [path.join(ROOT, "core")]: ["skills"],
+      [path.join(ROOT, "workspace")]: ["agency", "worktrees"],
+      [path.join(ROOT, "workspace", "worktrees")]: ["wt-1"],
+      [path.join(ROOT, "repos")]: ["hq-cloud"],
+    };
+    const plan = planWatchRoots(ROOT, filter, {
+      listChildDirs: treeLister(tree),
+    });
+
+    const excludedDirs = Object.keys(tree)
+      .flatMap((dir) => (tree[dir] ?? []).map((n) => path.join(dir, n)))
+      .filter((p) => !filter(p, true));
+    expect(excludedDirs.length).toBeGreaterThan(0);
+
+    for (const excluded of excludedDirs) {
+      // Not watched directly...
+      expect(allWatched(plan)).not.toContain(excluded);
+      // ...and not swept in as a descendant of some recursive root either.
+      for (const root of plan.recursive) {
+        expect(excluded.startsWith(root + path.sep)).toBe(false);
+      }
+    }
+  });
+
+  it("stops descending at maxDepth and takes a recursive watch there", () => {
+    const filter = makeFilter({ anySegment: ["node_modules"] });
+    const plan = planWatchRoots(ROOT, filter, {
+      maxDepth: 1,
+      listChildDirs: treeLister({
+        [ROOT]: ["a", "node_modules"],
+        [path.join(ROOT, "a")]: ["b", "node_modules"],
+        [path.join(ROOT, "a", "b")]: ["c"],
+      }),
+    });
+
+    // Depth 0 has an excluded child → shallow. Depth 1 is the bound, so `a`
+    // takes a recursive watch even though it still contains node_modules; the
+    // per-event filter drops that residue. This bounds handle count on trees
+    // with deeply scattered exclusions.
+    expect(plan.shallow).toEqual([ROOT]);
+    expect(plan.recursive).toEqual([path.join(ROOT, "a")]);
+  });
+
+  it("skips a directory it cannot read instead of throwing", () => {
+    const plan = planWatchRoots(ROOT, makeFilter({ prefixes: ["repos"] }), {
+      listChildDirs: (dir: string) => {
+        if (dir === path.join(ROOT, "denied")) {
+          throw Object.assign(new Error("EACCES"), { code: "EACCES" });
+        }
+        return dir === ROOT
+          ? [path.join(ROOT, "denied"), path.join(ROOT, "repos")]
+          : [];
+      },
+    });
+
+    // The unreadable dir is still watched (we cannot see inside it to decide
+    // better) and the walk completes rather than crashing start().
+    expect(allWatched(plan)).toContain(path.join(ROOT, "denied"));
+    expect(allWatched(plan)).not.toContain(path.join(ROOT, "repos"));
+  });
+
+  it("reports every in-scope directory through onDirectory, and no excluded one", () => {
+    // TreeWatcher builds its known-kinds index from this callback instead of
+    // walking the same tree a second time, so the callback must cover every
+    // in-scope directory — including ones inside a collapsed recursive root.
+    const filter = makeFilter({ prefixes: ["repos"] });
+    const seen: string[] = [];
+    planWatchRoots(ROOT, filter, {
+      onDirectory: (dir) => seen.push(dir),
+      listChildDirs: treeLister({
+        [ROOT]: ["companies", "repos"],
+        [path.join(ROOT, "companies")]: ["acme"],
+        [path.join(ROOT, "companies", "acme")]: ["knowledge"],
+        [path.join(ROOT, "repos")]: ["hq-cloud"],
+      }),
+    });
+
+    expect(seen).toEqual([
+      path.join(ROOT, "companies"),
+      path.join(ROOT, "companies", "acme"),
+      path.join(ROOT, "companies", "acme", "knowledge"),
+    ]);
+    expect(seen).not.toContain(path.join(ROOT, "repos"));
+    expect(seen).not.toContain(path.join(ROOT, "repos", "hq-cloud"));
+  });
+
+  it("resolves coverage by walking ancestors, not by scanning every root", () => {
+    // This runs on EVERY rename event, in the hot path of a change whose whole
+    // point is cutting per-event cost. A linear scan is O(number of roots) —
+    // 685 on a real HQ tree — where an ancestor walk is O(path depth), ~10.
+    // The behavior must be identical, including the prefix trap below.
+    const roots = new Set([path.join(ROOT, "a", "b"), path.join(ROOT, "c")]);
+
+    expect(isCoveredByRecursiveRoot(path.join(ROOT, "a", "b"), roots)).toBe(true);
+    expect(
+      isCoveredByRecursiveRoot(path.join(ROOT, "a", "b", "deep", "x.md"), roots),
+    ).toBe(true);
+    expect(isCoveredByRecursiveRoot(path.join(ROOT, "a"), roots)).toBe(false);
+    expect(isCoveredByRecursiveRoot(path.join(ROOT, "d"), roots)).toBe(false);
+    // The prefix trap: `/hq/a/bc` shares a string prefix with root `/hq/a/b`
+    // but is NOT under it. A naive startsWith without the separator would say
+    // covered, and the whole subtree would go unwatched.
+    expect(isCoveredByRecursiveRoot(path.join(ROOT, "a", "bc"), roots)).toBe(
+      false,
+    );
+    expect(
+      isCoveredByRecursiveRoot(path.join(ROOT, "a", "bc", "x.md"), roots),
+    ).toBe(false);
+  });
+
+  it("reports nothing as covered when there are no recursive roots", () => {
+    expect(
+      isCoveredByRecursiveRoot(path.join(ROOT, "a", "b"), new Set<string>()),
+    ).toBe(false);
+  });
+
+  it("plans over a real directory tree using the default reader", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "hqcloud-planroots-"));
+    try {
+      await mkdir(path.join(root, "companies", "acme"), { recursive: true });
+      await mkdir(path.join(root, "repos", "hq-cloud", "src"), {
+        recursive: true,
+      });
+
+      const filter: WatchPathFilter = (abs) => {
+        const rel = path.relative(root, abs).split(path.sep).join("/");
+        if (rel === "" || rel.startsWith("..")) return false;
+        return rel !== "repos" && !rel.startsWith("repos/");
+      };
+      const plan = planWatchRoots(root, filter);
+
+      expect(plan.shallow).toContain(root);
+      expect(plan.recursive).toContain(path.join(root, "companies"));
+      expect(allWatched(plan)).not.toContain(path.join(root, "repos"));
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/watch-roots.ts

@@ -0,0 +1,162 @@
+/**
+ * Watch-root planner — reduce the in-scope tree to the smallest set of OS
+ * watches that covers exactly the paths that can upload.
+ *
+ * Why this exists: on macOS/Windows the watcher used to place ONE recursive
+ * `fs.watch` on hqRoot. That is cheap in handles but the OS then delivers every
+ * event in the tree, including the buckets sync never uploads — on a real HQ
+ * root that is `repos/` (~26k directories) and `workspace/worktrees/` (~62k),
+ * where agent builds, installs, and checkouts churn constantly. Every one of
+ * those events woke the runner, cost a `path.resolve` (plus a synchronous
+ * `lstat` for renames), and was then dropped by the emit filter. The result was
+ * a node process pinned above 100% CPU doing nothing but allocating and
+ * garbage-collecting discarded paths.
+ *
+ * The planner walks the exclusion filter ONCE at start and returns:
+ *   - `recursive`: directories whose entire subtree is in scope. One recursive
+ *     watch each; the OS never reports an excluded path under them.
+ *   - `shallow`: directories that contain an excluded descendant. Watched
+ *     non-recursively so their own files still fire, with their in-scope
+ *     children planned separately.
+ *
+ * The walk is post-order: whether a directory can collapse to a single
+ * recursive watch depends on its whole subtree, not just its direct children
+ * (`workspace/` looks clean until you reach `workspace/worktrees/`).
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+import type { WatchPathFilter } from "./watcher.js";
+
+export interface WatchRootPlan {
+  /** Directories to watch recursively — their whole subtree is in scope. */
+  recursive: string[];
+  /** Directories to watch non-recursively — they contain excluded children. */
+  shallow: string[];
+}
+
+export interface PlanWatchRootsOptions {
+  /**
+   * Optional depth at which the walk stops splitting and takes a recursive
+   * watch even if the subtree still holds exclusions. Unbounded by default:
+   * the walk costs about what {@link TreeWatcher}'s known-kinds seed walk
+   * already cost on every start, and the two are fused via `onDirectory`, so
+   * paying for full pruning is free. A bound trades pruning for walk time on
+   * pathologically deep trees; the per-event filter drops whatever residue it
+   * admits, so this is a performance dial, never a correctness one.
+   */
+  maxDepth?: number;
+  /** Directory reader seam — defaults to a real `readdirSync`. */
+  listChildDirs?: (dir: string) => string[];
+  /**
+   * Invoked once for every in-scope directory the walk visits. Lets a caller
+   * populate its own directory index in the SAME pass instead of walking the
+   * tree a second time.
+   */
+  onDirectory?: (absolutePath: string) => void;
+}
+
+function defaultListChildDirs(dir: string): string[] {
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(dir, entry.name));
+}
+
+interface VisitResult {
+  /** True when every descendant of this directory is in scope. */
+  clean: boolean;
+  plan: WatchRootPlan;
+}
+
+/**
+ * Plan the watch roots for `hqRoot` under `shouldEmit`.
+ *
+ * `shouldEmit(dir, true)` is the same directory predicate the watcher uses at
+ * event time, so the plan and the emit filter can never disagree about what is
+ * in scope.
+ */
+export function planWatchRoots(
+  hqRoot: string,
+  shouldEmit: WatchPathFilter,
+  opts: PlanWatchRootsOptions = {},
+): WatchRootPlan {
+  const maxDepth = opts.maxDepth ?? Number.POSITIVE_INFINITY;
+  const listChildDirs = opts.listChildDirs ?? defaultListChildDirs;
+  const onDirectory = opts.onDirectory;
+  const root = path.resolve(hqRoot);
+
+  const visit = (dir: string, depth: number): VisitResult => {
+    let children: string[];
+    try {
+      children = listChildDirs(dir);
+    } catch {
+      // Unreadable (permissions, or a race with a concurrent delete). We cannot
+      // prove the subtree is clean, but dropping it would silently stop syncing
+      // it — take the recursive watch and let the per-event filter sort it out.
+      return { clean: true, plan: { recursive: [dir], shallow: [] } };
+    }
+
+    const included: string[] = [];
+    let hasExcludedChild = false;
+    for (const child of children) {
+      if (shouldEmit(child, true)) {
+        included.push(child);
+        onDirectory?.(path.resolve(child));
+      } else hasExcludedChild = true;
+    }
+
+    // At the depth bound we stop splitting. `clean` still reports what we can
+    // see one level down so an ancestor does not collapse over a known
+    // exclusion it could have pruned.
+    if (depth >= maxDepth) {
+      return {
+        clean: !hasExcludedChild,
+        plan: { recursive: [dir], shallow: [] },
+      };
+    }
+
+    const childResults = included.map((child) => visit(child, depth + 1));
+    const clean =
+      !hasExcludedChild && childResults.every((result) => result.clean);
+
+    // A clean subtree collapses to a single recursive watch here, discarding
+    // the per-child watches the recursion built below it.
+    if (clean) return { clean: true, plan: { recursive: [dir], shallow: [] } };
+
+    return {
+      clean: false,
+      plan: {
+        recursive: childResults.flatMap((result) => result.plan.recursive),
+        shallow: [dir, ...childResults.flatMap((result) => result.plan.shallow)],
+      },
+    };
+  };
+
+  return visit(root, 0).plan;
+}
+
+/**
+ * True when `absolutePath` already falls under one of `recursiveRoots`.
+ *
+ * Walks the path's own ancestors rather than scanning the root set: this runs
+ * on every rename event, in the hot path of a backend whose entire purpose is
+ * cutting per-event cost, and a real HQ tree plans ~685 roots. Ancestor-walking
+ * is O(path depth) — about ten set lookups — instead of O(roots) string
+ * comparisons. It also cannot fall into the shared-prefix trap, where `/hq/a/bc`
+ * looks like it sits under the root `/hq/a/b`.
+ */
+export function isCoveredByRecursiveRoot(
+  absolutePath: string,
+  recursiveRoots: ReadonlySet<string>,
+): boolean {
+  if (recursiveRoots.size === 0) return false;
+  let current = path.resolve(absolutePath);
+  for (;;) {
+    if (recursiveRoots.has(current)) return true;
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}

package/src/watcher-event-gate.test.ts

@@ -0,0 +1,212 @@
+/**
+ * The emit filter must run BEFORE handleEvent pays for a stat.
+ *
+ * The recursive backend hands every OS event to handleEvent, and a `rename`
+ * used to be lstat'd before the exclusion filter was consulted. On a real HQ
+ * that is one synchronous syscall for every file touched anywhere under
+ * `repos/` or `workspace/worktrees/` — build, install, and checkout churn the
+ * watcher immediately throws away. Scoped watch roots (see watch-roots.ts) keep
+ * most of that traffic from being delivered at all; this gate makes whatever
+ * still arrives cost a string compare instead of a syscall.
+ *
+ * This lives in its own file because it mocks `fs` module-wide, which would
+ * otherwise perturb the 53 tests in watcher.test.ts.
+ */
+
+import * as os from "os";
+import * as path from "path";
+
+import { describe, expect, it, vi } from "vitest";
+
+const { lstatCalls } = vi.hoisted(() => ({ lstatCalls: vi.fn() }));
+
+vi.mock("fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("fs")>();
+  return {
+    ...actual,
+    lstatSync: (...args: Parameters<typeof actual.lstatSync>) => {
+      lstatCalls(...args);
+      return actual.lstatSync(...args);
+    },
+  };
+});
+
+const { FakeClock, TreeWatcher } = await import("./watcher.js");
+
+const hqRoot = path.join(os.tmpdir(), "hqcloud-event-gate-root");
+/** Everything under `repos/` is out of scope, as file AND as directory. */
+const outOfScope = (abs: string) => !abs.split(path.sep).includes("repos");
+
+function makeWatcher() {
+  return new TreeWatcher({
+    hqRoot,
+    clock: new FakeClock(),
+    debounceMs: 100,
+    pathFilter: outOfScope,
+  });
+}
+
+describe("TreeWatcher.handleEvent — an excluded path costs no syscall", () => {
+  it("does NOT stat an out-of-scope rename before dropping it", () => {
+    const watcher = makeWatcher();
+    lstatCalls.mockClear();
+    try {
+      watcher.handleEvent(
+        path.join(hqRoot, "repos", "hq-cloud", "src", "a.ts"),
+        "rename",
+      );
+      expect(lstatCalls).not.toHaveBeenCalled();
+    } finally {
+      watcher.dispose();
+    }
+  });
+
+  it("still stats an in-scope rename, so kind classification is unchanged", () => {
+    const watcher = makeWatcher();
+    lstatCalls.mockClear();
+    try {
+      watcher.handleEvent(
+        path.join(hqRoot, "companies", "acme", "note.md"),
+        "rename",
+      );
+      expect(lstatCalls).toHaveBeenCalled();
+    } finally {
+      watcher.dispose();
+    }
+  });
+
+  it("skips its own seed walk when the backend already indexed directories", async () => {
+    // The scoped backend indexes every in-scope directory while planning its
+    // watch roots. TreeWatcher must NOT then walk the same tree again — on a
+    // real HQ root that walk is ~3.6s, and doing it twice per runner start was
+    // a straight doubling of startup cost for an identical index.
+    const fsp = await import("node:fs/promises");
+    const realRoot = await fsp.mkdtemp(
+      path.join(os.tmpdir(), "hqcloud-seed-fusion-"),
+    );
+    try {
+      await fsp.mkdir(path.join(realRoot, "companies", "acme", "knowledge"), {
+        recursive: true,
+      });
+
+      const watcher = new TreeWatcher({
+        hqRoot: realRoot,
+        clock: new FakeClock(),
+        pathFilter: () => true,
+        backendFactory: (opts) => {
+          opts.onDirectorySeen?.(path.join(realRoot, "companies"));
+          return {
+            close: () => {},
+            needsKnownKinds: true,
+            seededKnownKinds: true,
+            watchedPathCount: () => 1,
+          };
+        },
+      });
+      watcher.start();
+      // Exactly the one directory the backend reported — not the three that a
+      // second full walk of this tree would have found.
+      expect(watcher.knownDirectoryCount()).toBe(1);
+      watcher.dispose();
+    } finally {
+      await fsp.rm(realRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("still walks itself when the backend did NOT index directories", async () => {
+    const fsp = await import("node:fs/promises");
+    const realRoot = await fsp.mkdtemp(
+      path.join(os.tmpdir(), "hqcloud-seed-legacy-"),
+    );
+    try {
+      await fsp.mkdir(path.join(realRoot, "companies", "acme", "knowledge"), {
+        recursive: true,
+      });
+
+      const watcher = new TreeWatcher({
+        hqRoot: realRoot,
+        clock: new FakeClock(),
+        pathFilter: () => true,
+        backendFactory: () => ({
+          close: () => {},
+          needsKnownKinds: true,
+          watchedPathCount: () => 1,
+        }),
+      });
+      watcher.start();
+      expect(watcher.knownDirectoryCount()).toBe(3);
+      watcher.dispose();
+    } finally {
+      await fsp.rm(realRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("does not let a duplicate delete downgrade unlinkDir to unlink", () => {
+    // One path can reach handleEvent twice when two watches overlap (the
+    // scoped backend briefly runs its bootstrap watch alongside the planned
+    // ones so in-flight events are not dropped). The first unlinkDir clears
+    // the path's known-kind hint, so without this guard the duplicate lands as
+    // a plain `unlink` — narrowing the deletion scope the vault applies and
+    // discarding the captured descendant snapshots.
+    const clock = new FakeClock();
+    const w = new TreeWatcher({
+      hqRoot,
+      clock,
+      debounceMs: 100,
+      pathFilter: () => true,
+      captureLocalDeleteSnapshots: (relativePath, kind) =>
+        kind === "unlinkDir"
+          ? [
+              {
+                journalSlug: "acme",
+                journalPath: `${relativePath}/child.md`,
+                absolutePath: path.join(hqRoot, relativePath, "child.md"),
+                remoteEtag: "etag",
+                localHash: "hash",
+                localKind: "file" as const,
+              },
+            ]
+          : [],
+    });
+    const batches: Array<Map<string, { kind: string }> | undefined> = [];
+    w.onChange((_first, batch) => batches.push(batch?.changes as never));
+    try {
+      const dir = path.join(hqRoot, "companies", "acme", "moved");
+      w.handleEvent(dir, "unlinkDir");
+      w.handleEvent(dir, "unlink"); // duplicate delivery of the same delete
+      clock.advance(200);
+
+      const change = batches[0]?.get(dir) as
+        | { kind: string; deleteSnapshots?: unknown[] }
+        | undefined;
+      expect(change?.kind).toBe("unlinkDir");
+      expect(change?.deleteSnapshots).toHaveLength(1);
+    } finally {
+      w.dispose();
+    }
+  });
+
+  it("keeps emitting in-scope changes after the gate", () => {
+    const watcher = makeWatcher();
+    const clock = new FakeClock();
+    const w = new TreeWatcher({
+      hqRoot,
+      clock,
+      debounceMs: 100,
+      pathFilter: outOfScope,
+    });
+    watcher.dispose();
+    const rels: string[] = [];
+    w.onChange((_first, batch) => {
+      if (batch) rels.push(...batch.paths.values());
+    });
+    try {
+      w.handleEvent(path.join(hqRoot, "companies", "acme", "note.md"), "change");
+      w.handleEvent(path.join(hqRoot, "repos", "x", "code.ts"), "change");
+      clock.advance(200);
+      expect(rels).toEqual(["companies/acme/note.md"]);
+    } finally {
+      w.dispose();
+    }
+  });
+});