@indigoai-us/hq-cloud 6.18.44-alpha.9 → 6.18.44

package/dist/watcher.test.js

@@ -1,4301 +0,0 @@
-import { afterEach, beforeEach, describe, it, expect, vi } from "vitest";
-import { EventEmitter } from "node:events";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import { createHash } from "node:crypto";
-import { monitorEventLoopDelay } from "node:perf_hooks";
-import { watch } from "chokidar";
-import { FakeClock, WatchPushDriver, TreeWatcher, ChokidarWatchBudget, createWatchPathFilter, toChokidarIgnored, PushEventEmitter, PUBLISH_OUTCOME_JOURNALD_CEILING_BYTES, PUBLISH_OUTCOME_SUCCESS_SAMPLE_CAP, resolveEventDebounceConfig, summarizePublishBatchOutcome, DEFAULT_EVENT_DEBOUNCE_MS, DEFAULT_EVENT_MAX_WAIT_MS, DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS, DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS, DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES, DEFAULT_PUBLISH_MIN_INTERVAL_MS, EVENT_DEBOUNCE_MS_ENV, EVENT_MAX_WAIT_MS_ENV, EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV, EVENT_SMALL_BATCH_MAX_PATHS_ENV, EVENT_SMALL_BATCH_MAX_BYTES_ENV, DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS, MAX_TREE_WATCHER_MAX_WATCHED_PATHS, TREE_WATCHER_MAX_WATCHED_PATHS_ENV, resolveMaxWatchedPaths, PUBLISH_MIN_INTERVAL_MS_ENV, resolvePublishMinIntervalMs, DurablePublishedContentHashes, DURABLE_PUBLISHED_HASH_BATCH_FLUSH_MS, replayDurablePublishedContentHashRecordsForTest, startScopedRecursiveWatch, startNativeRootWatch, startTreeWatch, selectTreeWatchBackend } from "./watcher.js";
-import { StateStore, StateStoreLockError } from "./sync/state-store.js";
-import { HttpPushTransport, PushScopeForbiddenError, RealtimeUnavailableError, } from "./sync/push-transport.js";
-import { computePersonalVaultPaths } from "./personal-vault.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;
-describe("scoped watcher resource errors", () => {
-    let root;
-    beforeEach(() => {
-        root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-resource-error-")));
-    });
-    afterEach(() => {
-        fs.rmSync(root, { recursive: true, force: true });
-    });
-    it("does not reopen a directory watch after EMFILE", () => {
-        const docs = path.join(root, "docs");
-        fs.mkdirSync(docs);
-        class FakeWatcher extends EventEmitter {
-            close() {
-                this.emit("close");
-                return this;
-            }
-        }
-        const handles = new Map();
-        const watchedPaths = [];
-        const backend = startScopedRecursiveWatch(root, createWatchPathFilter(root, false), () => { }, () => { }, undefined, {
-            recursiveWatches: false,
-            listChildDirs: (dir) => dir === root ? [docs] : [],
-            watchDirectory: (dir) => {
-                const watchPath = dir.toString();
-                watchedPaths.push(watchPath);
-                const handle = new FakeWatcher();
-                handles.set(watchPath, handle);
-                return handle;
-            },
-        });
-        try {
-            expect(watchedPaths.filter((dir) => dir === docs)).toHaveLength(1);
-            handles.get(docs).emit("error", Object.assign(new Error("too many open files"), { code: "EMFILE" }));
-            expect(watchedPaths.filter((dir) => dir === docs)).toHaveLength(1);
-        }
-        finally {
-            backend.close();
-        }
-    });
-});
-function publishedHashRecords(count) {
-    const maxPaths = Math.max(1, Math.floor(count / 2));
-    let seed = 0x14c0ffee;
-    const next = () => {
-        seed = (seed * 1_664_525 + 1_013_904_223) >>> 0;
-        return seed;
-    };
-    return Array.from({ length: count }, (_, index) => {
-        const relativePath = `path-${next() % maxPaths}`;
-        return next() % 5 === 0
-            ? { sequence: index + 1, type: 0x5032, flags: 0, payload: { relativePath } }
-            : {
-                sequence: index + 1,
-                type: 0x5031,
-                flags: 0,
-                payload: { relativePath, contentHash: `sha256:${next()}`, maxPaths },
-            };
-    });
-}
-/**
- * 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) {
-    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) => clock.advance(ms),
-    };
-}
-async function flushImmediate() {
-    await new Promise((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("TreeWatcher adaptive watch budget", () => {
-    it("uses half of Linux max_user_watches, bounded by the floor and ceiling", () => {
-        const readFileSync = vi.fn(() => "1048576\n");
-        expect(resolveMaxWatchedPaths(undefined, {
-            platform: "linux",
-            env: {},
-            readFileSync,
-        })).toBe(MAX_TREE_WATCHER_MAX_WATCHED_PATHS);
-        expect(readFileSync).toHaveBeenCalledWith("/proc/sys/fs/inotify/max_user_watches", "utf8");
-        expect(resolveMaxWatchedPaths(undefined, {
-            platform: "linux",
-            env: {},
-            readFileSync: () => "40000\n",
-        })).toBe(DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS);
-        expect(resolveMaxWatchedPaths(undefined, {
-            platform: "linux",
-            env: {},
-            readFileSync: () => "8192\n",
-        })).toBe(4096);
-    });
-    it("keeps an explicit environment override authoritative", () => {
-        expect(resolveMaxWatchedPaths(undefined, {
-            platform: "linux",
-            env: { [TREE_WATCHER_MAX_WATCHED_PATHS_ENV]: "500000" },
-            readFileSync: () => {
-                throw new Error("must not read when overridden");
-            },
-        })).toBe(500_000);
-    });
-    it("falls back to the established constant off Linux or when proc is unreadable", () => {
-        expect(resolveMaxWatchedPaths(undefined, {
-            platform: "darwin",
-            env: {},
-            readFileSync: () => "1048576\n",
-        })).toBe(DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS);
-        expect(resolveMaxWatchedPaths(undefined, {
-            platform: "linux",
-            env: {},
-            readFileSync: () => {
-                throw new Error("proc unavailable");
-            },
-        })).toBe(DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS);
-    });
-});
-describe("TreeWatcher pending backlog caps", () => {
-    it("collects only warm-up mutations plus journal-backed deletions in one local scan", () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-warmup-"));
-        try {
-            for (let i = 0; i < 12; i++)
-                fs.writeFileSync(path.join(dir, `unchanged-${i}.md`), "old");
-            const settle = Date.now() + 50;
-            while (Date.now() < settle) { /* let old ctime settle below the cutoff */ }
-            const cutoff = Date.now();
-            while (Date.now() < cutoff + 50) { /* filesystems may round ctime down */ }
-            const fresh = path.join(dir, "created-during-warmup.md");
-            fs.writeFileSync(fresh, "new");
-            const capture = vi.fn(() => []);
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                pathFilter: () => true,
-                captureLocalDeleteSnapshots: capture,
-            });
-            const result = watcher.collectWarmupCatchup(cutoff, ["gone-during-warmup.md"]);
-            expect([...result.batch.paths.values()]).toEqual([
-                "created-during-warmup.md",
-                "gone-during-warmup.md",
-            ]);
-            expect(result.batch.changes?.get(path.join(dir, "gone-during-warmup.md")))
-                .toMatchObject({ kind: "unlink" });
-            expect(capture).toHaveBeenCalledWith("gone-during-warmup.md", "unlink");
-            expect(result.scannedPaths).toBe(13);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("yields through a 50k-row warm-up journal catch-up without losing coverage", async () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-warmup-yield-"));
-        try {
-            const watcher = new TreeWatcher({ hqRoot: dir, pathFilter: () => true });
-            const journalRows = Array.from({ length: 50_000 }, (_, index) => `personal/missing-${index}.md`);
-            const histogram = monitorEventLoopDelay({ resolution: 1 });
-            let eventLoopTicks = 0;
-            let keepTicking = true;
-            const tick = () => {
-                if (!keepTicking)
-                    return;
-                eventLoopTicks += 1;
-                setImmediate(tick);
-            };
-            histogram.enable();
-            setImmediate(tick);
-            const result = await watcher.collectWarmupCatchupAsync(Date.now(), journalRows);
-            keepTicking = false;
-            await flushImmediate();
-            histogram.disable();
-            expect(result.scannedPaths).toBe(0);
-            expect(result.batch.paths.size).toBe(50_000);
-            expect(eventLoopTicks).toBeGreaterThan(1);
-            expect(Number(histogram.max) / 1_000_000).toBeLessThan(50);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("uses async filesystem calls and prunes excluded trees during warm-up", async () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-warmup-async-fs-"));
-        const allowed = path.join(dir, "core", "knowledge", "public");
-        const nodeModules = path.join(dir, "core", "workers", "demo", "node_modules", "pkg");
-        const target = path.join(dir, "core", "packages", "demo", "target", "debug");
-        fs.mkdirSync(allowed, { recursive: true });
-        fs.mkdirSync(nodeModules, { recursive: true });
-        fs.mkdirSync(target, { recursive: true });
-        fs.writeFileSync(path.join(allowed, "keep.md"), "keep");
-        fs.writeFileSync(path.join(nodeModules, "skip.js"), "skip");
-        fs.writeFileSync(path.join(target, "skip.o"), "skip");
-        try {
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                pathFilter: createWatchPathFilter(dir, false),
-            });
-            const result = await watcher.collectWarmupCatchupAsync(Date.now() - 10_000);
-            expect(result.scannedPaths).toBeGreaterThan(0);
-            expect([...result.batch.paths.values()]).toEqual([
-                "core/knowledge/public/keep.md",
-            ]);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("stops a yielding warm-up catch-up without scheduling the remaining chunks", async () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-warmup-stop-"));
-        const originalSetImmediate = globalThis.setImmediate;
-        let releaseFirstYield;
-        let firstYieldReached;
-        const firstYield = new Promise((resolve) => {
-            firstYieldReached = resolve;
-        });
-        const setImmediateSpy = vi.spyOn(globalThis, "setImmediate").mockImplementation(((callback, ...args) => {
-            if (!releaseFirstYield) {
-                releaseFirstYield = () => callback(...args);
-                firstYieldReached?.();
-                return undefined;
-            }
-            return originalSetImmediate(callback, ...args);
-        }));
-        try {
-            const watcher = new TreeWatcher({ hqRoot: dir, pathFilter: () => true });
-            const journalRows = Array.from({ length: 256 }, (_, index) => `personal/missing-${index}.md`);
-            const catchup = watcher.collectWarmupCatchupAsync(Date.now(), journalRows);
-            await firstYield;
-            watcher.stop();
-            releaseFirstYield?.();
-            const result = await catchup;
-            expect(result.cancelled).toBe(true);
-            expect(result.batch.paths.size).toBeLessThan(journalRows.length);
-            expect(setImmediateSpy).toHaveBeenCalledTimes(1);
-        }
-        finally {
-            setImmediateSpy.mockRestore();
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("keeps a warm-up epoch only for a queued deletion capture, and only while it runs", async () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-warmup-epochs-"));
-        try {
-            for (let i = 0; i < 6; i++)
-                fs.writeFileSync(path.join(dir, `unchanged-${i}.md`), "old");
-            const settle = Date.now() + 50;
-            while (Date.now() < settle) { /* let old ctime settle below the cutoff */ }
-            const cutoff = Date.now();
-            while (Date.now() < cutoff + 50) { /* filesystems may round ctime down */ }
-            for (let i = 0; i < 4; i++)
-                fs.writeFileSync(path.join(dir, `fresh-${i}.md`), "new");
-            let resolveCapture;
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                pathFilter: () => true,
-                queueLocalDeleteSnapshots: async () => {
-                    await new Promise((resolve) => { resolveCapture = resolve; });
-                    return [];
-                },
-            });
-            const result = watcher.collectWarmupCatchup(cutoff, ["gone-during-warmup.md"]);
-            expect([...result.batch.paths.values()].sort()).toEqual([
-                "fresh-0.md", "fresh-1.md", "fresh-2.md", "fresh-3.md", "gone-during-warmup.md",
-            ]);
-            // Four live changes were recorded, but only the deletion has a capture
-            // in flight, so only the deletion holds an epoch.
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
-            await new Promise((resolve) => setImmediate(resolve)); // the queued job starts
-            resolveCapture();
-            await new Promise((resolve) => setImmediate(resolve));
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
-            watcher.dispose();
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("does not report a journal row as deleted when its file exists behind a symlinked directory", () => {
-        // The warm-up walk never descends through a symlinked directory (a Dirent
-        // symlink is not a directory), so rows journaled under such a path were
-        // never `observed` and every one of them came back as an `unlink` even
-        // though the file was right there. On one HQ, `.codex/claude -> ../.claude`
-        // made 11.4k present state files look deleted on every runner start: 11.4k
-        // delete roots, 11.4k queued delete-intent writes, and a delete plan that
-        // then refused each one. A journal row the walk missed must be stat'ed like
-        // any walked file: absent -> unlink, present and unchanged -> nothing,
-        // present and touched since the cutoff -> change.
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-warmup-symlink-dir-"));
-        try {
-            fs.mkdirSync(path.join(dir, ".claude", "state"), { recursive: true });
-            fs.writeFileSync(path.join(dir, ".claude", "state", "stable.txt"), "old");
-            fs.mkdirSync(path.join(dir, ".codex"));
-            fs.symlinkSync(path.join("..", ".claude"), path.join(dir, ".codex", "claude"), "dir");
-            const settle = Date.now() + 50;
-            while (Date.now() < settle) { /* let old ctime settle below the cutoff */ }
-            const cutoff = Date.now();
-            while (Date.now() < cutoff + 50) { /* filesystems may round ctime down */ }
-            fs.writeFileSync(path.join(dir, ".claude", "state", "fresh.txt"), "new");
-            const capture = vi.fn(() => []);
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                pathFilter: () => true,
-                captureLocalDeleteSnapshots: capture,
-            });
-            const result = watcher.collectWarmupCatchup(cutoff, [
-                ".codex/claude/state/stable.txt",
-                ".codex/claude/state/fresh.txt",
-                ".codex/claude/state/gone.txt",
-            ]);
-            const kinds = Object.fromEntries([...result.batch.paths].map(([absolute, relative]) => [relative, result.batch.changes?.get(absolute)?.kind]));
-            expect(kinds).toEqual({
-                ".claude/state/fresh.txt": "change",
-                ".codex/claude/state/fresh.txt": "change",
-                ".codex/claude/state/gone.txt": "unlink",
-            });
-            expect(capture).toHaveBeenCalledTimes(1);
-            expect(capture).toHaveBeenCalledWith(".codex/claude/state/gone.txt", "unlink");
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("canonicalizes a legacy journal key before adding its warm-up deletion to the batch", () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-warmup-posix-key-"));
-        try {
-            const capture = vi.fn(() => []);
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                pathFilter: () => true,
-                captureLocalDeleteSnapshots: capture,
-            });
-            const result = watcher.collectWarmupCatchup(Date.now(), [
-                "projects\\forecast\\x.csv",
-            ]);
-            const absolute = path.join(dir, "projects", "forecast", "x.csv");
-            expect([...result.batch.paths.entries()]).toEqual([
-                [absolute, "projects/forecast/x.csv"],
-            ]);
-            expect(capture).toHaveBeenCalledWith("projects/forecast/x.csv", "unlink");
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("recovers a warm-up path even when the event backlog dropped it", () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-warmup-overflow-"));
-        try {
-            const retained = path.join(dir, "retained.md");
-            fs.writeFileSync(retained, "old");
-            const settle = Date.now() + 50;
-            while (Date.now() < settle) { /* let old ctime settle below the cutoff */ }
-            const cutoff = Date.now();
-            while (Date.now() < cutoff + 50) { /* filesystems may round ctime down */ }
-            const dropped = path.join(dir, "dropped-during-warmup.md");
-            fs.writeFileSync(dropped, "new");
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                pathFilter: () => true,
-                maxPendingPaths: 1,
-                maxPendingBytes: 100_000,
-            });
-            watcher.handleEvent(retained);
-            watcher.handleEvent(dropped);
-            const result = watcher.collectWarmupCatchup(cutoff);
-            expect([...result.batch.paths.values()]).toEqual(["dropped-during-warmup.md"]);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("honors the pending-path environment cap in the production constructor", () => {
-        vi.stubEnv("HQ_SYNC_MAX_PENDING_PATHS", "3");
-        vi.stubEnv("HQ_SYNC_MAX_PENDING_BYTES", "100000");
-        try {
-            const clock = new FakeClock();
-            const changed = vi.fn();
-            const watcher = new TreeWatcher({
-                hqRoot: ROOT,
-                clock,
-                debounceMs: DEBOUNCE,
-                pathFilter: () => true,
-            });
-            watcher.onChange(changed);
-            for (let i = 0; i < 4; i++) {
-                watcher.handleEvent(path.join(ROOT, `env-cap-${i}.md`));
-            }
-            clock.advance(DEBOUNCE);
-            expect(changed.mock.calls[0][1].paths.size).toBe(3);
-            expect(changed.mock.calls[0][1].overflowed).toBe(true);
-        }
-        finally {
-            vi.unstubAllEnvs();
-        }
-    });
-    it("honors the pending-byte environment cap in the production constructor", () => {
-        vi.stubEnv("HQ_SYNC_MAX_PENDING_PATHS", "100");
-        vi.stubEnv("HQ_SYNC_MAX_PENDING_BYTES", "1");
-        try {
-            const clock = new FakeClock();
-            const changed = vi.fn();
-            const watcher = new TreeWatcher({
-                hqRoot: ROOT,
-                clock,
-                debounceMs: DEBOUNCE,
-                pathFilter: () => true,
-            });
-            watcher.onChange(changed);
-            watcher.handleEvent(path.join(ROOT, "byte-cap.md"));
-            clock.advance(DEBOUNCE);
-            expect(changed.mock.calls[0][1].paths.size).toBe(0);
-            expect(changed.mock.calls[0][1].overflowed).toBe(true);
-        }
-        finally {
-            vi.unstubAllEnvs();
-        }
-    });
-    it.each([
-        ["HQ_SYNC_MAX_PENDING_PATHS", "0"],
-        ["HQ_SYNC_MAX_PENDING_PATHS", "0.5"],
-        ["HQ_SYNC_MAX_PENDING_PATHS", "-1"],
-        ["HQ_SYNC_MAX_PENDING_PATHS", "not-a-number"],
-        ["HQ_SYNC_MAX_PENDING_BYTES", "0"],
-        ["HQ_SYNC_MAX_PENDING_BYTES", "0.5"],
-        ["HQ_SYNC_MAX_PENDING_BYTES", "-1"],
-        ["HQ_SYNC_MAX_PENDING_BYTES", "not-a-number"],
-    ])("warns once and falls back for invalid %s=%s", (name, value) => {
-        vi.stubEnv(name, value);
-        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
-        try {
-            new TreeWatcher({ hqRoot: ROOT });
-            expect(warn).toHaveBeenCalledOnce();
-            expect(warn).toHaveBeenCalledWith(expect.stringContaining(name));
-        }
-        finally {
-            warn.mockRestore();
-            vi.unstubAllEnvs();
-        }
-    });
-    it("keeps a burst at the configured cap without marking it overflowed", () => {
-        vi.stubEnv("HQ_SYNC_MAX_PENDING_PATHS", "4");
-        vi.stubEnv("HQ_SYNC_MAX_PENDING_BYTES", "100000");
-        try {
-            const clock = new FakeClock();
-            const changed = vi.fn();
-            const overflow = vi.fn();
-            const watcher = new TreeWatcher({
-                hqRoot: ROOT,
-                clock,
-                debounceMs: DEBOUNCE,
-                pathFilter: () => true,
-                onBacklogOverflow: overflow,
-            });
-            watcher.onChange(changed);
-            for (let i = 0; i < 4; i++) {
-                watcher.handleEvent(path.join(ROOT, `below-cap-${i}.md`));
-            }
-            clock.advance(DEBOUNCE);
-            expect(overflow).not.toHaveBeenCalled();
-            expect(changed.mock.calls[0][1]).not.toHaveProperty("overflowed");
-        }
-        finally {
-            vi.unstubAllEnvs();
-        }
-    });
-    it("reports the hit cap and cumulative dropped count in every overflow episode", () => {
-        const clock = new FakeClock();
-        const overflow = vi.fn();
-        const watcher = new TreeWatcher({
-            hqRoot: ROOT,
-            clock,
-            debounceMs: DEBOUNCE,
-            pathFilter: () => true,
-            maxPendingPaths: 1,
-            maxPendingBytes: 100_000,
-            onBacklogOverflow: overflow,
-        });
-        watcher.handleEvent(path.join(ROOT, "kept-first.md"));
-        watcher.handleEvent(path.join(ROOT, "dropped-first.md"));
-        clock.advance(DEBOUNCE);
-        watcher.handleEvent(path.join(ROOT, "kept-second.md"));
-        clock.advance(10);
-        watcher.handleEvent(path.join(ROOT, "dropped-second.md"));
-        expect(overflow).toHaveBeenCalledTimes(2);
-        expect(overflow.mock.calls[0][0]).toMatchObject({
-            capHit: "paths",
-            totalDroppedPaths: 1,
-            maxPendingPaths: 1,
-            maxPendingBytes: 100_000,
-            pendingPaths: 1,
-            inFlightPassMs: 0,
-        });
-        expect(overflow.mock.calls[1][0]).toMatchObject({
-            capHit: "paths",
-            totalDroppedPaths: 2,
-            inFlightPassMs: 10,
-        });
-    });
-    it("logs every default overflow record with the cumulative total and hit cap", () => {
-        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
-        try {
-            const watcher = new TreeWatcher({
-                hqRoot: ROOT,
-                pathFilter: () => true,
-                maxPendingPaths: 1,
-                maxPendingBytes: 100_000,
-            });
-            watcher.handleEvent(path.join(ROOT, "kept.md"));
-            watcher.handleEvent(path.join(ROOT, "dropped-one.md"));
-            watcher.handleEvent(path.join(ROOT, "dropped-two.md"));
-            expect(warn).toHaveBeenCalledTimes(2);
-            expect(warn).toHaveBeenLastCalledWith(expect.stringContaining("backlog cap exceeded"), expect.objectContaining({
-                capHit: "paths",
-                totalDroppedPaths: 2,
-                pendingPaths: 1,
-                maxPendingPaths: 1,
-                maxPendingBytes: 100_000,
-                inFlightPassMs: expect.any(Number),
-            }));
-        }
-        finally {
-            warn.mockRestore();
-        }
-    });
-    it("omits route hints when an overflow exceeds the route-evidence cap", () => {
-        const clock = new FakeClock();
-        const changed = vi.fn();
-        const watcher = new TreeWatcher({
-            hqRoot: ROOT,
-            clock,
-            debounceMs: DEBOUNCE,
-            pathFilter: () => true,
-            maxPendingPaths: 1,
-            maxPendingBytes: 100_000,
-            onBacklogOverflow: () => { },
-        });
-        watcher.onChange(changed);
-        watcher.handleEvent(path.join(ROOT, "companies", "kept", "a.md"));
-        for (let i = 0; i < 33; i++) {
-            watcher.handleEvent(path.join(ROOT, "companies", `dropped-${i}`, "a.md"));
-        }
-        clock.advance(DEBOUNCE);
-        expect(changed.mock.calls[0][1]).toMatchObject({ overflowed: true });
-        expect(changed.mock.calls[0][1]).not.toHaveProperty("droppedRouteHints");
-    });
-});
-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;
-        const inFlight = new Promise((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 = [];
-        const onUnhandled = (reason) => {
-            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 AppleDouble files", () => {
-        expect(filter(path.join(ROOT, "._README.md"))).toBe(false);
-        expect(filter(path.join(ROOT, "core/connectors/._README.md"))).toBe(false);
-    });
-    it("does NOT emit for restore staging paths", () => {
-        expect(filter(path.join(ROOT, "core/packages.hq-restore-9980"), true)).toBe(false);
-        expect(filter(path.join(ROOT, "core/packages.hq-restore-9980/connectors/README.md"))).toBe(false);
-        expect(filter(path.join(ROOT, "core/README.md.hq-restore-probe-9980-m6bx"))).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("emits for the pointer's active continuity thread file", () => {
-        const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-active-thread-")));
-        const thread = path.join(root, "workspace", "threads", "x.json");
-        try {
-            fs.mkdirSync(path.dirname(thread), { recursive: true });
-            fs.writeFileSync(thread, "{}");
-            fs.writeFileSync(path.join(root, "workspace", "threads", "handoff.json"), JSON.stringify({ thread_path: "workspace/threads/x.json" }));
-            const scoped = createWatchPathFilter(root, true);
-            expect(scoped(thread)).toBe(true);
-        }
-        finally {
-            fs.rmSync(root, { recursive: true, force: true });
-        }
-    });
-    it("covers every present personal-vault root, while preserving .hqignore exclusions", () => {
-        const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-scope-invariant-")));
-        const activeThread = path.join(root, "workspace", "threads", "x.json");
-        try {
-            fs.mkdirSync(path.join(root, "personal"), { recursive: true });
-            fs.mkdirSync(path.join(root, ".codex"), { recursive: true });
-            fs.mkdirSync(path.join(root, "companies", "local"), { recursive: true });
-            fs.mkdirSync(path.join(root, "workspace", "agency", "team"), { recursive: true });
-            fs.mkdirSync(path.join(root, "workspace", ".session-logs"), { recursive: true });
-            fs.mkdirSync(path.dirname(activeThread), { recursive: true });
-            fs.writeFileSync(path.join(root, "personal", "note.md"), "note");
-            fs.writeFileSync(path.join(root, ".codex", "settings.json"), "{}");
-            fs.writeFileSync(path.join(root, "companies", "manifest.yaml"), "companies: {}\n");
-            fs.writeFileSync(path.join(root, "companies", "local", "note.md"), "local");
-            fs.writeFileSync(path.join(root, "workspace", "agency", "team", "state.json"), "{}");
-            fs.writeFileSync(path.join(root, "workspace", ".session-logs", "session.jsonl"), "{}\n");
-            fs.writeFileSync(activeThread, "{}");
-            fs.writeFileSync(path.join(root, "workspace", "threads", "handoff.json"), JSON.stringify({ thread_path: "workspace/threads/x.json" }));
-            fs.writeFileSync(path.join(root, ".hqignore"), "workspace/agency/ignored/\n");
-            const filter = createWatchPathFilter(root, true);
-            const uncovered = computePersonalVaultPaths(root).filter((scopeRoot) => !filter(scopeRoot, fs.lstatSync(scopeRoot).isDirectory()));
-            // Scope roots must be watched, unless a future change introduces an
-            // explicit, reasoned exclusion. There are deliberately no such
-            // exclusions in this representative personal scope.
-            expect(uncovered).toEqual([]);
-            expect(filter(path.join(root, "workspace", "agency", "ignored"), true)).toBe(false);
-        }
-        finally {
-            fs.rmSync(root, { recursive: true, force: 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("combined personal + company mode retains company trees without admitting unrelated workspace churn", () => {
-        const combined = createWatchPathFilter(ROOT, true, {
-            includeCompanyPaths: true,
-        });
-        expect(combined(path.join(ROOT, "personal/rt-hour.md"))).toBe(true);
-        expect(combined(path.join(ROOT, "companies/indigo/board.json"))).toBe(true);
-        expect(combined(path.join(ROOT, "workspace/locks/sync.lock"))).toBe(false);
-        expect(combined(path.join(ROOT, "workspace/agency/indigo/chat.jsonl"))).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;
-    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("defers a file-shaped pre-stat candidate to the stat-aware directory verdict", () => {
-        const filter = createWatchPathFilter(dir, false);
-        const nodeModules = path.join(dir, "companies", "acme", "knowledge", "node_modules");
-        // `node_modules/` is directory-only. A no-stat chokidar probe cannot know
-        // whether this is a new file or a directory, so it must survive long
-        // enough to receive the stat-aware verdict below.
-        expect(filter(nodeModules, false)).toBe(true);
-        expect(filter(nodeModules, true)).toBe(false);
-        const ignored = toChokidarIgnored(filter, dir);
-        expect(ignored(nodeModules)).toBe(false);
-        expect(ignored(nodeModules, fs.lstatSync(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((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("chokidar polling symlink boundaries", () => {
-    async function waitFor(check) {
-        const deadline = Date.now() + 6000;
-        while (Date.now() < deadline) {
-            if (check())
-                return;
-            await new Promise((resolve) => setTimeout(resolve, 25));
-        }
-        expect(check()).toBe(true);
-    }
-    async function waitReady(backend) {
-        await new Promise((resolve, reject) => {
-            if (!backend.onReady)
-                return resolve();
-            const timer = setTimeout(() => reject(new Error("watcher did not become ready")), 6000);
-            backend.onReady(() => {
-                clearTimeout(timer);
-                resolve();
-            });
-        });
-    }
-    it("polls ordinary paths without descending or budgeting symlink targets, while reporting the link entry", async () => {
-        const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-poll-link-root-")));
-        const external = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-poll-link-target-")));
-        const link = path.join(root, ".agents");
-        const events = [];
-        const budgetExceeded = vi.fn();
-        const errors = [];
-        try {
-            fs.mkdirSync(path.join(external, "many", "nested", "directories", "under", "the", "alias"), { recursive: true });
-            fs.mkdirSync(path.join(root, ".codex"), { recursive: true });
-            fs.writeFileSync(path.join(root, ".codex", "config.toml"), "model = 'test'\n");
-            fs.mkdirSync(path.join(root, "workspace", "agency", "scratch"), { recursive: true });
-            fs.writeFileSync(path.join(root, "workspace", "agency", "scratch", "notes.md"), "notes\n");
-            fs.symlinkSync(external, link, "dir");
-            const filter = createWatchPathFilter(root, true);
-            expect(filter(path.join(root, ".codex", "config.toml"))).toBe(true);
-            expect(filter(path.join(root, "workspace", "agency", "scratch", "notes.md"))).toBe(true);
-            const backend = startTreeWatch(root, filter, (absolutePath, kind) => events.push({ path: absolutePath, kind }), (error) => errors.push(error), 7, budgetExceeded, undefined, true);
-            try {
-                await waitReady(backend);
-                expect(backend.mode).toBe("polling");
-                // Root + .codex + workspace/agency/scratch; the link target costs no watches.
-                expect(backend.watchedPathCount()).toBe(5);
-                expect(budgetExceeded).not.toHaveBeenCalled();
-                expect(errors).toEqual([]);
-                fs.unlinkSync(link);
-                await waitFor(() => events.some((event) => event.path === link && event.kind === "unlink"));
-                fs.symlinkSync(external, link, "dir");
-                await waitFor(() => events.some((event) => event.path === link && event.kind === "add"));
-                expect(backend.watchedPathCount()).toBe(5);
-            }
-            finally {
-                backend.close();
-            }
-        }
-        finally {
-            fs.rmSync(root, { recursive: true, force: true });
-            fs.rmSync(external, { recursive: true, force: true });
-        }
-    });
-    it("continues watching when the supplied HQ root is itself a symlink", async () => {
-        const realRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-poll-real-root-")));
-        const parent = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-poll-root-link-")));
-        const linkedRoot = path.join(parent, "hq");
-        const events = [];
-        const errors = [];
-        fs.mkdirSync(path.join(realRoot, "workspace", "agency", "scratch"), { recursive: true });
-        fs.symlinkSync(realRoot, linkedRoot, "dir");
-        const filter = createWatchPathFilter(linkedRoot, true);
-        const backend = startTreeWatch(linkedRoot, filter, (absolutePath) => events.push(absolutePath), (error) => errors.push(error), 20, () => { }, undefined, true);
-        try {
-            await waitReady(backend);
-            const file = path.join(linkedRoot, "workspace", "agency", "scratch", "after-ready.md");
-            fs.writeFileSync(file, "observed\n");
-            await waitFor(() => events.includes(file));
-            expect(errors).toEqual([]);
-        }
-        finally {
-            backend.close();
-            fs.rmSync(linkedRoot, { recursive: true, force: true });
-            fs.rmSync(parent, { recursive: true, force: true });
-            fs.rmSync(realRoot, { recursive: true, force: true });
-        }
-    });
-});
-describe("US-002: TreeWatcher — debounce coalesce (FakeClock seam)", () => {
-    function makeWatcher(opts) {
-        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("flushes a quiet, known-small batch through the 60s debounce window", () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-small-debounce-"));
-        try {
-            const small = path.join(dir, "small.md");
-            fs.writeFileSync(small, "sixteen-byte-doc");
-            const clock = new FakeClock();
-            const changed = vi.fn();
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                debounceMs: 60_000,
-                smallBatchDebounceMs: 60_000,
-                smallBatchMaxPaths: 8,
-                smallBatchMaxBytes: 1024 * 1024,
-                clock,
-                pathFilter: () => true,
-            });
-            watcher.onChange(changed);
-            watcher.handleEvent(small);
-            // The old 2.5s small-batch fast path must no longer fire.
-            clock.advance(2_500);
-            expect(changed).not.toHaveBeenCalled();
-            clock.advance(57_499);
-            expect(changed).not.toHaveBeenCalled();
-            clock.advance(1);
-            expect(changed).toHaveBeenCalledTimes(1);
-            expect(changed.mock.calls[0][1].paths.get(small)).toBe("small.md");
-            watcher.dispose();
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("keeps a burst above the small-path cap on the 60s debounce", () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-burst-debounce-"));
-        try {
-            const clock = new FakeClock();
-            const changed = vi.fn();
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                debounceMs: 60_000,
-                smallBatchDebounceMs: 60_000,
-                smallBatchMaxPaths: 8,
-                smallBatchMaxBytes: 1024 * 1024,
-                clock,
-                pathFilter: () => true,
-            });
-            watcher.onChange(changed);
-            for (let index = 0; index < 9; index += 1) {
-                const file = path.join(dir, `burst-${index}.md`);
-                fs.writeFileSync(file, "small");
-                watcher.handleEvent(file);
-                clock.advance(100);
-            }
-            // The final event landed at t=800ms; the loop's final 100ms advance is
-            // outside the quiet window, so stop one millisecond before t=60_800ms.
-            clock.advance(59_899);
-            expect(changed).not.toHaveBeenCalled();
-            clock.advance(1);
-            expect(changed).toHaveBeenCalledTimes(1);
-            expect(changed.mock.calls[0][1].paths.size).toBe(9);
-            watcher.dispose();
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("preserves max-wait for a continuous small batch that never becomes quiet", () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-small-max-wait-"));
-        try {
-            const file = path.join(dir, "continuous.md");
-            fs.writeFileSync(file, "small");
-            const clock = new FakeClock();
-            const changed = vi.fn();
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                debounceMs: 60_000,
-                maxWaitMs: 120_000,
-                smallBatchDebounceMs: 60_000,
-                smallBatchMaxPaths: 8,
-                smallBatchMaxBytes: 1024 * 1024,
-                clock,
-                pathFilter: () => true,
-            });
-            watcher.onChange(changed);
-            for (let elapsed = 0; elapsed < 120_000; elapsed += 2_000) {
-                watcher.handleEvent(file);
-                if (elapsed < 118_000)
-                    clock.advance(2_000);
-            }
-            expect(changed).not.toHaveBeenCalled();
-            clock.advance(2_000);
-            expect(changed).toHaveBeenCalledTimes(1);
-            watcher.dispose();
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("keeps a duplicate directory delete out of the short debounce lane", () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-delete-debounce-"));
-        try {
-            const deleted = path.join(dir, "deleted-directory");
-            const clock = new FakeClock();
-            const changed = vi.fn();
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                debounceMs: 60_000,
-                smallBatchDebounceMs: 60_000,
-                smallBatchMaxPaths: 8,
-                smallBatchMaxBytes: 1024 * 1024,
-                clock,
-                pathFilter: () => true,
-            });
-            watcher.onChange(changed);
-            watcher.handleEvent(deleted, "unlinkDir");
-            watcher.handleEvent(deleted, "unlink");
-            clock.advance(59_999);
-            expect(changed).not.toHaveBeenCalled();
-            clock.advance(1);
-            expect(changed).toHaveBeenCalledTimes(1);
-            expect(changed.mock.calls[0][1].changes.get(deleted)).toMatchObject({
-                kind: "unlinkDir",
-            });
-            watcher.dispose();
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("keeps an overflowed batch out of the short debounce lane", () => {
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-overflow-debounce-"));
-        try {
-            const first = path.join(dir, "first.md");
-            const dropped = path.join(dir, "dropped.md");
-            fs.writeFileSync(first, "small");
-            fs.writeFileSync(dropped, "small");
-            const clock = new FakeClock();
-            const changed = vi.fn();
-            const watcher = new TreeWatcher({
-                hqRoot: dir,
-                debounceMs: 60_000,
-                smallBatchDebounceMs: 60_000,
-                smallBatchMaxPaths: 8,
-                smallBatchMaxBytes: 1024 * 1024,
-                maxPendingPaths: 1,
-                maxPendingBytes: 1024 * 1024,
-                clock,
-                pathFilter: () => true,
-                onBacklogOverflow: () => undefined,
-            });
-            watcher.onChange(changed);
-            watcher.handleEvent(first);
-            watcher.handleEvent(dropped);
-            clock.advance(59_999);
-            expect(changed).not.toHaveBeenCalled();
-            clock.advance(1);
-            expect(changed).toHaveBeenCalledTimes(1);
-            expect(changed.mock.calls[0][1]).toMatchObject({ overflowed: true });
-            watcher.dispose();
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    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("max-wait ceiling: a continuous event stream still emits one coalesced batch", () => {
-        const clock = new FakeClock();
-        const changed = vi.fn();
-        const watcher = new TreeWatcher({
-            hqRoot: ROOT,
-            debounceMs: 60_000,
-            maxWaitMs: 120_000,
-            personalMode: false,
-            clock,
-        });
-        watcher.onChange(changed);
-        // Events every 10s — the quiet window (60s) never elapses, so only the
-        // max-wait ceiling can fire. Events land at t=0s..110s.
-        for (let i = 0; i < 12; i++) {
-            watcher.handleEvent(path.join(ROOT, `personal/file-${i % 3}.md`));
-            if (i < 11)
-                clock.advance(10_000);
-        }
-        expect(changed).not.toHaveBeenCalled();
-        clock.advance(10_000); // reaches t=120s — the ceiling since the FIRST event
-        expect(changed).toHaveBeenCalledTimes(1);
-        // One coalesced batch carrying every distinct path of the stream.
-        const batch = changed.mock.calls[0][1];
-        expect([...batch.paths.values()].sort()).toEqual([
-            "personal/file-0.md",
-            "personal/file-1.md",
-            "personal/file-2.md",
-        ]);
-        // The ceiling resets between windows: a fresh burst gets a fresh window
-        // and settles on the ordinary quiet period.
-        watcher.handleEvent(path.join(ROOT, "personal/next.md"));
-        clock.advance(60_000);
-        expect(changed).toHaveBeenCalledTimes(2);
-        expect(watcher.pendingTimerCount()).toBe(0);
-        watcher.dispose();
-    });
-    it("max-wait ceiling never fires before one quiet window (floored at debounceMs)", () => {
-        const clock = new FakeClock();
-        const changed = vi.fn();
-        const watcher = new TreeWatcher({
-            hqRoot: ROOT,
-            debounceMs: 60_000,
-            maxWaitMs: 1, // absurdly low — must be floored to the quiet window
-            personalMode: false,
-            clock,
-        });
-        watcher.onChange(changed);
-        watcher.handleEvent(path.join(ROOT, "personal/a.md"));
-        clock.advance(59_999);
-        expect(changed).not.toHaveBeenCalled();
-        clock.advance(1);
-        expect(changed).toHaveBeenCalledTimes(1);
-        watcher.dispose();
-    });
-    it("without maxWaitMs the legacy pure quiet-window behavior is preserved", () => {
-        const { clock, changed, watcher } = makeWatcher();
-        // Keep resetting the quiet window far past any would-be ceiling.
-        for (let i = 0; i < 200; i++) {
-            watcher.handleEvent(path.join(ROOT, "personal/a.md"));
-            clock.advance(DEBOUNCE - 1);
-        }
-        expect(changed).not.toHaveBeenCalled();
-        clock.advance(DEBOUNCE);
-        expect(changed).toHaveBeenCalledTimes(1);
-    });
-    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];
-        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("overflow records one dropped-route hint per touched route so the drain can stay targeted", () => {
-        const clock = new FakeClock();
-        const changed = vi.fn();
-        const watcher = new TreeWatcher({
-            hqRoot: ROOT,
-            debounceMs: DEBOUNCE,
-            clock,
-            pathFilter: () => true,
-            maxPendingPaths: 2,
-            maxPendingBytes: 10_000,
-            onBacklogOverflow: () => { },
-        });
-        watcher.onChange(changed);
-        // Two retained, then drops spanning two company routes + personal.
-        watcher.handleEvent(path.join(ROOT, "companies", "indigo", "kept-a.md"));
-        watcher.handleEvent(path.join(ROOT, "companies", "indigo", "kept-b.md"));
-        watcher.handleEvent(path.join(ROOT, "companies", "indigo", "dropped-1.md"));
-        watcher.handleEvent(path.join(ROOT, "companies", "acme", "dropped-2.md"));
-        watcher.handleEvent(path.join(ROOT, "notes", "dropped-3.md"));
-        clock.advance(DEBOUNCE);
-        const batch = changed.mock.calls[0][1];
-        expect(batch.overflowed).toBe(true);
-        expect(batch.droppedPaths).toBe(3);
-        // One representative relative path per route (companies/indigo,
-        // companies/acme, personal) — enough to reconstruct the touched-route
-        // set without holding the dropped paths themselves.
-        expect(batch.droppedRouteHints?.sort()).toEqual([
-            "companies/acme/dropped-2.md",
-            "companies/indigo/dropped-1.md",
-            "notes/dropped-3.md",
-        ]);
-        // Next window starts clean: a non-overflow batch carries no hints.
-        changed.mockClear();
-        watcher.handleEvent(path.join(ROOT, "companies", "indigo", "later.md"));
-        clock.advance(DEBOUNCE);
-        const nextBatch = changed.mock.calls[0][1];
-        expect(nextBatch.overflowed).toBeUndefined();
-        expect(nextBatch.droppedRouteHints).toBeUndefined();
-    });
-    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 = [];
-        let backendClosed = false;
-        const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
-        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) => {
-                        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(warn).toHaveBeenCalledWith(expect.stringContaining('"type":"watch-scope-excluded"'));
-            expect(warn).toHaveBeenCalledWith(expect.stringContaining('"excludedRoot"'));
-            expect(backendClosed).toBe(true);
-            expect(watcher.isWatching()).toBe(false);
-            clock.advance(DEBOUNCE);
-            expect(changed).toHaveBeenCalledWith(undefined, expect.objectContaining({ overflowed: true }));
-        }
-        finally {
-            warn.mockRestore();
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it.each(["ENOSPC", "EMFILE", "ENFILE"])("keeps event watching through polling when a backend emits runtime %s", (errorCode) => {
-        const clock = new FakeClock();
-        const degraded = vi.fn();
-        const changed = vi.fn();
-        const telemetry = [];
-        const telemetryClient = {
-            postTelemetryEvents: vi.fn(async (batch) => {
-                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: ({ forcePolling, onError }) => {
-                const backend = {
-                    close: () => {
-                        closeCalls += 1;
-                    },
-                    needsKnownKinds: false,
-                    mode: forcePolling ? "polling" : "chokidar",
-                    watchedPathCount: () => forcePolling ? 200 : 0,
-                };
-                if (!forcePolling) {
-                    queueMicrotask(() => onError(Object.assign(new Error("watch resource limit"), {
-                        code: errorCode,
-                        path: path.join(ROOT, "companies", "acme", "knowledge"),
-                    })));
-                }
-                return backend;
-            },
-        });
-        watcher.onChange(changed);
-        watcher.start();
-        return new Promise((resolve) => queueMicrotask(resolve)).then(() => {
-            expect(closeCalls).toBe(1);
-            expect(watcher.isWatching()).toBe(true);
-            expect(watcher.watchMode()).toBe("polling");
-            expect(watcher.watchedPathCount()).toBe(200);
-            const reason = errorCode === "ENOSPC" ? "inotify_enospc" : "watch_resource_exhausted";
-            expect(degraded).toHaveBeenCalledWith(expect.objectContaining({
-                reason,
-                errorCode,
-                offendingPath: path.join(ROOT, "companies", "acme", "knowledge"),
-            }));
-            expect(telemetry).toEqual([
-                expect.objectContaining({
-                    events: [
-                        expect.objectContaining({
-                            eventName: "watcher_degraded",
-                            source: "watcher",
-                            properties: expect.objectContaining({
-                                reason,
-                                offendingTopLevel: "companies",
-                            }),
-                        }),
-                    ],
-                }),
-            ]);
-            clock.advance(DEBOUNCE);
-            expect(changed).toHaveBeenCalledWith(undefined, expect.objectContaining({ overflowed: true }));
-        });
-    });
-    it("keeps a large synthetic watch set alive across multiple debounced passes", () => {
-        const clock = new FakeClock();
-        const changed = vi.fn();
-        const handles = new Set(Array.from({ length: 20_000 }, (_, i) => `dir-${i}`));
-        const watcher = new TreeWatcher({
-            hqRoot: ROOT,
-            clock,
-            debounceMs: DEBOUNCE,
-            backendFactory: () => ({
-                close: () => handles.clear(),
-                mode: "chokidar",
-                needsKnownKinds: false,
-                watchedPathCount: () => handles.size,
-            }),
-        });
-        watcher.onChange(changed);
-        watcher.start();
-        for (let pass = 0; pass < 3; pass += 1) {
-            watcher.handleEvent(path.join(ROOT, "personal", `change-${pass}.md`));
-            clock.advance(DEBOUNCE);
-            expect(watcher.isWatching()).toBe(true);
-            expect(watcher.watchedPathCount()).toBe(20_000);
-        }
-        expect(changed).toHaveBeenCalledTimes(3);
-        watcher.dispose();
-    });
-    it("continues initial discovery while the watched-path count is still growing", () => {
-        const clock = new FakeClock();
-        const degraded = vi.fn();
-        let watchedPaths = 0;
-        const watcher = new TreeWatcher({
-            hqRoot: ROOT,
-            clock,
-            discoveryTimeoutMs: 100,
-            onDegraded: degraded,
-            backendFactory: () => ({
-                close: () => { },
-                mode: "chokidar",
-                needsKnownKinds: false,
-                watchedPathCount: () => watchedPaths,
-                // Deliberately never ready: this models a large, still-discovering tree.
-                onReady: () => () => { },
-            }),
-        });
-        watcher.start();
-        watchedPaths = 9_220;
-        clock.advance(100);
-        watchedPaths = 14_588;
-        clock.advance(100);
-        expect(watcher.isWatching()).toBe(true);
-        expect(watcher.watchMode()).toBe("chokidar");
-        expect(degraded).not.toHaveBeenCalled();
-        watcher.dispose();
-    });
-    it("stands down loudly when polling discovery also times out", () => {
-        const clock = new FakeClock();
-        const degraded = vi.fn();
-        let closeCalls = 0;
-        const watcher = new TreeWatcher({
-            hqRoot: ROOT,
-            clock,
-            discoveryTimeoutMs: 100,
-            onDegraded: degraded,
-            backendFactory: ({ forcePolling }) => ({
-                close: () => { closeCalls += 1; },
-                mode: forcePolling ? "polling" : "chokidar",
-                needsKnownKinds: false,
-                watchedPathCount: () => forcePolling ? 20 : 10,
-                // Deliberately never invokes its listener: this simulates discovery
-                // that hangs before chokidar can report ready.
-                onReady: () => () => { },
-            }),
-        });
-        watcher.start();
-        clock.advance(100);
-        expect(watcher.isWatching()).toBe(true);
-        expect(watcher.watchMode()).toBe("polling");
-        clock.advance(100);
-        expect(watcher.isWatching()).toBe(false);
-        expect(closeCalls).toBe(2);
-        expect(degraded).toHaveBeenLastCalledWith(expect.objectContaining({
-            reason: "initial_discovery_timeout",
-            action: "stopped",
-            watchedPaths: 20,
-        }));
-    });
-    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;
-    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;
-    beforeEach(() => {
-        dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "pushemit-")));
-    });
-    afterEach(() => {
-        fs.rmSync(dir, { recursive: true, force: true });
-    });
-    it("replays randomized hash records with the same LRU state as the legacy reducer", () => {
-        const records = publishedHashRecords(4_096);
-        expect(replayDurablePublishedContentHashRecordsForTest(records, true))
-            .toEqual(replayDurablePublishedContentHashRecordsForTest(records, false));
-    });
-    it("replays legacy records followed by a batch with the exact single-record LRU state", () => {
-        const batchEntries = [
-            { kind: "delete", relativePath: "alpha" },
-            { kind: "set", relativePath: "gamma", contentHash: "sha256:gamma", maxPaths: 2 },
-            { kind: "set", relativePath: "beta", contentHash: "sha256:beta-new", maxPaths: 2 },
-        ];
-        const legacyThenBatch = [
-            { sequence: 1, type: 0x5031, flags: 0, payload: { relativePath: "alpha", contentHash: "sha256:alpha", maxPaths: 2 } },
-            { sequence: 2, type: 0x5031, flags: 0, payload: { relativePath: "beta", contentHash: "sha256:beta", maxPaths: 2 } },
-            { sequence: 3, type: 0x5033, flags: 0, payload: { entries: batchEntries } },
-        ];
-        const equivalentSingles = [
-            ...legacyThenBatch.slice(0, 2),
-            ...batchEntries.map((entry, index) => ({
-                sequence: index + 3,
-                type: entry.kind === "set" ? 0x5031 : 0x5032,
-                flags: 0,
-                payload: entry.kind === "set"
-                    ? { relativePath: entry.relativePath, contentHash: entry.contentHash, maxPaths: entry.maxPaths }
-                    : { relativePath: entry.relativePath },
-            })),
-        ];
-        const batched = replayDurablePublishedContentHashRecordsForTest(legacyThenBatch);
-        expect(JSON.stringify(batched)).toBe(JSON.stringify(replayDurablePublishedContentHashRecordsForTest(equivalentSingles)));
-        expect(batched).toEqual(replayDurablePublishedContentHashRecordsForTest(legacyThenBatch, false));
-    });
-    it("coalesces pull marks into one append and persists only the final mutation for a path", async () => {
-        const clock = new FakeClock();
-        const appendGenerated = vi.spyOn(StateStore.prototype, "appendGeneratedIfAsync");
-        const stateDir = path.join(dir, "coalesced-state");
-        const emitter = makeEmitter({ clock, lastPublishedContentHashStateDir: stateDir });
-        const finalContent = "final revision\n";
-        const finalHash = `sha256:${createHash("sha256").update(finalContent).digest("hex")}`;
-        try {
-            for (let index = 0; index < 128; index++) {
-                emitter.markContentPublished(`path-${index}.md`, `sha256:${index}`);
-            }
-            emitter.markContentPublished("same.md", "sha256:obsolete");
-            emitter.markContentPublished("same.md", finalHash);
-            clock.advance(DURABLE_PUBLISHED_HASH_BATCH_FLUSH_MS);
-            await flushImmediate();
-            expect(appendGenerated).toHaveBeenCalledTimes(1);
-            await emitter.dispose();
-            const samePath = path.join(dir, "same.md");
-            fs.writeFileSync(samePath, finalContent);
-            const published = [];
-            await makeEmitter({ published, lastPublishedContentHashStateDir: stateDir }).emitForBatch({
-                paths: new Map([[samePath, "same.md"]]),
-            });
-            expect(published).toEqual([]);
-        }
-        finally {
-            appendGenerated.mockRestore();
-        }
-    });
-    it("drops a stale guarded mutation at flush time without dropping the rest of its batch", async () => {
-        const clock = new FakeClock();
-        const hashes = new DurablePublishedContentHashes(path.join(dir, "predicate-state"), "test", 4, {}, clock);
-        let shouldPersist = true;
-        const stale = hashes.setIfCurrent("stale.md", "sha256:stale", 4, () => shouldPersist);
-        const kept = hashes.set("kept.md", "sha256:kept", 4, false);
-        shouldPersist = false;
-        await hashes.dispose();
-        await expect(stale).resolves.toBe(false);
-        await expect(kept).resolves.toBeUndefined();
-        expect(hashes.get("stale.md")).toBeUndefined();
-        expect(hashes.get("kept.md")).toBe("sha256:kept");
-    });
-    it("flushes pending durable pull marks while disposing", async () => {
-        const appendGenerated = vi.spyOn(StateStore.prototype, "appendGeneratedIfAsync");
-        const emitter = makeEmitter({ lastPublishedContentHashStateDir: path.join(dir, "dispose-state") });
-        try {
-            emitter.markContentPublished("pending.md", "sha256:pending");
-            await emitter.dispose();
-            expect(appendGenerated).toHaveBeenCalledTimes(1);
-        }
-        finally {
-            appendGenerated.mockRestore();
-        }
-    });
-    it("reports and retries a failed durable hash append as one physical batch", async () => {
-        const clock = new FakeClock();
-        const onError = vi.fn();
-        const appendGenerated = vi.spyOn(StateStore.prototype, "appendGeneratedIfAsync")
-            .mockRejectedValueOnce(new StateStoreLockError("timed out acquiring append.lock"));
-        const emitter = makeEmitter({
-            clock,
-            onError,
-            lastPublishedContentHashStateDir: path.join(dir, "batch-lock-timeout-state"),
-        });
-        try {
-            for (let index = 0; index < 128; index += 1) {
-                emitter.markContentPublished(`batch-${index}.md`, `sha256:${index}`);
-            }
-            clock.advance(DURABLE_PUBLISHED_HASH_BATCH_FLUSH_MS);
-            await flushImmediate();
-            expect(onError).toHaveBeenCalledTimes(1);
-            expect(onError.mock.calls[0]?.[0]).toMatchObject({ name: "StateStoreLockError" });
-            expect((onError.mock.calls[0]?.[0]).message).toContain("128 mutations");
-            expect(clock.pendingTimerCount()).toBe(1);
-        }
-        finally {
-            await emitter.dispose();
-            appendGenerated.mockRestore();
-        }
-    });
-    it("does not revive a superseded mutation while its failed batch is retrying", async () => {
-        const clock = new FakeClock();
-        let releaseRetry;
-        const retryGate = new Promise((resolve) => { releaseRetry = resolve; });
-        let retryEntered;
-        const retryStarted = new Promise((resolve) => { retryEntered = resolve; });
-        const originalAppendGeneratedIfAsync = StateStore.prototype.appendGeneratedIfAsync;
-        const appendGenerated = vi.spyOn(StateStore.prototype, "appendGeneratedIfAsync")
-            .mockRejectedValueOnce(new StateStoreLockError("timed out acquiring append.lock"))
-            .mockImplementationOnce(async function (type, preparePayload, flags) {
-            retryEntered();
-            await retryGate;
-            return originalAppendGeneratedIfAsync.call(this, type, preparePayload, flags);
-        });
-        const hashes = new DurablePublishedContentHashes(path.join(dir, "superseded-batch-retry-state"), "test", 4, {}, clock);
-        try {
-            const stale = hashes.setIfCurrent("same.md", "sha256:stale", 4, () => true);
-            await expect(stale).resolves.toBe(false);
-            expect(clock.pendingTimerCount()).toBe(1);
-            clock.advance(250);
-            await retryStarted;
-            const newer = hashes.set("same.md", "sha256:newer", 4, false);
-            releaseRetry();
-            await flushImmediate();
-            clock.advance(DURABLE_PUBLISHED_HASH_BATCH_FLUSH_MS);
-            await expect(newer).resolves.toBeUndefined();
-            expect(hashes.get("same.md")).toBe("sha256:newer");
-        }
-        finally {
-            await hashes.dispose();
-            appendGenerated.mockRestore();
-        }
-    });
-    it("rechecks a guarded mutation when its failed batch retries", async () => {
-        const clock = new FakeClock();
-        let shouldPersist = true;
-        const appendGenerated = vi.spyOn(StateStore.prototype, "appendGeneratedIfAsync")
-            .mockRejectedValueOnce(new StateStoreLockError("timed out acquiring append.lock"));
-        const hashes = new DurablePublishedContentHashes(path.join(dir, "guarded-batch-retry-state"), "test", 4, {}, clock);
-        try {
-            const stale = hashes.setIfCurrent("stale.md", "sha256:stale", 4, () => shouldPersist);
-            await expect(stale).resolves.toBe(false);
-            shouldPersist = false;
-            clock.advance(250);
-            await flushImmediate();
-            expect(hashes.get("stale.md")).toBeUndefined();
-            expect(appendGenerated).toHaveBeenCalledTimes(2);
-        }
-        finally {
-            await hashes.dispose();
-            appendGenerated.mockRestore();
-        }
-    });
-    it("drains an active publish into the durable memo before disposing", async () => {
-        let releasePublish;
-        const publishGate = new Promise((resolve) => { releasePublish = resolve; });
-        let publishEntered;
-        const publishStarted = new Promise((resolve) => { publishEntered = resolve; });
-        const published = [];
-        const stateDir = path.join(dir, "dispose-publish-drain-state");
-        const changed = path.join(dir, "dispose-publish-drain.md");
-        fs.writeFileSync(changed, "drain me\n");
-        const emitter = makeEmitter({
-            lastPublishedContentHashStateDir: stateDir,
-            transport: {
-                start: async () => { },
-                dispose: async () => { },
-                connected: true,
-                publish: async (event) => {
-                    publishEntered();
-                    await publishGate;
-                    published.push(event);
-                },
-            },
-        });
-        const publishing = emitter.emitForBatch({ paths: new Map([[changed, "dispose-publish-drain.md"]]) });
-        await publishStarted;
-        let disposed = false;
-        const disposing = emitter.dispose().then(() => { disposed = true; });
-        await Promise.resolve();
-        expect(disposed).toBe(false);
-        releasePublish();
-        await Promise.all([publishing, disposing]);
-        const afterRestart = [];
-        await makeEmitter({
-            published: afterRestart,
-            lastPublishedContentHashStateDir: stateDir,
-        }).emitForBatch({ paths: new Map([[changed, "dispose-publish-drain.md"]]) });
-        expect(published).toHaveLength(1);
-        expect(afterRestart).toEqual([]);
-    });
-    it("leaves the durable memo open when a publish outlives the shutdown drain", async () => {
-        const clock = new FakeClock();
-        const onError = vi.fn();
-        let releasePublish;
-        const publishGate = new Promise((resolve) => { releasePublish = resolve; });
-        let publishEntered;
-        const publishStarted = new Promise((resolve) => { publishEntered = resolve; });
-        const stateDir = path.join(dir, "dispose-timeout-state");
-        const changed = path.join(dir, "dispose-timeout.md");
-        fs.writeFileSync(changed, "late publish\n");
-        const emitter = makeEmitter({
-            clock,
-            onError,
-            lastPublishedContentHashStateDir: stateDir,
-            transport: {
-                start: async () => { },
-                dispose: async () => { },
-                connected: true,
-                publish: async () => {
-                    publishEntered();
-                    await publishGate;
-                },
-            },
-        });
-        const publishing = emitter.emitForBatch({ paths: new Map([[changed, "dispose-timeout.md"]]) });
-        await publishStarted;
-        const disposing = emitter.dispose();
-        clock.advance(60_000);
-        await disposing;
-        expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining("timed out draining active publish") }), {});
-        releasePublish();
-        await publishing;
-        await flushImmediate();
-        const afterRestart = [];
-        await makeEmitter({
-            published: afterRestart,
-            lastPublishedContentHashStateDir: stateDir,
-        }).emitForBatch({ paths: new Map([[changed, "dispose-timeout.md"]]) });
-        expect(afterRestart).toEqual([]);
-    });
-    it("returns one disposal barrier until the final durable batch is appended", async () => {
-        let releaseAppend;
-        const appendGate = new Promise((resolve) => { releaseAppend = resolve; });
-        let appendEntered;
-        const appendStarted = new Promise((resolve) => { appendEntered = resolve; });
-        const originalAppendGeneratedIfAsync = StateStore.prototype.appendGeneratedIfAsync;
-        const appendGenerated = vi.spyOn(StateStore.prototype, "appendGeneratedIfAsync")
-            .mockImplementationOnce(async function (type, preparePayload, flags) {
-            appendEntered();
-            await appendGate;
-            return originalAppendGeneratedIfAsync.call(this, type, preparePayload, flags);
-        });
-        const emitter = makeEmitter({ lastPublishedContentHashStateDir: path.join(dir, "concurrent-dispose-state") });
-        try {
-            emitter.markContentPublished("pending.md", "sha256:pending");
-            const firstDispose = emitter.dispose();
-            await appendStarted;
-            let secondDisposed = false;
-            const secondDispose = emitter.dispose();
-            expect(secondDispose).toBe(firstDispose);
-            void secondDispose.then(() => { secondDisposed = true; });
-            await Promise.resolve();
-            expect(secondDisposed).toBe(false);
-            releaseAppend();
-            await Promise.all([firstDispose, secondDispose]);
-            expect(secondDisposed).toBe(true);
-            expect(appendGenerated).toHaveBeenCalledTimes(1);
-        }
-        finally {
-            appendGenerated.mockRestore();
-        }
-    });
-    it("replays __proto__ hash records with the same state as the legacy reducer", async () => {
-        const records = [
-            { sequence: 1, type: 0x5031, flags: 0, payload: { relativePath: "__proto__", contentHash: "sha256:proto", maxPaths: 4 } },
-            { sequence: 2, type: 0x5031, flags: 0, payload: { relativePath: "ordinary", contentHash: "sha256:ordinary", maxPaths: 4 } },
-        ];
-        const keyed = replayDurablePublishedContentHashRecordsForTest(records, true);
-        expect(keyed).toEqual(replayDurablePublishedContentHashRecordsForTest(records, false));
-        expect(keyed.hashes["__proto__"]).toBe("sha256:proto");
-        records.push({ sequence: 3, type: 0x5032, flags: 0, payload: { relativePath: "__proto__" } });
-        records.push({ sequence: 4, type: 0x5032, flags: 0, payload: { relativePath: "ordinary" } });
-        expect(replayDurablePublishedContentHashRecordsForTest(records, true))
-            .toEqual(replayDurablePublishedContentHashRecordsForTest(records, false));
-        // This restart uses DurablePublishedContentHashes.get("__proto__") to
-        // decide whether a successfully acknowledged hash may be suppressed.
-        const filePath = path.join(dir, "proto-sentinel.md");
-        const stateDir = path.join(dir, "proto-state");
-        const batch = { paths: new Map([[filePath, "__proto__"]]) };
-        fs.writeFileSync(filePath, "proto content\n");
-        await makeEmitter({ lastPublishedContentHashStateDir: stateDir }).emitForBatch(batch);
-        const afterRestart = [];
-        await makeEmitter({ published: afterRestart, lastPublishedContentHashStateDir: stateDir }).emitForBatch(batch);
-        expect(afterRestart).toEqual([]);
-    });
-    it("replays fifty thousand hash records with sub-quadratic scaling", () => {
-        const replayFor = (count) => {
-            const started = performance.now();
-            replayDurablePublishedContentHashRecordsForTest(publishedHashRecords(count));
-            return performance.now() - started;
-        };
-        const small = replayFor(5_000);
-        const large = replayFor(50_000);
-        // The keyed reducer does a constant number of Map/object operations per
-        // record. Keep ample room for slow CI while rejecting a quadratic replay.
-        expect(large).toBeLessThan(small * 20 + 100);
-    });
-    function makeEmitter(opts) {
-        const published = opts?.published ?? [];
-        const transport = opts?.transport ?? {
-            start: async () => { },
-            dispose: async () => { },
-            connected: true,
-            publish: async (event) => {
-                published.push(event);
-            },
-        };
-        return new PushEventEmitter({
-            originTenantId: "tenant-indigo",
-            originDeviceId: "device-a",
-            transport,
-            flagProvider: { isEnabled: () => true },
-            now: () => new Date("2026-06-18T12:00:00.000Z"),
-            clock: opts?.clock,
-            getSequenceNumber: opts?.getSequenceNumber,
-            onError: opts?.onError,
-            lastPublishedContentHashMaxPaths: opts?.lastPublishedContentHashMaxPaths,
-            publishMinIntervalMs: opts?.publishMinIntervalMs ?? 0,
-            ...(opts?.lastPublishedContentHashStateDir
-                ? { lastPublishedContentHashStateDir: opts.lastPublishedContentHashStateDir }
-                : {}),
-            ...(opts?.initialPublishedContentHashes
-                ? { initialPublishedContentHashes: opts.initialPublishedContentHashes }
-                : {}),
-            ...(opts?.publishedContentHashLookup
-                ? { publishedContentHashLookup: opts.publishedContentHashLookup }
-                : {}),
-            ...(opts?.caseFoldingVolume !== undefined
-                ? { caseFoldingVolume: opts.caseFoldingVolume }
-                : {}),
-        });
-    }
-    it("lazily rechecks the journal baseline on a durable-cache miss without pinning a full snapshot", async () => {
-        const published = [];
-        const relativePath = "companies/indigo/seeded-lazily.md";
-        const filePath = path.join(dir, relativePath);
-        const content = "already uploaded\n";
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(filePath, content);
-        const hash = `sha256:${createHash("sha256").update(content).digest("hex")}`;
-        const lookup = vi.fn((path) => path === relativePath ? hash : undefined);
-        const emitter = makeEmitter({
-            published,
-            lastPublishedContentHashStateDir: path.join(dir, "lazy-baseline-state"),
-            publishedContentHashLookup: lookup,
-        });
-        await emitter.emitForBatch({ paths: new Map([[filePath, relativePath]]) });
-        expect(lookup).toHaveBeenCalledWith(relativePath);
-        expect(published).toEqual([]);
-        // A failed/unknown lazy lookup must never suppress a genuine local edit.
-        const changedPath = path.join(dir, "companies/indigo/unknown-baseline.md");
-        fs.writeFileSync(changedPath, "local edit\n");
-        await emitter.emitForBatch({
-            paths: new Map([[changedPath, "companies/indigo/unknown-baseline.md"]]),
-        });
-        expect(published).toHaveLength(1);
-    });
-    it("F13: watcher batch event publishing applies bounded backpressure", async () => {
-        const paths = new Map();
-        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;
-        const gate = new Promise((resolve) => {
-            releaseGate = resolve;
-        });
-        const transport = {
-            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: { isEnabled: () => true },
-            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 = [];
-        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 = [];
-        const onError = vi.fn();
-        const emitter = makeEmitter({
-            published,
-            onError,
-            getSequenceNumber: () => 99,
-            caseFoldingVolume: true,
-        });
-        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");
-        expect(published[0]).not.toHaveProperty("sizeBytes");
-    });
-    it("clears a pull-applied delete marker after a re-upload without a realtime emit", async () => {
-        const published = [];
-        const emitter = makeEmitter({ published });
-        const recreatedPath = path.join(dir, "recreated.md");
-        fs.writeFileSync(recreatedPath, "recreated content");
-        emitter.markContentDeleted("recreated.md");
-        // A successful scoped upload clears the marker even when publishing was
-        // unavailable, so the next genuine unlink cannot be swallowed.
-        emitter.clearContentDeleted("recreated.md");
-        fs.unlinkSync(recreatedPath);
-        await emitter.emitForBatch({
-            paths: new Map([[recreatedPath, "recreated.md"]]),
-        });
-        expect(published.map(({ kind, relativePath }) => ({ kind, relativePath })))
-            .toEqual([{ kind: "delete", relativePath: "recreated.md" }]);
-        await emitter.dispose();
-    });
-    it("keeps a case-only directory rename on the journal's existing remote spelling", async () => {
-        const contentByPath = new Map([
-            ["a.md", "a content"],
-            ["b.md", "b content"],
-        ]);
-        const renamedDir = path.join(dir, "dir");
-        fs.mkdirSync(renamedDir, { recursive: true });
-        const paths = new Map();
-        const knownHashes = new Map();
-        const remote = new Map();
-        for (const [name, content] of contentByPath) {
-            const localPath = path.join(renamedDir, name);
-            fs.writeFileSync(localPath, content);
-            const oldKey = `Dir/${name}`;
-            const newKey = `dir/${name}`;
-            knownHashes.set(oldKey, `sha256:${createHash("sha256").update(content).digest("hex")}`);
-            remote.set(oldKey, content);
-            paths.set(path.join(dir, "Dir", name), oldKey);
-            paths.set(localPath, newKey);
-        }
-        // APFS and NTFS already resolve `Dir` to this folder; a case-sensitive
-        // host gets the same lookup through a symlink.
-        if (!fs.existsSync(path.join(dir, "Dir")))
-            fs.symlinkSync("dir", path.join(dir, "Dir"), "dir");
-        const published = [];
-        const emitter = makeEmitter({
-            published,
-            publishedContentHashLookup: (relativePath) => knownHashes.get(relativePath),
-            caseFoldingVolume: true,
-        });
-        await emitter.emitForBatch({ paths });
-        for (const event of published) {
-            if (event.kind === "delete")
-                remote.delete(event.relativePath);
-            else
-                remote.set(event.relativePath, contentByPath.get(path.basename(event.relativePath)));
-        }
-        expect(published.some((event) => event.kind === "delete")).toBe(false);
-        expect([...remote.entries()].sort(([a], [b]) => a.localeCompare(b))).toEqual([
-            ["Dir/a.md", "a content"],
-            ["Dir/b.md", "b content"],
-        ]);
-    });
-    it("canonicalizes native-separator event keys and leaves POSIX keys byte-identical", async () => {
-        const published = [];
-        const onError = vi.fn();
-        const legacyPath = path.join(dir, "legacy.csv");
-        const posixPath = path.join(dir, "already-posix.csv");
-        fs.writeFileSync(legacyPath, "legacy\n");
-        fs.writeFileSync(posixPath, "posix\n");
-        const emitter = makeEmitter({ published, onError });
-        const windowsKey = "projects\\forecast\\x.csv";
-        await emitter.emitForBatch({
-            paths: new Map([[legacyPath, windowsKey]]),
-        });
-        await emitter.emitForBatch({
-            paths: new Map([[posixPath, "projects/forecast/already-posix.csv"]]),
-        });
-        if (path.sep === "\\") {
-            expect(published.map((event) => event.relativePath)).toEqual([
-                "projects/forecast/x.csv",
-                "projects/forecast/already-posix.csv",
-            ]);
-            expect(onError).not.toHaveBeenCalled();
-        }
-        else {
-            // POSIX: `\\` is a filename character. Do not remap onto a nested key.
-            expect(published.map((event) => event.relativePath)).toEqual([
-                "projects/forecast/already-posix.csv",
-            ]);
-            expect(onError).toHaveBeenCalled();
-        }
-    });
-    it("canonicalizes a native-separator tombstone only when `\\` is path.sep", async () => {
-        const published = [];
-        const onError = vi.fn();
-        const missing = path.join(dir, "deleted.csv");
-        const emitter = makeEmitter({ published, onError });
-        await emitter.emitForBatch({
-            paths: new Map([[missing, "projects\\forecast\\deleted.csv"]]),
-        });
-        if (path.sep === "\\") {
-            expect(published).toEqual([
-                expect.objectContaining({
-                    kind: "delete",
-                    relativePath: "projects/forecast/deleted.csv",
-                }),
-            ]);
-            expect(onError).not.toHaveBeenCalled();
-        }
-        else {
-            expect(published).toEqual([]);
-            expect(onError).toHaveBeenCalled();
-        }
-    });
-    it("publishes N unchanged watcher announcements exactly once", async () => {
-        const published = [];
-        const unchanged = path.join(dir, "unchanged-session-log.jsonl");
-        fs.writeFileSync(unchanged, '{"tool":"read"}\n');
-        const emitter = makeEmitter({ published });
-        const batch = { paths: new Map([[unchanged, "workspace/.session-logs/unchanged-session-log.jsonl"]]) };
-        for (let i = 0; i < 5; i += 1) {
-            await emitter.emitForBatch(batch);
-        }
-        expect(published).toHaveLength(1);
-        expect(published[0]).toMatchObject({
-            kind: "upsert",
-            relativePath: "workspace/.session-logs/unchanged-session-log.jsonl",
-        });
-    });
-    it("publishes again when content changes", async () => {
-        const published = [];
-        const changed = path.join(dir, "changed-session-log.jsonl");
-        fs.writeFileSync(changed, "A\n");
-        const emitter = makeEmitter({ published });
-        const batch = { paths: new Map([[changed, "workspace/.session-logs/changed-session-log.jsonl"]]) };
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(changed, "B\n");
-        await emitter.emitForBatch(batch);
-        expect(published).toHaveLength(2);
-        expect(published.map((event) => event.contentHash)).toEqual([
-            expect.stringMatching(/^sha256:/),
-            expect.stringMatching(/^sha256:/),
-        ]);
-        expect(published[0].contentHash).not.toBe(published[1].contentHash);
-    });
-    it("does not echo a pull-applied upsert but publishes a later local edit", async () => {
-        const published = [];
-        const applied = path.join(dir, "companies", "indigo", "remote-note.md");
-        const relativePath = "companies/indigo/remote-note.md";
-        const remoteContent = "from remote\n";
-        fs.mkdirSync(path.dirname(applied), { recursive: true });
-        fs.writeFileSync(applied, remoteContent);
-        const emitter = makeEmitter({ published });
-        // The pull completed its file write and journal update, then the runner
-        // bridged that upsert into the live emitter before the watcher settled.
-        emitter.markContentPublished(relativePath, `sha256:${createHash("sha256").update(remoteContent).digest("hex")}`);
-        await emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        expect(published).toEqual([]);
-        fs.writeFileSync(applied, "local follow-up\n");
-        await emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        expect(published).toHaveLength(1);
-        expect(published[0]).toMatchObject({
-            kind: "upsert",
-            relativePath,
-            contentHash: `sha256:${createHash("sha256")
-                .update("local follow-up\n")
-                .digest("hex")}`,
-        });
-    });
-    it("publishes a local edit immediately after a pull mark despite the publish interval", async () => {
-        const clock = new FakeClock();
-        const published = [];
-        const applied = path.join(dir, "companies", "indigo", "remote-interval-note.md");
-        const relativePath = "companies/indigo/remote-interval-note.md";
-        const remoteContent = "from remote\n";
-        fs.mkdirSync(path.dirname(applied), { recursive: true });
-        fs.writeFileSync(applied, remoteContent);
-        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000, clock });
-        emitter.markContentPublished(relativePath, `sha256:${createHash("sha256").update(remoteContent).digest("hex")}`);
-        fs.writeFileSync(applied, "local follow-up\n");
-        await emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        expect(published).toHaveLength(1);
-        expect(published[0]).toMatchObject({
-            kind: "upsert",
-            relativePath,
-            contentHash: `sha256:${createHash("sha256")
-                .update("local follow-up\n")
-                .digest("hex")}`,
-        });
-    });
-    it("keeps a newer pull mark when an older local publish completes", async () => {
-        const published = [];
-        const applied = path.join(dir, "companies", "indigo", "publish-race.md");
-        const relativePath = "companies/indigo/publish-race.md";
-        const oldContent = "local old bytes\n";
-        const remoteContent = "remote newer bytes\n";
-        fs.mkdirSync(path.dirname(applied), { recursive: true });
-        fs.writeFileSync(applied, oldContent);
-        let releasePublish;
-        let publishStartedResolve;
-        const publishStarted = new Promise((resolve) => {
-            publishStartedResolve = resolve;
-        });
-        const publishGate = new Promise((resolve) => {
-            releasePublish = resolve;
-        });
-        const emitter = makeEmitter({
-            published,
-            transport: {
-                start: async () => { },
-                dispose: async () => { },
-                connected: true,
-                publish: async (event) => {
-                    published.push(event);
-                    publishStartedResolve?.();
-                    await publishGate;
-                },
-            },
-        });
-        const oldPublish = emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        await publishStarted;
-        emitter.markContentPublished(relativePath, `sha256:${createHash("sha256").update(remoteContent).digest("hex")}`);
-        releasePublish?.();
-        await oldPublish;
-        fs.writeFileSync(applied, remoteContent);
-        await emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        // The remote bytes remain suppressed: old publish completion could not
-        // overwrite the newer pull mark in the per-path publication ledger.
-        expect(published).toHaveLength(1);
-        expect(published[0]).toMatchObject({
-            kind: "upsert",
-            relativePath,
-            contentHash: `sha256:${createHash("sha256").update(oldContent).digest("hex")}`,
-        });
-    });
-    it("bounds publishedContentHashGenerations to the published-hash cap (was an unbounded Map)", () => {
-        const maxPaths = 8;
-        const K = 12;
-        const emitter = makeEmitter({ lastPublishedContentHashMaxPaths: maxPaths });
-        for (let i = 0; i < maxPaths + K; i++) {
-            emitter.markContentPublished(`companies/indigo/gen-${i}.md`, `sha256:h${i}`);
-        }
-        const sizes = emitter.censusSizes();
-        // The generations map used to be a plain Map with no eviction, so it grew to
-        // maxPaths + K and stayed there for the whole watch session — the unbounded
-        // retention this fix removes. It must now hold no more than its bounded
-        // sibling's cap.
-        expect(sizes.publishedContentHashGenerations).toBeLessThanOrEqual(maxPaths);
-        expect(sizes.lastPublishedContentHashes).toBeLessThanOrEqual(maxPaths);
-        // Sanity: we really did drive more distinct paths than the cap.
-        expect(maxPaths + K).toBeGreaterThan(maxPaths);
-    });
-    it("bounds the generations map without breaking pull-apply echo suppression for a hot path", async () => {
-        const published = [];
-        const maxPaths = 4;
-        const emitter = makeEmitter({ published, lastPublishedContentHashMaxPaths: maxPaths });
-        // Churn several cold paths first: each takes a fresh monotonic generation and
-        // evicts older ones from the now-bounded map.
-        for (let i = 0; i < maxPaths * 4; i++) {
-            emitter.markContentPublished(`companies/indigo/cold-${i}.md`, `sha256:c${i}`);
-        }
-        // The pulled path is marked LAST, so it is the hot, retained entry.
-        const applied = path.join(dir, "companies", "indigo", "hot-note.md");
-        const relativePath = "companies/indigo/hot-note.md";
-        const remoteContent = "from remote\n";
-        fs.mkdirSync(path.dirname(applied), { recursive: true });
-        fs.writeFileSync(applied, remoteContent);
-        emitter.markContentPublished(relativePath, `sha256:${createHash("sha256").update(remoteContent).digest("hex")}`);
-        // The identical local write is still suppressed as an echo (contract #456).
-        await emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        expect(published).toEqual([]);
-        // A genuinely new local edit still publishes.
-        fs.writeFileSync(applied, "local follow-up\n");
-        await emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        expect(published).toHaveLength(1);
-    });
-    it("keeps generation currency fail-closed under the bounded map: a newer pull mark still wins the publish race", async () => {
-        const published = [];
-        const maxPaths = 4;
-        const applied = path.join(dir, "companies", "indigo", "fail-closed-race.md");
-        const relativePath = "companies/indigo/fail-closed-race.md";
-        const oldContent = "local old bytes\n";
-        const remoteContent = "remote newer bytes\n";
-        fs.mkdirSync(path.dirname(applied), { recursive: true });
-        fs.writeFileSync(applied, oldContent);
-        let releasePublish;
-        let publishStartedResolve;
-        const publishStarted = new Promise((resolve) => {
-            publishStartedResolve = resolve;
-        });
-        const publishGate = new Promise((resolve) => {
-            releasePublish = resolve;
-        });
-        const emitter = makeEmitter({
-            published,
-            lastPublishedContentHashMaxPaths: maxPaths,
-            transport: {
-                start: async () => { },
-                dispose: async () => { },
-                connected: true,
-                publish: async (event) => {
-                    published.push(event);
-                    publishStartedResolve?.();
-                    await publishGate;
-                },
-            },
-        });
-        // Mark the path with an UNRELATED hash before the publish starts, so the
-        // in-flight publish captures a NON-ZERO generation yet is NOT echo-suppressed
-        // (the file's bytes differ from the marked hash).
-        emitter.markContentPublished(relativePath, "sha256:00decoy00");
-        const oldPublish = emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        await publishStarted;
-        // A pull applies newer bytes while the old publish is in flight, taking a
-        // fresh monotonic generation the captured value can never match.
-        emitter.markContentPublished(relativePath, `sha256:${createHash("sha256").update(remoteContent).digest("hex")}`);
-        releasePublish?.();
-        await oldPublish;
-        fs.writeFileSync(applied, remoteContent);
-        await emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        // The stale in-flight publish could not resurrect its captured generation to
-        // overwrite the newer pull mark, so the remote bytes stay suppressed.
-        expect(published.filter((event) => event.relativePath === relativePath)).toHaveLength(1);
-        expect(published[published.length - 1]).toMatchObject({
-            kind: "upsert",
-            relativePath,
-            contentHash: `sha256:${createHash("sha256").update(oldContent).digest("hex")}`,
-        });
-    });
-    it("does not resurrect an evicted generation to record a stale publish (ABA at the eviction boundary)", async () => {
-        const published = [];
-        const maxPaths = 2;
-        const applied = path.join(dir, "companies", "indigo", "aba-race.md");
-        const relativePath = "companies/indigo/aba-race.md";
-        const oldContent = "local old bytes\n";
-        const remoteContent = "remote newer bytes\n";
-        const oldHash = `sha256:${createHash("sha256").update(oldContent).digest("hex")}`;
-        fs.mkdirSync(path.dirname(applied), { recursive: true });
-        fs.writeFileSync(applied, oldContent);
-        let releasePublish;
-        let firstStartedResolve;
-        const firstStarted = new Promise((resolve) => {
-            firstStartedResolve = resolve;
-        });
-        const publishGate = new Promise((resolve) => {
-            releasePublish = resolve;
-        });
-        let publishCount = 0;
-        const emitter = makeEmitter({
-            published,
-            lastPublishedContentHashMaxPaths: maxPaths,
-            transport: {
-                start: async () => { },
-                dispose: async () => { },
-                connected: true,
-                publish: async (event) => {
-                    published.push(event);
-                    publishCount += 1;
-                    // Gate only the FIRST publish so it is still in flight while the pull
-                    // mark and eviction happen underneath it.
-                    if (publishCount === 1) {
-                        firstStartedResolve?.();
-                        await publishGate;
-                    }
-                },
-            },
-        });
-        // The path has NEVER been marked, so the in-flight publish captures the
-        // never-marked sentinel — the exact ABA precondition.
-        const firstPublish = emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        await firstStarted;
-        // A pull applies newer bytes for this path while the publish is in flight...
-        emitter.markContentPublished(relativePath, `sha256:${createHash("sha256").update(remoteContent).digest("hex")}`);
-        // ...then enough other paths are marked to evict this path's generation entry,
-        // collapsing it back to the absent sentinel.
-        for (let i = 0; i < maxPaths * 4; i += 1) {
-            emitter.markContentPublished(`companies/indigo/aba-churn-${i}.md`, `sha256:z${i}`);
-        }
-        releasePublish?.();
-        await firstPublish;
-        // The stale completion must NOT have recorded oldHash for this path. If it
-        // had (the ABA bug), the genuine local revert to oldContent below would be
-        // wrongly suppressed as an echo and never published — silent data loss.
-        await emitter.emitForBatch({ paths: new Map([[applied, relativePath]]) });
-        const forPath = published.filter((event) => event.relativePath === relativePath);
-        expect(forPath).toHaveLength(2);
-        expect(forPath[1]).toMatchObject({ kind: "upsert", relativePath, contentHash: oldHash });
-    });
-    it("stamps an upsert with the byte length of the content it hashes", async () => {
-        const published = [];
-        const file = path.join(dir, "sized-content.bin");
-        const content = Buffer.from([0, 1, 2, 3, 4, 5, 6]);
-        fs.writeFileSync(file, content);
-        await makeEmitter({ published }).emitForBatch({
-            paths: new Map([[file, "sized-content.bin"]]),
-        });
-        expect(published).toHaveLength(1);
-        expect(published[0]).toMatchObject({
-            kind: "upsert",
-            sizeBytes: content.byteLength,
-            contentHash: `sha256:${createHash("sha256").update(content).digest("hex")}`,
-        });
-    });
-    it("coalesces ten rewrites of one path into an immediate and trailing latest publish", async () => {
-        const clock = new FakeClock();
-        const published = [];
-        const rewritten = path.join(dir, "high-churn-prd.json");
-        const relativePath = "personal/projects/churn/prd.json";
-        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000, clock });
-        const batch = { paths: new Map([[rewritten, relativePath]]) };
-        for (let version = 0; version < 10; version += 1) {
-            fs.writeFileSync(rewritten, `{"version":${version}}\n`);
-            await emitter.emitForBatch(batch);
-            if (version < 9)
-                clock.advance(5_000);
-        }
-        expect(published).toHaveLength(1);
-        clock.advance(15_000);
-        await emitter.emitForBatch({ paths: new Map() });
-        expect(published).toHaveLength(2);
-        expect(clock.pendingTimerCount()).toBe(0);
-        expect(published[1]).toMatchObject({ kind: "upsert", relativePath });
-        expect(published[1].contentHash).toBe(`sha256:${createHash("sha256").update('{"version":9}\n').digest("hex")}`);
-    });
-    it("suppresses a deferred continuation queued behind a realtime-unavailable denial", async () => {
-        const clock = new FakeClock();
-        const published = [];
-        const deferred = path.join(dir, "deferred-after-denial.json");
-        const active = path.join(dir, "active-denial.json");
-        const deferredRelativePath = "personal/projects/deferred-after-denial.json";
-        let releaseDenial;
-        let activePublishStarted;
-        const denialGate = new Promise((resolve) => {
-            releaseDenial = resolve;
-        });
-        const activeStarted = new Promise((resolve) => {
-            activePublishStarted = resolve;
-        });
-        const emitter = makeEmitter({
-            published,
-            clock,
-            publishMinIntervalMs: 60_000,
-            transport: {
-                start: async () => { },
-                dispose: async () => { },
-                connected: true,
-                publish: async (event) => {
-                    published.push(event);
-                    if (event.relativePath === "personal/projects/active-denial.json") {
-                        activePublishStarted?.();
-                        await denialGate;
-                        throw new RealtimeUnavailableError({ status: 403, operation: "test push" });
-                    }
-                },
-            },
-        });
-        fs.writeFileSync(deferred, '{"revision":1}\n');
-        await emitter.emitForBatch({ paths: new Map([[deferred, deferredRelativePath]]) });
-        fs.writeFileSync(deferred, '{"revision":2}\n');
-        await emitter.emitForBatch({ paths: new Map([[deferred, deferredRelativePath]]) });
-        fs.writeFileSync(active, '{"active":true}\n');
-        const activeRun = emitter.emitForBatch({
-            paths: new Map([[active, "personal/projects/active-denial.json"]]),
-        });
-        await activeStarted;
-        clock.advance(60_000);
-        releaseDenial?.();
-        await activeRun;
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
-        expect(emitter.realtimeUnavailable).toBe(true);
-        expect(published.map((event) => event.relativePath)).toEqual([
-            deferredRelativePath,
-            "personal/projects/active-denial.json",
-        ]);
-    });
-    it("keeps publishing other companies after a company membership denial", async () => {
-        const deniedRelativePath = "companies/liverecover/projects/denied.md";
-        const allowedRelativePath = "companies/indigo/projects/allowed.md";
-        const denied = path.join(dir, deniedRelativePath);
-        const allowed = path.join(dir, allowedRelativePath);
-        fs.mkdirSync(path.dirname(denied), { recursive: true });
-        fs.mkdirSync(path.dirname(allowed), { recursive: true });
-        fs.writeFileSync(denied, "denied\n");
-        fs.writeFileSync(allowed, "allowed\n");
-        const observedPaths = [];
-        const fetch = vi.fn(async (_url, init) => {
-            const relativePath = JSON.parse(init?.body ?? "{}").relativePath;
-            observedPaths.push(relativePath);
-            return relativePath === deniedRelativePath
-                ? {
-                    ok: false,
-                    status: 403,
-                    text: async () => JSON.stringify({
-                        error: "cross-tenant",
-                        code: "cross-tenant-push-rejected",
-                    }),
-                }
-                : { ok: true, status: 200, text: async () => "" };
-        });
-        const onError = vi.fn();
-        const emitter = makeEmitter({
-            onError,
-            transport: new HttpPushTransport({
-                apiUrl: "https://api.example.com",
-                authToken: "token",
-                fetchImpl: fetch,
-            }),
-        });
-        await emitter.emitForBatch({ paths: new Map([[denied, deniedRelativePath]]) });
-        await emitter.emitForBatch({ paths: new Map([[allowed, allowedRelativePath]]) });
-        expect(fetch).toHaveBeenCalledTimes(2);
-        expect(observedPaths).toEqual([deniedRelativePath, allowedRelativePath]);
-        expect(emitter.realtimeUnavailable).toBe(false);
-        expect(onError).toHaveBeenCalledTimes(1);
-        expect(onError).toHaveBeenCalledWith(expect.any(PushScopeForbiddenError), { relativePath: deniedRelativePath });
-    });
-    it("suppresses repeated membership-denied publishes for one company scope", async () => {
-        const relativePath = "companies/liverecover/projects/retry-loop.md";
-        const file = path.join(dir, relativePath);
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, "still local\n");
-        const fetch = vi.fn(async () => ({
-            ok: false,
-            status: 403,
-            text: async () => JSON.stringify({
-                error: "cross-tenant",
-                code: "cross-tenant-push-rejected",
-            }),
-        }));
-        const onError = vi.fn();
-        const emitter = makeEmitter({
-            onError,
-            transport: new HttpPushTransport({
-                apiUrl: "https://api.example.com",
-                authToken: "token",
-                fetchImpl: fetch,
-            }),
-        });
-        const batch = { paths: new Map([[file, relativePath]]) };
-        await emitter.emitForBatch(batch);
-        await emitter.emitForBatch(batch);
-        await emitter.emitForBatch(batch);
-        expect(fetch).toHaveBeenCalledTimes(1);
-        expect(onError).toHaveBeenCalledTimes(1);
-        expect(onError).toHaveBeenCalledWith(expect.any(PushScopeForbiddenError), { relativePath });
-    });
-    it("publishes the uploaded deferred revision when the local file changes before flush", async () => {
-        const clock = new FakeClock();
-        const published = [];
-        const rewritten = path.join(dir, "captured-deferred-revision.json");
-        const relativePath = "personal/projects/captured/prd.json";
-        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000, clock });
-        const batch = { paths: new Map([[rewritten, relativePath]]) };
-        fs.writeFileSync(rewritten, '{"revision":"uploaded"}\n');
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(rewritten, '{"revision":"deferred-uploaded"}\n');
-        await emitter.emitForBatch(batch);
-        const expectedHash = `sha256:${createHash("sha256")
-            .update('{"revision":"deferred-uploaded"}\n')
-            .digest("hex")}`;
-        // This local revision has not completed its scoped push yet. The trailing
-        // announcement must remain bound to the previously uploaded bytes.
-        fs.writeFileSync(rewritten, '{"revision":"newer-local"}\n');
-        clock.advance(60_000);
-        await emitter.emitForBatch({ paths: new Map() });
-        expect(published).toHaveLength(2);
-        expect(published[1]).toMatchObject({
-            kind: "upsert",
-            relativePath,
-            contentHash: expectedHash,
-        });
-        expect(published[1].contentHash).not.toBe(`sha256:${createHash("sha256")
-            .update('{"revision":"newer-local"}\n')
-            .digest("hex")}`);
-    });
-    it("skips the trailing publish when the final rewrite restores the last published hash", async () => {
-        const clock = new FakeClock();
-        const published = [];
-        const rewritten = path.join(dir, "reverted-prd.json");
-        const relativePath = "personal/projects/reverted/prd.json";
-        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000, clock });
-        const batch = { paths: new Map([[rewritten, relativePath]]) };
-        fs.writeFileSync(rewritten, "A\n");
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(rewritten, "B\n");
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(rewritten, "A\n");
-        await emitter.emitForBatch(batch);
-        clock.advance(60_000);
-        await emitter.emitForBatch({ paths: new Map() });
-        expect(published).toHaveLength(1);
-        expect(clock.pendingTimerCount()).toBe(0);
-        expect(published[0]).toMatchObject({ kind: "upsert", relativePath });
-    });
-    it("publishes a delete immediately while an upsert is deferred", async () => {
-        const clock = new FakeClock();
-        const published = [];
-        const deleted = path.join(dir, "delete-during-quiet.jsonl");
-        const relativePath = "workspace/.session-logs/delete-during-quiet.jsonl";
-        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000, clock });
-        const batch = { paths: new Map([[deleted, relativePath]]) };
-        fs.writeFileSync(deleted, "A\n");
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(deleted, "B\n");
-        await emitter.emitForBatch(batch);
-        fs.rmSync(deleted);
-        await emitter.emitForBatch(batch);
-        expect(published.map((event) => event.kind)).toEqual(["upsert", "delete"]);
-        clock.advance(60_000);
-        await emitter.emitForBatch({ paths: new Map() });
-        expect(published).toHaveLength(2);
-    });
-    it("does not make a second path wait behind another path's quiet interval", async () => {
-        const published = [];
-        const first = path.join(dir, "first-high-churn.jsonl");
-        const second = path.join(dir, "independent.jsonl");
-        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000 });
-        fs.writeFileSync(first, "A\n");
-        fs.writeFileSync(second, "B\n");
-        await emitter.emitForBatch({ paths: new Map([[first, "workspace/.session-logs/first.jsonl"]]) });
-        fs.writeFileSync(first, "A2\n");
-        await emitter.emitForBatch({ paths: new Map([[first, "workspace/.session-logs/first.jsonl"]]) });
-        await emitter.emitForBatch({ paths: new Map([[second, "workspace/.session-logs/second.jsonl"]]) });
-        expect(published.map((event) => event.relativePath)).toEqual([
-            "workspace/.session-logs/first.jsonl",
-            "workspace/.session-logs/second.jsonl",
-        ]);
-    });
-    it("publishes a content revert because it compares only with the last publication", async () => {
-        const published = [];
-        const reverted = path.join(dir, "reverted-session-log.jsonl");
-        fs.writeFileSync(reverted, "A\n");
-        const emitter = makeEmitter({ published });
-        const batch = { paths: new Map([[reverted, "workspace/.session-logs/reverted-session-log.jsonl"]]) };
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(reverted, "B\n");
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(reverted, "A\n");
-        await emitter.emitForBatch(batch);
-        expect(published).toHaveLength(3);
-        expect(published[0].contentHash).toBe(published[2].contentHash);
-        expect(published[0].contentHash).not.toBe(published[1].contentHash);
-    });
-    it("re-announces a revert after an intervening changed publication fails", async () => {
-        const published = [];
-        let fail = false;
-        const changed = path.join(dir, "failed-revert-session-log.jsonl");
-        fs.writeFileSync(changed, "A\n");
-        const emitter = new PushEventEmitter({
-            originTenantId: "tenant-indigo",
-            originDeviceId: "device-a",
-            flagProvider: { isEnabled: () => true },
-            publishMinIntervalMs: 0,
-            transport: {
-                start: async () => { },
-                dispose: async () => { },
-                connected: true,
-                publish: async (event) => {
-                    if (fail)
-                        throw new Error("push unavailable");
-                    published.push(event);
-                },
-            },
-            onError: vi.fn(),
-        });
-        const batch = { paths: new Map([[changed, "workspace/.session-logs/failed-revert-session-log.jsonl"]]) };
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(changed, "B\n");
-        fail = true;
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(changed, "A\n");
-        fail = false;
-        await emitter.emitForBatch(batch);
-        expect(published).toHaveLength(2);
-        expect(published[0].contentHash).toBe(published[1].contentHash);
-    });
-    it("always publishes deletes after an unchanged touch and clears the path state", async () => {
-        const published = [];
-        const deleted = path.join(dir, "deleted-after-touch.jsonl");
-        fs.writeFileSync(deleted, "A\n");
-        const emitter = makeEmitter({ published });
-        const batch = { paths: new Map([[deleted, "workspace/.session-logs/deleted-after-touch.jsonl"]]) };
-        await emitter.emitForBatch(batch);
-        await emitter.emitForBatch(batch);
-        fs.rmSync(deleted);
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(deleted, "A\n");
-        await emitter.emitForBatch(batch);
-        expect(published).toHaveLength(3);
-        expect(published.map((event) => event.kind)).toEqual(["upsert", "delete", "upsert"]);
-    });
-    it("re-announces a same-content recreation after a failed delete", async () => {
-        const published = [];
-        let fail = false;
-        const deleted = path.join(dir, "failed-delete-session-log.jsonl");
-        fs.writeFileSync(deleted, "A\n");
-        const emitter = new PushEventEmitter({
-            originTenantId: "tenant-indigo",
-            originDeviceId: "device-a",
-            flagProvider: { isEnabled: () => true },
-            transport: {
-                start: async () => { },
-                dispose: async () => { },
-                connected: true,
-                publish: async (event) => {
-                    if (fail)
-                        throw new Error("push unavailable");
-                    published.push(event);
-                },
-            },
-            onError: vi.fn(),
-        });
-        const batch = { paths: new Map([[deleted, "workspace/.session-logs/failed-delete-session-log.jsonl"]]) };
-        await emitter.emitForBatch(batch);
-        fs.rmSync(deleted);
-        fail = true;
-        await emitter.emitForBatch(batch);
-        fs.writeFileSync(deleted, "A\n");
-        fail = false;
-        await emitter.emitForBatch(batch);
-        expect(published.map((event) => event.kind)).toEqual(["upsert", "upsert"]);
-    });
-    it("bounds last-published content state and only re-publishes an evicted path", async () => {
-        const published = [];
-        const emitter = makeEmitter({ published, lastPublishedContentHashMaxPaths: 2 });
-        const paths = ["first.jsonl", "second.jsonl", "third.jsonl"].map((name) => {
-            const absolute = path.join(dir, name);
-            fs.writeFileSync(absolute, `${name}\n`);
-            return [absolute, `workspace/.session-logs/${name}`];
-        });
-        for (const entry of paths)
-            await emitter.emitForBatch({ paths: new Map([entry]) });
-        await emitter.emitForBatch({ paths: new Map([paths[0]]) });
-        await emitter.emitForBatch({ paths: new Map([paths[2]]) });
-        expect(published.map((event) => event.relativePath)).toEqual([
-            "workspace/.session-logs/first.jsonl",
-            "workspace/.session-logs/second.jsonl",
-            "workspace/.session-logs/third.jsonl",
-            "workspace/.session-logs/first.jsonl",
-        ]);
-    });
-    it("restart simulation: preserves published hashes so an unchanged first pass emits zero upserts", async () => {
-        const published = [];
-        const journaled = path.join(dir, "pre-populated-journal.jsonl");
-        fs.writeFileSync(journaled, "A\n");
-        const batch = { paths: new Map([[journaled, "workspace/.session-logs/pre-populated-journal.jsonl"]]) };
-        const stateDir = path.join(dir, "state");
-        await makeEmitter({ published, lastPublishedContentHashStateDir: stateDir }).emitForBatch(batch);
-        await makeEmitter({ published, lastPublishedContentHashStateDir: stateDir }).emitForBatch(batch);
-        expect(published).toHaveLength(1);
-        fs.writeFileSync(journaled, "B\n");
-        await makeEmitter({ published, lastPublishedContentHashStateDir: stateDir }).emitForBatch(batch);
-        expect(published).toHaveLength(2);
-        expect(published[1].contentHash).not.toBe(published[0].contentHash);
-    });
-    it("restart simulation: publishes a tombstone for a delete during downtime", async () => {
-        const published = [];
-        const deleted = path.join(dir, "deleted-during-downtime.md");
-        const batch = { paths: new Map([[deleted, "deleted-during-downtime.md"]]) };
-        const stateDir = path.join(dir, "state");
-        fs.writeFileSync(deleted, "A\n");
-        await makeEmitter({ published, lastPublishedContentHashStateDir: stateDir }).emitForBatch(batch);
-        fs.rmSync(deleted);
-        await makeEmitter({ published, lastPublishedContentHashStateDir: stateDir }).emitForBatch(batch);
-        expect(published.map((event) => event.kind)).toEqual(["upsert", "delete"]);
-    });
-    it("journal baseline suppresses unchanged files when durable state is first created", async () => {
-        const published = [];
-        const existing = path.join(dir, "journaled-before-upgrade.md");
-        const relativePath = "companies/indigo/journaled-before-upgrade.md";
-        fs.writeFileSync(existing, "already synced\n");
-        const contentHash = `sha256:${createHash("sha256").update("already synced\n").digest("hex")}`;
-        await makeEmitter({
-            published,
-            lastPublishedContentHashStateDir: path.join(dir, "baseline-state"),
-            initialPublishedContentHashes: { [relativePath]: contentHash },
-        }).emitForBatch({ paths: new Map([[existing, relativePath]]) });
-        expect(published).toEqual([]);
-    });
-    it("does not seed suppression for a journaled local divergence", async () => {
-        const published = [];
-        const changed = path.join(dir, "changed-while-down.md");
-        const relativePath = "companies/indigo/changed-while-down.md";
-        fs.writeFileSync(changed, "changed while down\n");
-        const contentHash = `sha256:${createHash("sha256").update("changed while down\n").digest("hex")}`;
-        await makeEmitter({
-            published,
-            lastPublishedContentHashStateDir: path.join(dir, "divergent-state"),
-        }).emitForBatch({ paths: new Map([[changed, relativePath]]) });
-        expect(published).toHaveLength(1);
-        expect(published[0]).toMatchObject({ kind: "upsert", contentHash });
-    });
-    it("fresh durable state publishes the first uploaded file", async () => {
-        const published = [];
-        const fresh = path.join(dir, "fresh-device.md");
-        fs.writeFileSync(fresh, "first upload\n");
-        await makeEmitter({
-            published,
-            lastPublishedContentHashStateDir: path.join(dir, "fresh-state"),
-        }).emitForBatch({ paths: new Map([[fresh, "fresh-device.md"]]) });
-        expect(published).toHaveLength(1);
-        expect(published[0]).toMatchObject({ kind: "upsert", relativePath: "fresh-device.md" });
-    });
-    it("retries a durable publish-state lock timeout without rejecting the watcher announce", async () => {
-        const clock = new FakeClock();
-        const onError = vi.fn();
-        const originalAppendGeneratedIfAsync = StateStore.prototype.appendGeneratedIfAsync;
-        const appendGeneratedIfAsync = vi.spyOn(StateStore.prototype, "appendGeneratedIfAsync")
-            .mockImplementationOnce(function (type, preparePayload, flags) {
-            return originalAppendGeneratedIfAsync.call(this, type, preparePayload, flags);
-        })
-            .mockRejectedValueOnce(new StateStoreLockError("timed out acquiring append.lock"));
-        const published = [];
-        const changed = path.join(dir, "lock-timeout.md");
-        fs.writeFileSync(changed, "lock timeout\n");
-        try {
-            await expect(makeEmitter({
-                clock,
-                onError,
-                published,
-                lastPublishedContentHashStateDir: path.join(dir, "lock-timeout-state"),
-            }).emitForBatch({ paths: new Map([[changed, "lock-timeout.md"]]) })).resolves.toBeUndefined();
-            expect(published).toHaveLength(1);
-            expect(onError).toHaveBeenCalledWith(expect.objectContaining({ name: "StateStoreLockError" }), { relativePath: "lock-timeout.md" });
-            expect(appendGeneratedIfAsync).toHaveBeenCalledTimes(2); // invalidate before the guarded durable set
-            const appendsBeforeRetry = appendGeneratedIfAsync.mock.calls.length;
-            clock.advance(250);
-            await Promise.resolve();
-            await Promise.resolve();
-            expect(appendGeneratedIfAsync).toHaveBeenCalledTimes(appendsBeforeRetry + 1);
-        }
-        finally {
-            appendGeneratedIfAsync.mockRestore();
-        }
-    });
-    it("cancels a stale durable-state retry after persisting a newer hash", async () => {
-        const clock = new FakeClock();
-        const originalAppendGeneratedIfAsync = StateStore.prototype.appendGeneratedIfAsync;
-        const appendGeneratedIfAsync = vi.spyOn(StateStore.prototype, "appendGeneratedIfAsync")
-            .mockImplementationOnce(function (type, preparePayload, flags) {
-            return originalAppendGeneratedIfAsync.call(this, type, preparePayload, flags);
-        })
-            .mockRejectedValueOnce(new StateStoreLockError("timed out acquiring append.lock"));
-        const stateDir = path.join(dir, "superseded-retry-state");
-        const changed = path.join(dir, "superseded-retry.md");
-        const published = [];
-        fs.writeFileSync(changed, "A\n");
-        try {
-            const emitter = makeEmitter({ clock, published, lastPublishedContentHashStateDir: stateDir });
-            await emitter.emitForBatch({ paths: new Map([[changed, "superseded-retry.md"]]) });
-            expect(clock.pendingTimerCount()).toBe(1);
-            fs.writeFileSync(changed, "B\n");
-            await emitter.emitForBatch({ paths: new Map([[changed, "superseded-retry.md"]]) });
-            expect(clock.pendingTimerCount()).toBe(0);
-            const appendsAfterNewerSuccess = appendGeneratedIfAsync.mock.calls.length;
-            clock.advance(10_000);
-            await Promise.resolve();
-            expect(appendGeneratedIfAsync).toHaveBeenCalledTimes(appendsAfterNewerSuccess);
-            const afterRestart = [];
-            await makeEmitter({
-                published: afterRestart,
-                lastPublishedContentHashStateDir: stateDir,
-            }).emitForBatch({ paths: new Map([[changed, "superseded-retry.md"]]) });
-            expect(afterRestart).toEqual([]);
-        }
-        finally {
-            appendGeneratedIfAsync.mockRestore();
-        }
-    });
-    it("drops permanent durable-state persistence errors without scheduling retries", async () => {
-        const clock = new FakeClock();
-        const onError = vi.fn();
-        const originalAppendGeneratedIfAsync = StateStore.prototype.appendGeneratedIfAsync;
-        const appendGeneratedIfAsync = vi.spyOn(StateStore.prototype, "appendGeneratedIfAsync")
-            .mockImplementationOnce(function (type, preparePayload, flags) {
-            return originalAppendGeneratedIfAsync.call(this, type, preparePayload, flags);
-        })
-            .mockRejectedValue(new Error("EACCES: state directory is unwritable"));
-        const changed = path.join(dir, "permanent-state-error.md");
-        fs.writeFileSync(changed, "cannot persist\n");
-        try {
-            await makeEmitter({
-                clock,
-                onError,
-                lastPublishedContentHashStateDir: path.join(dir, "permanent-state-error"),
-            }).emitForBatch({ paths: new Map([[changed, "permanent-state-error.md"]]) });
-            expect(onError).toHaveBeenCalledTimes(1);
-            expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining("EACCES") }), { relativePath: "permanent-state-error.md" });
-            expect(clock.pendingTimerCount()).toBe(0);
-            const appendsAfterFailure = appendGeneratedIfAsync.mock.calls.length;
-            clock.advance(60_000);
-            await Promise.resolve();
-            expect(appendGeneratedIfAsync).toHaveBeenCalledTimes(appendsAfterFailure);
-            expect(onError).toHaveBeenCalledTimes(1);
-        }
-        finally {
-            appendGeneratedIfAsync.mockRestore();
-        }
-    });
-    it("emits push telemetry only when publication fails", async () => {
-        const posts = [];
-        const telemetryClient = {
-            postTelemetryEvents: vi.fn(async (batch) => {
-                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: { isEnabled: () => true },
-            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: { isEnabled: () => true },
-            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",
-                },
-            }),
-        ]);
-    });
-    it("emits one outcome record with the correct mixed-batch attempt denominator", async () => {
-        const first = path.join(dir, "first.md");
-        const second = path.join(dir, "second.md");
-        fs.writeFileSync(first, "first");
-        fs.writeFileSync(second, "second");
-        const outcomes = [];
-        const emitter = new PushEventEmitter({
-            originTenantId: "tenant-indigo",
-            originDeviceId: "device-a",
-            transport: {
-                start: async () => { },
-                dispose: async () => { },
-                connected: true,
-                publish: async (event) => {
-                    if (event.relativePath === "second.md") {
-                        throw new Error("second publish failed");
-                    }
-                },
-            },
-            flagProvider: { isEnabled: () => true },
-            getSequenceNumber: (() => {
-                let next = 41;
-                return () => next++;
-            })(),
-            onError: vi.fn(),
-            onPublishOutcome: (outcome) => outcomes.push(outcome),
-        });
-        await emitter.emitForBatch({
-            paths: new Map([
-                [first, "first.md"],
-                [second, "second.md"],
-            ]),
-        });
-        expect(outcomes).toHaveLength(1);
-        expect(outcomes[0]).toMatchObject({
-            attempted: 2,
-            succeeded: 1,
-            failed: 1,
-        });
-        expect(outcomes[0].omitted).toBe(0);
-        expect(outcomes[0].attempts).toContainEqual(expect.objectContaining({
-            error: expect.objectContaining({ message: "second publish failed" }),
-        }));
-    });
-    it("caps successful attempt evidence while retaining every failure and full-set latency statistics", () => {
-        const successes = Array.from({ length: 1_000 }, (_, index) => ({
-            sequenceNumber: index,
-            elapsedMs: index + 1,
-            abortedAtIssue: false,
-        }));
-        const failures = Array.from({ length: 16 }, (_, index) => ({
-            sequenceNumber: 10_000 + index,
-            elapsedMs: 60_000 + index,
-            abortedAtIssue: false,
-            error: {
-                name: "AbortError",
-                message: `publish timeout ${index}`,
-                stack: "at Timeout._onTimeout (push-transport.js:195)",
-            },
-        }));
-        const outcome = summarizePublishBatchOutcome([...successes, ...failures]);
-        const serialized = JSON.stringify(outcome);
-        const retainedFailures = outcome.attempts.filter((attempt) => attempt.error !== undefined);
-        const retainedSuccesses = outcome.attempts.filter((attempt) => attempt.error === undefined);
-        expect(outcome).toMatchObject({
-            attempted: 1_016,
-            succeeded: 1_000,
-            failed: 16,
-            omitted: 1_000 - PUBLISH_OUTCOME_SUCCESS_SAMPLE_CAP,
-            successfulElapsedMs: { min: 1, median: 500.5, max: 1_000 },
-        });
-        expect(retainedSuccesses).toEqual(successes.slice(0, 3));
-        expect(retainedFailures).toEqual(failures);
-        for (const aggregate of ["attempted", "succeeded", "failed"]) {
-            expect(serialized.indexOf(`"${aggregate}"`)).toBeLessThan(serialized.indexOf('"attempts"'));
-        }
-        expect(Buffer.byteLength(serialized)).toBeLessThan(PUBLISH_OUTCOME_JOURNALD_CEILING_BYTES);
-    });
-});
-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 = [];
-        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();
-    });
-});
-describe("TreeWatcher deferred delete snapshots", () => {
-    it("does not let a thrown delete-capture callback kill later watcher delivery", () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-capture-error-"));
-        const clock = new FakeClock();
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            queueLocalDeleteSnapshots: () => {
-                throw new Error("capture failed");
-            },
-        });
-        const batches = [];
-        watcher.onChange((_first, batch) => batches.push([...(batch?.paths.values() ?? [])]));
-        expect(() => watcher.handleEvent(path.join(hqRoot, "deleted.md"), "unlink")).not.toThrow();
-        expect(() => watcher.handleEvent(path.join(hqRoot, "later.md"), "add")).not.toThrow();
-        clock.advance(25);
-        expect(batches).toEqual([["deleted.md", "later.md"]]);
-        watcher.dispose();
-        fs.rmSync(hqRoot, { recursive: true, force: true });
-    });
-    it("marks a queued unlink stale when a newer revision arrives", async () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-capture-stale-"));
-        const clock = new FakeClock();
-        let resolveCapture;
-        let observedCurrent = true;
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            queueLocalDeleteSnapshots: async (_relative, _kind, isCurrent) => {
-                await new Promise((resolve) => { resolveCapture = resolve; });
-                observedCurrent = isCurrent();
-                return [];
-            },
-        });
-        watcher.handleEvent(path.join(hqRoot, "recreated.md"), "unlink");
-        await Promise.resolve();
-        watcher.handleEvent(path.join(hqRoot, "recreated.md"), "add");
-        resolveCapture();
-        await Promise.resolve();
-        expect(observedCurrent).toBe(false);
-        watcher.dispose();
-        fs.rmSync(hqRoot, { recursive: true, force: true });
-    });
-    it("batches one watcher turn and keeps per-path current checks", async () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-capture-batch-"));
-        const clock = new FakeClock();
-        const observed = [];
-        const queueBatch = async (captures) => {
-            const results = captures.map((capture) => {
-                const current = capture.isCurrent();
-                observed.push({ relativePath: capture.relativePath, current });
-                return current ? [{
-                        journalSlug: "indigo",
-                        journalPath: capture.relativePath,
-                        deleteScopeRoot: "",
-                        absolutePath: path.join(hqRoot, capture.relativePath),
-                        remoteEtag: "etag",
-                        localHash: "hash",
-                        localKind: "file",
-                    }] : [];
-            });
-            return results;
-        };
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            queueLocalDeleteSnapshotsBatch: queueBatch,
-        });
-        try {
-            const recreated = path.join(hqRoot, "recreated.md");
-            const deleted = path.join(hqRoot, "deleted.md");
-            watcher.handleEvent(recreated, "unlink");
-            watcher.handleEvent(recreated, "add");
-            watcher.handleEvent(deleted, "unlink");
-            await settle();
-            expect(observed).toEqual([
-                { relativePath: "recreated.md", current: false },
-                { relativePath: "deleted.md", current: true },
-            ]);
-            await settle();
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
-        }
-        finally {
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    // `deleteSnapshotEpochs` exists to let a newer revision of a path
-    // invalidate a delete-snapshot capture that is still queued or running. A
-    // long-lived runner touches hundreds of thousands of distinct paths, so a
-    // key may live in that map only while such a capture is in flight; any
-    // other write into it is a leak keyed by path.
-    it("batches warmup missing-file snapshots through the queued capture path", async () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-warmup-capture-batch-"));
-        const observed = [];
-        const queueBatch = async (captures) => {
-            observed.push(captures.map((capture) => capture.relativePath));
-            return captures.map(() => []);
-        };
-        const watcher = new TreeWatcher({
-            hqRoot,
-            pathFilter: () => true,
-            queueLocalDeleteSnapshotsBatch: queueBatch,
-        });
-        try {
-            const catchup = await watcher.collectWarmupCatchupAsync(Date.now(), [
-                "missing-one.md",
-                "missing-two.md",
-            ]);
-            await Promise.all([...(catchup.batch.changes?.values() ?? [])].map((change) => change.deleteSnapshotCapture ?? Promise.resolve([])));
-            await settle();
-            expect(observed).toEqual([["missing-one.md", "missing-two.md"]]);
-        }
-        finally {
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    const settle = () => new Promise((resolve) => setImmediate(resolve));
-    it("retires a superseded capture's epoch when that capture completes", async () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-retire-"));
-        const clock = new FakeClock();
-        let resolveCapture;
-        let observedCurrent = true;
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            queueLocalDeleteSnapshots: async (_relative, _kind, isCurrent) => {
-                await new Promise((resolve) => { resolveCapture = resolve; });
-                observedCurrent = isCurrent();
-                return [];
-            },
-        });
-        try {
-            const target = path.join(hqRoot, "recreated.md");
-            watcher.handleEvent(target, "unlink");
-            await Promise.resolve();
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
-            // The newer revision invalidates the running capture but must keep the
-            // marker until that capture has actually observed it.
-            watcher.handleEvent(target, "add");
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
-            resolveCapture();
-            await settle();
-            expect(observedCurrent).toBe(false);
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
-        }
-        finally {
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("never creates an epoch for a live event or for a synchronous capture", () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-live-"));
-        const clock = new FakeClock();
-        const capture = vi.fn(() => []);
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            captureLocalDeleteSnapshots: capture,
-        });
-        try {
-            watcher.handleEvent(path.join(hqRoot, "added.md"), "add");
-            watcher.handleEvent(path.join(hqRoot, "edited.md"), "change");
-            watcher.handleEvent(path.join(hqRoot, "made"), "addDir");
-            watcher.handleEvent(path.join(hqRoot, "gone.md"), "unlink");
-            watcher.handleEvent(path.join(hqRoot, "gone-dir"), "unlinkDir");
-            clock.advance(25);
-            expect(capture).toHaveBeenCalledTimes(2);
-            // A synchronous capture has already run by the time the event returns:
-            // there is nothing left to invalidate, so there is nothing to remember.
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
-        }
-        finally {
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("shares one epoch across overlapping captures of a path and retires it with the last", async () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-overlap-"));
-        const clock = new FakeClock();
-        const resolvers = [];
-        const observed = [];
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            queueLocalDeleteSnapshots: async (_relative, _kind, isCurrent) => {
-                await new Promise((resolve) => { resolvers.push(resolve); });
-                observed.push(isCurrent());
-                return [];
-            },
-        });
-        try {
-            const target = path.join(hqRoot, "twice.md");
-            watcher.handleEvent(target, "unlink");
-            await Promise.resolve();
-            watcher.handleEvent(target, "unlink"); // second delete in the window queues behind the first
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
-            resolvers.shift()();
-            await settle();
-            // The first capture was superseded by the second; the second is still
-            // queued, so the path keeps its marker.
-            expect(observed).toEqual([false]);
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
-            resolvers.shift()();
-            await settle();
-            expect(observed).toEqual([false, true]);
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
-        }
-        finally {
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("leaves no epoch for a path whose capture the full queue rejected", async () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-full-"));
-        const clock = new FakeClock();
-        const resolvers = [];
-        const observed = [];
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            maxPendingPaths: 2,
-            queueLocalDeleteSnapshots: async (relative, _kind, isCurrent) => {
-                await new Promise((resolve) => { resolvers.push(resolve); });
-                observed.push(`${relative}:${isCurrent()}`);
-                return [];
-            },
-        });
-        const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
-        try {
-            const a = path.join(hqRoot, "a.md");
-            const b = path.join(hqRoot, "b.md");
-            watcher.handleEvent(a, "unlink");
-            await Promise.resolve();
-            resolvers.shift()();
-            await settle(); // a's capture is done; a is still pending in the window
-            expect(observed).toEqual(["a.md:true"]);
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
-            watcher.handleEvent(b, "unlink");
-            watcher.handleEvent(b, "unlink"); // two captures queued for b: the queue is full
-            // A third delete of `a` finds the queue full. Nothing is in flight for
-            // `a`, so nothing may be recorded for it either.
-            watcher.handleEvent(a, "unlink");
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
-            // A full queue must still supersede a capture that IS in flight for the
-            // path, exactly as it did before, and that path's marker still retires.
-            watcher.handleEvent(b, "unlink");
-            await settle(); // the first queued capture for b starts
-            resolvers.shift()();
-            await settle(); // ...and the second, queued behind it
-            resolvers.shift()();
-            await settle();
-            expect(observed).toEqual(["a.md:true", "b.md:false", "b.md:false"]);
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
-        }
-        finally {
-            consoleError.mockRestore();
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-});
-describe("TreeWatcher untracked delete drop", () => {
-    // Atomic writers (`.name.<pid>.<random>.tmp` renamed into place, editor
-    // swap files) create and remove a path within one debounce window. Such a
-    // path has no journal row, so its unlink has nothing to delete remotely and
-    // no revision to bind: queueing it only cost a delete-snapshot capture, a
-    // pending-map slot, and a targeted push that found nothing on disk. On the
-    // controller these were 370 of 380 agency watcher events per minute.
-    function makeRoot() {
-        return fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-untracked-"));
-    }
-    it("drops a file unlink that has no journal row before it reaches a batch", () => {
-        const hqRoot = makeRoot();
-        const clock = new FakeClock();
-        const capture = vi.fn(() => []);
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            captureLocalDeleteSnapshots: capture,
-            isUntrackedDelete: (relativePath) => relativePath.endsWith(".tmp"),
-        });
-        const batches = [];
-        watcher.onChange((_first, batch) => batches.push([...(batch?.paths.values() ?? [])]));
-        try {
-            watcher.handleEvent(path.join(hqRoot, "notes", ".draft.md.123.abc.tmp"), "unlink");
-            watcher.handleEvent(path.join(hqRoot, "notes", "kept.md"), "unlink");
-            clock.advance(25);
-            expect(batches).toEqual([["notes/kept.md"]]);
-            // The dropped path never paid for a delete-snapshot capture.
-            expect(capture).toHaveBeenCalledTimes(1);
-            expect(capture).toHaveBeenCalledWith("notes/kept.md", "unlink");
-            expect(watcher.untrackedDeletesDropped()).toBe(1);
-            // Neither path leaves an epoch behind: the kept unlink was captured
-            // synchronously (nothing in flight to invalidate) and the dropped one
-            // never had a capture at all.
-            expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
-        }
-        finally {
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("leaves no delete-snapshot epoch behind for an atomic write cancelled inside its own window", () => {
-        // Every agency writer saves through `.<name>.<pid>.<random>.tmp` and
-        // renames it into place, so the watcher sees an `add` and then an
-        // `unlink` of a name it will never see again. 370 of those a minute on
-        // the controller: if each one left a key in a per-path map, the map
-        // would grow by half a million randomised paths a day.
-        const hqRoot = makeRoot();
-        const clock = new FakeClock();
-        const queue = vi.fn(async () => []);
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            queueLocalDeleteSnapshots: queue,
-            isUntrackedDelete: (relativePath) => relativePath.endsWith(".tmp"),
-        });
-        const changed = vi.fn();
-        watcher.onChange(changed);
-        try {
-            for (let i = 0; i < 250; i++) {
-                const temp = path.join(hqRoot, "workspace", "agency", `.ledger.json.${i}.${(i * 7919).toString(36)}.tmp`);
-                watcher.handleEvent(temp, "add");
-                watcher.handleEvent(temp, "unlink");
-            }
-            clock.advance(1_000);
-            expect(queue).not.toHaveBeenCalled();
-            expect(changed).not.toHaveBeenCalled();
-            expect(watcher.untrackedDeletesDropped()).toBe(250);
-            expect(watcher.pendingTimerCount()).toBe(0);
-            expect(watcher.censusSizes()).toMatchObject({ deleteSnapshotEpochs: 0, knownKinds: 0 });
-        }
-        finally {
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("resolves a vanished rename to an unlink, purges the path's earlier queued add, and leaves no timer armed", () => {
-        const hqRoot = makeRoot();
-        const clock = new FakeClock();
-        const seam = vi.fn((relativePath) => relativePath.endsWith(".tmp"));
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            isUntrackedDelete: seam,
-        });
-        const changed = vi.fn();
-        watcher.onChange(changed);
-        try {
-            const temp = path.join(hqRoot, "state.json.tmp");
-            fs.writeFileSync(temp, "{}");
-            watcher.handleEvent(temp, "rename"); // exists → add
-            expect(watcher.pendingTimerCount()).toBe(1);
-            fs.rmSync(temp);
-            watcher.handleEvent(temp, "rename"); // ENOENT → unlink → untracked → dropped
-            // The create and the delete cancelled out inside one window. Nothing is
-            // left to emit, so the window closes without waking the push at all.
-            expect(seam).toHaveBeenCalledWith("state.json.tmp");
-            expect(watcher.pendingTimerCount()).toBe(0);
-            clock.advance(1_000);
-            expect(changed).not.toHaveBeenCalled();
-            expect(watcher.untrackedDeletesDropped()).toBe(1);
-        }
-        finally {
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("keeps journaled unlinks and never consults the seam for live files or directory deletes", () => {
-        const hqRoot = makeRoot();
-        const clock = new FakeClock();
-        const seam = vi.fn(() => false);
-        const capture = vi.fn(() => []);
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            captureLocalDeleteSnapshots: capture,
-            isUntrackedDelete: seam,
-        });
-        const batches = [];
-        watcher.onChange((_first, batch) => batches.push(batch?.paths ?? new Map()));
-        try {
-            const live = path.join(hqRoot, "live.md");
-            fs.writeFileSync(live, "x");
-            watcher.handleEvent(live, "add");
-            // A directory with no row of its own may still cover journaled
-            // descendants; only the capture's prefix scan can tell, so directory
-            // deletes always go through.
-            watcher.handleEvent(path.join(hqRoot, "gone-dir"), "unlinkDir");
-            watcher.handleEvent(path.join(hqRoot, "journaled.md"), "unlink");
-            clock.advance(25);
-            expect(seam).toHaveBeenCalledTimes(1);
-            expect(seam).toHaveBeenCalledWith("journaled.md");
-            expect([...(batches[0]?.values() ?? [])].sort()).toEqual(["gone-dir", "journaled.md", "live.md"]);
-            expect(capture).toHaveBeenCalledWith("gone-dir", "unlinkDir");
-            expect(capture).toHaveBeenCalledWith("journaled.md", "unlink");
-            expect(watcher.untrackedDeletesDropped()).toBe(0);
-        }
-        finally {
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("keeps the unlink when the seam throws", () => {
-        const hqRoot = makeRoot();
-        const clock = new FakeClock();
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            isUntrackedDelete: () => {
-                throw new Error("journal unavailable");
-            },
-        });
-        const batches = [];
-        watcher.onChange((_first, batch) => batches.push([...(batch?.paths.values() ?? [])]));
-        const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
-        try {
-            expect(() => watcher.handleEvent(path.join(hqRoot, "maybe.md"), "unlink")).not.toThrow();
-            clock.advance(25);
-            // Dropping is an optimisation; keeping the event is the safe default.
-            expect(batches).toEqual([["maybe.md"]]);
-            expect(watcher.untrackedDeletesDropped()).toBe(0);
-        }
-        finally {
-            consoleError.mockRestore();
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("a dropped unlink supersedes an in-flight queued capture for the same path", async () => {
-        const hqRoot = makeRoot();
-        const clock = new FakeClock();
-        let untracked = false;
-        let resolveCapture;
-        let observedCurrent;
-        const watcher = new TreeWatcher({
-            hqRoot,
-            clock,
-            debounceMs: 25,
-            pathFilter: () => true,
-            isUntrackedDelete: () => untracked,
-            queueLocalDeleteSnapshots: async (_relative, _kind, isCurrent) => {
-                await new Promise((resolve) => { resolveCapture = resolve; });
-                observedCurrent = isCurrent();
-                return [];
-            },
-        });
-        try {
-            const target = path.join(hqRoot, "flip.md");
-            watcher.handleEvent(target, "unlink"); // journal view cold: kept, capture queued
-            await Promise.resolve();
-            untracked = true;
-            watcher.handleEvent(target, "unlink"); // journal view warm: no row → dropped
-            resolveCapture();
-            await Promise.resolve();
-            // The queued capture must not bind a revision for a path the watcher
-            // has since discarded.
-            expect(observedCurrent).toBe(false);
-            expect(watcher.pendingTimerCount()).toBe(0);
-            expect(watcher.untrackedDeletesDropped()).toBe(1);
-        }
-        finally {
-            watcher.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-});
-// ---------------------------------------------------------------------------
-// Event-pass debounce configuration (HQ_SYNC_EVENT_DEBOUNCE_MS / _MAX_WAIT_MS)
-// ---------------------------------------------------------------------------
-describe("resolveEventDebounceConfig", () => {
-    const ENV_KEYS = [
-        EVENT_DEBOUNCE_MS_ENV,
-        EVENT_MAX_WAIT_MS_ENV,
-        EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV,
-        EVENT_SMALL_BATCH_MAX_PATHS_ENV,
-        EVENT_SMALL_BATCH_MAX_BYTES_ENV,
-    ];
-    let saved;
-    beforeEach(() => {
-        saved = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
-        for (const k of ENV_KEYS)
-            delete process.env[k];
-    });
-    afterEach(() => {
-        for (const k of ENV_KEYS) {
-            if (saved[k] === undefined)
-                delete process.env[k];
-            else
-                process.env[k] = saved[k];
-        }
-    });
-    it("defaults to a 60s quiet window, a 60s small-batch window, and a 120s max-wait ceiling", () => {
-        expect(DEFAULT_EVENT_DEBOUNCE_MS).toBe(60_000);
-        expect(DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS).toBe(60_000);
-        expect(DEFAULT_EVENT_MAX_WAIT_MS).toBe(120_000);
-        expect(resolveEventDebounceConfig({})).toEqual({
-            debounceMs: 60_000,
-            maxWaitMs: 120_000,
-            smallBatchDebounceMs: 60_000,
-            smallBatchMaxPaths: DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS,
-            smallBatchMaxBytes: DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES,
-        });
-        expect(resolveEventDebounceConfig()).toEqual({
-            debounceMs: DEFAULT_EVENT_DEBOUNCE_MS,
-            maxWaitMs: DEFAULT_EVENT_MAX_WAIT_MS,
-            smallBatchDebounceMs: DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS,
-            smallBatchMaxPaths: DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS,
-            smallBatchMaxBytes: DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES,
-        });
-    });
-    it("honors env overrides", () => {
-        process.env[EVENT_DEBOUNCE_MS_ENV] = "5000";
-        process.env[EVENT_MAX_WAIT_MS_ENV] = "30000";
-        process.env[EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV] = "2000";
-        process.env[EVENT_SMALL_BATCH_MAX_PATHS_ENV] = "6";
-        process.env[EVENT_SMALL_BATCH_MAX_BYTES_ENV] = "4096";
-        expect(resolveEventDebounceConfig()).toEqual({
-            debounceMs: 5000,
-            maxWaitMs: 30_000,
-            smallBatchDebounceMs: 2000,
-            smallBatchMaxPaths: 6,
-            smallBatchMaxBytes: 4096,
-        });
-    });
-    it("lets HQ_SYNC_EVENT_DEBOUNCE_MS override the quiet window independently", () => {
-        expect(resolveEventDebounceConfig({
-            [EVENT_DEBOUNCE_MS_ENV]: "90000",
-        })).toEqual({
-            debounceMs: 90_000,
-            maxWaitMs: 120_000,
-            smallBatchDebounceMs: 60_000,
-            smallBatchMaxPaths: DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS,
-            smallBatchMaxBytes: DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES,
-        });
-    });
-    it("lets HQ_SYNC_EVENT_SMALL_BATCH_DEBOUNCE_MS override the small-batch window independently", () => {
-        expect(resolveEventDebounceConfig({
-            [EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV]: "10000",
-        })).toEqual({
-            debounceMs: 60_000,
-            maxWaitMs: 120_000,
-            smallBatchDebounceMs: 10_000,
-            smallBatchMaxPaths: DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS,
-            smallBatchMaxBytes: DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES,
-        });
-    });
-    it("clamps a small-batch override above the quiet window down to the quiet window", () => {
-        expect(resolveEventDebounceConfig({
-            [EVENT_DEBOUNCE_MS_ENV]: "30000",
-            [EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV]: "50000",
-        })).toEqual({
-            debounceMs: 30_000,
-            maxWaitMs: 120_000,
-            smallBatchDebounceMs: 30_000,
-            smallBatchMaxPaths: DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS,
-            smallBatchMaxBytes: DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES,
-        });
-    });
-    it("treats 0, negative, and non-numeric values as unset (defaults)", () => {
-        for (const bad of ["0", "-5", "banana", ""]) {
-            process.env[EVENT_DEBOUNCE_MS_ENV] = bad;
-            process.env[EVENT_MAX_WAIT_MS_ENV] = bad;
-            expect(resolveEventDebounceConfig()).toEqual({
-                debounceMs: DEFAULT_EVENT_DEBOUNCE_MS,
-                maxWaitMs: DEFAULT_EVENT_MAX_WAIT_MS,
-                smallBatchDebounceMs: DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS,
-                smallBatchMaxPaths: DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS,
-                smallBatchMaxBytes: DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES,
-            });
-        }
-    });
-    it("floors the max-wait ceiling at the quiet window", () => {
-        process.env[EVENT_DEBOUNCE_MS_ENV] = "60000";
-        process.env[EVENT_MAX_WAIT_MS_ENV] = "10000";
-        expect(resolveEventDebounceConfig()).toEqual({
-            debounceMs: 60_000,
-            maxWaitMs: 60_000,
-            smallBatchDebounceMs: DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS,
-            smallBatchMaxPaths: DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS,
-            smallBatchMaxBytes: DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES,
-        });
-    });
-    it("accepts an injected env record without touching process.env", () => {
-        expect(resolveEventDebounceConfig({
-            [EVENT_DEBOUNCE_MS_ENV]: "1000",
-            [EVENT_MAX_WAIT_MS_ENV]: "2000",
-            [EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV]: "750",
-            [EVENT_SMALL_BATCH_MAX_PATHS_ENV]: "4",
-            [EVENT_SMALL_BATCH_MAX_BYTES_ENV]: "1024",
-        })).toEqual({
-            debounceMs: 1000,
-            maxWaitMs: 2000,
-            smallBatchDebounceMs: 750,
-            smallBatchMaxPaths: 4,
-            smallBatchMaxBytes: 1024,
-        });
-    });
-});
-describe("resolvePublishMinIntervalMs", () => {
-    it("defaults to 60 seconds, accepts zero to disable coalescing, and rejects invalid values", () => {
-        expect(resolvePublishMinIntervalMs({})).toBe(DEFAULT_PUBLISH_MIN_INTERVAL_MS);
-        expect(resolvePublishMinIntervalMs({ [PUBLISH_MIN_INTERVAL_MS_ENV]: "0" })).toBe(0);
-        expect(resolvePublishMinIntervalMs({ [PUBLISH_MIN_INTERVAL_MS_ENV]: "invalid" })).toBe(DEFAULT_PUBLISH_MIN_INTERVAL_MS);
-        expect(resolvePublishMinIntervalMs({ [PUBLISH_MIN_INTERVAL_MS_ENV]: "-1" })).toBe(DEFAULT_PUBLISH_MIN_INTERVAL_MS);
-    });
-    it("uses the environment override in milliseconds", () => {
-        expect(resolvePublishMinIntervalMs({ [PUBLISH_MIN_INTERVAL_MS_ENV]: "1234.9" })).toBe(1234);
-    });
-});
-/**
- * Linux folder-only backend.
- *
- * On Linux there is no recursive `fs.watch`, and chokidar's answer was one
- * inotify watch per directory PLUS one per file. On a real HQ root that was
- * ~74k directories and ~878k files — ~950k watches, ~16 KB each — while the
- * safety cap counted only the directories and so never fired. A directory
- * watch already reports content changes to the files directly inside it, so
- * the per-file watches bought nothing. These tests pin the replacement: the
- * scoped native backend driven with `recursiveWatches: false`, taking exactly
- * one shallow watch per in-scope directory and none per file.
- */
-describe("Linux folder-only native backend (startScopedRecursiveWatch, recursiveWatches: false)", () => {
-    let root;
-    const isLinux = process.platform === "linux";
-    beforeEach(() => {
-        root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "folder-watch-")));
-    });
-    afterEach(() => {
-        fs.rmSync(root, { recursive: true, force: true });
-    });
-    /** In-scope tree: root, docs, docs/deep, notes — 4 dirs, 8 files, plus an excluded node_modules. */
-    function seedTree() {
-        const dirs = [
-            path.join(root, "docs"),
-            path.join(root, "docs", "deep"),
-            path.join(root, "notes"),
-        ];
-        for (const d of dirs)
-            fs.mkdirSync(d, { recursive: true });
-        const files = [];
-        for (const d of [root, ...dirs]) {
-            for (const n of ["one.md", "two.md"]) {
-                const f = path.join(d, n);
-                fs.writeFileSync(f, "x");
-                files.push(f);
-            }
-        }
-        const nm = path.join(root, "docs", "node_modules", "pkg");
-        fs.mkdirSync(nm, { recursive: true });
-        fs.writeFileSync(path.join(nm, "index.js"), "1");
-        return { inScopeDirs: [root, ...dirs], files };
-    }
-    /** Count this process's live inotify watch descriptors (Linux only). */
-    function inotifyWatchDescriptors() {
-        let total = 0;
-        for (const fd of fs.readdirSync("/proc/self/fdinfo")) {
-            try {
-                const info = fs.readFileSync(path.join("/proc/self/fdinfo", fd), "utf8");
-                total += (info.match(/^inotify wd:/gm) ?? []).length;
-            }
-            catch {
-                /* fd closed between readdir and read */
-            }
-        }
-        return total;
-    }
-    async function waitFor(check, ms = 4000) {
-        const deadline = Date.now() + ms;
-        while (Date.now() < deadline) {
-            if (check())
-                return;
-            await new Promise((r) => setTimeout(r, 25));
-        }
-        expect(check()).toBe(true);
-    }
-    function waitForReady(backend) {
-        return new Promise((resolve) => {
-            if (backend.onReady)
-                backend.onReady(resolve);
-            else
-                resolve();
-        });
-    }
-    function startFolderOnly(opts = {}) {
-        const shouldEmit = opts.includeAll
-            ? () => true
-            : createWatchPathFilter(root, false);
-        return startScopedRecursiveWatch(root, shouldEmit, opts.onEvent ?? (() => { }), opts.onError ?? ((err) => { throw err; }), undefined, {
-            recursiveWatches: false,
-            maxWatchedPaths: opts.maxWatchedPaths,
-            onWatchBudgetExceeded: opts.onWatchBudgetExceeded,
-            listChildDirs: opts.listChildDirs,
-            watchDirectory: opts.watchDirectory,
-            directoryIdentity: opts.directoryIdentity,
-        });
-    }
-    it("takes exactly one watch per in-scope directory and none per file", async () => {
-        const { inScopeDirs } = seedTree();
-        const before = isLinux ? inotifyWatchDescriptors() : 0;
-        const backend = startFolderOnly();
-        try {
-            await waitForReady(backend);
-            expect(backend.mode).toBe("native");
-            expect(backend.attachFailures).toBe(0);
-            // 4 in-scope directories; 8 in-scope files and an excluded subtree add nothing.
-            expect(backend.watchedPathCount()).toBe(inScopeDirs.length);
-            if (isLinux) {
-                // Measured immediately, before any drain window: a whole-tree
-                // bootstrap watch would show up here as extra descriptors.
-                expect(inotifyWatchDescriptors() - before).toBe(inScopeDirs.length);
-            }
-        }
-        finally {
-            backend.close();
-        }
-        if (isLinux)
-            expect(inotifyWatchDescriptors()).toBe(before);
-    });
-    it("reports a content change to a file inside a watched folder without a file watch", async () => {
-        const { files } = seedTree();
-        const seen = [];
-        const backend = startFolderOnly({ onEvent: (p) => seen.push(p) });
-        try {
-            await new Promise((r) => setTimeout(r, 150));
-            const target = files.find((f) => f.includes(path.join("docs", "deep")));
-            fs.appendFileSync(target, "more");
-            await waitFor(() => seen.includes(target));
-        }
-        finally {
-            backend.close();
-        }
-    });
-    it("attaches a folder created after start, then reports files written inside it", async () => {
-        seedTree();
-        const seen = [];
-        const backend = startFolderOnly({ onEvent: (p) => seen.push(p) });
-        try {
-            await new Promise((r) => setTimeout(r, 150));
-            const before = backend.watchedPathCount();
-            const created = path.join(root, "notes", "later");
-            fs.mkdirSync(created);
-            await waitFor(() => backend.watchedPathCount() === before + 1);
-            const file = path.join(created, "fresh.md");
-            fs.writeFileSync(file, "hello");
-            await waitFor(() => seen.includes(file));
-        }
-        finally {
-            backend.close();
-        }
-    });
-    it("scans a folder that already holds files when it attaches, so nothing arrives silently", async () => {
-        seedTree();
-        const seen = [];
-        const backend = startFolderOnly({ onEvent: (p) => seen.push(p) });
-        try {
-            await new Promise((r) => setTimeout(r, 150));
-            // Build the subtree OUTSIDE the watched root, then move it in with one
-            // rename: the folder watch only ever sees the directory appear, never
-            // the files inside it. Chokidar walked such a directory on addDir;
-            // the folder-only backend must do the same.
-            const staging = fs.mkdtempSync(path.join(os.tmpdir(), "folder-watch-stage-"));
-            fs.mkdirSync(path.join(staging, "inner"));
-            fs.writeFileSync(path.join(staging, "a.md"), "a");
-            fs.writeFileSync(path.join(staging, "inner", "b.md"), "b");
-            const dest = path.join(root, "docs", "moved");
-            fs.renameSync(staging, dest);
-            await waitFor(() => seen.includes(path.join(dest, "a.md")) &&
-                seen.includes(path.join(dest, "inner", "b.md")));
-            expect(backend.watchedPathCount()).toBe(4 + 2);
-        }
-        finally {
-            backend.close();
-        }
-    });
-    it("re-attaches when a watched folder is swapped for a new one at the same path (Linux inode change)", async () => {
-        seedTree();
-        const seen = [];
-        const backend = startFolderOnly({ onEvent: (p) => seen.push(p) });
-        try {
-            await new Promise((r) => setTimeout(r, 150));
-            expect(backend.watchedPathCount()).toBe(4);
-            // Atomic swap: the old `docs` moves out of the tree and a replacement
-            // (built outside, so its creation is never observed) lands at the same
-            // pathname — both renames complete before any watch callback runs. On
-            // Linux the old handle follows the moved-away INODE, so without an
-            // identity check the backend would keep it, consider `docs` covered,
-            // and never hear another event from the replacement subtree.
-            const staging = fs.mkdtempSync(path.join(os.tmpdir(), "folder-watch-swap-"));
-            fs.mkdirSync(path.join(staging, "deep"));
-            fs.writeFileSync(path.join(staging, "a.md"), "a");
-            fs.writeFileSync(path.join(staging, "deep", "b.md"), "b");
-            const parked = fs.mkdtempSync(path.join(os.tmpdir(), "folder-watch-parked-"));
-            const docs = path.join(root, "docs");
-            fs.renameSync(docs, path.join(parked, "docs"));
-            fs.renameSync(staging, docs);
-            // The replacement's existing files are announced, exactly like a
-            // populated folder moved in from outside.
-            await waitFor(() => seen.includes(path.join(docs, "a.md")) &&
-                seen.includes(path.join(docs, "deep", "b.md")));
-            // A later write inside the replacement is reported: the new inode is
-            // watched, and the stale handles (docs + docs/deep) are gone — still
-            // root, docs, docs/deep, notes.
-            const after = path.join(docs, "deep", "after.md");
-            fs.writeFileSync(after, "after");
-            await waitFor(() => seen.includes(after));
-            expect(backend.watchedPathCount()).toBe(4);
-            // The moved-away tree must not keep reporting under its OLD path.
-            seen.length = 0;
-            fs.writeFileSync(path.join(parked, "docs", "stale.md"), "stale");
-            await new Promise((r) => setTimeout(r, 300));
-            expect(seen.filter((p) => p.startsWith(docs + path.sep))).toEqual([]);
-            fs.rmSync(parked, { recursive: true, force: true });
-        }
-        finally {
-            backend.close();
-        }
-    });
-    it("probeCoverage reports root-missing when the HQ root is gone", () => {
-        seedTree();
-        const backend = startFolderOnly();
-        try {
-            expect(backend.probeCoverage()).toEqual({ ok: true });
-            fs.rmSync(root, { recursive: true, force: true });
-            const probe = backend.probeCoverage();
-            expect(probe.ok).toBe(false);
-            if (!probe.ok)
-                expect(probe.reason).toBe("root-missing");
-        }
-        finally {
-            backend.close();
-        }
-    });
-    it("covers a folder created after its parent was listed but before the plan attached (walk/attach race)", async () => {
-        seedTree();
-        const seen = [];
-        const late = path.join(root, "notes", "late");
-        const watchEvents = new Map();
-        // The plan walk lists `notes`, then — before any watch existed on the
-        // old code path — `notes/late` appears. The snapshot plan never holds
-        // it, and a shallow watch on `notes` attached only after the whole walk
-        // would never have seen it appear. On a real HQ root the walk takes
-        // seconds; agents create directories the whole time.
-        const listChildDirs = (dir) => {
-            const children = fs
-                .readdirSync(dir, { withFileTypes: true })
-                .filter((e) => e.isDirectory())
-                .map((e) => path.join(dir, e.name));
-            if (dir === path.join(root, "notes"))
-                fs.mkdirSync(late);
-            return children;
-        };
-        const backend = startFolderOnly({
-            onEvent: (p) => seen.push(p),
-            listChildDirs,
-            watchDirectory: ((dir, _options, listener) => {
-                watchEvents.set(path.resolve(String(dir)), listener);
-                const handle = new EventEmitter();
-                handle.close = () => { };
-                return handle;
-            }),
-        });
-        try {
-            await waitForReady(backend);
-            watchEvents.get(path.join(root, "notes"))?.("rename", "late");
-            // root, docs, docs/deep, notes — plus `late`, picked up by the live
-            // watch on `notes` rather than by the plan.
-            await waitFor(() => backend.watchedPathCount() === 5);
-            const file = path.join(late, "inside.md");
-            fs.writeFileSync(file, "x");
-            watchEvents.get(late)?.("rename", "inside.md");
-            await waitFor(() => seen.includes(file));
-        }
-        finally {
-            backend.close();
-        }
-    });
-    it("releases every watch beneath a deleted folder", async () => {
-        seedTree();
-        const backend = startFolderOnly();
-        try {
-            await new Promise((r) => setTimeout(r, 150));
-            expect(backend.watchedPathCount()).toBe(4);
-            fs.rmSync(path.join(root, "docs"), { recursive: true, force: true });
-            // docs and docs/deep both go; root and notes remain.
-            await waitFor(() => backend.watchedPathCount() === 2);
-            if (isLinux) {
-                await waitFor(() => inotifyWatchDescriptors() <= 2);
-            }
-        }
-        finally {
-            backend.close();
-        }
-    });
-    it("stops attaching at the budget and reports the exhaustion exactly once, counting real watches", async () => {
-        seedTree();
-        const exceeded = vi.fn();
-        const backend = startFolderOnly({
-            maxWatchedPaths: 2,
-            onWatchBudgetExceeded: exceeded,
-        });
-        try {
-            await waitForReady(backend);
-            expect(backend.watchedPathCount()).toBe(2);
-            expect(exceeded).toHaveBeenCalledTimes(1);
-            expect(exceeded.mock.calls[0][0]).toMatchObject({
-                watchedPaths: 2,
-                maxWatchedPaths: 2,
-            });
-            expect(typeof exceeded.mock.calls[0][0].offendingPath).toBe("string");
-        }
-        finally {
-            backend.close();
-        }
-    });
-    it("selects the single-root backend on darwin and leaves linux and windows unchanged", () => {
-        expect(selectTreeWatchBackend("linux", false)).toBe("native-shallow");
-        expect(selectTreeWatchBackend("darwin", false)).toBe("native-root");
-        expect(selectTreeWatchBackend("win32", false)).toBe("native-recursive");
-        expect(selectTreeWatchBackend("freebsd", false)).toBe("chokidar");
-        expect(selectTreeWatchBackend("linux", true)).toBe("polling");
-        expect(selectTreeWatchBackend("darwin", true)).toBe("polling");
-    });
-    it("filters native-root callbacks before forwarding them to onEvent", () => {
-        const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "native-root-filter-")));
-        const excludedDir = path.join(dir, "node_modules");
-        fs.mkdirSync(path.join(excludedDir, "pkg"), { recursive: true });
-        fs.writeFileSync(path.join(excludedDir, "pkg", "index.js"), "x");
-        const callback = vi.fn();
-        const handle = new EventEmitter();
-        handle.close = vi.fn();
-        let listener;
-        const backend = startNativeRootWatch(dir, createWatchPathFilter(dir, false), callback, vi.fn(), {
-            watchDirectory: ((root, options, onChange) => {
-                expect(root).toBe(dir);
-                expect(options).toEqual({ recursive: true, persistent: true });
-                listener = onChange;
-                return handle;
-            }),
-        });
-        try {
-            expect(backend.mode).toBe("native-root");
-            expect(backend.watchedPathCount()).toBe(1);
-            listener?.("rename", "companies/indigo/knowledge/note.md");
-            listener?.("rename", "node_modules");
-            listener?.("change", "workspace/node_modules/pkg/index.js");
-            expect(callback).toHaveBeenCalledTimes(1);
-            expect(callback).toHaveBeenCalledWith(path.join(dir, "companies/indigo/knowledge/note.md"), "rename");
-        }
-        finally {
-            backend.close();
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("switches a native-root watcher to polling after a systemic watch error", async () => {
-        const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "native-root-fallback-")));
-        const closed = [];
-        const backend = new TreeWatcher({
-            hqRoot: dir,
-            debounceMs: 50,
-            backendFactory: ({ forcePolling, onError }) => {
-                if (forcePolling) {
-                    return {
-                        close: () => closed.push("polling"),
-                        mode: "polling",
-                        needsKnownKinds: false,
-                        watchedPathCount: () => 1,
-                    };
-                }
-                const handle = new EventEmitter();
-                handle.close = vi.fn(() => closed.push("native-root"));
-                const native = startNativeRootWatch(dir, () => true, vi.fn(), onError, {
-                    watchDirectory: (() => {
-                        queueMicrotask(() => handle.emit("error", Object.assign(new Error("too many open files"), { code: "EMFILE" })));
-                        return handle;
-                    }),
-                });
-                return native;
-            },
-        });
-        const log = vi.spyOn(console, "error").mockImplementation(() => { });
-        backend.start();
-        try {
-            await new Promise((resolve) => setTimeout(resolve, 0));
-            expect(backend.watchMode()).toBe("polling");
-            expect(backend.watchedPathCount()).toBe(1);
-            expect(closed).toContain("native-root");
-        }
-        finally {
-            backend.dispose();
-            log.mockRestore();
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("TreeWatcher on linux starts natively with one watch per directory (no chokidar, no file watches)", async () => {
-        if (!isLinux)
-            return;
-        const { inScopeDirs } = seedTree();
-        const before = inotifyWatchDescriptors();
-        const w = new TreeWatcher({ hqRoot: root, debounceMs: 50 });
-        const changed = vi.fn();
-        w.onChange(changed);
-        w.start();
-        try {
-            await new Promise((resolve) => w.onReady(resolve));
-            expect(w.watchMode()).toBe("native");
-            expect(inotifyWatchDescriptors() - before).toBe(inScopeDirs.length);
-            fs.writeFileSync(path.join(root, "notes", "new.md"), "hi");
-            await waitFor(() => changed.mock.calls.length > 0);
-        }
-        finally {
-            w.dispose();
-        }
-    });
-});
-//# sourceMappingURL=watcher.test.js.map