@indigoai-us/hq-cloud 6.14.13 → 6.14.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "6.14.13",
+  "version": "6.14.14",
   "description": "HQ by Indigo cloud sync engine — bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/bin/sync-runner-watch-loop.ts

@@ -1,3 +1,4 @@
+import * as os from "os";
 import * as path from "path";
 import { inventoryManagedSnapshots } from "../backup-prune.js";
 import { VaultClient } from "../index.js";
@@ -40,6 +41,39 @@ import type { Direction, RunnerLoopDeps, WatcherSurface } from "./sync-runner.js
 
 const FULL_RECONCILE_EVERY_TICKS = 10;
 
+/**
+ * Adaptive remote-poll backoff bounds (whole-box CPU aware). When
+ * `--poll-remote-ms` is NOT passed, the watch loop scales its poll cadence to
+ * the host's overall load instead of using a fixed interval: ~60s when the box
+ * is idle, stretching toward ~10min under sustained full load, so the periodic
+ * pull yields CPU/I-O to whatever else is running (e.g. the user's live agent
+ * session). The poll is only a correctness backstop — event-push handles
+ * real-time — so a stale interval under load is safe. An explicit
+ * `--poll-remote-ms <n>` overrides this entirely and pins a fixed interval.
+ */
+const ADAPTIVE_POLL_FLOOR_MS = 60_000;
+const ADAPTIVE_POLL_CEIL_MS = 600_000;
+
+/**
+ * Map whole-box load to a poll interval in the [floor, ceil] range.
+ *
+ * `load1` is the 1-minute load average ({@link os.loadavg}[0]); dividing by the
+ * CPU count yields per-core saturation. ratio 0 (idle) → floor; ratio ≥ 1
+ * (fully saturated) → ceil; linear in between. Pure + injectable so the loop
+ * can be unit-tested without a real host or a 10-minute wait.
+ */
+export function adaptivePollMs(
+  load1: number,
+  cpuCount: number,
+  floorMs: number = ADAPTIVE_POLL_FLOOR_MS,
+  ceilMs: number = ADAPTIVE_POLL_CEIL_MS,
+): number {
+  const cores = cpuCount > 0 ? cpuCount : 1;
+  const saturation = load1 > 0 ? load1 / cores : 0;
+  const ratio = Math.max(0, Math.min(1, saturation));
+  return Math.round(floorMs + ratio * (ceilMs - floorMs));
+}
+
 export interface ParsedLoopArgs {
   hqRoot: string;
   lockTimeoutSec?: number;
@@ -95,8 +129,13 @@ export async function runWatchLoop(
   const runPass =
     deps.runPass ?? runtime.runPassWithOperationLockAlreadyHeld;
   const pollIdx = argv.indexOf("--poll-remote-ms");
-  const pollMs =
-    pollIdx >= 0 && argv[pollIdx + 1] ? Number(argv[pollIdx + 1]) : 600_000;
+  // An explicit --poll-remote-ms pins a fixed interval (menubar/CLI still set
+  // one). When it is omitted, the interval is resolved fresh each cycle from
+  // whole-box load via adaptivePollMs() — see the sleep at the loop's tail.
+  const explicitPollMs =
+    pollIdx >= 0 && argv[pollIdx + 1] ? Number(argv[pollIdx + 1]) : undefined;
+  const sampleLoadAvg = deps.sampleLoadAvg ?? (() => os.loadavg()[0]);
+  const cpuCount = os.cpus().length;
   const eventPush = argv.includes("--event-push");
   const companiesMode = argv.includes("--companies");
   const hqRoot = parsed.hqRoot;
@@ -534,7 +573,9 @@ export async function runWatchLoop(
         try { await runBackupPrune(hqRoot); }
         catch (error) { process.stderr.write(`hq-sync-runner: backup retention dry-run failed — ${error instanceof Error ? error.message : String(error)}\n`); }
       }
-      await Promise.race([sleep(pollMs), stoppedSignal]);
+      const nextPollMs =
+        explicitPollMs ?? adaptivePollMs(sampleLoadAvg(), cpuCount);
+      await Promise.race([sleep(nextPollMs), stoppedSignal]);
     }
     return 0;
   } finally {

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

@@ -34,6 +34,7 @@ import type {
   WatcherSurface,
 } from "./sync-runner.js";
 import { FakeClock } from "../watcher.js";
+import { adaptivePollMs } from "./sync-runner-watch-loop.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";
@@ -3577,6 +3578,127 @@ function makeSteppableSleep() {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Adaptive remote-poll backoff — whole-box CPU aware (no --poll-remote-ms)
+// ---------------------------------------------------------------------------
+
+describe("adaptivePollMs (whole-box CPU backoff)", () => {
+  const FLOOR = 60_000;
+  const CEIL = 600_000;
+
+  it("returns the floor when the box is idle (load 0)", () => {
+    expect(adaptivePollMs(0, 8)).toBe(FLOOR);
+  });
+
+  it("returns the ceiling when load equals the core count (fully saturated)", () => {
+    expect(adaptivePollMs(8, 8)).toBe(CEIL);
+  });
+
+  it("clamps to the ceiling when load exceeds the core count", () => {
+    expect(adaptivePollMs(64, 8)).toBe(CEIL);
+  });
+
+  it("scales linearly between floor and ceiling at half saturation", () => {
+    // load 4 on 8 cores → ratio 0.5 → midpoint of [60s, 600s] = 330s.
+    expect(adaptivePollMs(4, 8)).toBe(330_000);
+  });
+
+  it("treats a negative load sample as idle (defensive)", () => {
+    expect(adaptivePollMs(-1, 8)).toBe(FLOOR);
+  });
+
+  it("guards a zero/absent core count without dividing by zero", () => {
+    // cores coerced to 1; load 1 → fully saturated → ceil.
+    expect(adaptivePollMs(1, 0)).toBe(CEIL);
+  });
+
+  it("honors custom floor/ceil bounds", () => {
+    expect(adaptivePollMs(0, 4, 30_000, 300_000)).toBe(30_000);
+    expect(adaptivePollMs(4, 4, 30_000, 300_000)).toBe(300_000);
+  });
+});
+
+describe("runRunnerWithLoop — adaptive poll interval (no --poll-remote-ms)", () => {
+  // Capture the ms handed to sleep on the FIRST poll, then hang so the loop
+  // parks until shutdown (mirrors the never-resolving sleep the other loop
+  // tests use).
+  function makeCapturingSleep() {
+    const calls: number[] = [];
+    return {
+      calls,
+      sleep: (ms: number) => {
+        calls.push(ms);
+        return new Promise<void>(() => {});
+      },
+    };
+  }
+
+  it("sleeps the floor interval when the box is idle", async () => {
+    const { calls, sleep } = makeCapturingSleep();
+    let triggerShutdown = () => {};
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--hq-root", "/tmp/hq"],
+      {
+        runPass: vi.fn().mockResolvedValue(0),
+        sleep,
+        sampleLoadAvg: () => 0,
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+      },
+    );
+    await flushLoopMicrotasks();
+    expect(calls[0]).toBe(60_000);
+    triggerShutdown();
+    await loop;
+  });
+
+  it("backs off to the ceiling interval when the box is fully loaded", async () => {
+    const { calls, sleep } = makeCapturingSleep();
+    let triggerShutdown = () => {};
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--hq-root", "/tmp/hq"],
+      {
+        runPass: vi.fn().mockResolvedValue(0),
+        sleep,
+        sampleLoadAvg: () => 1_000, // far above any core count → clamps to ceil
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+      },
+    );
+    await flushLoopMicrotasks();
+    expect(calls[0]).toBe(600_000);
+    triggerShutdown();
+    await loop;
+  });
+
+  it("an explicit --poll-remote-ms pins a fixed interval and ignores load", async () => {
+    const { calls, sleep } = makeCapturingSleep();
+    const sampleLoadAvg = vi.fn(() => 1_000);
+    let triggerShutdown = () => {};
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--poll-remote-ms", "123456", "--hq-root", "/tmp/hq"],
+      {
+        runPass: vi.fn().mockResolvedValue(0),
+        sleep,
+        sampleLoadAvg,
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+      },
+    );
+    await flushLoopMicrotasks();
+    expect(calls[0]).toBe(123456);
+    expect(sampleLoadAvg).not.toHaveBeenCalled();
+    triggerShutdown();
+    await loop;
+  });
+});
+
 describe("runRunnerWithLoop — event-push wiring", () => {
   it("starts the watcher alongside the poll loop when --event-push is on", async () => {
     const watcher = makeWatcherStub();

package/src/bin/sync-runner.ts

@@ -1741,6 +1741,13 @@ const isDirectInvocation = (() => {
 export interface RunnerLoopDeps {
   /** Sleep `ms` between passes. Default: host setTimeout. */
   sleep?: (ms: number) => Promise<void>;
+  /**
+   * 1-minute whole-box load average source for the adaptive remote-poll
+   * backoff (used only when `--poll-remote-ms` is omitted). Defaults to
+   * `os.loadavg()[0]`. Tests inject a fixed sample to assert the interval
+   * scales with load without depending on the host's real load.
+   */
+  sampleLoadAvg?: () => number;
   /**
    * Run a single sync pass. Defaults to {@link runRunner}. Injected by tests
    * (and the event-push wiring) so the poll loop and the watcher-triggered