@indigoai-us/hq-cloud 6.15.6 → 6.15.8

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

@@ -1152,6 +1152,180 @@ describe("fanout-plan", () => {
         expect(plan.companies).toEqual([{ uid: "cmp_empty", slug: "cmp_empty" }]);
     });
 });
+describe("automatic journal maintenance", () => {
+    it("accepts direct liveness pulses from synchronous engine planning", async () => {
+        vi.useFakeTimers();
+        vi.setSystemTime(0);
+        try {
+            const sync = vi.fn().mockImplementation(async (options) => {
+                // Moving wall time does not run a fake interval. The maintenance event
+                // can only come from the direct planner callback wired into SyncOptions.
+                vi.setSystemTime(30_000);
+                options.onHeartbeat?.();
+                return defaultSyncResult();
+            });
+            const deps = makeDeps({
+                createVaultClient: () => makeVaultStub({
+                    memberships: [{ companyUid: "cmp_indigo" }],
+                    entityGet: (uid) => Promise.resolve({ uid, slug: "indigo" }),
+                }),
+                repairJournalStateIfNeeded: vi
+                    .fn()
+                    .mockReturnValue({ status: "not-needed", slug: "indigo" }),
+                fanoutHeartbeatIntervalMs: 30_000,
+                sync,
+            });
+            expect(await runRunner(["--companies", "--skip-personal"], deps)).toBe(0);
+            expect(deps.stdout.events().filter((event) => event.type === "maintenance-progress")).toEqual([
+                {
+                    type: "maintenance-progress",
+                    company: "indigo",
+                    bytesProcessed: 0,
+                    totalBytes: 0,
+                },
+            ]);
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+    it("keeps the desktop protocol alive while a long fanout is still reconciling", async () => {
+        vi.useFakeTimers();
+        try {
+            let finishSync;
+            const sync = vi.fn().mockImplementation(() => new Promise((resolve) => {
+                finishSync = resolve;
+            }));
+            const deps = makeDeps({
+                createVaultClient: () => makeVaultStub({
+                    memberships: [{ companyUid: "cmp_indigo" }],
+                    entityGet: (uid) => Promise.resolve({ uid, slug: "indigo" }),
+                }),
+                repairJournalStateIfNeeded: vi
+                    .fn()
+                    .mockReturnValue({ status: "not-needed", slug: "indigo" }),
+                fanoutHeartbeatIntervalMs: 30_000,
+                sync,
+            });
+            const running = runRunner(["--companies", "--skip-personal"], deps);
+            await vi.waitFor(() => expect(sync).toHaveBeenCalledTimes(1));
+            await vi.advanceTimersByTimeAsync(30_000);
+            expect(deps.stdout.events().filter((event) => event.type === "maintenance-progress")).toContainEqual({
+                type: "maintenance-progress",
+                company: "indigo",
+                bytesProcessed: 0,
+                totalBytes: 0,
+            });
+            finishSync(defaultSyncResult());
+            await expect(running).resolves.toBe(0);
+            await vi.advanceTimersByTimeAsync(30_000);
+            expect(deps.stdout.events().filter((event) => event.type === "maintenance-progress")).toHaveLength(1);
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+    it("repairs every resolved journal shard before fanout and streams known heartbeat events", async () => {
+        const order = [];
+        const repairJournalStateIfNeeded = vi.fn().mockImplementation((slug, options) => {
+            order.push(`repair:${slug}`);
+            options.onProgress?.({ bytesRead: 13, totalBytes: 26 });
+            options.onProgress?.({ bytesRead: 26, totalBytes: 26 });
+            return { status: "repaired", slug };
+        });
+        const deps = makeDeps({
+            createVaultClient: () => makeVaultStub({
+                memberships: [{ companyUid: "cmp_indigo" }],
+                entityGet: (uid) => Promise.resolve({ uid, slug: "indigo" }),
+                listPersons: () => Promise.resolve([
+                    {
+                        uid: "prs_me",
+                        slug: "me",
+                        type: "person",
+                        status: "active",
+                        bucketName: "hq-vault-prs-me",
+                        createdAt: "2026-01-01T00:00:00Z",
+                    },
+                ]),
+            }),
+            repairJournalStateIfNeeded,
+            sync: vi.fn().mockImplementation(async (options) => {
+                order.push(`sync:${options.journalSlug ?? "indigo"}`);
+                return defaultSyncResult();
+            }),
+        });
+        expect(await runRunner(["--companies"], deps)).toBe(0);
+        expect(repairJournalStateIfNeeded.mock.calls.map(([slug]) => slug)).toEqual([
+            "indigo",
+            PERSONAL_VAULT_JOURNAL_SLUG,
+            "personal",
+        ]);
+        expect(order.slice(0, 3)).toEqual([
+            "repair:indigo",
+            `repair:${PERSONAL_VAULT_JOURNAL_SLUG}`,
+            "repair:personal",
+        ]);
+        expect(order[3]).toBe("sync:indigo");
+        expect(deps.stdout.events().filter((event) => event.type === "maintenance-progress")).toEqual([
+            {
+                type: "maintenance-progress",
+                company: "indigo",
+                bytesProcessed: 13,
+                totalBytes: 26,
+            },
+            {
+                type: "maintenance-progress",
+                company: "indigo",
+                bytesProcessed: 26,
+                totalBytes: 26,
+            },
+            {
+                type: "maintenance-progress",
+                company: "personal",
+                bytesProcessed: 13,
+                totalBytes: 26,
+            },
+            {
+                type: "maintenance-progress",
+                company: "personal",
+                bytesProcessed: 26,
+                totalBytes: 26,
+            },
+            {
+                type: "maintenance-progress",
+                company: "personal",
+                bytesProcessed: 13,
+                totalBytes: 26,
+            },
+            {
+                type: "maintenance-progress",
+                company: "personal",
+                bytesProcessed: 26,
+                totalBytes: 26,
+            },
+        ]);
+    });
+    it("fails before network work when authoritative local journal recovery fails", async () => {
+        const sync = vi.fn().mockResolvedValue(defaultSyncResult());
+        const deps = makeDeps({
+            createVaultClient: () => makeVaultStub({
+                memberships: [{ companyUid: "cmp_indigo" }],
+                entityGet: (uid) => Promise.resolve({ uid, slug: "indigo" }),
+            }),
+            repairJournalStateIfNeeded: () => {
+                throw new Error("newest journal generation is unreadable");
+            },
+            sync,
+        });
+        expect(await runRunner(["--companies"], deps)).toBe(1);
+        expect(sync).not.toHaveBeenCalled();
+        expect(deps.stderr.events()).toContainEqual({
+            type: "error",
+            path: "(local-state)",
+            message: "newest journal generation is unreadable",
+        });
+    });
+});
 // ---------------------------------------------------------------------------
 // per-company event tagging
 // ---------------------------------------------------------------------------
@@ -3334,6 +3508,9 @@ function makeWatcherStub() {
     };
     return stub;
 }
+function completedPassOutcome(exitCode = 0) {
+    return { exitCode, result: { pushPathResults: [] } };
+}
 async function flushLoopMicrotasks(n = 8) {
     for (let i = 0; i < n; i++)
         await Promise.resolve();
@@ -3490,10 +3667,164 @@ describe("runRunnerWithLoop — adaptive poll interval (no --poll-remote-ms)", (
     });
 });
 describe("runRunnerWithLoop — event-push wiring", () => {
+    it("does not start journal-reading watcher callbacks before the initial pass finishes", async () => {
+        const watcher = makeWatcherStub();
+        let maintenanceComplete = false;
+        let callbackObservedMaintenance = false;
+        let triggerShutdown = () => { };
+        let releaseInitialPass = () => { };
+        const initialPass = new Promise((resolve) => {
+            releaseInitialPass = resolve;
+        });
+        const runPass = vi.fn().mockImplementation(async () => {
+            await initialPass;
+            maintenanceComplete = true;
+            return completedPassOutcome();
+        });
+        const createWatcher = vi.fn((opts) => {
+            watcher.start = () => {
+                watcher.started = true;
+                callbackObservedMaintenance = maintenanceComplete;
+                opts.captureLocalDeleteSnapshots("companies/indigo/knowledge/deleted.md", "unlink");
+            };
+            return watcher;
+        });
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
+            runPass,
+            createWatcher: createWatcher,
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        expect(runPass).toHaveBeenCalledTimes(1);
+        expect(createWatcher).not.toHaveBeenCalled();
+        expect(watcher.started).toBe(false);
+        releaseInitialPass();
+        await flushLoopMicrotasks();
+        expect(createWatcher).toHaveBeenCalledTimes(1);
+        expect(watcher.started).toBe(true);
+        expect(callbackObservedMaintenance).toBe(true);
+        triggerShutdown();
+        await loop;
+    });
+    it("keeps every event surface off until a result proves maintenance completed", async () => {
+        const watcher = makeWatcherStub();
+        const sleep = makeSteppableSleep();
+        let triggerShutdown = () => { };
+        const runPass = vi.fn()
+            .mockResolvedValueOnce({ exitCode: TRANSIENT_NETWORK_EXIT })
+            .mockResolvedValueOnce(completedPassOutcome());
+        const createWatcher = vi.fn(() => watcher);
+        const receiver = {
+            connected: false,
+            start: vi.fn().mockResolvedValue(undefined),
+            dispose: vi.fn().mockResolvedValue(undefined),
+        };
+        const createReceiver = vi.fn(() => receiver);
+        const scheduler = {
+            signal: vi.fn(),
+            checkHighWater: vi.fn().mockResolvedValue(undefined),
+            dispose: vi.fn().mockResolvedValue(undefined),
+        };
+        const startRealtimeScheduler = vi.fn().mockResolvedValue(scheduler);
+        const startEventSync = vi.fn().mockResolvedValue(null);
+        const priorEventSyncOverride = process.env.HQ_SYNC_EVENT_SYNC;
+        process.env.HQ_SYNC_EVENT_SYNC = "1";
+        try {
+            const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
+                runPass,
+                createWatcher,
+                createReceiver,
+                startRealtimeScheduler,
+                startEventSync,
+                getIdTokenClaims: () => null,
+                getAccessToken: async () => "jwt-test",
+                sleep: sleep.sleep,
+                onShutdownSignal: (handler) => {
+                    triggerShutdown = handler;
+                    return () => { };
+                },
+            });
+            await flushLoopMicrotasks();
+            expect(runPass).toHaveBeenCalledTimes(1);
+            expect(createWatcher).not.toHaveBeenCalled();
+            expect(createReceiver).not.toHaveBeenCalled();
+            expect(startRealtimeScheduler).not.toHaveBeenCalled();
+            expect(startEventSync).not.toHaveBeenCalled();
+            sleep.tick();
+            await flushLoopMicrotasks();
+            expect(runPass).toHaveBeenCalledTimes(2);
+            expect(createWatcher).toHaveBeenCalledTimes(1);
+            expect(createReceiver).toHaveBeenCalledTimes(1);
+            expect(receiver.start).toHaveBeenCalledTimes(1);
+            expect(startRealtimeScheduler).toHaveBeenCalledTimes(1);
+            expect(startEventSync).toHaveBeenCalledTimes(1);
+            expect(watcher.started).toBe(true);
+            triggerShutdown();
+            await loop;
+        }
+        finally {
+            if (priorEventSyncOverride === undefined) {
+                delete process.env.HQ_SYNC_EVENT_SYNC;
+            }
+            else {
+                process.env.HQ_SYNC_EVENT_SYNC = priorEventSyncOverride;
+            }
+        }
+    });
+    it("rejects paused-company delete snapshots before opening their journal", async () => {
+        const watcher = makeWatcherStub();
+        let capture;
+        let triggerShutdown = () => { };
+        const priorSkipCompanies = process.env.HQ_SYNC_SKIP_COMPANIES;
+        process.env.HQ_SYNC_SKIP_COMPANIES = "indigo";
+        const stateDir = process.env.HQ_STATE_DIR;
+        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
+            runPass: vi.fn().mockResolvedValue(completedPassOutcome()),
+            createWatcher: (options) => {
+                capture = options.captureLocalDeleteSnapshots;
+                return watcher;
+            },
+            startEventSync: vi.fn().mockResolvedValue(null),
+            getIdTokenClaims: () => null,
+            getAccessToken: async () => "jwt-test",
+            sleep: () => new Promise(() => { }),
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        try {
+            await flushLoopMicrotasks();
+            expect(watcher.started).toBe(true);
+            expect(capture).toBeTypeOf("function");
+            // Turn the configured state directory into a regular file. Any attempt
+            // to open a journal beneath it now fails with ENOTDIR, so returning an
+            // empty snapshot proves the pause check happens before journal I/O.
+            fs.rmSync(stateDir, { recursive: true, force: true });
+            fs.writeFileSync(stateDir, "not-a-directory");
+            expect(capture("companies/indigo/knowledge/deleted.md", "unlink")).toEqual([]);
+        }
+        finally {
+            triggerShutdown();
+            await loop;
+            fs.rmSync(stateDir, { force: true });
+            fs.mkdirSync(stateDir, { recursive: true });
+            if (priorSkipCompanies === undefined) {
+                delete process.env.HQ_SYNC_SKIP_COMPANIES;
+            }
+            else {
+                process.env.HQ_SYNC_SKIP_COMPANIES = priorSkipCompanies;
+            }
+        }
+    });
     it("starts the watcher alongside the poll loop when --event-push is on", async () => {
         const watcher = makeWatcherStub();
         let triggerShutdown = () => { };
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
             runPass,
             clock: new FakeClock(),
@@ -3518,7 +3849,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         const watcher = makeWatcherStub();
         const clock = new FakeClock();
         let triggerShutdown = () => { };
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const sleepCalls = [];
         const loop = runRunnerWithLoop([
             "--companies",
@@ -3556,7 +3887,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         const watcher = makeWatcherStub();
         const clock = new FakeClock();
         let triggerShutdown = () => { };
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
             runPass,
             clock,
@@ -3596,7 +3927,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
             if (callCount === 1)
                 await firstGate; // hold the first (poll) pass
             active--;
-            return 0;
+            return completedPassOutcome();
         });
         const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
             runPass,
@@ -3631,7 +3962,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         triggerShutdown();
         await loop;
     });
-    it("U07: retains a watcher event raised before the next wait registers, without guarded overlap", async () => {
+    it("U07: drains the first watcher event after activation without guarded overlap", async () => {
         const watcher = makeWatcherStub();
         let triggerShutdown = () => { };
         let releaseFirstPass = () => { };
@@ -3647,7 +3978,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
             if (passes === 1)
                 await firstPassGate;
             span.exitedAt = process.hrtime.bigint();
-            return 0;
+            return completedPassOutcome();
         });
         const loop = runRunnerWithLoop([
             "--companies",
@@ -3668,11 +3999,13 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         });
         await flushLoopMicrotasks();
         expect(spans).toHaveLength(1);
-        // This event arrives while the initial guarded pass owns the scheduler,
-        // before its next sleep/wait has been registered.
-        watcher.emit("companies/indigo/pre-registration.md");
         releaseFirstPass();
         await flushLoopMicrotasks();
+        expect(watcher.started).toBe(true);
+        // Activation happens synchronously after the maintenance-bearing pass,
+        // 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[1].enteredAt >= spans[0].exitedAt).toBe(true);
         triggerShutdown();
@@ -3696,7 +4029,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
             if (calls === 1)
                 await pollGate;
             active--;
-            return 0;
+            return completedPassOutcome();
         });
         const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
             runPass,
@@ -3737,7 +4070,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         const poll = { resolve: null };
         const runPass = vi.fn().mockImplementation(async () => {
             passes++;
-            return 0;
+            return completedPassOutcome();
         });
         // A sleep we can step: resolve once to allow a second poll pass.
         const sleep = () => new Promise((resolve) => {
@@ -3771,7 +4104,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         const clock = new FakeClock();
         let triggerShutdown = () => { };
         let detached = false;
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
             runPass,
             clock,
@@ -3806,7 +4139,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
             onShutdownSignal: () => () => { },
         });
         expect(code).toBe(1);
-        expect(watcher.disposed).toBe(true);
+        expect(watcher.disposed).toBe(false);
     });
     it("an exit-0 auth-required pass stops the unattended loop without reporting a crash", async () => {
         const watcher = makeWatcherStub();
@@ -3822,7 +4155,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         expect(code).toBe(0);
         expect(runPass).toHaveBeenCalledTimes(1);
         expect(sleep).not.toHaveBeenCalled();
-        expect(watcher.disposed).toBe(true);
+        expect(watcher.disposed).toBe(false);
     });
     it("a TRANSIENT_NETWORK_EXIT poll pass does NOT surface as a crash — the loop retries (HQ-SYNC-1W)", async () => {
         // A transient offline blip must keep the watcher alive: the loop logs and
@@ -3849,7 +4182,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         // …and the transient code was never surfaced as the watcher's exit code.
         expect(code).toBe(1);
         expect(code).not.toBe(TRANSIENT_NETWORK_EXIT);
-        expect(watcher.disposed).toBe(true);
+        expect(watcher.disposed).toBe(false);
     });
     it("keeps the watch loop alive when a company leg returns transient exit 75 (HQ-SYNC-X)", async () => {
         const watcher = makeWatcherStub();
@@ -3883,7 +4216,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         expect(transientPass.stderr
             .events()
             .some((event) => event.type === "error" && event.path === "(company)")).toBe(false);
-        expect(watcher.disposed).toBe(true);
+        expect(watcher.disposed).toBe(false);
     });
     it("a PARTIAL_SYNC_EXIT poll pass does NOT surface as a crash — the loop retries", async () => {
         // A partial pass (some per-file transfers threw: oversized object on an
@@ -3913,7 +4246,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         // …and the partial code was never surfaced as the watcher's exit code.
         expect(code).toBe(1);
         expect(code).not.toBe(PARTIAL_SYNC_EXIT);
-        expect(watcher.disposed).toBe(true);
+        expect(watcher.disposed).toBe(false);
     });
     it("alerts when a partial pass failed before a company's download leg", async () => {
         const watcher = makeWatcherStub();
@@ -3961,7 +4294,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
     it("without --event-push, no watcher is created (poll-only safety net)", async () => {
         let triggerShutdown = () => { };
         const createWatcher = vi.fn(() => makeWatcherStub());
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const loop = runRunnerWithLoop(["--companies", "--watch"], {
             runPass,
             createWatcher,
@@ -3992,17 +4325,17 @@ describe("runRunnerWithLoop — U58 realtime scheduler guard", () => {
             active += 1;
             maximumActive = Math.max(maximumActive, active);
             passes += 1;
-            if (passes === 1)
+            if (passes === 2)
                 await pollGate;
             active -= 1;
-            return 0;
+            return completedPassOutcome();
         });
         let signal = null;
         const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
             runPass,
             clock: new FakeClock(),
             createWatcher: () => watcher,
-            sleep: () => new Promise(() => { }),
+            sleep: makeSteppableSleep().sleep,
             onShutdownSignal: (handler) => {
                 triggerShutdown = handler;
                 return () => { };
@@ -4022,7 +4355,12 @@ describe("runRunnerWithLoop — U58 realtime scheduler guard", () => {
                 dispose: async () => undefined,
             }),
         });
-        for (let i = 0; i < 6; i++)
+        for (let i = 0; i < 12; i++)
+            await Promise.resolve();
+        expect(watcher.started).toBe(true);
+        // A second legacy pass owns the guard after activation.
+        watcher.emit("companies/indigo/legacy.md");
+        for (let i = 0; i < 8; i++)
             await Promise.resolve();
         expect(active).toBe(1);
         watcher.emit("companies/indigo/v2.md");
@@ -4054,7 +4392,7 @@ describe("runRunnerWithLoop — U58 realtime scheduler guard", () => {
                 passes += 1;
                 if (passes === 1)
                     await initial;
-                return 0;
+                return completedPassOutcome();
             },
             clock: new FakeClock(),
             createWatcher: () => watcher,
@@ -4073,11 +4411,10 @@ describe("runRunnerWithLoop — U58 realtime scheduler guard", () => {
                 dispose: async () => undefined,
             }),
         });
-        for (let i = 0; i < 6; i++)
+        for (let i = 0; i < 12; i++)
             await Promise.resolve();
         releaseInitial();
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
+        await flushLoopMicrotasks(20);
         expect(sleepState.delays[0]).toBe(300_000);
         clockState.now = 300_000;
         sleepState.resolve?.();
@@ -4133,7 +4470,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         };
     }
     it("startup runs one full reconcile, then watcher edits interrupt the pending wait", async () => {
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const { loop, watcher, tick, shutdown } = startDrainLoop(runPass);
         await flushLoopMicrotasks();
         expect(runPass.mock.calls.map((call) => call[0])).toEqual([fullArgv]);
@@ -4158,7 +4495,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         await loop;
     });
     it("coalesces repeated edits to the same path into one scoped push", async () => {
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const { loop, watcher, tick, shutdown } = startDrainLoop(runPass);
         await flushLoopMicrotasks();
         runPass.mockClear();
@@ -4186,7 +4523,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         await loop;
     });
     it("U08: --companies --skip-personal drops a personal watcher edit before it queues work", async () => {
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const { loop, watcher, tick, shutdown } = startDrainLoopWithArgv(runPass, [
             ...watchArgv,
             "--skip-personal",
@@ -4204,7 +4541,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         await loop;
     });
     it("drains an unlink path through the same scoped tombstone push path", async () => {
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const { loop, watcher, tick, shutdown } = startDrainLoop(runPass);
         await flushLoopMicrotasks();
         runPass.mockClear();
@@ -4226,7 +4563,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         await loop;
     });
     it("omitted --direction is pull-only (parser default): a scoped tick never pushes", async () => {
-        const runPass = vi.fn().mockResolvedValue(0);
+        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
@@ -4260,7 +4597,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
     it("restores failed scoped push paths so the next tick retries them", async () => {
         const runPass = vi
             .fn()
-            .mockResolvedValueOnce(0)
+            .mockResolvedValueOnce(completedPassOutcome())
             .mockResolvedValueOnce(1)
             .mockResolvedValueOnce(0)
             .mockResolvedValueOnce(0)
@@ -4303,7 +4640,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         await loop;
     });
     it("empty scoped ticks run only the pull leg", async () => {
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const { loop, tick, shutdown } = startDrainLoop(runPass);
         await flushLoopMicrotasks();
         runPass.mockClear();
@@ -4315,7 +4652,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         await loop;
     });
     it("personal scoped ticks preserve personal mode for the pull leg", async () => {
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const { loop, watcher, tick, shutdown } = startDrainLoopWithArgv(runPass, [
             "--personal",
             "--watch",
@@ -4349,7 +4686,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         await loop;
     });
     it("single-company scoped ticks preserve company mode for the pull leg", async () => {
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const { loop, watcher, tick, shutdown } = startDrainLoopWithArgv(runPass, [
             "--company",
             "acme",
@@ -4385,7 +4722,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         await loop;
     });
     it("push-only scoped ticks run the scoped push and no pull leg", async () => {
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const { loop, watcher, tick, shutdown } = startDrainLoopWithArgv(runPass, [
             "--companies",
             "--watch",
@@ -4422,7 +4759,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         const watcher = makeBatchWatcherStub();
         const sleep = makeSteppableSleep();
         let triggerShutdown = () => { };
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const loop = runRunnerWithLoop(watchArgv, {
             runPass,
             clock: new FakeClock(),
@@ -5210,7 +5547,8 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
     const UNENROLLED_CLAIMS = { email: "someone@getindigo.ai" };
     function runLoop(opts) {
         const watcher = opts.watcher ?? makeBatchWatcherStub();
-        const runPass = opts.runPass ?? vi.fn().mockResolvedValue(0);
+        const runPass = opts.runPass ??
+            vi.fn().mockResolvedValue(completedPassOutcome());
         const clock = new FakeClock();
         const sleep = makeSteppableSleep();
         let triggerShutdown = () => { };
@@ -5304,7 +5642,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         });
         const runPass = vi
             .fn()
-            .mockResolvedValueOnce(0)
+            .mockResolvedValueOnce(completedPassOutcome())
             .mockImplementation((passArgv) => passArgv.includes("--company") ? targetedPush : Promise.resolve(0));
         const { loop, watcher, clock, shutdown } = runLoop({
             claims: EMAIL_CLAIMS,
@@ -5349,7 +5687,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         // Initial poll pass succeeds; the targeted pass fails.
         const runPass = vi
             .fn()
-            .mockResolvedValueOnce(0)
+            .mockResolvedValueOnce(completedPassOutcome())
             .mockResolvedValue(1);
         const { loop, watcher, clock, tick, shutdown } = runLoop({
             claims: EMAIL_CLAIMS,
@@ -5381,7 +5719,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
                 ownDeviceId: "dev-test",
                 dispose: vi.fn().mockResolvedValue(undefined),
             });
-            const runPass = vi.fn().mockResolvedValue(0);
+            const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
             const { loop, watcher, clock, tick, shutdown } = runLoop({
                 claims: EMAIL_CLAIMS,
                 startEventSync,
@@ -5421,7 +5759,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         });
         const runPass = vi
             .fn()
-            .mockResolvedValueOnce(0)
+            .mockResolvedValueOnce(completedPassOutcome())
             .mockResolvedValueOnce({
             exitCode: 0,
             result: {
@@ -5462,7 +5800,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         });
         const runPass = vi
             .fn()
-            .mockResolvedValueOnce(0)
+            .mockResolvedValueOnce(completedPassOutcome())
             .mockResolvedValueOnce({
             exitCode: 0,
             result: {
@@ -5503,7 +5841,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
             ownDeviceId: "dev-test",
             dispose: vi.fn().mockResolvedValue(undefined),
         });
-        const runPass = vi.fn().mockResolvedValue(0);
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
         const { loop, watcher, clock, tick, shutdown } = runLoop({
             claims: EMAIL_CLAIMS,
             startEventSync,
@@ -5580,9 +5918,9 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         let passCount = 0;
         const runPass = vi.fn().mockImplementation(async () => {
             passCount += 1;
-            if (passCount === 1)
+            if (passCount === 2)
                 await pollGate;
-            return 0;
+            return completedPassOutcome();
         });
         const loop = runRunnerWithLoop(
         // `--direction both` so the queued watcher pushes actually run (an omitted
@@ -5619,6 +5957,21 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         await microtasks();
         expect(passCount).toBe(1);
         expect(receiverSync).toBeTruthy();
+        const remotePull = receiverSync({
+            event: {
+                kind: "upsert",
+                relativePath: "companies/acme/remote.md",
+                contentHash: "sha256:remote",
+                mtime: "2026-06-18T12:00:00.000Z",
+                originDeviceId: "peer-device",
+                originTenantId: "tenant-acme",
+                sequenceNumber: 7,
+                eventTimestamp: "2026-06-18T12:00:00.000Z",
+            },
+            signal: new AbortController().signal,
+        });
+        await microtasks();
+        expect(passCount).toBe(2);
         const indigoBatch = {
             paths: new Map([
                 ["/tmp/hq/companies/indigo/a.md", "companies/indigo/a.md"],
@@ -5635,20 +5988,6 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         watcher.emit("companies/beta/b.md", betaBatch);
         clock.advance(0);
         await microtasks();
-        const remotePull = receiverSync({
-            event: {
-                kind: "upsert",
-                relativePath: "companies/acme/remote.md",
-                contentHash: "sha256:remote",
-                mtime: "2026-06-18T12:00:00.000Z",
-                originDeviceId: "peer-device",
-                originTenantId: "tenant-acme",
-                sequenceNumber: 7,
-                eventTimestamp: "2026-06-18T12:00:00.000Z",
-            },
-            signal: new AbortController().signal,
-        });
-        await microtasks();
         releasePoll();
         await remotePull;
         await microtasks();
@@ -6622,7 +6961,7 @@ describe("watcher delete intents without pre-seeded authorization", () => {
         const initialPullGate = new Promise((resolve) => {
             releaseInitialPull = resolve;
         });
-        let initialPullGated = options.gateInitialPull === true;
+        let pullPasses = 0;
         const runPass = vi.fn(async (argv) => {
             // Lets a test hold a pass mid-flight and act while the loop is awaiting
             // it, which is where producer-side state that outlives a pass is decided.
@@ -6673,8 +7012,8 @@ describe("watcher delete intents without pre-seeded authorization", () => {
                 return { exitCode: 0, result: { pushPathResults: pathResults } };
             }
             if (direction === "pull" || direction === "both") {
-                if (initialPullGated) {
-                    initialPullGated = false;
+                pullPasses += 1;
+                if (options.gateNextPull === true && pullPasses === 2) {
                     await initialPullGate;
                 }
                 const journal = readJournal("indigo");
@@ -6694,7 +7033,7 @@ describe("watcher delete intents without pre-seeded authorization", () => {
                     downloads++;
                 }
             }
-            return 0;
+            return completedPassOutcome();
         });
         const loop = runRunnerWithLoop([
             "--companies", "--watch", "--event-push",
@@ -6761,7 +7100,9 @@ describe("watcher delete intents without pre-seeded authorization", () => {
         await stopHarness(h);
     });
     it("persists the intent before an in-flight pull plans the missing path", async () => {
-        const h = startDeleteHarness(["knowledge/in-flight.md"], { gateInitialPull: true });
+        const h = startDeleteHarness(["knowledge/in-flight.md"], { gateNextPull: true });
+        await settle();
+        h.tick();
         await settle();
         const relativePath = "companies/indigo/knowledge/in-flight.md";
         const absolutePath = path.join(h.companyRoot, "knowledge/in-flight.md");
@@ -6907,7 +7248,16 @@ describe("watcher delete intents without pre-seeded authorization", () => {
             "--poll-remote-ms",
             "60000",
         ], {
-            runPass: (passArgv) => runRunner(passArgv, runnerDeps),
+            runPass: async (passArgv) => {
+                let result;
+                const exitCode = await runRunner(passArgv, {
+                    ...runnerDeps,
+                    onPassResult: (passResult) => {
+                        result = passResult;
+                    },
+                });
+                return { exitCode, ...(result ? { result } : {}) };
+            },
             createWatcher: (options) => {
                 capture = options.captureLocalDeleteSnapshots;
                 return watcher;