@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/version.ts

@@ -1,24 +0,0 @@
-/**
- * The hq-cloud package version, read once at module load.
- *
- * Mirrors hq-cli's `cli-version.ts` pattern: resolve the version from the
- * package.json at runtime via `import.meta.url` (rootDir-safe — no JSON import
- * that would trip `tsc`'s rootDir, and resolves correctly from both `src/`
- * during tests and `dist/` at runtime). Used to stamp `clientInfo.version` on
- * the sync-runner's vault requests so the company-vend min-version gate (HQ-59,
- * hq-pro) can tell a compliant (>= 6.11.6) sync-runner from a pre-6.11.6
- * straggler. This is the hq-cloud package version — the version the gate
- * compares against its floor — NOT the hq-sync desktop app version.
- */
-
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import path from "node:path";
-
-const here = path.dirname(fileURLToPath(import.meta.url));
-// src/version.ts → dist/version.js; one level up from either is the package root.
-const pkg = JSON.parse(
-  readFileSync(path.resolve(here, "..", "package.json"), "utf-8"),
-) as { name: string; version: string };
-
-export const HQ_CLOUD_VERSION: string = pkg.version;

package/src/watch-roots.test.ts

@@ -1,278 +0,0 @@
-/**
- * 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

@@ -1,162 +0,0 @@
-/**
- * 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

@@ -1,212 +0,0 @@
-/**
- * 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();
-    }
-  });
-});