@indigoai-us/hq-cloud 6.15.31 → 6.15.32

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

@@ -12,6 +12,7 @@ import * as os from "os";
 import * as path from "path";
 import { runRunner, runRunnerWithLoop, resolveDeletePolicy, resolveSkipPersonal, resolveSkipCompanies, selectObjectIOFactory, routeChangeToTarget, buildTargetedPushArgv, resolvePullScope, readPinnedPrefixes, SESSIONS_SCOPE_PREFIX, defaultCollectTelemetry, AUTH_REQUIRED_PASS_EXIT, } from "./sync-runner.js";
 import { PresignObjectIO, S3SdkObjectIO } from "../object-io.js";
+import { setBandwidthGovernorForTesting } from "../bandwidth.js";
 import { FakeClock, } from "../watcher.js";
 import { adaptivePollMs, advanceMonotonicDeadline, journalEntriesForWatcherDelete, shouldQuarantineWatcherDeleteIntents, } from "./sync-runner-watch-loop.js";
 import { PERSONAL_VAULT_JOURNAL_SLUG, readJournal, writeJournal, } from "../journal.js";
@@ -215,6 +216,63 @@ describe("argv parsing", () => {
     });
 });
 // ---------------------------------------------------------------------------
+// bandwidth governor startup line
+// ---------------------------------------------------------------------------
+describe("bandwidth governor startup line", () => {
+    const ENV_KEYS = [
+        "HQ_SYNC_MAX_BYTES_PER_SEC",
+        "HQ_SYNC_MAX_CONCURRENCY",
+        "HQ_SYNC_BANDWIDTH_PERCENT",
+    ];
+    let saved;
+    beforeEach(() => {
+        saved = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+        for (const k of ENV_KEYS)
+            delete process.env[k];
+        setBandwidthGovernorForTesting(null); // re-read env per test
+    });
+    afterEach(() => {
+        for (const k of ENV_KEYS) {
+            if (saved[k] === undefined)
+                delete process.env[k];
+            else
+                process.env[k] = saved[k];
+        }
+        setBandwidthGovernorForTesting(null);
+    });
+    it("states the effective policy on stderr when the env vars are set", async () => {
+        process.env.HQ_SYNC_MAX_BYTES_PER_SEC = "500000";
+        process.env.HQ_SYNC_MAX_CONCURRENCY = "2";
+        const deps = makeDeps({
+            createVaultClient: () => makeVaultStub({ memberships: [] }),
+        });
+        const code = await runRunner(["--companies"], deps);
+        expect(code).toBe(0);
+        expect(deps.stderr.events()).toContainEqual({
+            type: "bandwidth-policy",
+            message: "bandwidth governor: 500000 B/s cap, concurrency 2",
+        });
+    });
+    it("stays silent (exact legacy stream) when no policy is configured", async () => {
+        const deps = makeDeps({
+            createVaultClient: () => makeVaultStub({ memberships: [] }),
+        });
+        const code = await runRunner(["--companies"], deps);
+        expect(code).toBe(0);
+        expect(deps.stderr.events().some((e) => e.type === "bandwidth-policy")).toBe(false);
+    });
+    it("treats invalid env values as off (no policy line)", async () => {
+        process.env.HQ_SYNC_MAX_BYTES_PER_SEC = "0";
+        process.env.HQ_SYNC_BANDWIDTH_PERCENT = "101";
+        const deps = makeDeps({
+            createVaultClient: () => makeVaultStub({ memberships: [] }),
+        });
+        const code = await runRunner(["--companies"], deps);
+        expect(code).toBe(0);
+        expect(deps.stderr.events().some((e) => e.type === "bandwidth-policy")).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
 // auth
 // ---------------------------------------------------------------------------
 describe("auth", () => {
@@ -4523,7 +4581,18 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
                 "--hq-root",
                 "/tmp/hq",
             ],
-            fullPullArgv,
+            // The drain pull is route-targeted AND path-scoped now: it lists only
+            // the touched subtree instead of running a full --companies pull.
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "pull",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
         ]);
         shutdown();
         tick();
@@ -4540,7 +4609,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         await flushLoopMicrotasks();
         const pushCalls = runPass.mock.calls
             .map((call) => call[0])
-            .filter((argv) => argv.includes("--company"));
+            .filter((argv) => argv.includes("--company") && argv.includes("push"));
         expect(pushCalls).toEqual([
             [
                 "--company",
@@ -4620,11 +4689,21 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         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]);
+        // ...only the pull leg ran — route-targeted and path-scoped now.
+        expect(calls).toEqual([
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "pull",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+        ]);
         shutdown();
         tick();
         await loop;
@@ -4647,7 +4726,7 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         await flushLoopMicrotasks();
         const pushCalls = runPass.mock.calls
             .map((call) => call[0])
-            .filter((argv) => argv.includes("--company"));
+            .filter((argv) => argv.includes("--company") && argv.includes("push"));
         expect(pushCalls).toEqual([
             [
                 "--company",
@@ -4714,7 +4793,17 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
                 "--hq-root",
                 "/tmp/hq",
             ],
-            ["--personal", "--direction", "pull", "--hq-root", "/tmp/hq"],
+            // Path-scoped now: the personal pull leg lists only the touched
+            // subtree instead of re-walking the whole vault on every event batch.
+            [
+                "--personal",
+                "--direction",
+                "pull",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
         ]);
         shutdown();
         tick();
@@ -4750,7 +4839,16 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
                 "--hq-root",
                 "/tmp/hq",
             ],
-            ["--company", "acme", "--direction", "pull", "--hq-root", "/tmp/hq"],
+            [
+                "--company",
+                "acme",
+                "--direction",
+                "pull",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
         ]);
         shutdown();
         tick();
@@ -4828,6 +4926,245 @@ describe("runRunnerWithLoop — accumulate-and-drain scoped push", () => {
         sleep.tick();
         await loop;
     });
+    it("overflow with known dropped-route hints fans out per touched route instead of a full reconcile", async () => {
+        const watcher = makeBatchWatcherStub();
+        const sleep = makeSteppableSleep();
+        let triggerShutdown = () => { };
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
+        const loop = runRunnerWithLoop(watchArgv, {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: () => watcher,
+            sleep: sleep.sleep,
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        // A burst overflowed, but every dropped path recorded route evidence:
+        // retained path in indigo, dropped paths in acme. The drain must run one
+        // whole-route pass per touched route — never the all-companies fanout.
+        watcher.emit("companies/indigo/a.md", {
+            paths: new Map([
+                ["/tmp/hq/companies/indigo/a.md", "companies/indigo/a.md"],
+            ]),
+            overflowed: true,
+            droppedPaths: 3,
+            droppedRouteHints: ["companies/acme/dropped.md"],
+        });
+        sleep.tick();
+        // Four guarded passes run sequentially — give the loop room to finish.
+        await flushLoopMicrotasks(40);
+        const calls = runPass.mock.calls.map((call) => call[0]);
+        expect(calls).toEqual([
+            // indigo: whole-route push (no --scope-path — dropped paths unknown)…
+            ["--company", "indigo", "--direction", "push", "--hq-root", "/tmp/hq"],
+            // …then the route's pull.
+            ["--company", "indigo", "--direction", "pull", "--hq-root", "/tmp/hq"],
+            ["--company", "acme", "--direction", "push", "--hq-root", "/tmp/hq"],
+            ["--company", "acme", "--direction", "pull", "--hq-root", "/tmp/hq"],
+        ]);
+        expect(calls).not.toContainEqual(fullArgv);
+        triggerShutdown();
+        await loop;
+    });
+    it("falls back to a full reconcile when an event batch exceeds HQ_SYNC_EVENT_BATCH_LIMIT", async () => {
+        const saved = process.env.HQ_SYNC_EVENT_BATCH_LIMIT;
+        process.env.HQ_SYNC_EVENT_BATCH_LIMIT = "2";
+        try {
+            const watcher = makeBatchWatcherStub();
+            const sleep = makeSteppableSleep();
+            let triggerShutdown = () => { };
+            const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
+            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"],
+                    ["/tmp/hq/companies/indigo/b.md", "companies/indigo/b.md"],
+                    ["/tmp/hq/companies/indigo/c.md", "companies/indigo/c.md"],
+                ]),
+            });
+            sleep.tick();
+            await flushLoopMicrotasks();
+            // Mass change: one full reconcile, no per-path scoped passes.
+            expect(runPass.mock.calls.map((call) => call[0])).toEqual([fullArgv]);
+            triggerShutdown();
+            await loop;
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.HQ_SYNC_EVENT_BATCH_LIMIT;
+            else
+                process.env.HQ_SYNC_EVENT_BATCH_LIMIT = saved;
+        }
+    });
+    it("a batch under the default limit stays on the targeted path", async () => {
+        const watcher = makeBatchWatcherStub();
+        const sleep = makeSteppableSleep();
+        let triggerShutdown = () => { };
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
+        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"],
+                ["/tmp/hq/companies/indigo/b.md", "companies/indigo/b.md"],
+                ["/tmp/hq/companies/indigo/c.md", "companies/indigo/c.md"],
+            ]),
+        });
+        sleep.tick();
+        await flushLoopMicrotasks();
+        const calls = runPass.mock.calls.map((call) => call[0]);
+        expect(calls).not.toContainEqual(fullArgv);
+        expect(calls[0]).toEqual([
+            "--company",
+            "indigo",
+            "--direction",
+            "push",
+            "--scope-path",
+            "a.md",
+            "--scope-path",
+            "b.md",
+            "--scope-path",
+            "c.md",
+            "--hq-root",
+            "/tmp/hq",
+        ]);
+        triggerShutdown();
+        await loop;
+    });
+    it("a throwing targeted pass falls back to one full reconcile instead of dropping the change", async () => {
+        const runPass = vi.fn(async (argv) => {
+            if (argv.includes("pull") && argv.includes("--scope-path")) {
+                throw new Error("scoped pull exploded");
+            }
+            return completedPassOutcome();
+        });
+        const { loop, watcher, tick, shutdown } = startDrainLoop(runPass);
+        await flushLoopMicrotasks();
+        runPass.mockClear();
+        watcher.emit("companies/indigo/knowledge/a.md");
+        tick();
+        await flushLoopMicrotasks(40);
+        expect(runPass.mock.calls.map((call) => call[0])).toEqual([
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "push",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+            // The scoped pull throws…
+            [
+                "--company",
+                "indigo",
+                "--direction",
+                "pull",
+                "--scope-path",
+                "knowledge/a.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
+            // …and the loop degrades to the full reconcile, never dropping the tick.
+            fullArgv,
+        ]);
+        shutdown();
+        tick();
+        await loop;
+    });
+    it("wires the event debounce config (default 15s quiet / 120s max-wait) into the watcher factory", async () => {
+        const captured = [];
+        const watcher = makeWatcherStub();
+        const sleep = makeSteppableSleep();
+        let triggerShutdown = () => { };
+        const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
+        const loop = runRunnerWithLoop(watchArgv, {
+            runPass,
+            clock: new FakeClock(),
+            createWatcher: (opts) => {
+                captured.push({ debounceMs: opts.debounceMs, maxWaitMs: opts.maxWaitMs });
+                return watcher;
+            },
+            sleep: sleep.sleep,
+            onShutdownSignal: (handler) => {
+                triggerShutdown = handler;
+                return () => { };
+            },
+        });
+        await flushLoopMicrotasks();
+        expect(captured).toEqual([{ debounceMs: 15_000, maxWaitMs: 120_000 }]);
+        triggerShutdown();
+        await loop;
+    });
+    it("HQ_SYNC_EVENT_DEBOUNCE_MS / HQ_SYNC_EVENT_MAX_WAIT_MS override the watcher debounce", async () => {
+        const savedDebounce = process.env.HQ_SYNC_EVENT_DEBOUNCE_MS;
+        const savedMaxWait = process.env.HQ_SYNC_EVENT_MAX_WAIT_MS;
+        process.env.HQ_SYNC_EVENT_DEBOUNCE_MS = "5000";
+        process.env.HQ_SYNC_EVENT_MAX_WAIT_MS = "45000";
+        try {
+            const captured = [];
+            const watcher = makeWatcherStub();
+            const sleep = makeSteppableSleep();
+            let triggerShutdown = () => { };
+            const runPass = vi.fn().mockResolvedValue(completedPassOutcome());
+            const loop = runRunnerWithLoop(watchArgv, {
+                runPass,
+                clock: new FakeClock(),
+                createWatcher: (opts) => {
+                    captured.push({
+                        debounceMs: opts.debounceMs,
+                        maxWaitMs: opts.maxWaitMs,
+                    });
+                    return watcher;
+                },
+                sleep: sleep.sleep,
+                onShutdownSignal: (handler) => {
+                    triggerShutdown = handler;
+                    return () => { };
+                },
+            });
+            await flushLoopMicrotasks();
+            expect(captured).toEqual([{ debounceMs: 5000, maxWaitMs: 45_000 }]);
+            triggerShutdown();
+            await loop;
+        }
+        finally {
+            if (savedDebounce === undefined)
+                delete process.env.HQ_SYNC_EVENT_DEBOUNCE_MS;
+            else
+                process.env.HQ_SYNC_EVENT_DEBOUNCE_MS = savedDebounce;
+            if (savedMaxWait === undefined)
+                delete process.env.HQ_SYNC_EVENT_MAX_WAIT_MS;
+            else
+                process.env.HQ_SYNC_EVENT_MAX_WAIT_MS = savedMaxWait;
+        }
+    });
 });
 // ---------------------------------------------------------------------------
 // Re-initialize for each test (mock state hygiene)
