From c5bc2c17544c4d30eb456090e056809d720aaa4d Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Mon, 16 Feb 2026 21:56:25 -0800
Subject: [PATCH] fix(companion): normalize heartbeat jitter random samples

---
 README.md                           |  2 +-
 docs/plans/state.json               | 13 +++++++++++++
 src/companion/heartbeatLoop.test.ts | 26 ++++++++++++++++++++++++++
 src/companion/heartbeatLoop.ts      |  3 ++-
 4 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 72539e8..fe715cc 100644
--- a/README.md
+++ b/README.md
@@ -1202,7 +1202,7 @@ Companion runtime helper:
   - lifecycle passthroughs for connection state/teardown (`connected`, `dispose(code?, reason?)`)
   - stream passthrough helpers (`subscribeEvents`, `subscribeEvent`, `clearEventSubscriptions`, `listKnownEventNames`, `eventSubscriptionCount`, `subscribeAgentStream/Typing/ContextWarning`, `waitForEvent`, `waitForAnyEvent`, `waitForAgentStream/Typing/ContextWarning`)
   - runtime observability/control passthroughs (`pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `connected`, `waitForIdle()`)
-- `src/companion/heartbeatLoop.ts` provides `CompanionHeartbeatLoop` for periodic heartbeat scheduling (`publishHeartbeat`) with start/stop safety, optional interval jitter (`jitterRatio`) to spread load, `tickNow()` for manual sends, success/error hooks, loop observability (`successCount`, `lastSuccessAt`, `failureCount`, `lastFailure`, `getState()`), and optional auto-stop after repeated failures.
+- `src/companion/heartbeatLoop.ts` provides `CompanionHeartbeatLoop` for periodic heartbeat scheduling (`publishHeartbeat`) with start/stop safety, optional interval jitter (`jitterRatio`) to spread load (with safe normalization for invalid random samples), `tickNow()` for manual sends, success/error hooks, loop observability (`successCount`, `lastSuccessAt`, `failureCount`, `lastFailure`, `getState()`), and optional auto-stop after repeated failures.
 
 ## Canvas / A2UI Foundation
 
diff --git a/docs/plans/state.json b/docs/plans/state.json
index cb9dbd2..55ebd8e 100644
--- a/docs/plans/state.json
+++ b/docs/plans/state.json
@@ -950,6 +950,19 @@
       ],
       "test_status": "pnpm test:run src/companion/runtimeClient.test.ts src/companion/platformClients.test.ts src/companion/heartbeatLoop.test.ts src/companion/platformClients.integration.test.ts + pnpm typecheck passing"
     },
+    "companion-heartbeat-loop-jitter-sample-normalization": {
+      "status": "completed",
+      "date": "2026-02-17",
+      "updated": "2026-02-17",
+      "summary": "Hardened heartbeat jitter scheduling by normalizing invalid `randomFn` samples (NaN/out-of-range) before delay calculation, with regression coverage for clamped/fallback behavior.",
+      "files_modified": [
+        "src/companion/heartbeatLoop.ts",
+        "src/companion/heartbeatLoop.test.ts",
+        "README.md",
+        "docs/plans/state.json"
+      ],
+      "test_status": "pnpm test:run src/companion/heartbeatLoop.test.ts src/companion/platformClients.test.ts src/companion/runtimeClient.test.ts src/companion/platformClients.integration.test.ts + pnpm typecheck passing"
+    },
     "browser-tools-activation-clarity": {
       "status": "completed",
       "date": "2026-02-17",
diff --git a/src/companion/heartbeatLoop.test.ts b/src/companion/heartbeatLoop.test.ts
index bcaa06b..21fe45f 100644
--- a/src/companion/heartbeatLoop.test.ts
+++ b/src/companion/heartbeatLoop.test.ts
@@ -81,6 +81,32 @@ describe('CompanionHeartbeatLoop', () => {
     loop.stop();
   });
 
+  it('normalizes invalid randomFn samples for jitter scheduling', async () => {
+    const publishHeartbeatHigh = vi.fn(async () => buildStatusResult());
+    const loopHigh = new CompanionHeartbeatLoop(
+      { publishHeartbeat: publishHeartbeatHigh },
+      { intervalMs: 1000, jitterRatio: 0.5, randomFn: () => 2 },
+    );
+    loopHigh.start(false);
+    await vi.advanceTimersByTimeAsync(1499);
+    expect(publishHeartbeatHigh).toHaveBeenCalledTimes(0);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(publishHeartbeatHigh).toHaveBeenCalledTimes(1);
+    loopHigh.stop();
+
+    const publishHeartbeatNaN = vi.fn(async () => buildStatusResult());
+    const loopNaN = new CompanionHeartbeatLoop(
+      { publishHeartbeat: publishHeartbeatNaN },
+      { intervalMs: 1000, jitterRatio: 0.5, randomFn: () => Number.NaN },
+    );
+    loopNaN.start(false);
+    await vi.advanceTimersByTimeAsync(999);
+    expect(publishHeartbeatNaN).toHaveBeenCalledTimes(0);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(publishHeartbeatNaN).toHaveBeenCalledTimes(1);
+    loopNaN.stop();
+  });
+
   it('calls onSuccess with heartbeat result payload', async () => {
     const result = buildStatusResult();
     const publishHeartbeat = vi.fn(async () => result);
diff --git a/src/companion/heartbeatLoop.ts b/src/companion/heartbeatLoop.ts
index 7d890a9..80260a4 100644
--- a/src/companion/heartbeatLoop.ts
+++ b/src/companion/heartbeatLoop.ts
@@ -154,7 +154,8 @@ export class CompanionHeartbeatLoop {
     }
     const minFactor = 1 - this.jitterRatio;
     const maxFactor = 1 + this.jitterRatio;
-    const random = this.randomFn();
+    const sampled = this.randomFn();
+    const random = Number.isFinite(sampled) ? Math.max(0, Math.min(1, sampled)) : 0.5;
     const factor = minFactor + (maxFactor - minFactor) * random;
     return Math.max(1, Math.round(this.intervalMs * factor));
   }