PR #71478: fix(heartbeat): clamp scheduler delay to Node setTimeout cap (#71414)

• Repository: openclaw/openclaw
• Author: hclsys
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/71478

Description (problem / solution / changelog)

Closes #71414.

Bug

When agents.defaults.heartbeat.every resolves to >2_147_483_647 ms (~24.85d), scheduleNext() in src/infra/heartbeat-runner.ts called setTimeout(fn, delay) with the raw oversized delay. Node clamps any delay > 2^31-1 to 1 ms, fires the callback, and the heartbeat re-arms with the same oversized value — a tight loop that floods logs with TimeoutOverflowWarning: ... Timeout duration was set to 1. and crashes the gateway with exit code 1.

Reproduces with the reporter's recipe: { "agents": { "defaults": { "heartbeat": { "every": "365d" } } } }.

Fix

Clamp the computed delay to HEARTBEAT_MAX_TIMEOUT_MS = 2_147_483_647 ms before calling setTimeout. Worst case is now one heartbeat every ~24.85d instead of crash-loop. Warn once per process when the clamp fires, so a misconfigured 365d is still visible without flooding logs.

This is a defense-in-depth fix at the scheduler layer. loadConfig-level rejection (suggested in the issue) is a broader change with more blast radius and a separate semantic question — some users likely want every: 365d to mean "effectively never", and the clamped behaviour matches that intent better than a hard error does.

Test

New src/infra/heartbeat-runner.scheduler.test.ts case: sets heartbeat.every: \"365d\" with fake timers, advances 60s, and asserts runSpy was never invoked. With the bug present, runSpy would have been called tens of thousands of times during the advance.

Lint clean: pnpm oxlint src/infra/heartbeat-runner.ts src/infra/heartbeat-runner.scheduler.test.ts — 0 warnings, 0 errors.

Out of scope (deliberately)

• Wrapper/supervisor auto-respawn after gateway exit code 1 (mentioned in the issue) — that lives in container/wrapper code, separate concern.
• CLI silent embedded-mode fallback — tracked separately at #71416.

🤖 generated with assistance from Claude Code Co-authored-by: HCL [email protected]

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/agents/runtime-auth-refresh.ts (modified, +2/-2)
• src/gateway/call.ts (modified, +2/-1)
• src/gateway/client.ts (modified, +3/-2)
• src/gateway/probe.ts (modified, +3/-2)
• src/gateway/server-chat.ts (modified, +3/-3)
• src/gateway/server-methods/agent-job.ts (modified, +4/-5)
• src/gateway/server-methods/agent-wait-dedupe.ts (modified, +2/-2)
• src/infra/heartbeat-runner.scheduler.test.ts (modified, +18/-0)
• src/infra/heartbeat-runner.timeout-warning.test.ts (added, +70/-0)
• src/infra/heartbeat-runner.ts (modified, +11/-1)
• src/utils/timer-delay.test.ts (added, +34/-0)
• src/utils/timer-delay.ts (added, +19/-0)