@@ -6050,7 +6387,17 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
                 "--hq-root",
                 "/tmp/hq",
             ],
-            ["--company", "acme", "--direction", "pull", "--hq-root", "/tmp/hq"],
+            // The receiver's targeted pull is path-scoped to the pushed key now.
+            [
+                "--company",
+                "acme",
+                "--direction",
+                "pull",
+                "--scope-path",
+                "remote.md",
+                "--hq-root",
+                "/tmp/hq",
+            ],
         ]));
         const pushedRoutes = new Set();
         for (const passArgv of passArgvs) {
@@ -6151,7 +6498,7 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
 // the differential signal for "did telemetry run".
 // ---------------------------------------------------------------------------
 describe("defaultCollectTelemetry person-entity gate", () => {
-    function makeTelemetryClient(persons) {
+    function makeTelemetryClient(persons, agents = []) {
         const calls = {
             listByType: 0,
             getTelemetryOptIn: 0,
@@ -6161,9 +6508,9 @@ describe("defaultCollectTelemetry person-entity gate", () => {
         const client = {
             entity: {
                 get: async () => ({}),
-                listByType: async (_type) => {
+                listByType: async (type) => {
                     calls.listByType++;
-                    return persons;
+                    return type === "agent" ? agents : persons;
                 },
             },
             // Telemetry surface (cast-to internally by defaultCollectTelemetry). With
@@ -6198,7 +6545,7 @@ describe("defaultCollectTelemetry person-entity gate", () => {
         try {
             const { client, calls } = makeTelemetryClient([]); // unprovisioned caller
             await defaultCollectTelemetry(client, false, hqRoot);
-            expect(calls.listByType).toBe(1); // orphan-safe probe ran
+            expect(calls.listByType).toBe(2); // person probe then agent probe
             expect(calls.getTelemetryOptIn).toBe(0); // collectors never ran
             expect(calls.postUsage).toBe(0);
             expect(calls.postSkillInvocations).toBe(0);
@@ -6220,6 +6567,79 @@ describe("defaultCollectTelemetry person-entity gate", () => {
             fs.rmSync(hqRoot, { recursive: true, force: true });
         }
     });
+    it("runs telemetry for an agent machine identity with no person entity", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-tele-agent-"));
+        try {
+            const AGENT = {
+                uid: "agt_01KUSAGEAGENTTEST00000000",
+                type: "agent",
+                slug: "jeff",
+                status: "active",
+                bucketName: "hq-vault-agt_01KUSAGEAGENTTEST00000000",
+                createdAt: "2026-06-01T00:00:00Z",
+            };
+            const { client, calls } = makeTelemetryClient([], [AGENT]);
+            await defaultCollectTelemetry(client, false, hqRoot, undefined, undefined, AGENT.uid);
+            expect(calls.listByType).toBe(2);
+            // Both collectors forceCollect — neither probes GET /v1/usage/opt-in.
+            expect(calls.getTelemetryOptIn).toBe(0);
+            // Passed the gate: identity resolution writes machine-id before collecting.
+            expect(fs.existsSync(path.join(hqRoot, ".hq", "machine-id"))).toBe(true);
+        }
+        finally {
+            fs.rmSync(hqRoot, { recursive: true, force: true });
+        }
+    });
+    it("does not force-collect when a claimed agent uid is absent from the self-listing", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-tele-agent-miss-"));
+        try {
+            const AGENT = {
+                uid: "agt_01KUSAGEAGENTTEST00000000",
+                type: "agent",
+                slug: "jeff",
+                status: "active",
+                bucketName: "hq-vault-agt_01KUSAGEAGENTTEST00000000",
+                createdAt: "2026-06-01T00:00:00Z",
+            };
+            const { client, calls } = makeTelemetryClient([], [AGENT]);
+            await defaultCollectTelemetry(client, false, hqRoot, undefined, undefined, "agt_01KSOMEONEELSE00000000000");
+            expect(calls.listByType).toBe(2);
+            expect(calls.getTelemetryOptIn).toBe(0);
+            expect(fs.existsSync(path.join(hqRoot, ".hq", "machine-id"))).toBe(false);
+        }
+        finally {
+            fs.rmSync(hqRoot, { recursive: true, force: true });
+        }
+    });
+    it("does not treat any agt_ listing as self when more than one agent is visible", async () => {
+        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-tele-agent-many-"));
+        try {
+            const a = {
+                uid: "agt_01KUSAGEAGENTTEST00000000",
+                type: "agent",
+                slug: "jeff",
+                status: "active",
+                bucketName: "hq-vault-agt_01KUSAGEAGENTTEST00000000",
+                createdAt: "2026-06-01T00:00:00Z",
+            };
+            const b = {
+                uid: "agt_01KUSAGEAGENTOTHER0000000",
+                type: "agent",
+                slug: "cx",
+                status: "active",
+                bucketName: "hq-vault-agt_01KUSAGEAGENTOTHER0000000",
+                createdAt: "2026-06-02T00:00:00Z",
+            };
+            const { client, calls } = makeTelemetryClient([], [a, b]);
+            await defaultCollectTelemetry(client, false, hqRoot);
+            expect(calls.listByType).toBe(2);
+            expect(calls.getTelemetryOptIn).toBe(0);
+            expect(fs.existsSync(path.join(hqRoot, ".hq", "machine-id"))).toBe(false);
+        }
+        finally {
+            fs.rmSync(hqRoot, { recursive: true, force: true });
+        }
+    });
     it("fails open: a thrown person probe still lets telemetry run (no provisioned-user regression)", async () => {
         const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-tele-throw-"));
         try {