@indigoai-us/hq-cloud 6.15.64 → 6.15.66

package/dist/bin/sync-runner.test.js

@@ -14,7 +14,7 @@ import { runRunner, runRunnerWithLoop, resolveDeletePolicy, resolveSkipPersonal,
 import { PresignObjectIO, S3SdkObjectIO } from "../object-io.js";
 import { setBandwidthGovernorForTesting } from "../bandwidth.js";
 import { FakeClock, TreeWatcher, } from "../watcher.js";
-import { adaptivePollMs, advanceMonotonicDeadline, DEFAULT_EVENT_BATCH_LIMIT, DEFAULT_FULL_RECONCILE_MS, EVENT_BATCH_LIMIT_ENV, FULL_RECONCILE_MS_ENV, journalEntriesForWatcherDelete, resolveEventBatchLimit, resolveFullReconcileMs, shouldQuarantineWatcherDeleteIntents, WATCHER_REDISCOVERY_RETRY_MS, WATCHER_REDISCOVERY_RETRY_MAX_MS, } from "./sync-runner-watch-loop.js";
+import { adaptivePollMs, advanceMonotonicDeadline, DEFAULT_EVENT_BATCH_LIMIT, DEFAULT_FAST_LANE_MAX_BYTES, DEFAULT_FAST_LANE_MAX_FILE_BYTES, DEFAULT_FAST_LANE_MAX_FILES, DEFAULT_FULL_RECONCILE_MS, EVENT_BATCH_LIMIT_ENV, FAST_LANE_MAX_BYTES_ENV, FAST_LANE_MAX_FILES_ENV, FULL_RECONCILE_MS_ENV, isFastLocalBatch, isFastReceiverBatch, partitionLocalBatch, journalEntriesForWatcherDelete, resolveEventBatchLimit, resolveFullReconcileMs, shouldQuarantineWatcherDeleteIntents, WATCHER_REDISCOVERY_RETRY_MS, WATCHER_REDISCOVERY_RETRY_MAX_MS, } from "./sync-runner-watch-loop.js";
 import { PERSONAL_VAULT_JOURNAL_SLUG, readJournal, writeJournal, } from "../journal.js";
 import { HQ_CLOUD_VERSION } from "../version.js";
 import { lockPathFor, OPERATION_LOCKED_EXIT } from "../operation-lock.js";
@@ -4340,6 +4340,63 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         triggerShutdown();
         await loop;
     });
+    it("pushes a file created before watcher ready through the warm-up catch-up", async () => {
+        const watcher = makeBatchWatcherStub();
+        let markReady = () => { };
+        watcher.onReady = (listener) => {
+            markReady = listener;
+            return () => { };
+        };
+        watcher.collectWarmupCatchup = vi.fn(() => ({
+            batch: {
+                paths: new Map([[
+                        "/tmp/hq/companies/indigo/knowledge/created-during-warmup.md",
+                        "companies/indigo/knowledge/created-during-warmup.md",
+                    ]]),
+                changes: new Map([[
+                        "/tmp/hq/companies/indigo/knowledge/created-during-warmup.md",
+                        { kind: "add" },
+                    ]]),
+            },
+            scannedPaths: 1,
+        }));
+        const sleep = makeSteppableSleep();
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
+        let shutdown = () => { };
+        const loop = runRunnerWithLoop([
+            "--company", "indigo", "--watch", "--event-push", "--direction", "pull",
+            "--hq-root", "/tmp/hq", "--poll-remote-ms", "60000",
+        ], {
+            runPass,
+            createWatcher: () => watcher,
+            sleep: sleep.sleep,
+            onShutdownSignal: (handler) => {
+                shutdown = handler;
+                return () => { };
+            },
+        });
+        try {
+            await flushLoopMicrotasks();
+            markReady();
+            await flushLoopMicrotasks();
+            expect(watcher.collectWarmupCatchup).toHaveBeenCalledOnce();
+            expect(runPass.mock.calls.map(([argv]) => argv)).toEqual([
+                ["--company", "indigo", "--direction", "pull", "--hq-root", "/tmp/hq"],
+                [
+                    "--company", "indigo", "--direction", "push",
+                    "--scope-path", "knowledge/created-during-warmup.md", "--hq-root", "/tmp/hq",
+                ],
+                [
+                    "--company", "indigo", "--direction", "pull",
+                    "--scope-path", "knowledge/created-during-warmup.md", "--hq-root", "/tmp/hq",
+                ],
+            ]);
+        }
+        finally {
+            shutdown();
+            await loop;
+        }
+    });
     it("keeps every event surface off until a result proves maintenance completed", async () => {
         const watcher = makeWatcherStub();
         const sleep = makeSteppableSleep();
@@ -4592,6 +4649,632 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         triggerShutdown();
         await loop;
     });
