@indigoai-us/hq-cloud 6.15.63 → 6.15.65

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_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, 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();
@@ -4506,10 +4563,10 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         await flushLoopMicrotasks();
         expect(sleepCalls).toEqual([600_000]);
         // The fake 600-second timer remains unresolved. The watcher wake must
-        // nonetheless start the next pass immediately through runGuarded.
+        // nonetheless start its bounded push and configured pull immediately.
         watcher.emit("companies/indigo/board.json");
         await flushLoopMicrotasks();
-        expect(runPass).toHaveBeenCalledTimes(2);
+        expect(runPass).toHaveBeenCalledTimes(3);
         triggerShutdown();
         await loop;
     });
@@ -4592,6 +4649,528 @@ 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: 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 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",
+            })),
+        ];
+        const receiverDrain = receiverSync({
+            events,
+            signal: new AbortController().signal,
+        });
+        await flushLoopMicrotasks(20);
+        expect(runPass).not.toHaveBeenCalled();
+        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("U07: drains the first watcher event after activation without guarded overlap", async () => {
         const watcher = makeWatcherStub();
         let triggerShutdown = () => { };
@@ -4636,8 +5215,9 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         // before the next wait is registered. Its first event must still drain.
         watcher.emit("companies/indigo/pre-registration.md");
         await flushLoopMicrotasks();
-        expect(spans).toHaveLength(2);
+        expect(spans).toHaveLength(3);
         expect(spans[1].enteredAt >= spans[0].exitedAt).toBe(true);
+        expect(spans[2].enteredAt >= spans[1].exitedAt).toBe(true);
         triggerShutdown();
         await loop;
     });
@@ -5146,6 +5726,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) {
@@ -5518,12 +6100,11 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         tick();
         await loop;
     });
