@indigoai-us/hq-cloud 6.13.4 → 6.14.0

package/src/bin/sync-runner.test.ts

@@ -35,6 +35,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 type { SyncResult, SyncOptions } from "../cli/sync.js";
 import type { ShareResult, ShareOptions } from "../cli/share.js";
 import type {
@@ -397,6 +399,49 @@ describe("memberships retry", () => {
     });
   });
 
+  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();
@@ -1936,6 +1981,101 @@ describe("--direction", () => {
     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: string) =>
+            Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
+        }),
+      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] as [ShareOptions])[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: string) =>
+            Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
+        }),
+      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] as [ShareOptions])[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: string) =>
+            Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
+        }),
+      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] as [ShareOptions])[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
@@ -1971,6 +2111,92 @@ describe("--direction", () => {
     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: string) =>
+          Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
+      }),
+      getMembershipSyncConfig: async () => ({
+        membershipId: "mk_a",
+        syncMode: "shared",
+        isDefault: false,
+      }),
+      listMyExplicitGrants: async () => [
+        { companyUid: "cmp_a", path: "knowledge/", permission: "read", source: "person" },
+      ],
+    } as unknown as ReturnType<typeof makeVaultStub>;
+    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] as [ShareOptions])[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: string) =>
+          Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
+      }),
+      getMembershipSyncConfig: async () => ({
+        membershipId: "mk_a",
+        syncMode: "shared",
+        isDefault: false,
+      }),
+      listMyExplicitGrants: async () => [
+        { companyUid: "cmp_a", path: "policies/", permission: "read", source: "person" },
+      ],
+    } as unknown as ReturnType<typeof makeVaultStub>;
+    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] as [ShareOptions])[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: Record<string, string> = { cmp_a: "acme", cmp_b: "beta" };
     const deps = makeDeps({
@@ -2948,6 +3174,25 @@ function makeWatcherStub(): WatcherStub {
   return stub;
 }
 
+async function flushLoopMicrotasks(n = 8) {
+  for (let i = 0; i < n; i++) await Promise.resolve();
+}
+
+function makeSteppableSleep() {
+  const pending: Array<() => void> = [];
+  return {
+    sleep: () =>
+      new Promise<void>((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();
@@ -2979,7 +3224,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
     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 = () => {};
@@ -3010,24 +3255,13 @@ describe("runRunnerWithLoop — event-push wiring", () => {
     await Promise.resolve();
     await Promise.resolve();
 
-    const targetedCall = runPass.mock.calls.find((c) =>
-      (c[0] as string[]).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 = () => {};
@@ -3056,19 +3290,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
     await Promise.resolve();
     await Promise.resolve();
 
-    const personalCall = runPass.mock.calls.find(
-      (c) =>
-        (c[0] as string[]).includes("--companies") &&
-        (c[0] as string[]).includes("--direction"),
-    );
-    expect(personalCall).toBeDefined();
-    expect(personalCall![0]).toEqual([
-      "--companies",
-      "--direction",
-      "push",
-      "--hq-root",
-      "/tmp/hq",
-    ]);
+    expect(runPass).not.toHaveBeenCalled();
 
     triggerShutdown();
     await loop;
@@ -3138,7 +3360,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
     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 = () => {};
@@ -3195,14 +3417,7 @@ describe("runRunnerWithLoop — event-push wiring", () => {
     const targetedCall = runPass.mock.calls.find((c) =>
       (c[0] as string[]).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 () => {
@@ -3307,6 +3522,39 @@ describe("runRunnerWithLoop — event-push wiring", () => {
     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());
@@ -3331,6 +3579,419 @@ describe("runRunnerWithLoop — event-push wiring", () => {
   });
 });
 
+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: ReturnType<typeof vi.fn>) {
+    return startDrainLoopWithArgv(runPass, watchArgv);
+  }
+
+  function startDrainLoopWithArgv(
+    runPass: ReturnType<typeof vi.fn>,
+    argv: string[],
+  ) {
+    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] as string[])
+      .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] as string[]);
+    // 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] as string[])
+      .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,
+    } as never);
+    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)
 // ---------------------------------------------------------------------------
@@ -4226,14 +4887,26 @@ 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"],
+      // `--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<void>(() => {}),
+        sleep: sleep.sleep,
         onShutdownSignal: (handler) => {
           triggerShutdown = handler;
           return () => {};
@@ -4244,7 +4917,14 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
           vi.fn().mockResolvedValue(null)) as never,
       },
     );
-    return { loop, watcher, runPass, clock, shutdown: () => triggerShutdown() };
+    return {
+      loop,
+      watcher,
+      runPass,
+      clock,
+      tick: sleep.tick,
+      shutdown: () => triggerShutdown(),
+    };
   }
 
   async function microtasks(n = 6) {
@@ -4300,7 +4980,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,
@@ -4314,11 +4994,18 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
     watcher.emit("companies/indigo/a.md", batch);
     clock.advance(0);
     await microtasks();
+    expect(runPass).not.toHaveBeenCalled();
+    expect(publishBatch).not.toHaveBeenCalled();
 
-    // Targeted push ran and succeeded → batch published.
+    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;
@@ -4337,7 +5024,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,
@@ -4350,6 +5037,8 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
     );
     clock.advance(0);
     await microtasks();
+    tick();
+    await microtasks();
 
     expect(publishBatch).not.toHaveBeenCalled();
     shutdown();
@@ -4365,7 +5054,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,
@@ -4382,6 +5071,8 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
     });
     clock.advance(0);
     await microtasks();
+    tick();
+    await microtasks();
 
     const pushedRoutes = new Set<string>();
     let pushedEverything = false;
@@ -4392,6 +5083,8 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
       const companyIdx = passArgv.indexOf("--company");
       if (companyIdx >= 0) {
         pushedRoutes.add(`company:${passArgv[companyIdx + 1]}`);
+      } else if (passArgv.includes("--personal")) {
+        pushedRoutes.add("personal");
       } else if (passArgv.includes("--companies")) {
         pushedEverything = true;
       }
@@ -4433,6 +5126,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
       | null = null;
     const watcher = makeBatchWatcherStub();
     const clock = new FakeClock();
+    const sleep = makeSteppableSleep();
     let triggerShutdown = () => {};
     let releasePoll: () => void = () => {};
     const pollGate = new Promise<void>((resolve) => {
@@ -4446,7 +5140,17 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
     });
 
     const loop = runRunnerWithLoop(
-      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      // `--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,
@@ -4459,7 +5163,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
             dispose: async () => {},
           };
         },
-        sleep: () => new Promise<void>(() => {}),
+        sleep: sleep.sleep,
         onShutdownSignal: (handler) => {
           triggerShutdown = handler;
           return () => {};
@@ -4508,14 +5212,32 @@ 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] as string[]);
     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"],
       ]),
     );
@@ -4556,7 +5278,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,
     });
@@ -4565,6 +5287,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] as {