+    it("fast lane: a small watcher batch dispatches during a slow bulk pass", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-watch-"));
+        const relativePath = "companies/indigo/realtime.md";
+        const absolutePath = path.join(hqRoot, relativePath);
+        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+        fs.writeFileSync(absolutePath, "tiny realtime edit");
+        const watcher = makeBatchWatcherStub();
+        let triggerShutdown = () => { };
+        let releaseBulk = () => { };
+        const bulkGate = new Promise((resolve) => { releaseBulk = resolve; });
+        const order = [];
+        let fullPasses = 0;
+        const runPass = vi.fn().mockImplementation(async (passArgv) => {
+            if (passArgv.includes("--scope-path")) {
+                order.push("fast");
+                return completedPassOutcome();
+            }
+            fullPasses += 1;
+            if (fullPasses === 2) {
+                order.push("bulk");
+                await bulkGate;
+            }
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--direction", "both", "--hq-root", hqRoot], {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        watcher.emit(); // starts the second, deliberately blocked full pass
+        await flushLoopMicrotasks();
+        expect(order).toEqual(["bulk"]);
+        watcher.emit(relativePath, { paths: new Map([[absolutePath, relativePath]]) });
+        await flushLoopMicrotasks(30);
+        // Regression: origin/main leaves this as ["bulk"] until releaseBulk().
+        expect(order).toEqual(["bulk", "fast", "fast"]);
+        releaseBulk();
+        await flushLoopMicrotasks();
+        triggerShutdown();
+        await loop;
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("fast lane: peels a tiny watcher path from mixed multi-megabyte residue", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-mixed-watch-"));
+        const tinyRel = "companies/indigo/realtime.md";
+        const tiny = path.join(hqRoot, tinyRel);
+        const bulk = [0, 1, 2].map((index) => path.join(hqRoot, `companies/indigo/session-${index}.log`));
+        fs.mkdirSync(path.dirname(tiny), { recursive: true });
+        fs.writeFileSync(tiny, "tiny realtime edit");
+        for (const file of bulk)
+            fs.writeFileSync(file, Buffer.alloc(8 * 1024 * 1024));
+        const watcher = makeBatchWatcherStub();
+        let triggerShutdown = () => { };
+        let releaseBulk = () => { };
+        const bulkGate = new Promise((resolve) => { releaseBulk = resolve; });
+        const calls = [];
+        let fullPasses = 0;
+        const runPass = vi.fn().mockImplementation(async (passArgv) => {
+            calls.push(passArgv);
+            if (!passArgv.includes("--scope-path")) {
+                fullPasses += 1;
+                if (fullPasses === 2)
+                    await bulkGate;
+            }
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--direction", "push", "--hq-root", hqRoot], {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        watcher.emit();
+        await flushLoopMicrotasks();
+        watcher.emit(tinyRel, {
+            paths: new Map([
+                [tiny, tinyRel],
+                ...bulk.map((file, index) => [file, `companies/indigo/session-${index}.log`]),
+            ]),
+        });
+        await flushLoopMicrotasks(30);
+        // origin/main failure: expected a scoped tiny path while the bulk pass is
+        // held, but #408 kept all four paths in the slow lane.
+        expect(calls.filter((argv) => argv.includes("--scope-path"))).toHaveLength(1);
+        expect(calls.flat().join(" ")).toContain("realtime.md");
+        releaseBulk();
+        await flushLoopMicrotasks(30);
+        expect(calls.filter((argv) => argv.includes("--scope-path"))).toHaveLength(2);
+        expect(calls.flat().join(" ")).toContain("session-0.log");
+        triggerShutdown();
+        await loop;
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("fast lane: a small receiver pull dispatches during a slow bulk pass", async () => {
+        const watcher = makeWatcherStub();
+        let triggerShutdown = () => { };
+        let receiverSync;
+        let releaseBulk = () => { };
+        const bulkGate = new Promise((resolve) => { releaseBulk = resolve; });
+        const order = [];
+        let fullPasses = 0;
+        const journal = readJournal("acme");
+        journal.files["realtime.md"] = {
+            hash: "sha256:x",
+            size: 16,
+            syncedAt: "2026-08-26T00:00:00.000Z",
+            direction: "down",
+        };
+        writeJournal("acme", journal);
+        const runPass = vi.fn().mockImplementation(async (passArgv) => {
+            if (passArgv.includes("--scope-path")) {
+                order.push("fast-pull");
+                return completedPassOutcome();
+            }
+            fullPasses += 1;
+            if (fullPasses === 2) {
+                order.push("bulk");
+                await bulkGate;
+            }
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq-fast-lane-receiver"], {
+            runPass,
+            createWatcher: () => watcher,
+            createReceiver: ({ syncBatchFn }) => {
+                receiverSync = syncBatchFn;
+                return { connected: true, start: async () => { }, dispose: async () => { } };
+            },
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        watcher.emit();
+        await flushLoopMicrotasks();
+        expect(order).toEqual(["bulk"]);
+        await receiverSync({
+            events: [{
+                    kind: "upsert", relativePath: "companies/acme/realtime.md", contentHash: "sha256:x",
+                    mtime: "2026-08-26T00:00:00.000Z", originDeviceId: "peer", originTenantId: "acme",
+                    sequenceNumber: 1, eventTimestamp: "2026-08-26T00:00:00.000Z",
+                }],
+            signal: new AbortController().signal,
+        });
+        expect(order).toEqual(["bulk", "fast-pull"]);
+        releaseBulk();
+        await flushLoopMicrotasks();
+        triggerShutdown();
+        await loop;
+    });
+    it("fast lane: retains the root lock until an outliving fast pass completes", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-lock-"));
+        const relativePath = "companies/indigo/realtime.md";
+        const absolutePath = path.join(hqRoot, relativePath);
+        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+        fs.writeFileSync(absolutePath, "tiny realtime edit");
+        const watcher = makeBatchWatcherStub();
+        let triggerShutdown = () => { };
+        let releaseBulk = () => { };
+        let releaseFast = () => { };
+        let markFastStarted = () => { };
+        const bulkGate = new Promise((resolve) => { releaseBulk = resolve; });
+        const fastGate = new Promise((resolve) => { releaseFast = resolve; });
+        const fastStarted = new Promise((resolve) => { markFastStarted = resolve; });
+        let fullPasses = 0;
+        const runPass = vi.fn().mockImplementation(async (passArgv) => {
+            if (passArgv.includes("--scope-path")) {
+                markFastStarted();
+                await fastGate;
+                return completedPassOutcome();
+            }
+            fullPasses += 1;
+            if (fullPasses === 2)
+                await bulkGate;
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--direction", "both", "--hq-root", hqRoot], {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        watcher.emit();
+        await flushLoopMicrotasks();
+        watcher.emit(relativePath, { paths: new Map([[absolutePath, relativePath]]) });
+        await fastStarted;
+        releaseBulk();
+        await flushLoopMicrotasks(20);
+        // The slow pass has finished, but its fast bypass still mutates. A second
+        // sync/rescue must not acquire the root operation lock in this interval.
+        expect(fs.existsSync(lockPathFor(hqRoot))).toBe(true);
+        releaseFast();
+        await flushLoopMicrotasks(20);
+        expect(fs.existsSync(lockPathFor(hqRoot))).toBe(false);
+        triggerShutdown();
+        await loop;
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("fast lane: an absent unlinkDir subtree is always slow-lane", () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-unlink-dir-"));
+        const deletedDir = path.join(hqRoot, "companies/indigo/archive");
+        fs.mkdirSync(deletedDir, { recursive: true });
+        fs.rmSync(deletedDir, { recursive: true, force: true });
+        expect(isFastLocalBatch([deletedDir], new Map([[deletedDir, { kind: "unlinkDir" }]]))).toBe(false);
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("fast lane: --skip-personal rejects a selected-out personal watcher batch", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-route-"));
+        const relativePath = "knowledge/private.md";
+        const absolutePath = path.join(hqRoot, relativePath);
+        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+        fs.writeFileSync(absolutePath, "private");
+        const watcher = makeBatchWatcherStub();
+        let triggerShutdown = () => { };
+        let releaseBulk = () => { };
+        const bulkGate = new Promise((resolve) => { releaseBulk = resolve; });
+        let fullPasses = 0;
+        const runPass = vi.fn().mockImplementation(async (passArgv) => {
+            if (passArgv.includes("--scope-path"))
+                return completedPassOutcome();
+            fullPasses += 1;
+            if (fullPasses === 2)
+                await bulkGate;
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--skip-personal", "--watch", "--event-push", "--direction", "both", "--hq-root", hqRoot], {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        watcher.emit();
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        watcher.emit(relativePath, { paths: new Map([[absolutePath, relativePath]]) });
+        await flushLoopMicrotasks(20);
+        expect(runPass.mock.calls).toEqual([]);
+        releaseBulk();
+        await flushLoopMicrotasks();
+        triggerShutdown();
+        await loop;
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("fast lane: signals the V2 scheduler for an immediate watcher dispatch", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-signal-"));
+        const relativePath = "companies/indigo/realtime.md";
+        const absolutePath = path.join(hqRoot, relativePath);
+        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+        fs.writeFileSync(absolutePath, "tiny realtime edit");
+        const watcher = makeBatchWatcherStub();
+        const scheduler = {
+            signal: vi.fn(),
+            checkHighWater: vi.fn().mockResolvedValue(undefined),
+            dispose: vi.fn().mockResolvedValue(undefined),
+        };
+        let triggerShutdown = () => { };
+        let releaseBulk = () => { };
+        const bulkGate = new Promise((resolve) => { releaseBulk = resolve; });
+        let fullPasses = 0;
+        const runPass = vi.fn().mockImplementation(async (passArgv) => {
+            if (passArgv.includes("--scope-path"))
+                return completedPassOutcome();
+            fullPasses += 1;
+            if (fullPasses === 2)
+                await bulkGate;
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--direction", "both", "--hq-root", hqRoot], {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            startRealtimeScheduler: async () => scheduler,
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks(20);
+        watcher.emit();
+        await flushLoopMicrotasks();
+        scheduler.signal.mockClear();
+        watcher.emit(relativePath, { paths: new Map([[absolutePath, relativePath]]) });
+        await flushLoopMicrotasks(20);
+        expect(scheduler.signal).toHaveBeenCalledWith("watcher");
+        releaseBulk();
+        await flushLoopMicrotasks();
+        triggerShutdown();
+        await loop;
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("fast lane: applies the receiver cap once across all eligible routes", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-receiver-cap-"));
+        const watcher = makeWatcherStub();
+        let receiverSync;
+        let triggerShutdown = () => { };
+        let releaseBulk = () => { };
+        const bulkGate = new Promise((resolve) => { releaseBulk = resolve; });
+        let fullPasses = 0;
+        const runPass = vi.fn().mockImplementation(async (passArgv) => {
+            if (passArgv.includes("--scope-path"))
+                return completedPassOutcome();
+            fullPasses += 1;
+            if (fullPasses === 2)
+                await bulkGate;
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", hqRoot], {
+            runPass,
+            createWatcher: () => watcher,
+            createReceiver: ({ syncBatchFn }) => {
+                receiverSync = syncBatchFn;
+                return { connected: true, start: async () => { }, dispose: async () => { } };
+            },
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        watcher.emit();
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        const events = [
+            ...Array.from({ length: 17 }, (_, index) => ({
+                kind: "upsert",
+                relativePath: `companies/acme/a-${index}.md`,
+                contentHash: "sha256:x",
+                mtime: "2026-08-26T00:00:00.000Z",
+                originDeviceId: "peer",
+                originTenantId: "acme",
+                sequenceNumber: index,
+                eventTimestamp: "2026-08-26T00:00:00.000Z",
+            })),
+            ...Array.from({ length: 16 }, (_, index) => ({
+                kind: "upsert",
+                relativePath: `companies/beta/b-${index}.md`,
+                contentHash: "sha256:x",
+                mtime: "2026-08-26T00:00:00.000Z",
+                originDeviceId: "peer",
+                originTenantId: "beta",
+                sequenceNumber: index + 17,
+                eventTimestamp: "2026-08-26T00:00:00.000Z",
+            })),
+        ];
+        for (const [slug, prefix, count] of [["acme", "a", 17], ["beta", "b", 16]]) {
+            const journal = readJournal(slug);
+            for (let index = 0; index < count; index++) {
+                journal.files[`${prefix}-${index}.md`] = {
+                    hash: "sha256:x",
+                    size: 16,
+                    syncedAt: "2026-08-26T00:00:00.000Z",
+                    direction: "down",
+                };
+            }
+            writeJournal(slug, journal);
+        }
+        const receiverDrain = receiverSync({
+            events,
+            signal: new AbortController().signal,
+        });
+        await flushLoopMicrotasks(20);
+        // The 33-event mixed delivery peels its first 32 bounded paths into the
+        // fast lane (17 acme + 15 beta); the final beta event remains slow.
+        expect(runPass).toHaveBeenCalledTimes(2);
+        expect(runPass.mock.calls.flat().join(" ")).toContain("a-16.md");
+        expect(runPass.mock.calls.flat().join(" ")).toContain("b-14.md");
+        releaseBulk();
+        await receiverDrain;
+        triggerShutdown();
+        await loop;
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("fast lane: queues slow work behind a receiver pass that owns the root lock", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-slow-queue-"));
+        const watcher = makeWatcherStub();
+        let receiverSync;
+        let triggerShutdown = () => { };
+        let releaseFast = () => { };
+        let markFastStarted = () => { };
+        const fastGate = new Promise((resolve) => { releaseFast = resolve; });
+        const fastStarted = new Promise((resolve) => { markFastStarted = resolve; });
+        const runPass = vi.fn().mockImplementation(async (passArgv) => {
+            if (passArgv.includes("--scope-path")) {
+                markFastStarted();
+                await fastGate;
+                return completedPassOutcome();
+            }
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--lock-timeout", "0", "--hq-root", hqRoot], {
+            runPass,
+            createWatcher: () => watcher,
+            createReceiver: ({ syncBatchFn }) => {
+                receiverSync = syncBatchFn;
+                return { connected: true, start: async () => { }, dispose: async () => { } };
+            },
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        let loopSettled = false;
+        void loop.then(() => { loopSettled = true; });
+        await flushLoopMicrotasks();
+        const receiverDrain = receiverSync({
+            events: [{
+                    kind: "upsert",
+                    relativePath: "companies/acme/remote.md",
+                    contentHash: "sha256:x",
+                    mtime: "2026-08-26T00:00:00.000Z",
+                    originDeviceId: "peer",
+                    originTenantId: "acme",
+                    sequenceNumber: 1,
+                    eventTimestamp: "2026-08-26T00:00:00.000Z",
+                }],
+            signal: new AbortController().signal,
+        });
+        await fastStarted;
+        // This wake requests a slow reconcile while the receiver owns the lock.
+        watcher.emit();
+        await flushLoopMicrotasks(20);
+        expect(loopSettled).toBe(false);
+        releaseFast();
+        await receiverDrain;
+        triggerShutdown();
+        await loop;
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("fast lane: keeps disjoint journal rows under a 16-path interleave with a bulk pass", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-journal-"));
+        const paths = Array.from({ length: 16 }, (_, index) => {
+            const relativePath = `companies/indigo/realtime-${index}.md`;
+            const absolutePath = path.join(hqRoot, relativePath);
+            fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+            fs.writeFileSync(absolutePath, "tiny realtime edit");
+            return [absolutePath, relativePath];
+        });
+        writeJournal("indigo", { version: "2", lastSync: "", pulls: [], files: {} });
+        const watcher = makeBatchWatcherStub();
+        let triggerShutdown = () => { };
+        let releaseBulk = () => { };
+        const bulkGate = new Promise((resolve) => { releaseBulk = resolve; });
+        let fullPasses = 0;
+        const runPass = vi.fn().mockImplementation(async (passArgv) => {
+            if (passArgv.includes("--scope-path")) {
+                const fast = readJournal("indigo");
+                for (let index = 0; index < paths.length; index++) {
+                    fast.files[`realtime-${index}.md`] = {
+                        hash: `fast-${index}`, size: 1, syncedAt: "", direction: "up",
+                    };
+                }
+                writeJournal("indigo", fast);
+                return completedPassOutcome();
+            }
+            fullPasses += 1;
+            if (fullPasses === 2) {
+                const slow = readJournal("indigo");
+                await bulkGate;
+                for (let index = 0; index < paths.length; index++) {
+                    slow.files[`bulk-${index}.md`] = {
+                        hash: `slow-${index}`, size: 1, syncedAt: "", direction: "up",
+                    };
+                }
+                writeJournal("indigo", slow);
+            }
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--direction", "push", "--hq-root", hqRoot], {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        watcher.emit();
+        await flushLoopMicrotasks();
+        watcher.emit(paths[0][1], { paths: new Map(paths) });
+        await flushLoopMicrotasks(30);
+        expect(Object.keys(readJournal("indigo").files)).toHaveLength(paths.length);
+        releaseBulk();
+        await flushLoopMicrotasks();
+        const journal = readJournal("indigo").files;
+        expect(Object.keys(journal)).toHaveLength(paths.length * 2);
+        for (let index = 0; index < paths.length; index++) {
+            expect(journal[`bulk-${index}.md`]?.hash).toBe(`slow-${index}`);
+            expect(journal[`realtime-${index}.md`]?.hash).toBe(`fast-${index}`);
+        }
+        triggerShutdown();
+        await loop;
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("fast lane: a bulk pass still completes after repeated small watcher batches", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-fairness-"));
+        const watcher = makeBatchWatcherStub();
+        let triggerShutdown = () => { };
+        let releaseBulk = () => { };
+        const bulkGate = new Promise((resolve) => { releaseBulk = resolve; });
+        const completed = [];
+        let fullPasses = 0;
+        const runPass = vi.fn().mockImplementation(async (passArgv) => {
+            if (passArgv.includes("--scope-path")) {
+                completed.push("fast");
+                return completedPassOutcome();
+            }
+            fullPasses += 1;
+            if (fullPasses === 2) {
+                await bulkGate;
+                completed.push("bulk");
+            }
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--direction", "push", "--hq-root", hqRoot], {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        watcher.emit();
+        await flushLoopMicrotasks();
+        for (let index = 0; index < 5; index++) {
+            const relativePath = `companies/indigo/realtime-${index}.md`;
+            const absolutePath = path.join(hqRoot, relativePath);
+            fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+            fs.writeFileSync(absolutePath, "tiny");
+            watcher.emit(relativePath, { paths: new Map([[absolutePath, relativePath]]) });
+        }
+        await flushLoopMicrotasks(60);
+        expect(completed).toEqual(["fast", "fast", "fast", "fast", "fast"]);
+        releaseBulk();
+        await flushLoopMicrotasks();
+        expect(completed).toContain("bulk");
+        triggerShutdown();
+        await loop;
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("fast lane: sends only batches at or below the file and byte limits", () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-limit-"));
+        const small = path.join(hqRoot, "small.md");
+        const boundary = path.join(hqRoot, "boundary.bin");
+        fs.writeFileSync(small, "small");
+        fs.writeFileSync(boundary, Buffer.alloc(DEFAULT_FAST_LANE_MAX_BYTES));
+        expect(isFastLocalBatch([small])).toBe(true);
+        expect(isFastLocalBatch([boundary])).toBe(true);
+        fs.appendFileSync(boundary, "x");
+        expect(isFastLocalBatch([boundary])).toBe(false);
+        expect(isFastReceiverBatch(DEFAULT_FAST_LANE_MAX_FILES)).toBe(true);
+        expect(isFastReceiverBatch(DEFAULT_FAST_LANE_MAX_FILES + 1)).toBe(false);
+        const previousFiles = process.env[FAST_LANE_MAX_FILES_ENV];
+        const previousBytes = process.env[FAST_LANE_MAX_BYTES_ENV];
+        process.env[FAST_LANE_MAX_FILES_ENV] = "1";
+        process.env[FAST_LANE_MAX_BYTES_ENV] = "4";
+        try {
+            expect(isFastLocalBatch([small])).toBe(false);
+            expect(isFastReceiverBatch(2)).toBe(false);
+        }
+        finally {
+            if (previousFiles === undefined)
+                delete process.env[FAST_LANE_MAX_FILES_ENV];
+            else
+                process.env[FAST_LANE_MAX_FILES_ENV] = previousFiles;
+            if (previousBytes === undefined)
+                delete process.env[FAST_LANE_MAX_BYTES_ENV];
+            else
+                process.env[FAST_LANE_MAX_BYTES_ENV] = previousBytes;
+            fs.rmSync(hqRoot, { recursive: true, force: true });
+        }
+    });
+    it("fast lane: keeps a latest large revision in the slow residue and caps 33 small paths", () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-fast-lane-partition-"));
+        const rel = "companies/indigo/revised.md";
+        const absolute = path.join(hqRoot, rel);
+        fs.mkdirSync(path.dirname(absolute), { recursive: true });
+        // The map is the coalescing/affinity boundary: its one value is the latest
+        // revision, so this path cannot appear in both sub-batches.
+        fs.writeFileSync(absolute, Buffer.alloc(DEFAULT_FAST_LANE_MAX_FILE_BYTES + 1));
+        const revised = partitionLocalBatch({ paths: new Map([[absolute, rel]]) });
+        expect(revised.fast).toBeNull();
+        expect(revised.slow?.paths.get(absolute)).toBe(rel);
+        const entries = [];
+        for (let index = 0; index < DEFAULT_FAST_LANE_MAX_FILES + 1; index++) {
+            const file = path.join(hqRoot, `companies/indigo/small-${index}.md`);
+            fs.writeFileSync(file, "x");
+            entries.push([file, `companies/indigo/small-${index}.md`]);
+        }
+        const capped = partitionLocalBatch({ paths: new Map(entries) });
+        expect(capped.fast?.paths.size).toBe(DEFAULT_FAST_LANE_MAX_FILES);
+        // The 33rd path deliberately remains in the slow residue, rather than
+        // creating a second concurrent realtime dispatch.
+        expect(capped.slow?.paths.size).toBe(1);
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
     it("U07: drains the first watcher event after activation without guarded overlap", async () => {
         const watcher = makeWatcherStub();
         let triggerShutdown = () => { };
@@ -5147,6 +5830,8 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         "bare-wake": matched.includes("bare-wake"),
         "batch-over-limit": matched.includes("batch-over-limit"),
         "overflow-routes-unknown": matched.includes("overflow-routes-unknown"),
+        "watcher-warmup-catch-up": matched.includes("watcher-warmup-catch-up"),
+        "watcher-warmup-catch-up-failed": matched.includes("watcher-warmup-catch-up-failed"),
         "scheduled-interval": matched.includes("scheduled-interval"),
     });
     function expectFullReconcileDecision(record, mode, reasons) {