-    it("omitted --direction is pull-only (parser default): a scoped tick never pushes", async () => {
+    it("a pending local batch is pushed on a pull-driven watcher tick", async () => {
         const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
-        // No --direction flag → parseArgs defaults the run to pull-only. The drain
-        // must honor that and NOT run a scoped push. Regression: the loop used to
-        // re-parse argv and wrongly default an omitted direction to "both", so a
-        // pull-only watcher would push local edits it should never send.
+        // No --direction flag → parseArgs defaults the cadence run to pull-only.
+        // A watcher batch remains an explicit local-write delivery request: its
+        // bounded push must run before the pull leg can consume the batch.
         const pullOnlyArgv = [
             "--companies",
             "--watch",
@@ -5540,11 +6121,19 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         tick();
         await flushLoopMicrotasks();
         const calls = runPass.mock.calls.map((call) => call[0]);
-        // No scoped push of any kind ran...
-        expect(calls.some((argv) => argv.includes("--direction") &&
-            argv[argv.indexOf("--direction") + 1] === "push")).toBe(false);
-        // ...only the pull leg ran — route-targeted and path-scoped now.
+        // This expectation fails on origin/main: the old pull-only branch runs
+        // only the second argv, so the local write waits for a later reconcile.
         expect(calls).toEqual([
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "push",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
             [
                 "--company",
                 "indigo",
@@ -5560,6 +6149,98 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         tick();
         await loop;
     });
+    it("pushes a local event in the pass immediately after a guarded receiver drain", async () => {
+        const watcher = makeBatchWatcherStub();
+        const sleep = makeSteppableSleep();
+        let shutdown = () => { };
+        let receiverSync = null;
+        let releaseReceiverPull = () => { };
+        const receiverPull = new Promise((resolve) => {
+            releaseReceiverPull = resolve;
+        });
+        const runPass = vi.fn(async (argv) => {
+            if (argv.includes("--company") &&
+                argv.includes("acme") &&
+                argv[argv.indexOf("--direction") + 1] === "pull") {
+                await receiverPull;
+            }
+            return completedPassOutcome();
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
+            runPass,
+            createWatcher: () => watcher,
+            createReceiver: ({ syncBatchFn }) => {
+                receiverSync = syncBatchFn;
+                return { connected: true, start: async () => { }, dispose: async () => { } };
+            },
+            sleep: sleep.sleep,
+            onShutdownSignal: (handler) => {
+                shutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks(12);
+        runPass.mockClear();
+        const receiverDrain = receiverSync({
+            events: [{
+                    kind: "upsert",
+                    relativePath: "companies/acme/remote.md",
+                    contentHash: "sha256:remote",
+                    mtime: "2026-08-26T08:00:00.000Z",
+                    originDeviceId: "peer-device",
+                    originTenantId: "tenant-acme",
+                    sequenceNumber: 1,
+                    eventTimestamp: "2026-08-26T08:00:00.000Z",
+                }],
+            signal: new AbortController().signal,
+        });
+        await flushLoopMicrotasks();
+        watcher.emit("companies/indigo/local.md", {
+            paths: new Map([
+                ["/tmp/hq/companies/indigo/local.md", "companies/indigo/local.md"],
+            ]),
+        });
+        await flushLoopMicrotasks();
+        releaseReceiverPull();
+        await receiverDrain;
+        await flushLoopMicrotasks(16);
+        // On origin/main the next call is an indigo pull, so this asserts the
+        // bounded local upload is not consumed by the receiver/drain cycle.
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual([
+            [
+                "--company",
+                "acme",
+                "--direction",
+                "pull",
+                "--scope-path",
+                "remote.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "push",
+                "--scope-path",
+                "local.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "pull",
+                "--scope-path",
+                "local.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+        ]);
+        shutdown();
+        await loop;
+    });
     it("restores failed scoped push paths so the next tick retries them", async () => {
         const runPass = vi
             .fn()
@@ -6975,15 +7656,14 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         const sleep = makeSteppableSleep();
         let triggerShutdown = () => { };
         const loop = runRunnerWithLoop(
-        // `--direction both` so the push leg (and therefore the publish-after-push
-        // wiring these tests exercise) actually runs. Omitting --direction is a
-        // pull-only run by the parser default, which correctly never pushes.
+        // Most wiring tests use `both`; pull-only watcher tests pin that a local
+        // event still takes its scoped upload and publishes after success.
         [
             "--companies",
             "--watch",
             "--event-push",
             "--direction",
-            "both",
+            opts.direction ?? "both",
             "--hq-root",
             "/tmp/hq",
         ], {
@@ -7136,6 +7816,33 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         shutdown();
         await loop;
     });
+    it("publishes exactly one event per path after a pull-only watcher upload", async () => {
+        const publishBatch = vi.fn();
+        const startEventSync = vi.fn().mockResolvedValue({
+            publishBatch,
+            receiver: { start: async () => { }, dispose: async () => { }, connected: true },
+            ownDeviceId: "dev-test",
+            dispose: vi.fn().mockResolvedValue(undefined),
+        });
+        const { loop, watcher, clock, shutdown } = runLoop({
+            claims: EMAIL_CLAIMS,
+            direction: "pull",
+            startEventSync,
+        });
+        await microtasks();
+        const relativePath = "companies/indigo/local.md";
+        watcher.emit(relativePath, {
+            paths: new Map([[`/tmp/hq/${relativePath}`, relativePath]]),
+        });
+        clock.advance(0);
+        await microtasks();
+        // The old pull-only branch never invoked the scoped push, so it published
+        // zero events here. One accepted local upload must announce its path once.
+        expect(publishBatch).toHaveBeenCalledTimes(1);
+        expect([...publishBatch.mock.calls[0][0].paths.values()]).toEqual([relativePath]);
+        shutdown();
+        await loop;
+    });
     it("publishes a personal-vault edit from a --companies event-push runner", async () => {
         const publishBatch = vi.fn();
         const startEventSync = vi.fn().mockResolvedValue({