PR #61638: fix(config): reject heartbeat.every values that overflow Node.js setTimeout

• Repository: openclaw/openclaw
• Author: LTS2
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/61638

Description (problem / solution / changelog)

Summary

• Problem: Setting heartbeat.every to values > ~596h (e.g., 99999h) causes Node.js setTimeout to silently overflow. The 32-bit signed integer limit (~2,147,483,647ms) clamps the delay to 1ms, firing heartbeats every millisecond and breaking channel message processing.
• Why it matters: Users who set large values to effectively disable heartbeats get the opposite behavior — rapid-fire heartbeats that exhaust resources and break message delivery.
• What changed: Added overflow validation in HeartbeatSchema.superRefine() to reject values exceeding the setTimeout limit at config load time with a clear error message.
• What did NOT change (scope boundary): parseDurationMs(), heartbeat-runner.ts, heartbeat-summary.ts — only the Zod schema validation layer is touched.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Gateway / orchestration

Linked Issue/PR

• Closes #61546
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: HeartbeatSchema.superRefine() validated that the duration string parses correctly but did not check whether the parsed millisecond value exceeds Node.js's 32-bit setTimeout limit.
• Missing detection / guardrail: No range validation on parsed duration values in the config schema.
• Prior context: The parseDurationMs() parser checks Number.isFinite() but not the setTimeout ceiling.
• Why this regressed now: Always present — any user setting heartbeat.every to a very large value would hit this.
• If unknown, what was ruled out: N/A

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/config/zod-schema.heartbeat-overflow.test.ts
• Scenario the test should lock in:
  1. "99999h" is rejected with error mentioning setTimeout limit
  2. "596h" is accepted (within limit)
  3. "30m" is accepted (typical value)
  4. "abc" still rejected with existing invalid duration message
• Why this is the smallest reliable guardrail: Validates at the config schema layer, the earliest point where the value is checked.
• Existing test that already covers this (if any): None
• If no new test is added, why not: N/A — 4 new tests added

User-visible / Behavior Changes

• Config validation now rejects heartbeat.every values > ~596h with: heartbeat.every exceeds the Node.js setTimeout limit (~596h). Use "0m" to disable or choose a shorter interval.

Diagram (if applicable)

N/A

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Any
• Runtime/container: Node 22+

Steps

1. Set agents.defaults.heartbeat.every to "99999h" in config
2. Run openclaw gateway

Expected

• Config validation rejects the value with a clear error message

Actual (before fix)

• Config loads successfully, setTimeout receives an overflowed value, heartbeat fires every ~1ms

Evidence

• Failing test/log before + passing after
• 4 new tests in zod-schema.heartbeat-overflow.test.ts all pass

Human Verification (required)

• Verified scenarios: All 4 tests pass; pnpm check lint passes (pre-existing TS error in unrelated file)
• Edge cases checked: Boundary value (596h accepted), typical value (30m accepted), invalid syntax preserved
• What you did not verify: Live gateway test with the overflow value

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes (only rejects previously-broken values)
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: Users with existing heartbeat.every > 596h configs will get a validation error on startup.
  • Mitigation: The error message explicitly suggests "0m" to disable or a shorter interval. These configs were already silently broken (firing every 1ms), so catching them is an improvement.

---

AI-assisted: Yes (Claude). Fully tested. I understand what the code does.

Changed files

• src/config/zod-schema.agent-runtime.ts (modified, +14/-1)
• src/config/zod-schema.heartbeat-overflow.test.ts (added, +52/-0)