@indigoai-us/hq-cloud 6.13.4 → 6.14.0

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

@@ -16,6 +16,8 @@ import { FakeClock } from "../watcher.js";
 import { PERSONAL_VAULT_JOURNAL_SLUG } from "../journal.js";
 import { HQ_CLOUD_VERSION } from "../version.js";
 import { lockPathFor, OPERATION_LOCKED_EXIT } from "../operation-lock.js";
+import { TRANSIENT_NETWORK_EXIT } from "../lib/net-errors.js";
+import { isCoveredByAny } from "../prefix-coalesce.js";
 import { VaultAuthError } from "../vault-client.js";
 // ---------------------------------------------------------------------------
 // Hermetic journal state — the runner now calls migratePersonalVaultJournal()
@@ -307,6 +309,47 @@ describe("memberships retry", () => {
             path: "(discovery)",
         });
     });
+    it("a transient network failure (fetch failed) during discovery returns TRANSIENT_NETWORK_EXIT, not 1 (HQ-SYNC-1W)", async () => {
+        // Regression for the "auto-sync watcher exited unexpectedly (code=Some(1))"
+        // cluster: a machine that stays offline through all 3 membership retries
+        // used to `return 1`, which the watch loop propagated and the menubar
+        // reported as a crash for every network blip. undici surfaces the blip as
+        // `TypeError: fetch failed`; that must map to the retryable exit code so the
+        // watcher stays alive instead of crash-reporting. A one-shot run still sees
+        // a non-zero exit.
+        let listCalls = 0;
+        const stub = makeVaultStub();
+        stub.listMyMemberships = () => {
+            listCalls++;
+            return Promise.reject(new TypeError("fetch failed"));
+        };
+        const deps = makeDeps({ createVaultClient: () => stub });
+        const code = await runRunner(["--companies"], deps);
+        expect(code).toBe(TRANSIENT_NETWORK_EXIT);
+        expect(listCalls).toBe(3);
+        // Still surfaced for observability — just no longer a "code 1" crash.
+        const events = deps.stderr.events();
+        expect(events).toHaveLength(1);
+        expect(events[0]).toMatchObject({
+            type: "error",
+            message: "fetch failed",
+            path: "(discovery)",
+        });
+    });
+    it("a NON-transient discovery failure still returns 1 (unchanged)", async () => {
+        // Guard the conservative classifier: a generic error (not a transport
+        // shape) is still a hard exit 1, exactly as before.
+        let listCalls = 0;
+        const stub = makeVaultStub();
+        stub.listMyMemberships = () => {
+            listCalls++;
+            return Promise.reject(new Error("unexpected 500 from vault api"));
+        };
+        const deps = makeDeps({ createVaultClient: () => stub });
+        const code = await runRunner(["--companies"], deps);
+        expect(code).toBe(1);
+        expect(listCalls).toBe(3);
+    });
     it("VaultAuthError short-circuits retry (no retries on auth failure)", async () => {
         let listCalls = 0;
         const stub = makeVaultStub();
@@ -1598,6 +1641,75 @@ describe("--direction", () => {
         // preserving the pre-fix company-target args shape (full access).
         expect(opts.prefixSet).toBeUndefined();
     });
+    it("direction=push with --scope-path: forwards exact and descendant scoped prefixes to share()", async () => {
+        const shareSpy = vi.fn().mockResolvedValue(defaultShareResult());
+        const deps = makeDeps({
+            createVaultClient: () => makeVaultStub({
+                memberships: [{ companyUid: "cmp_a" }],
+                entityGet: (uid) => Promise.resolve({ uid, slug: "acme" }),
+            }),
+            sync: vi.fn(),
+            share: shareSpy,
+        });
+        await runRunner([
+            "--companies",
+            "--direction",
+            "push",
+            "--hq-root",
+            "/tmp/fake-hq",
+            "--scope-path",
+            "knowledge/a.md",
+        ], deps);
+        const opts = shareSpy.mock.calls[0][0];
+        expect(opts.prefixSet).toEqual(["knowledge/a.md", "knowledge/a.md/"]);
+    });
+    it("direction=push with directory --scope-path covers descendant keys for tombstones", async () => {
+        const shareSpy = vi.fn().mockResolvedValue(defaultShareResult());
+        const deps = makeDeps({
+            createVaultClient: () => makeVaultStub({
+                memberships: [{ companyUid: "cmp_a" }],
+                entityGet: (uid) => Promise.resolve({ uid, slug: "acme" }),
+            }),
+            sync: vi.fn(),
+            share: shareSpy,
+        });
+        await runRunner([
+            "--companies",
+            "--direction",
+            "push",
+            "--hq-root",
+            "/tmp/fake-hq",
+            "--scope-path",
+            "knowledge/archive",
+        ], deps);
+        const opts = shareSpy.mock.calls[0][0];
+        expect(opts.prefixSet).toBeDefined();
+        expect(isCoveredByAny("knowledge/archive/a.md", opts.prefixSet ?? [])).toBe(true);
+    });
+    it("direction=push with file --scope-path does not cover siblings", async () => {
+        const shareSpy = vi.fn().mockResolvedValue(defaultShareResult());
+        const deps = makeDeps({
+            createVaultClient: () => makeVaultStub({
+                memberships: [{ companyUid: "cmp_a" }],
+                entityGet: (uid) => Promise.resolve({ uid, slug: "acme" }),
+            }),
+            sync: vi.fn(),
+            share: shareSpy,
+        });
+        await runRunner([
+            "--companies",
+            "--direction",
+            "push",
+            "--hq-root",
+            "/tmp/fake-hq",
+            "--scope-path",
+            "board.json",
+        ], deps);
+        const opts = shareSpy.mock.calls[0][0];
+        expect(opts.prefixSet).toBeDefined();
+        expect(isCoveredByAny("board.json", opts.prefixSet ?? [])).toBe(true);
+        expect(isCoveredByAny("other.json", opts.prefixSet ?? [])).toBe(false);
+    });
     it("direction=push (shared membership): forwards the resolved ACL prefixSet to share() (feedback_ded09d56)", async () => {
         // Plumbing regression for the fresh fix: a member/guest's push must be
         // scoped to their granted prefixes so out-of-scope keys are filtered
@@ -1627,6 +1739,76 @@ describe("--direction", () => {
         const opts = shareSpy.mock.calls[0][0];
         expect(opts.prefixSet).toEqual(["knowledge/", "policies/"]);
     });
+    it("direction=push with --scope-path never widens a shared ACL prefixSet", async () => {
+        const shareSpy = vi.fn().mockResolvedValue(defaultShareResult());
+        const client = {
+            ...makeVaultStub({
+                memberships: [{ companyUid: "cmp_a" }],
+                entityGet: (uid) => Promise.resolve({ uid, slug: "acme" }),
+            }),
+            getMembershipSyncConfig: async () => ({
+                membershipId: "mk_a",
+                syncMode: "shared",
+                isDefault: false,
+            }),
+            listMyExplicitGrants: async () => [
+                { companyUid: "cmp_a", path: "knowledge/", permission: "read", source: "person" },
+            ],
+        };
+        const deps = makeDeps({
+            createVaultClient: () => client,
+            sync: vi.fn(),
+            share: shareSpy,
+        });
+        await runRunner([
+            "--companies",
+            "--direction",
+            "push",
+            "--hq-root",
+            "/tmp/fake-hq",
+            "--scope-path",
+            "knowledge/a.md",
+            "--scope-path",
+            "secrets/b.md",
+        ], deps);
+        const opts = shareSpy.mock.calls[0][0];
+        expect(opts.prefixSet).toEqual(["knowledge/a.md", "knowledge/a.md/"]);
+        expect(isCoveredByAny("secrets/b.md", opts.prefixSet ?? [])).toBe(false);
+    });
+    it("direction=push with directory --scope-path never widens outside a shared ACL prefixSet", async () => {
+        const shareSpy = vi.fn().mockResolvedValue(defaultShareResult());
+        const client = {
+            ...makeVaultStub({
+                memberships: [{ companyUid: "cmp_a" }],
+                entityGet: (uid) => Promise.resolve({ uid, slug: "acme" }),
+            }),
+            getMembershipSyncConfig: async () => ({
+                membershipId: "mk_a",
+                syncMode: "shared",
+                isDefault: false,
+            }),
+            listMyExplicitGrants: async () => [
+                { companyUid: "cmp_a", path: "policies/", permission: "read", source: "person" },
+            ],
+        };
+        const deps = makeDeps({
+            createVaultClient: () => client,
+            sync: vi.fn(),
+            share: shareSpy,
+        });
+        await runRunner([
+            "--companies",
+            "--direction",
+            "push",
+            "--hq-root",
+            "/tmp/fake-hq",
+            "--scope-path",
+            "knowledge/archive",
+        ], deps);
+        const opts = shareSpy.mock.calls[0][0];
+        expect(isCoveredByAny("knowledge/archive/a.md", opts.prefixSet ?? [])).toBe(false);
+        expect(isCoveredByAny("policies/a.md", opts.prefixSet ?? [])).toBe(false);
+    });
     it("direction=both: all-complete sums uploaded and downloaded across companies", async () => {
         const slugs = { cmp_a: "acme", cmp_b: "beta" };
         const deps = makeDeps({
@@ -2371,6 +2553,24 @@ function makeWatcherStub() {
     };
     return stub;
 }
+async function flushLoopMicrotasks(n = 8) {
+    for (let i = 0; i < n; i++)
+        await Promise.resolve();
+}
+function makeSteppableSleep() {
+    const pending = [];
+    return {
+        sleep: () => new Promise((resolve) => {
+            pending.push(resolve);
+        }),
+        tick() {
+            const resolve = pending.shift();
+            if (!resolve)
+                throw new Error("poll sleep was not pending");
+            resolve();
+        },
+    };
+}
 describe("runRunnerWithLoop — event-push wiring", () => {
     it("starts the watcher alongside the poll loop when --event-push is on", async () => {
         const watcher = makeWatcherStub();
@@ -2396,7 +2596,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         expect(runPass).toHaveBeenCalled();
         expect(watcher.disposed).toBe(true);
     });
-    it("trigger-on-change: a debounced changed signal runs a targeted company push", async () => {
+    it("trigger-on-change: a changed signal accumulates without an immediate push", async () => {
         const watcher = makeWatcherStub();
         const clock = new FakeClock();
         let triggerShutdown = () => { };
@@ -2420,20 +2620,11 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         clock.advance(0);
         await Promise.resolve();
         await Promise.resolve();
-        const targetedCall = runPass.mock.calls.find((c) => c[0].includes("--company"));
-        expect(targetedCall).toBeDefined();
-        expect(targetedCall[0]).toEqual([
-            "--company",
-            "indigo",
-            "--direction",
-            "push",
-            "--hq-root",
-            "/tmp/hq",
-        ]);
+        expect(runPass).not.toHaveBeenCalled();
         triggerShutdown();
         await loop;
     });
-    it("bare signal (no path) routes the targeted push to the personal vault", async () => {
+    it("bare signal (no path) accumulates without an immediate push", async () => {
         const watcher = makeWatcherStub();
         const clock = new FakeClock();
         let triggerShutdown = () => { };
@@ -2455,16 +2646,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         clock.advance(0);
         await Promise.resolve();
         await Promise.resolve();
-        const personalCall = runPass.mock.calls.find((c) => c[0].includes("--companies") &&
-            c[0].includes("--direction"));
-        expect(personalCall).toBeDefined();
-        expect(personalCall[0]).toEqual([
-            "--companies",
-            "--direction",
-            "push",
-            "--hq-root",
-            "/tmp/hq",
-        ]);
+        expect(runPass).not.toHaveBeenCalled();
         triggerShutdown();
         await loop;
     });
@@ -2522,7 +2704,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         triggerShutdown();
         await loop;
     });
-    it("F05: guard-held watcher push is queued after the active poll pass", async () => {
+    it("F05: guard-held watcher changes stay accumulated until a poll drain", async () => {
         const watcher = makeWatcherStub();
         const clock = new FakeClock();
         let triggerShutdown = () => { };
@@ -2570,14 +2752,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         await loop;
         expect(maxConcurrent).toBe(1);
         const targetedCall = runPass.mock.calls.find((c) => c[0].includes("--company"));
-        expect(targetedCall?.[0]).toEqual([
-            "--company",
-            "indigo",
-            "--direction",
-            "push",
-            "--hq-root",
-            "/tmp/hq",
-        ]);
+        expect(targetedCall).toBeUndefined();
     });
     it("poll-still-runs: the poll loop fires passes independent of the watcher", async () => {
         const watcher = makeWatcherStub();
@@ -2660,6 +2835,33 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         expect(code).toBe(2);
         expect(watcher.disposed).toBe(true);
     });
+    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
+        // polls again instead of returning the code and letting the process exit
+        // (which the menubar reports as "watcher exited unexpectedly"). A genuine
+        // hard error on a later pass still terminates the loop.
+        const watcher = makeWatcherStub();
+        let n = 0;
+        const runPass = vi.fn().mockImplementation(async () => {
+            n++;
+            // First pass: machine is offline (transient). Second pass: a real hard
+            // error, used here only to end the otherwise-infinite loop deterministically.
+            return n === 1 ? TRANSIENT_NETWORK_EXIT : 2;
+        });
+        const code = await runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            sleep: () => Promise.resolve(),
+            onShutdownSignal: () => () => { },
+        });
+        // The transient pass did NOT end the loop — it ran again…
+        expect(runPass).toHaveBeenCalledTimes(2);
+        // …and the transient code was never surfaced as the watcher's exit code.
+        expect(code).toBe(2);
+        expect(code).not.toBe(TRANSIENT_NETWORK_EXIT);
+        expect(watcher.disposed).toBe(true);
+    });
     it("without --event-push, no watcher is created (poll-only safety net)", async () => {
         let triggerShutdown = () => { };
         const createWatcher = vi.fn(() => makeWatcherStub());
@@ -2681,6 +2883,360 @@ describe("runRunnerWithLoop — event-push wiring", () => {
         await loop;
     });
 });
+describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
+    const watchArgv = [
+        "--companies",
+        "--watch",
+        "--event-push",
+        "--direction",
+        "both",
+        "--hq-root",
+        "/tmp/hq",
+        "--poll-remote-ms",
+        "60000",
+    ];
+    const fullArgv = ["--companies", "--direction", "both", "--hq-root", "/tmp/hq"];
+    const fullPullArgv = [
+        "--companies",
+        "--direction",
+        "pull",
+        "--hq-root",
+        "/tmp/hq",
+    ];
+    function startDrainLoop(runPass) {
+        return startDrainLoopWithArgv(runPass, watchArgv);
+    }
+    function startDrainLoopWithArgv(runPass, argv) {
+        const watcher = makeWatcherStub();
+        const sleep = makeSteppableSleep();
+        let triggerShutdown = () => { };
+        const loop = runRunnerWithLoop(argv, {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            sleep: sleep.sleep,
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        return {
+            loop,
+            watcher,
+            tick: sleep.tick,
+            shutdown: () => triggerShutdown(),
+        };
+    }
+    it("startup runs one full reconcile, then watcher edits wait for the poll drain", async () => {
+        const runPass = vi.fn().mockResolvedValue(0);
+        const { loop, watcher, tick, shutdown } = startDrainLoop(runPass);
+        await flushLoopMicrotasks();
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual([fullArgv]);
+        runPass.mockClear();
+        watcher.emit("companies/indigo/knowledge/a.md");
+        await flushLoopMicrotasks();
+        expect(runPass).not.toHaveBeenCalled();
+        tick();
+        await flushLoopMicrotasks();
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual([
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "push",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+            fullPullArgv,
+        ]);
+        shutdown();
+        tick();
+        await loop;
+    });
+    it("coalesces repeated edits to the same path into one scoped push", async () => {
+        const runPass = vi.fn().mockResolvedValue(0);
+        const { loop, watcher, tick, shutdown } = startDrainLoop(runPass);
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        watcher.emit("companies/indigo/knowledge/a.md");
+        watcher.emit("companies/indigo/knowledge/a.md");
+        tick();
+        await flushLoopMicrotasks();
+        const pushCalls = runPass.mock.calls
+            .map((call) => call[0])
+            .filter((argv) => argv.includes("--company"));
+        expect(pushCalls).toEqual([
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "push",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+        ]);
+        shutdown();
+        tick();
+        await loop;
+    });
+    it("drains an unlink path through the same scoped tombstone push path", async () => {
+        const runPass = vi.fn().mockResolvedValue(0);
+        const { loop, watcher, tick, shutdown } = startDrainLoop(runPass);
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        watcher.emit("companies/indigo/knowledge/deleted.md");
+        tick();
+        await flushLoopMicrotasks();
+        expect(runPass.mock.calls[0][0]).toEqual([
+            "--company",
+            "indigo",
+            "--direction",
+            "push",
+            "--scope-path",
+            "knowledge/deleted.md",
+            "--hq-root",
+            "/tmp/hq",
+        ]);
+        shutdown();
+        tick();
+        await loop;
+    });
+    it("omitted --direction is pull-only (parser default): a scoped tick never pushes", async () => {
+        const runPass = vi.fn().mockResolvedValue(0);
+        // 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.
+        const pullOnlyArgv = [
+            "--companies",
+            "--watch",
+            "--event-push",
+            "--hq-root",
+            "/tmp/hq",
+            "--poll-remote-ms",
+            "60000",
+        ];
+        const { loop, watcher, tick, shutdown } = startDrainLoopWithArgv(runPass, pullOnlyArgv);
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        watcher.emit("companies/indigo/knowledge/a.md");
+        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("--company"))).toBe(false);
+        expect(calls.some((argv) => argv.includes("--direction") &&
+            argv[argv.indexOf("--direction") + 1] === "push")).toBe(false);
+        // ...only the pull leg ran.
+        expect(calls).toEqual([fullPullArgv]);
+        shutdown();
+        tick();
+        await loop;
+    });
+    it("restores failed scoped push paths so the next tick retries them", async () => {
+        const runPass = vi
+            .fn()
+            .mockResolvedValueOnce(0)
+            .mockResolvedValueOnce(1)
+            .mockResolvedValueOnce(0)
+            .mockResolvedValueOnce(0)
+            .mockResolvedValueOnce(0);
+        const { loop, watcher, tick, shutdown } = startDrainLoop(runPass);
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        watcher.emit("companies/indigo/knowledge/retry.md");
+        tick();
+        await flushLoopMicrotasks();
+        tick();
+        await flushLoopMicrotasks();
+        const pushCalls = runPass.mock.calls
+            .map((call) => call[0])
+            .filter((argv) => argv.includes("--company"));
+        expect(pushCalls).toEqual([
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "push",
+                "--scope-path",
+                "knowledge/retry.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "push",
+                "--scope-path",
+                "knowledge/retry.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+        ]);
+        shutdown();
+        tick();
+        await loop;
+    });
+    it("empty scoped ticks run only the pull leg", async () => {
+        const runPass = vi.fn().mockResolvedValue(0);
+        const { loop, tick, shutdown } = startDrainLoop(runPass);
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        tick();
+        await flushLoopMicrotasks();
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual([fullPullArgv]);
+        shutdown();
+        tick();
+        await loop;
+    });
+    it("personal scoped ticks preserve personal mode for the pull leg", async () => {
+        const runPass = vi.fn().mockResolvedValue(0);
+        const { loop, watcher, tick, shutdown } = startDrainLoopWithArgv(runPass, [
+            "--personal",
+            "--watch",
+            "--event-push",
+            "--direction",
+            "both",
+            "--hq-root",
+            "/tmp/hq",
+            "--poll-remote-ms",
+            "60000",
+        ]);
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        watcher.emit("knowledge/a.md");
+        tick();
+        await flushLoopMicrotasks();
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual([
+            [
+                "--personal",
+                "--direction",
+                "push",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+            ["--personal", "--direction", "pull", "--hq-root", "/tmp/hq"],
+        ]);
+        shutdown();
+        tick();
+        await loop;
+    });
+    it("single-company scoped ticks preserve company mode for the pull leg", async () => {
+        const runPass = vi.fn().mockResolvedValue(0);
+        const { loop, watcher, tick, shutdown } = startDrainLoopWithArgv(runPass, [
+            "--company",
+            "acme",
+            "--watch",
+            "--event-push",
+            "--direction",
+            "both",
+            "--hq-root",
+            "/tmp/hq",
+            "--poll-remote-ms",
+            "60000",
+        ]);
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        watcher.emit("companies/acme/knowledge/a.md");
+        tick();
+        await flushLoopMicrotasks();
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual([
+            [
+                "--company",
+                "acme",
+                "--direction",
+                "push",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+            ["--company", "acme", "--direction", "pull", "--hq-root", "/tmp/hq"],
+        ]);
+        shutdown();
+        tick();
+        await loop;
+    });
+    it("push-only scoped ticks run the scoped push and no pull leg", async () => {
+        const runPass = vi.fn().mockResolvedValue(0);
+        const { loop, watcher, tick, shutdown } = startDrainLoopWithArgv(runPass, [
+            "--companies",
+            "--watch",
+            "--event-push",
+            "--direction",
+            "push",
+            "--hq-root",
+            "/tmp/hq",
+            "--poll-remote-ms",
+            "60000",
+        ]);
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        watcher.emit("companies/indigo/knowledge/a.md");
+        tick();
+        await flushLoopMicrotasks();
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual([
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "push",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+        ]);
+        shutdown();
+        tick();
+        await loop;
+    });
+    it("overflow and every tenth tick run a full unscoped reconcile", async () => {
+        const watcher = makeBatchWatcherStub();
+        const sleep = makeSteppableSleep();
+        let triggerShutdown = () => { };
+        const runPass = vi.fn().mockResolvedValue(0);
+        const loop = runRunnerWithLoop(watchArgv, {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            sleep: sleep.sleep,
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        watcher.emit("companies/indigo/a.md", {
+            paths: new Map([["/tmp/hq/companies/indigo/a.md", "companies/indigo/a.md"]]),
+            overflowed: true,
+        });
+        sleep.tick();
+        await flushLoopMicrotasks();
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual([fullArgv]);
+        runPass.mockClear();
+        for (let i = 0; i < 7; i++) {
+            sleep.tick();
+            await flushLoopMicrotasks();
+        }
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual(Array.from({ length: 7 }, () => fullPullArgv));
+        runPass.mockClear();
+        sleep.tick();
+        await flushLoopMicrotasks();
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual([fullArgv]);
+        triggerShutdown();
+        sleep.tick();
+        await loop;
+    });
+});
 // ---------------------------------------------------------------------------
 // Re-initialize for each test (mock state hygiene)
 // ---------------------------------------------------------------------------
@@ -3369,12 +3925,25 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         const watcher = opts.watcher ?? makeBatchWatcherStub();
         const runPass = opts.runPass ?? vi.fn().mockResolvedValue(0);
         const clock = new FakeClock();
+        const sleep = makeSteppableSleep();
         let triggerShutdown = () => { };
-        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
+        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.
+        [
+            "--companies",
+            "--watch",
+            "--event-push",
+            "--direction",
+            "both",
+            "--hq-root",
+            "/tmp/hq",
+        ], {
             runPass,
             clock,
             createWatcher: () => watcher,
-            sleep: () => new Promise(() => { }),
+            sleep: sleep.sleep,
             onShutdownSignal: (handler) => {
                 triggerShutdown = handler;
                 return () => { };
@@ -3384,7 +3953,14 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
             startEventSync: (opts.startEventSync ??
                 vi.fn().mockResolvedValue(null)),
         });
-        return { loop, watcher, runPass, clock, shutdown: () => triggerShutdown() };
+        return {
+            loop,
+            watcher,
+            runPass,
+            clock,
+            tick: sleep.tick,
+            shutdown: () => triggerShutdown(),
+        };
     }
     async function microtasks(n = 6) {
         for (let i = 0; i < n; i++)
@@ -3436,7 +4012,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
             dispose: vi.fn().mockResolvedValue(undefined),
         });
         const runPass = vi.fn().mockResolvedValue(0);
-        const { loop, watcher, clock, shutdown } = runLoop({
+        const { loop, watcher, clock, tick, shutdown } = runLoop({
             claims: ENROLLED_CLAIMS,
             startEventSync,
             runPass,
@@ -3449,10 +4025,16 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         watcher.emit("companies/indigo/a.md", batch);
         clock.advance(0);
         await microtasks();
-        // Targeted push ran and succeeded → batch published.
+        expect(runPass).not.toHaveBeenCalled();
+        expect(publishBatch).not.toHaveBeenCalled();
+        tick();
+        await microtasks();
+        // Scoped push drained and succeeded → batch published.
         expect(runPass).toHaveBeenCalled();
         expect(publishBatch).toHaveBeenCalledTimes(1);
-        expect(publishBatch.mock.calls[0][0]).toBe(batch);
+        expect([...publishBatch.mock.calls[0][0].paths.values()]).toEqual([
+            "companies/indigo/a.md",
+        ]);
         shutdown();
         await loop;
     });
@@ -3469,7 +4051,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
             .fn()
             .mockResolvedValueOnce(0)
             .mockResolvedValue(1);
-        const { loop, watcher, clock, shutdown } = runLoop({
+        const { loop, watcher, clock, tick, shutdown } = runLoop({
             claims: ENROLLED_CLAIMS,
             startEventSync,
             runPass,
@@ -3478,6 +4060,8 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         watcher.emit("companies/indigo/a.md", { paths: new Map([["/tmp/hq/companies/indigo/a.md", "companies/indigo/a.md"]]) });
         clock.advance(0);
         await microtasks();
+        tick();
+        await microtasks();
         expect(publishBatch).not.toHaveBeenCalled();
         shutdown();
         await loop;
@@ -3491,7 +4075,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
             dispose: vi.fn().mockResolvedValue(undefined),
         });
         const runPass = vi.fn().mockResolvedValue(0);
-        const { loop, watcher, clock, shutdown } = runLoop({
+        const { loop, watcher, clock, tick, shutdown } = runLoop({
             claims: ENROLLED_CLAIMS,
             startEventSync,
             runPass,
@@ -3507,6 +4091,8 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         });
         clock.advance(0);
         await microtasks();
+        tick();
+        await microtasks();
         const pushedRoutes = new Set();
         let pushedEverything = false;
         for (const call of runPass.mock.calls) {
@@ -3518,6 +4104,9 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
             if (companyIdx >= 0) {
                 pushedRoutes.add(`company:${passArgv[companyIdx + 1]}`);
             }
+            else if (passArgv.includes("--personal")) {
+                pushedRoutes.add("personal");
+            }
             else if (passArgv.includes("--companies")) {
                 pushedEverything = true;
             }
@@ -3553,6 +4142,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         let receiverSync = null;
         const watcher = makeBatchWatcherStub();
         const clock = new FakeClock();
+        const sleep = makeSteppableSleep();
         let triggerShutdown = () => { };
         let releasePoll = () => { };
         const pollGate = new Promise((resolve) => {
@@ -3565,7 +4155,18 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
                 await pollGate;
             return 0;
         });
-        const loop = runRunnerWithLoop(["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"], {
+        const loop = runRunnerWithLoop(
+        // `--direction both` so the queued watcher pushes actually run (an omitted
+        // direction is pull-only by the parser default).
+        [
+            "--companies",
+            "--watch",
+            "--event-push",
+            "--direction",
+            "both",
+            "--hq-root",
+            "/tmp/hq",
+        ], {
             runPass,
             clock,
             createWatcher: () => watcher,
@@ -3577,7 +4178,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
                     dispose: async () => { },
                 };
             },
-            sleep: () => new Promise(() => { }),
+            sleep: sleep.sleep,
             onShutdownSignal: (handler) => {
                 triggerShutdown = handler;
                 return () => { };
@@ -3622,12 +4223,30 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         releasePoll();
         await remotePull;
         await microtasks();
-        clock.advance(0);
+        sleep.tick();
         await microtasks();
         const passArgvs = runPass.mock.calls.map((call) => call[0]);
         expect(passArgvs).toEqual(expect.arrayContaining([
-            ["--company", "indigo", "--direction", "push", "--hq-root", "/tmp/hq"],
-            ["--company", "beta", "--direction", "push", "--hq-root", "/tmp/hq"],
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "push",
+                "--scope-path",
+                "a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+            [
+                "--company",
+                "beta",
+                "--direction",
+                "push",
+                "--scope-path",
+                "b.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
             ["--company", "acme", "--direction", "pull", "--hq-root", "/tmp/hq"],
         ]));
         const pushedRoutes = new Set();
@@ -3663,7 +4282,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
             ownDeviceId: "dev-test",
             dispose: vi.fn().mockResolvedValue(undefined),
         });
-        const { loop, watcher, clock, shutdown } = runLoop({
+        const { loop, watcher, clock, tick, shutdown } = runLoop({
             claims: ENROLLED_CLAIMS,
             startEventSync,
         });
@@ -3671,6 +4290,8 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
         watcher.emit("companies/indigo/b.md"); // no batch
         clock.advance(0);
         await microtasks();
+        tick();
+        await microtasks();
         expect(publishBatch).toHaveBeenCalledTimes(1);
         const synthesized = publishBatch.mock.calls[0][0];
         expect([...synthesized.paths.values()]).toEqual(["companies/indigo/b.md"]);