@indigoai-us/hq-cloud 6.14.50 → 6.15.1

package/src/watcher.test.ts

@@ -1,1079 +0,0 @@
-import { afterEach, beforeEach, describe, it, expect, vi } from "vitest";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import { watch } from "chokidar";
-import {
-  FakeClock,
-  WatchPushDriver,
-  TreeWatcher,
-  ChokidarWatchBudget,
-  createWatchPathFilter,
-  toChokidarIgnored,
-  PushEventEmitter,
-} from "./watcher.js";
-import { StaticFlagProvider } from "./sync/feature-flags.js";
-import type { PushEvent } from "./sync/push-event.js";
-import type { PushTransport } from "./sync/push-transport.js";
-import type { TelemetryEventsBatch } from "./vault-client.js";
-
-/**
- * US-001 — Phase 1 test harness: watch-triggered push seam + latency assertion.
- *
- * These tests drive the debounce/coalesce core ({@link WatchPushDriver}) with an
- * injected {@link FakeClock} and an injected spy push fn — no real chokidar
- * watcher, no real S3, no real 10-minute sleep. US-002/US-003 build the real
- * watcher + targeted-push fn on top of this same seam, so the tests here also
- * serve as regression guards for the contract those stories depend on.
- */
-
-const DEBOUNCE = 2000;
-
-/**
- * Build a driver wired to a FakeClock and a spy push fn. Returns everything a
- * test needs to drive and assert against the seam. This helper is the reusable
- * "test harness" the story asks for.
- */
-function makeHarness(opts?: { debounceMs?: number }) {
-  const clock = new FakeClock();
-  const push = vi.fn(() => {});
-  const driver = new WatchPushDriver({
-    debounceMs: opts?.debounceMs ?? DEBOUNCE,
-    clock,
-    push,
-  });
-  return {
-    clock,
-    push,
-    driver,
-    /** Emit a synthetic file-change event into the driver. */
-    emitChange: () => driver.notifyChange(),
-    /** Advance virtual time. */
-    advance: (ms: number) => clock.advance(ms),
-  };
-}
-
-async function flushImmediate(): Promise<void> {
-  await new Promise<void>((resolve) => setImmediate(resolve));
-}
-
-describe("FakeClock", () => {
-  it("fires a timer exactly when its deadline is reached", () => {
-    const clock = new FakeClock();
-    const fn = vi.fn();
-    clock.setTimeout(fn, 100);
-    clock.advance(99);
-    expect(fn).not.toHaveBeenCalled();
-    clock.advance(1);
-    expect(fn).toHaveBeenCalledTimes(1);
-  });
-
-  it("does not fire a cleared timer", () => {
-    const clock = new FakeClock();
-    const fn = vi.fn();
-    const handle = clock.setTimeout(fn, 100);
-    clock.clearTimeout(handle);
-    clock.advance(1000);
-    expect(fn).not.toHaveBeenCalled();
-    expect(clock.pendingTimerCount()).toBe(0);
-  });
-
-  it("reports pending timer count for leak checks", () => {
-    const clock = new FakeClock();
-    clock.setTimeout(() => {}, 100);
-    clock.setTimeout(() => {}, 200);
-    expect(clock.pendingTimerCount()).toBe(2);
-    clock.advance(100);
-    expect(clock.pendingTimerCount()).toBe(1);
-  });
-});
-
-describe("US-001: WatchPushDriver — debounced push seam", () => {
-  it("calls the injected push fn exactly once within debounce+grace after a synthetic change", async () => {
-    const h = makeHarness();
-
-    h.emitChange();
-    // Before the window elapses, no push.
-    h.advance(DEBOUNCE - 1);
-    expect(h.push).not.toHaveBeenCalled();
-
-    // Crossing the debounce boundary fires the push exactly once.
-    h.advance(1);
-    await Promise.resolve();
-    expect(h.push).toHaveBeenCalledTimes(1);
-  });
-
-  it("coalesces N rapid changes within the window to exactly 1 push", async () => {
-    const h = makeHarness();
-
-    // 5 synthetic changes spread across less than one debounce window.
-    for (let i = 0; i < 5; i++) {
-      h.emitChange();
-      h.advance(100); // total 500ms << 2000ms debounce
-    }
-    // Window has not fully elapsed since the LAST change yet.
-    expect(h.push).not.toHaveBeenCalled();
-
-    // Let the quiet window after the final change elapse.
-    h.advance(DEBOUNCE);
-    await Promise.resolve();
-    expect(h.push).toHaveBeenCalledTimes(1);
-  });
-
-  it("treats two separate bursts as two pushes", async () => {
-    const h = makeHarness();
-
-    h.emitChange();
-    h.advance(DEBOUNCE);
-    await Promise.resolve();
-    expect(h.push).toHaveBeenCalledTimes(1);
-
-    h.emitChange();
-    h.advance(DEBOUNCE);
-    await Promise.resolve();
-    expect(h.push).toHaveBeenCalledTimes(2);
-  });
-
-  it("never overlaps an in-flight push; a mid-push change re-triggers one follow-up pass", async () => {
-    const clock = new FakeClock();
-    let release!: () => void;
-    const inFlight = new Promise<void>((r) => {
-      release = r;
-    });
-    let calls = 0;
-    const push = vi.fn(() => {
-      calls += 1;
-      // First push hangs until released; later pushes resolve immediately.
-      return calls === 1 ? inFlight : Promise.resolve();
-    });
-    const driver = new WatchPushDriver({ debounceMs: DEBOUNCE, clock, push });
-
-    // First burst -> first push starts and hangs.
-    driver.notifyChange();
-    clock.advance(DEBOUNCE);
-    await Promise.resolve();
-    expect(push).toHaveBeenCalledTimes(1);
-    expect(driver.isPushing()).toBe(true);
-
-    // A change arrives while the first push is in flight: must NOT start a
-    // concurrent push.
-    driver.notifyChange();
-    clock.advance(DEBOUNCE);
-    await Promise.resolve();
-    expect(push).toHaveBeenCalledTimes(1);
-
-    // Release the first push; the collapsed mid-push change re-arms.
-    release();
-    await inFlight;
-    await Promise.resolve();
-    // Re-armed window must elapse before the follow-up push fires.
-    clock.advance(DEBOUNCE);
-    await Promise.resolve();
-    expect(push).toHaveBeenCalledTimes(2);
-
-    driver.dispose();
-  });
-
-  it("F17: rejected watch push is caught instead of surfacing as an unhandled rejection", async () => {
-    const clock = new FakeClock();
-    const rejection = new Error("push failed");
-    const push = vi.fn(async () => {
-      throw rejection;
-    });
-    const driver = new WatchPushDriver({ debounceMs: DEBOUNCE, clock, push });
-    const unhandled: unknown[] = [];
-    const onUnhandled = (reason: unknown) => {
-      unhandled.push(reason);
-    };
-
-    process.prependListener("unhandledRejection", onUnhandled);
-    try {
-      driver.notifyChange();
-      clock.advance(DEBOUNCE);
-      await Promise.resolve();
-      await flushImmediate();
-
-      expect(push).toHaveBeenCalledTimes(1);
-      expect(driver.isPushing()).toBe(false);
-      expect(unhandled).toEqual([]);
-    } finally {
-      process.removeListener("unhandledRejection", onUnhandled);
-      driver.dispose();
-    }
-  });
-
-  it("respects a custom debounce window", async () => {
-    const h = makeHarness({ debounceMs: 500 });
-    h.emitChange();
-    h.advance(499);
-    expect(h.push).not.toHaveBeenCalled();
-    h.advance(1);
-    await Promise.resolve();
-    expect(h.push).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe("US-001: WatchPushDriver — teardown leaves no leaked timers", () => {
-  it("dispose() cancels a pending debounce timer", () => {
-    const h = makeHarness();
-    h.emitChange();
-    expect(h.clock.pendingTimerCount()).toBe(1);
-
-    h.driver.dispose();
-    expect(h.clock.pendingTimerCount()).toBe(0);
-
-    // A push must not fire after dispose, even if time advances.
-    h.advance(DEBOUNCE * 10);
-    expect(h.push).not.toHaveBeenCalled();
-  });
-
-  it("notifyChange() after dispose is a no-op and schedules nothing", () => {
-    const h = makeHarness();
-    h.driver.dispose();
-    h.emitChange();
-    expect(h.clock.pendingTimerCount()).toBe(0);
-    h.advance(DEBOUNCE * 10);
-    expect(h.push).not.toHaveBeenCalled();
-  });
-
-  it("dispose() is idempotent", () => {
-    const h = makeHarness();
-    h.emitChange();
-    h.driver.dispose();
-    h.driver.dispose();
-    expect(h.clock.pendingTimerCount()).toBe(0);
-  });
-
-  it("a fully drained burst leaves zero pending timers", async () => {
-    const h = makeHarness();
-    for (let i = 0; i < 5; i++) h.emitChange();
-    h.advance(DEBOUNCE);
-    await Promise.resolve();
-    expect(h.push).toHaveBeenCalledTimes(1);
-    expect(h.clock.pendingTimerCount()).toBe(0);
-  });
-});
-
-/**
- * US-002 — file-watcher module (debounced, ignore-aware, exclusion-aware).
- *
- * `createWatchPathFilter` is pure (no chokidar) so the exclusion logic is
- * tested directly against absolute paths. `TreeWatcher` is then exercised via
- * its `handleEvent` seam + FakeClock so debounce/coalesce/lifecycle assert
- * deterministically without spinning a real chokidar instance.
- */
-
-const ROOT = "/tmp/hq-root";
-
-describe("US-002: createWatchPathFilter — ignore-list matching", () => {
-  const filter = createWatchPathFilter(ROOT, false);
-
-  it("emits for an ordinary tracked file", () => {
-    expect(filter(path.join(ROOT, "personal/notes.md"))).toBe(true);
-  });
-
-  it("does NOT emit for a .env file (DEFAULT_IGNORES secret)", () => {
-    expect(filter(path.join(ROOT, ".env"))).toBe(false);
-    expect(filter(path.join(ROOT, "personal/.env.local"))).toBe(false);
-  });
-
-  it("does NOT emit for node_modules / dist build artifacts", () => {
-    expect(filter(path.join(ROOT, "node_modules/foo/index.js"))).toBe(false);
-    expect(filter(path.join(ROOT, "dist/bundle.js"))).toBe(false);
-  });
-
-  it("does NOT emit for the watched root itself or paths outside it", () => {
-    expect(filter(ROOT)).toBe(false);
-    expect(filter("/some/other/place/file.txt")).toBe(false);
-  });
-});
-
-describe("US-002: createWatchPathFilter — personal-vault exclusions", () => {
-  const personal = createWatchPathFilter(ROOT, true);
-  const nonPersonal = createWatchPathFilter(ROOT, false);
-
-  it("does NOT emit for PERSONAL_VAULT_DEFAULT_EXCLUSIONS in personalMode (output/, .beads/)", () => {
-    expect(personal(path.join(ROOT, "personal/output/x.txt"))).toBe(false);
-    expect(personal(path.join(ROOT, "personal/.beads/issues.db"))).toBe(false);
-  });
-
-  it("does NOT emit for PERSONAL_VAULT_EXCLUDED_TOP_LEVEL in personalMode (.git/companies/repos/workspace)", () => {
-    expect(personal(path.join(ROOT, "companies/indigo/board.json"))).toBe(false);
-    expect(personal(path.join(ROOT, "workspace/threads/x.json"))).toBe(false);
-    expect(personal(path.join(ROOT, "repos/private/foo/file.ts"))).toBe(false);
-  });
-
-  // ── DEV-1778 continuity-pointer carve-out ───────────────────────────────
-  it("DOES emit for workspace/threads/handoff.json (the continuity pointer)", () => {
-    expect(personal(path.join(ROOT, "workspace/threads/handoff.json"))).toBe(
-      true,
-    );
-  });
-
-  it("still does NOT emit for other workspace/ files (carve-out is pointer-only)", () => {
-    // The pointer is the ONLY re-include — sibling threads, the journal, and
-    // unrelated workspace litter stay machine-local.
-    expect(personal(path.join(ROOT, "workspace/threads/T-old.json"))).toBe(
-      false,
-    );
-    expect(personal(path.join(ROOT, "workspace/threads/INDEX.md"))).toBe(false);
-    expect(personal(path.join(ROOT, "workspace/locks/x.lock"))).toBe(false);
-    // The pointer queried as a directory is not an emit target either.
-    expect(
-      personal(path.join(ROOT, "workspace/threads/handoff.json"), true),
-    ).toBe(false);
-  });
-
-  it("allows chokidar to DESCEND through the pointer's ancestor dirs (dir probe)", () => {
-    // Without this the Linux chokidar backend prunes `workspace/` before ever
-    // reaching the leaf. Ancestor dirs return true ONLY when queried as dirs.
-    expect(personal(path.join(ROOT, "workspace"), true)).toBe(true);
-    expect(personal(path.join(ROOT, "workspace/threads"), true)).toBe(true);
-    // A non-ancestor dir under workspace/ is still pruned.
-    expect(personal(path.join(ROOT, "workspace/locks"), true)).toBe(false);
-    // Ancestor dirs queried as FILES are not emit targets.
-    expect(personal(path.join(ROOT, "workspace"), false)).toBe(false);
-  });
-
-  // ── workspace/agency subtree carve-out (personal mode) ──────────────────
-  // The personal push uploads workspace/agency/** (computeAgencySyncPaths), so
-  // the personal watcher must emit those changes event-driven, not leave them
-  // for the 60s poll. Mirrors the continuity-pointer carve-out, for a subtree.
-  it("DOES emit for workspace/agency files in personalMode (synced subtree)", () => {
-    expect(
-      personal(path.join(ROOT, "workspace/agency/indigo/nick/chat.jsonl")),
-    ).toBe(true);
-    expect(
-      personal(path.join(ROOT, "workspace/agency/indigo/nick/status.json")),
-    ).toBe(true);
-    // The agency root itself, as a file event, also emits.
-    expect(personal(path.join(ROOT, "workspace/agency"))).toBe(true);
-  });
-
-  it("allows chokidar to DESCEND to workspace/agency in personalMode (dir probes)", () => {
-    // workspace/ and workspace/agency queried as dirs must return true so the
-    // chokidar backend descends instead of pruning workspace/ at the top.
-    expect(personal(path.join(ROOT, "workspace"), true)).toBe(true);
-    expect(personal(path.join(ROOT, "workspace/agency"), true)).toBe(true);
-    expect(
-      personal(path.join(ROOT, "workspace/agency/indigo"), true),
-    ).toBe(true);
-  });
-
-  it("agency carve-out is exact-segment (does NOT leak to workspace/agencyX)", () => {
-    // Only workspace/agency (and its subtree) is re-included; a sibling whose
-    // name merely starts with 'agency' stays excluded like other workspace litter.
-    expect(personal(path.join(ROOT, "workspace/agencyX/foo.txt"))).toBe(false);
-    expect(personal(path.join(ROOT, "workspace/agency-notes.md"))).toBe(false);
-  });
-
-  it("agency carve-out does not re-include other workspace/ litter", () => {
-    // Regression: the new carve-out must not widen the workspace exclusion for
-    // anything other than agency + the continuity pointer.
-    expect(personal(path.join(ROOT, "workspace/locks/x.lock"))).toBe(false);
-    expect(personal(path.join(ROOT, "workspace/threads/T-old.json"))).toBe(false);
-    expect(personal(path.join(ROOT, "workspace/worktrees/x/a.ts"))).toBe(false);
-  });
-
-  // ── workspace/.session-logs subtree carve-out (personal mode) ────────────
-  // The personal push uploads workspace/.session-logs/** (reindex-captured
-  // Claude Code transcripts, computeSessionLogsSyncPaths), so the personal
-  // watcher must emit those changes event-driven. Mirrors the agency carve-out.
-  it("DOES emit for workspace/.session-logs files in personalMode (synced subtree)", () => {
-    expect(
-      personal(path.join(ROOT, "workspace/.session-logs/session.jsonl")),
-    ).toBe(true);
-    expect(
-      personal(path.join(ROOT, "workspace/.session-logs/tool-results/r.txt")),
-    ).toBe(true);
-    // The subtree root itself, as a file event, also emits.
-    expect(personal(path.join(ROOT, "workspace/.session-logs"))).toBe(true);
-  });
-
-  it("allows chokidar to DESCEND to workspace/.session-logs in personalMode (dir probes)", () => {
-    expect(personal(path.join(ROOT, "workspace"), true)).toBe(true);
-    expect(personal(path.join(ROOT, "workspace/.session-logs"), true)).toBe(true);
-    expect(
-      personal(path.join(ROOT, "workspace/.session-logs/tool-results"), true),
-    ).toBe(true);
-  });
-
-  it("session-logs carve-out is exact-segment (does NOT leak to a similarly-named sibling)", () => {
-    expect(
-      personal(path.join(ROOT, "workspace/.session-logs-old/foo.txt")),
-    ).toBe(false);
-    expect(personal(path.join(ROOT, "workspace/.session-logsX.md"))).toBe(false);
-  });
-
-  it("does not apply the carve-out in non-personal mode", () => {
-    // In non-personal mode the excluded-top-level layer never runs, so the
-    // carve-out is irrelevant; handoff.json passes via the ordinary ignore
-    // stack like any other tracked file (no special-casing needed).
-    expect(
-      nonPersonal(path.join(ROOT, "workspace/threads/handoff.json")),
-    ).toBe(true);
-  });
-
-  it("DOES emit for an included top-level personal path in personalMode", () => {
-    expect(personal(path.join(ROOT, "personal/notes.md"))).toBe(true);
-    expect(personal(path.join(ROOT, "core/policies/x.md"))).toBe(true);
-  });
-
-  it("non-personal mode does NOT apply the excluded-top-level buckets", () => {
-    // companies/ is only excluded by the personal-vault layer; in non-personal
-    // mode the ignore stack alone governs and lets it through.
-    expect(nonPersonal(path.join(ROOT, "companies/indigo/board.json"))).toBe(true);
-  });
-
-  // ── Never-synced heavy buckets pruned in BOTH modes ─────────────────────
-  // In --companies mode personalMode=false, so the excluded-top-level layer
-  // never ran and the watcher descended into the local git worktrees
-  // (workspace/worktrees/, ~200k transient files from agent coding runs) and
-  // the on-box repos checkout (repos/). Neither ever vault-syncs in any mode,
-  // so watching them only burns inotify watches (near the OS limit) + CPU on
-  // build churn it discards, and can trip the overflow→full-reconcile fallback.
-  it("non-personal mode EXCLUDES never-synced heavy buckets (workspace/worktrees, repos)", () => {
-    expect(
-      nonPersonal(path.join(ROOT, "workspace/worktrees/hq-console/src/a.ts")),
-    ).toBe(false);
-    // The bucket dir itself is pruned so chokidar never descends into it.
-    expect(nonPersonal(path.join(ROOT, "workspace/worktrees"), true)).toBe(false);
-    expect(
-      nonPersonal(path.join(ROOT, "repos/private/hq-cloud/src/x.ts")),
-    ).toBe(false);
-    expect(nonPersonal(path.join(ROOT, "repos"), true)).toBe(false);
-  });
-
-  it("non-personal mode STILL watches synced content (companies/, workspace/agency, continuity)", () => {
-    expect(
-      nonPersonal(path.join(ROOT, "companies/indigo/board.json")),
-    ).toBe(true);
-    expect(
-      nonPersonal(path.join(ROOT, "workspace/agency/indigo/nick/status.json")),
-    ).toBe(true);
-    expect(
-      nonPersonal(path.join(ROOT, "workspace/threads/handoff.json")),
-    ).toBe(true);
-    // chokidar must still descend into workspace/ to reach agency + continuity.
-    expect(nonPersonal(path.join(ROOT, "workspace"), true)).toBe(true);
-    // A worktrees SIBLING under workspace/ is unaffected (only worktrees pruned).
-    expect(
-      nonPersonal(path.join(ROOT, "workspace/agency"), true),
-    ).toBe(true);
-  });
-
-  it("personal mode still excludes worktrees + repos (regression, unchanged)", () => {
-    expect(personal(path.join(ROOT, "workspace/worktrees/x/a.ts"))).toBe(false);
-    expect(personal(path.join(ROOT, "repos/private/x/a.ts"))).toBe(false);
-  });
-});
-
-describe("US-002: chokidar descent scope", () => {
-  let dir: string;
-
-  beforeEach(() => {
-    dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-scope-")));
-    // This is the real HQ allowlist shape. The synthetic heavy directories
-    // deliberately sit both under an in-scope company and under the two
-    // never-synced top-level buckets from #156.
-    fs.writeFileSync(path.join(dir, ".hqinclude"), "companies/*/knowledge/\n");
-    fs.mkdirSync(
-      path.join(dir, "companies", "acme", "knowledge", "node_modules", "heavy"),
-      { recursive: true },
-    );
-    fs.writeFileSync(
-      path.join(dir, "companies", "acme", "knowledge", "node_modules", "heavy", "index.js"),
-      "module.exports = 1;\n",
-    );
-    fs.mkdirSync(path.join(dir, "repos", "checkout", "heavy"), { recursive: true });
-    fs.mkdirSync(
-      path.join(dir, "workspace", "worktrees", "repo", "node_modules", "heavy"),
-      { recursive: true },
-    );
-  });
-
-  afterEach(() => {
-    fs.rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("uses the directory verdict, not a file-shaped false positive, for the pre-stat probe", () => {
-    const filter = createWatchPathFilter(dir, false);
-    const nodeModules = path.join(
-      dir,
-      "companies",
-      "acme",
-      "knowledge",
-      "node_modules",
-    );
-    // `node_modules/` is directory-only. Asking the generic emit filter as
-    // though it were a file returns true, which is exactly what the old
-    // `file || directory` probe used to mistake for permission to descend.
-    expect(filter(nodeModules, false)).toBe(true);
-    expect(filter(nodeModules, true)).toBe(false);
-    const ignored = toChokidarIgnored(filter, dir);
-    expect(ignored(nodeModules)).toBe(true);
-    // The allowlist's exact ancestor matcher remains the only carve-out: the
-    // watcher can still reach companies/<slug>/knowledge without opening every
-    // otherwise-file-shaped ignored directory below it.
-    expect(ignored(path.join(dir, "companies"))).toBe(false);
-    expect(ignored(path.join(dir, "companies", "acme"))).toBe(false);
-  });
-
-  it("prunes ignored directories during chokidar's pre-stat descent probe", async () => {
-    const filter = createWatchPathFilter(dir, false);
-    const chokidarWatcher = watch(dir, {
-      ignored: toChokidarIgnored(filter, dir),
-      ignoreInitial: true,
-      persistent: false,
-    });
-    try {
-      await new Promise<void>((resolve, reject) => {
-        chokidarWatcher.once("ready", resolve);
-        chokidarWatcher.once("error", reject);
-      });
-      const descended = Object.keys(chokidarWatcher.getWatched())
-        .map((watchedPath) => path.resolve(watchedPath))
-        .sort();
-
-      expect(descended).toContain(
-        path.join(dir, "companies", "acme", "knowledge"),
-      );
-      expect(descended).not.toContain(
-        path.join(dir, "companies", "acme", "knowledge", "node_modules"),
-      );
-      expect(descended).not.toContain(path.join(dir, "repos"));
-      expect(descended).not.toContain(path.join(dir, "workspace", "worktrees"));
-    } finally {
-      await chokidarWatcher.close();
-    }
-  });
-});
-
-describe("US-002: TreeWatcher — debounce coalesce (FakeClock seam)", () => {
-  function makeWatcher(opts?: { debounceMs?: number; personalMode?: boolean }) {
-    const clock = new FakeClock();
-    const changed = vi.fn();
-    const watcher = new TreeWatcher({
-      hqRoot: ROOT,
-      debounceMs: opts?.debounceMs ?? DEBOUNCE,
-      personalMode: opts?.personalMode ?? false,
-      clock,
-    });
-    watcher.onChange(changed);
-    return { clock, changed, watcher };
-  }
-
-  it("coalesces 5 rapid changes within the window into exactly 1 changed signal", () => {
-    const { clock, changed, watcher } = makeWatcher();
-    for (let i = 0; i < 5; i++) {
-      watcher.handleEvent(path.join(ROOT, `personal/file-${i}.md`));
-      clock.advance(20); // 100ms total << 2000ms debounce
-    }
-    expect(changed).not.toHaveBeenCalled();
-    clock.advance(DEBOUNCE);
-    expect(changed).toHaveBeenCalledTimes(1);
-    expect(watcher.pendingTimerCount()).toBe(0);
-  });
-
-  it("fires once after the quiet window for a single change", () => {
-    const { clock, changed, watcher } = makeWatcher();
-    watcher.handleEvent(path.join(ROOT, "personal/a.md"));
-    clock.advance(DEBOUNCE - 1);
-    expect(changed).not.toHaveBeenCalled();
-    clock.advance(1);
-    expect(changed).toHaveBeenCalledTimes(1);
-  });
-
-  it("does NOT emit for an ignored / excluded path", () => {
-    const { clock, changed, watcher } = makeWatcher({ personalMode: true });
-    watcher.handleEvent(path.join(ROOT, ".env"));
-    watcher.handleEvent(path.join(ROOT, "personal/output/big.bin"));
-    watcher.handleEvent(path.join(ROOT, "companies/indigo/board.json"));
-    clock.advance(DEBOUNCE * 2);
-    expect(changed).not.toHaveBeenCalled();
-    expect(watcher.pendingTimerCount()).toBe(0);
-  });
-
-  it("treats two separate bursts as two changed signals", () => {
-    const { clock, changed, watcher } = makeWatcher();
-    watcher.handleEvent(path.join(ROOT, "personal/a.md"));
-    clock.advance(DEBOUNCE);
-    expect(changed).toHaveBeenCalledTimes(1);
-    watcher.handleEvent(path.join(ROOT, "personal/b.md"));
-    clock.advance(DEBOUNCE);
-    expect(changed).toHaveBeenCalledTimes(2);
-  });
-
-  it("R-F13: caps watcher backlog and keeps EMFILE polling fallback removed", () => {
-    const clock = new FakeClock();
-    const changed = vi.fn();
-    const overflow = vi.fn();
-    const watcher = new TreeWatcher({
-      hqRoot: ROOT,
-      debounceMs: DEBOUNCE,
-      clock,
-      pathFilter: () => true,
-      maxPendingPaths: 3,
-      maxPendingBytes: 10_000,
-      onBacklogOverflow: overflow,
-    });
-    watcher.onChange(changed);
-
-    for (let i = 0; i < 10; i++) {
-      watcher.handleEvent(path.join(ROOT, `bulk-${i}.md`));
-    }
-
-    expect(overflow).toHaveBeenCalledTimes(1);
-    clock.advance(DEBOUNCE);
-    expect(changed).toHaveBeenCalledTimes(1);
-    const batch = changed.mock.calls[0][1] as {
-      paths: Map<string, string>;
-      overflowed?: boolean;
-      droppedPaths?: number;
-    };
-    expect(batch.paths.size).toBe(3);
-    expect(batch.overflowed).toBe(true);
-    expect(batch.droppedPaths).toBe(7);
-
-    const source = fs.readFileSync(path.join(process.cwd(), "src/watcher.ts"), "utf8");
-    expect(source).not.toContain("startPollingTreeWatch");
-    expect(source).not.toContain("snapshotWatchTree");
-  });
-
-  it("stops descending at the hard watch budget, reports, and degrades to polling", () => {
-    const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-cap-")));
-    fs.mkdirSync(path.join(dir, "personal", "a", "deep"), { recursive: true });
-    fs.mkdirSync(path.join(dir, "personal", "b", "deep"), { recursive: true });
-    const clock = new FakeClock();
-    const degraded = vi.fn();
-    const changed = vi.fn();
-    const descended: string[] = [];
-    let backendClosed = false;
-    try {
-      const watcher = new TreeWatcher({
-        hqRoot: dir,
-        clock,
-        debounceMs: DEBOUNCE,
-        maxWatchedPaths: 3,
-        onDegraded: degraded,
-        // This faked backend drives chokidar's real ignored predicate through
-        // its pre-stat and post-stat calls, without needing an inotify slot on
-        // a host already exhausted by another process.
-        backendFactory: ({
-          hqRoot,
-          shouldEmit,
-          maxWatchedPaths,
-          onWatchBudgetExceeded,
-        }) => {
-          const budget = new ChokidarWatchBudget(
-            maxWatchedPaths,
-            onWatchBudgetExceeded,
-          );
-          const ignored = toChokidarIgnored(shouldEmit, hqRoot, budget);
-          const visit = (candidate: string): void => {
-            if (ignored(candidate)) return;
-            const stats = fs.lstatSync(candidate);
-            if (ignored(candidate, stats)) return;
-            if (!stats.isDirectory()) return;
-            descended.push(path.resolve(candidate));
-            for (const entry of fs.readdirSync(candidate)) {
-              visit(path.join(candidate, entry));
-            }
-          };
-          visit(hqRoot);
-          return {
-            close: () => {
-              backendClosed = true;
-            },
-            needsKnownKinds: false,
-            watchedPathCount: () => descended.length,
-          };
-        },
-      });
-      watcher.onChange(changed);
-      watcher.start();
-
-      expect(descended).toHaveLength(3);
-      expect(descended).not.toContain(path.join(dir, "personal", "a", "deep"));
-      expect(degraded).toHaveBeenCalledWith(
-        expect.objectContaining({
-          reason: "watch_budget_exhausted",
-          maxWatchedPaths: 3,
-          watchedPaths: 3,
-          offendingPath: expect.stringContaining(path.join("personal", "a", "deep")),
-        }),
-      );
-      expect(backendClosed).toBe(true);
-      expect(watcher.isWatching()).toBe(false);
-
-      clock.advance(DEBOUNCE);
-      expect(changed).toHaveBeenCalledWith(
-        undefined,
-        expect.objectContaining({ overflowed: true }),
-      );
-    } finally {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("degrades instead of dying when chokidar emits runtime ENOSPC", () => {
-    const clock = new FakeClock();
-    const degraded = vi.fn();
-    const changed = vi.fn();
-    const telemetry: TelemetryEventsBatch[] = [];
-    const telemetryClient = {
-      postTelemetryEvents: vi.fn(async (batch: TelemetryEventsBatch) => {
-        telemetry.push(batch);
-        return { ok: true, written: batch.events.length, skipped: [] };
-      }),
-    };
-    let closeCalls = 0;
-    const watcher = new TreeWatcher({
-      hqRoot: ROOT,
-      clock,
-      debounceMs: DEBOUNCE,
-      onDegraded: degraded,
-      telemetryClient,
-      backendFactory: ({ onError }) => {
-        const backend = {
-          close: () => {
-            closeCalls += 1;
-          },
-          needsKnownKinds: false,
-          watchedPathCount: () => 0,
-        };
-        queueMicrotask(() =>
-          onError(
-            Object.assign(new Error("inotify limit"), {
-              code: "ENOSPC",
-              path: path.join(ROOT, "companies", "acme", "knowledge"),
-            }),
-          ),
-        );
-        return backend;
-      },
-    });
-    watcher.onChange(changed);
-    watcher.start();
-
-    return new Promise<void>((resolve) => queueMicrotask(resolve)).then(() => {
-      expect(closeCalls).toBe(1);
-      expect(watcher.isWatching()).toBe(false);
-      expect(degraded).toHaveBeenCalledWith(
-        expect.objectContaining({
-          reason: "inotify_enospc",
-          errorCode: "ENOSPC",
-          offendingPath: path.join(ROOT, "companies", "acme", "knowledge"),
-        }),
-      );
-      expect(telemetry).toEqual([
-        expect.objectContaining({
-          events: [
-            expect.objectContaining({
-              eventName: "watcher_degraded",
-              source: "watcher",
-              properties: expect.objectContaining({
-                reason: "inotify_enospc",
-                offendingTopLevel: "companies",
-              }),
-            }),
-          ],
-        }),
-      ]);
-      clock.advance(DEBOUNCE);
-      expect(changed).toHaveBeenCalledWith(
-        undefined,
-        expect.objectContaining({ overflowed: true }),
-      );
-    });
-  });
-
-  it("does not retain one rename-kind entry for every changed file", () => {
-    const clock = new FakeClock();
-    const watcher = new TreeWatcher({
-      hqRoot: ROOT,
-      clock,
-      pathFilter: () => true,
-      maxPendingPaths: 20_000,
-      maxPendingBytes: 20_000_000,
-    });
-    for (let i = 0; i < 10_000; i++) {
-      watcher.handleEvent(path.join(ROOT, "personal", `file-${i}.md`));
-    }
-    expect(watcher.knownDirectoryCount()).toBe(0);
-    watcher.stop();
-  });
-});
-
-describe("US-002: TreeWatcher — lifecycle (real chokidar over a temp dir)", () => {
-  let dir: string;
-
-  beforeEach(() => {
-    // realpathSync resolves macOS's /var -> /private/var symlink so chokidar's
-    // canonicalized event paths stay inside hqRoot (path.relative would
-    // otherwise yield a `..`-prefixed path and the filter would reject them).
-    dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "treewatcher-")));
-  });
-
-  afterEach(() => {
-    fs.rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("start() is idempotent — a second start does not open a second watcher", () => {
-    const w = new TreeWatcher({ hqRoot: dir });
-    w.start();
-    expect(w.isWatching()).toBe(true);
-    w.start(); // no throw, no second instance
-    expect(w.isWatching()).toBe(true);
-    w.stop();
-    expect(w.isWatching()).toBe(false);
-  });
-
-  it("stop() closes the watcher and clears pending timers; dispose() is permanent", () => {
-    const clock = new FakeClock();
-    const w = new TreeWatcher({ hqRoot: dir, clock });
-    w.start();
-    w.handleEvent(path.join(dir, "x.md"));
-    expect(w.pendingTimerCount()).toBe(1);
-    w.stop();
-    expect(w.pendingTimerCount()).toBe(0);
-    expect(w.isWatching()).toBe(false);
-
-    // After dispose, events are inert and start is a no-op.
-    w.dispose();
-    w.handleEvent(path.join(dir, "y.md"));
-    expect(w.pendingTimerCount()).toBe(0);
-    w.start();
-    expect(w.isWatching()).toBe(false);
-  });
-
-  it("emits a debounced changed signal for a real file write", async () => {
-    const w = new TreeWatcher({ hqRoot: dir, debounceMs: 50 });
-    const changed = vi.fn();
-    w.onChange(changed);
-    w.start();
-    // Give chokidar a beat to set up its watch before writing.
-    await new Promise((r) => setTimeout(r, 200));
-    fs.writeFileSync(path.join(dir, "hello.md"), "hi");
-    await new Promise((r) => setTimeout(r, 1500));
-    expect(changed).toHaveBeenCalled();
-    w.dispose();
-  }, 10_000);
-});
-
-describe("PushEventEmitter — directory and delete tombstone handling", () => {
-  let dir: string;
-
-  beforeEach(() => {
-    dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "pushemit-")));
-  });
-
-  afterEach(() => {
-    fs.rmSync(dir, { recursive: true, force: true });
-  });
-
-  function makeEmitter(opts?: {
-    published?: PushEvent[];
-    onError?: ReturnType<typeof vi.fn>;
-    getSequenceNumber?: () => number;
-  }): PushEventEmitter {
-    const published = opts?.published ?? [];
-    const transport: PushTransport = {
-      start: async () => {},
-      dispose: async () => {},
-      connected: true,
-      publish: async (event) => {
-        published.push(event);
-      },
-    };
-    return new PushEventEmitter({
-      originTenantId: "tenant-indigo",
-      originDeviceId: "device-a",
-      transport,
-      flagProvider: new StaticFlagProvider(["tenant-indigo"]),
-      now: () => new Date("2026-06-18T12:00:00.000Z"),
-      getSequenceNumber: opts?.getSequenceNumber,
-      onError: opts?.onError,
-    });
-  }
-
-  it("F13: watcher batch event publishing applies bounded backpressure", async () => {
-    const paths = new Map<string, string>();
-    for (let i = 0; i < 32; i++) {
-      const rel = `bulk-${i}.md`;
-      const abs = path.join(dir, rel);
-      fs.writeFileSync(abs, `file ${i}`);
-      paths.set(abs, rel);
-    }
-
-    let inFlight = 0;
-    let maxInFlight = 0;
-    let releaseGate!: () => void;
-    const gate = new Promise<void>((resolve) => {
-      releaseGate = resolve;
-    });
-    const transport: PushTransport = {
-      start: async () => {},
-      dispose: async () => {},
-      connected: true,
-      publish: async () => {
-        inFlight += 1;
-        maxInFlight = Math.max(maxInFlight, inFlight);
-        await gate;
-        inFlight -= 1;
-      },
-    };
-    const emitter = new PushEventEmitter({
-      originTenantId: "tenant-indigo",
-      originDeviceId: "device-a",
-      transport,
-      flagProvider: new StaticFlagProvider(["tenant-indigo"]),
-      now: () => new Date("2026-06-18T12:00:00.000Z"),
-    });
-
-    const run = emitter.emitForBatch({ paths });
-    try {
-      for (let i = 0; i < 200 && maxInFlight <= 16; i++) {
-        await flushImmediate();
-      }
-      releaseGate();
-      await run;
-
-      expect(maxInFlight).toBeLessThanOrEqual(16);
-    } finally {
-      releaseGate();
-      await run.catch(() => {});
-    }
-  });
-
-  it("skips directory changes silently without publishing or reporting an error", async () => {
-    const published: PushEvent[] = [];
-    const onError = vi.fn();
-    const subdir = path.join(dir, "folder");
-    fs.mkdirSync(subdir);
-    const emitter = makeEmitter({ published, onError });
-
-    await emitter.emitForBatch({ paths: new Map([[subdir, "folder"]]) });
-
-    expect(published).toEqual([]);
-    expect(onError).not.toHaveBeenCalled();
-  });
-
-  it("emits and publishes a delete tombstone when the changed file is gone", async () => {
-    const published: PushEvent[] = [];
-    const onError = vi.fn();
-    const emitter = makeEmitter({
-      published,
-      onError,
-      getSequenceNumber: () => 99,
-    });
-    const missing = path.join(dir, "deleted.md");
-
-    await emitter.emitForBatch({ paths: new Map([[missing, "deleted.md"]]) });
-
-    expect(onError).not.toHaveBeenCalled();
-    expect(published).toEqual([
-      {
-        kind: "delete",
-        relativePath: "deleted.md",
-        originDeviceId: "device-a",
-        originTenantId: "tenant-indigo",
-        sequenceNumber: 99,
-        eventTimestamp: "2026-06-18T12:00:00.000Z",
-      },
-    ]);
-    expect(published[0]).not.toHaveProperty("contentHash");
-    expect(published[0]).not.toHaveProperty("mtime");
-  });
-
-  it("emits push telemetry only when publication fails", async () => {
-    const posts: TelemetryEventsBatch[] = [];
-    const telemetryClient = {
-      postTelemetryEvents: vi.fn(async (batch: TelemetryEventsBatch) => {
-        posts.push(batch);
-        return { ok: true, written: batch.events.length, skipped: [] };
-      }),
-    };
-    const changed = path.join(dir, "changed.md");
-    fs.writeFileSync(changed, "changed");
-    const success = new PushEventEmitter({
-      originTenantId: "tenant-indigo",
-      originDeviceId: "device-a",
-      transport: {
-        start: async () => {},
-        dispose: async () => {},
-        connected: true,
-        publish: async () => {},
-      },
-      flagProvider: new StaticFlagProvider(["tenant-indigo"]),
-      telemetryClient,
-    });
-
-    await success.emitForBatch({ paths: new Map([[changed, "changed.md"]]) });
-    await flushImmediate();
-    expect(posts).toEqual([]);
-
-    const failed = new PushEventEmitter({
-      originTenantId: "tenant-indigo",
-      originDeviceId: "device-a",
-      transport: {
-        start: async () => {},
-        dispose: async () => {},
-        connected: true,
-        publish: async () => {
-          throw new Error("network down");
-        },
-      },
-      flagProvider: new StaticFlagProvider(["tenant-indigo"]),
-      telemetryClient,
-      onError: vi.fn(),
-    });
-
-    await failed.emitForBatch({ paths: new Map([[changed, "changed.md"]]) });
-    await flushImmediate();
-    expect(posts.flatMap((post) => post.events)).toEqual([
-      expect.objectContaining({
-        eventName: "push_event_failed",
-        properties: {
-          kind: "upsert",
-          count: 1,
-          status: "failure",
-          stage: "publish",
-        },
-      }),
-    ]);
-  });
-});
-
-describe("TreeWatcher wire-key codec boundary (US-002)", () => {
-  it("emits the canonical vault key for an encoded win32 farm name (verbatim local name on POSIX)", () => {
-    const hqRoot = path.join(os.tmpdir(), "hq-watch-codec-test-root");
-    const clock = new FakeClock();
-    const watcher = new TreeWatcher({
-      hqRoot,
-      clock,
-      debounceMs: 100,
-      pathFilter: () => true,
-    });
-    const rels: string[] = [];
-    watcher.onChange((_first, batch) => {
-      if (batch) rels.push(...batch.paths.values());
-    });
-
-    watcher.handleEvent(
-      path.join(hqRoot, ".claude", "skills", "indigo%3Acall-prep-brief"),
-    );
-    clock.advance(200);
-
-    // The batch rel is a WIRE identifier (PushEvent.relativePath / targeted
-    // push route). On win32 the encoded local farm name must decode back to
-    // the canonical key or event-driven push re-mints the junk key family;
-    // on POSIX the local name IS the key verbatim (codec is identity there).
-    const expectedRel =
-      process.platform === "win32"
-        ? ".claude/skills/indigo:call-prep-brief"
-        : ".claude/skills/indigo%3Acall-prep-brief";
-    expect(rels).toEqual([expectedRel]);
-    watcher.dispose();
-  });
-});