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

[hclsys]

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 CLI silently falls back to embedded mode when gateway is unreachable #71416.

🤖 generated with assistance from Claude Code
Co-authored-by: HCL chenglunhu@gmail.com

[greptile-apps]

Greptile Summary

Clamps the scheduleNext delay to 2_147_483_647 ms before passing it to setTimeout, preventing the Node crash-loop that occurred when heartbeat.every exceeded the signed-32-bit cap. The fix is well-scoped, the comment explains the Node behavior clearly, and the regression test correctly catches the original bug.

Confidence Score: 4/5

Safe to merge; the crash-loop is fixed and no regressions are introduced.

One P2 finding: the warned flag is module-level rather than per-runner, so a second startHeartbeatRunner instance with an oversized delay in the same process silently clamps without logging. No P0 or P1 issues found.

src/infra/heartbeat-runner.ts — module-level heartbeatTimeoutOverflowWarned flag

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/infra/heartbeat-runner.ts
Line: 130

Comment:
**Module-level flag shared across all runner instances**

`heartbeatTimeoutOverflowWarned` is a module-level singleton. If `startHeartbeatRunner` is called more than once in the same process (e.g., on config reload or in back-to-back tests without module isolation), a second runner with an oversized delay will silently clamp without warning. In production a config reload that preserves the oversized delay produces no signal.

A per-runner flag would scope the warning to each runner lifetime:

```ts
// inside startHeartbeatRunner, alongside other state:
let timeoutOverflowWarned = false;
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "fix(heartbeat): clamp scheduler delay to..." | Re-trigger Greptile}

[greptile-apps]

Module-level flag shared across all runner instances

heartbeatTimeoutOverflowWarned is a module-level singleton. If startHeartbeatRunner is called more than once in the same process (e.g., on config reload or in back-to-back tests without module isolation), a second runner with an oversized delay will silently clamp without warning. In production a config reload that preserves the oversized delay produces no signal.

A per-runner flag would scope the warning to each runner lifetime:

// inside startHeartbeatRunner, alongside other state:
let timeoutOverflowWarned = false;

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/infra/heartbeat-runner.ts
Line: 130

Comment:
**Module-level flag shared across all runner instances**

`heartbeatTimeoutOverflowWarned` is a module-level singleton. If `startHeartbeatRunner` is called more than once in the same process (e.g., on config reload or in back-to-back tests without module isolation), a second runner with an oversized delay will silently clamp without warning. In production a config reload that preserves the oversized delay produces no signal.

A per-runner flag would scope the warning to each runner lifetime:

```ts
// inside startHeartbeatRunner, alongside other state:
let timeoutOverflowWarned = false;
```

How can I resolve this? If you propose a fix, please make it concise.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 80ba6b27d1

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Exercise actual overflow branch in regression test

This test case does not currently trigger the setTimeout overflow condition it claims to guard. scheduleNext() only overflows when nextDue - now > HEARTBEAT_MAX_TIMEOUT_MS (src/infra/heartbeat-runner.ts), but with TEST_SCHEDULER_SEED, agent main, and now=0, the phase-based first due time is about 8 days, so setTimeout is scheduled normally and the test passes even on the pre-fix behavior. That means this regression test won’t catch a future removal/break of the clamp logic; it should force rawDelay above the Node cap (e.g., by controlling phase/clock so next due is >24.85 days).

Useful? React with 👍 / 👎.

[steipete]

Codex maintainer review: good fix, approved.

What I checked:

• #71414 is a real scheduler bug: Node turns any setTimeout delay greater than 2_147_483_647 ms into a 1 ms timer. I reproduced that directly with Node; it emitted TimeoutOverflowWarning and fired immediately.
• heartbeat.every: "365d" flows through resolveHeartbeatIntervalMs() as a valid positive duration, then into resolveNextHeartbeatDueMs() / scheduleNext(), so the scheduler layer is the implicated path.
• The fix clamps only the timer arm delay. It does not reject the config and does not change the stored heartbeat interval.
• Early clamp ticks are safe: the wake handler checks isInterval && now < agent.nextDueMs and returns not-due, then scheduleNext() re-arms. So a 365d heartbeat does not run at ~24.85d; the clamp effectively becomes a long-timer chain.
• The new regression covers the original tight loop: fake time advances 60s with 365d, and runOnce stays uncalled.
• Greptile's module-level warning flag note is real but non-blocking. It only affects repeated warning visibility across multiple runner instances in the same process; the scheduling safety and user behavior are correct.

I pushed one maintainer fixup commit to the PR branch: style: format heartbeat scheduler clamp, because local pnpm format:check caught formatter drift in src/infra/heartbeat-runner.ts.

Verification:

pnpm format:check src/infra/heartbeat-runner.ts src/infra/heartbeat-runner.scheduler.test.ts
pnpm test src/infra/heartbeat-runner.scheduler.test.ts src/infra/heartbeat-runner.returns-default-unset.test.ts
node -e 'let fired=false; const t=setTimeout(()=>{fired=true; console.log("fired");},2147483648); setTimeout(()=>{clearTimeout(t); console.log({fired});},20)'

Results: format passed; infra heartbeat tests passed (2 files / 42 tests); Node repro confirmed the overflow warning plus immediate timer fire.