fix: schedule discord heartbeat checks after sends

[bryce-d-greybeard]

Summary

Fixes the Discord gateway heartbeat scheduler so ACK timeout checks are measured from the actual heartbeat send time, not from the HELLO-time fixed interval.

The previous scheduler randomized the first heartbeat but started a fixed interval immediately. If the first heartbeat fired late in that interval — or the event loop was delayed — the next interval tick could check lastHeartbeatAck too soon after the send and trigger a false Gateway heartbeat ACK timeout/reconnect cycle while the Discord channel was still awaiting readiness.

Changes

• Replace the fixed heartbeat interval with a chained timeout cycle.
• Keep randomized first heartbeat behavior.
• After each heartbeat send, schedule the ACK check one full heartbeat interval later.
• If ACKed, send the next heartbeat and schedule the next check from that send.
• Keep reconnect cleanup clearing both first-heartbeat and heartbeat-cycle timers.
• Add dedicated regression coverage for late randomized first heartbeat, genuine ACK timeout, ACKed heartbeat cycles, and timer cleanup.
• Add a changelog entry crediting both contributors.

Real Behavior Proof

Behavior or issue addressed: Discord gateway heartbeat ACK timeout race causing false reconnect loops and intermittent awaiting gateway readiness hangs (#77668).

Real environment tested: OpenClaw 2026.5.5 from commit 43dcdcd9 on WSL2 Ubuntu 22.04, Node.js v22.22.0, Discord bot runtime.

Exact steps or command run after this patch:

1. pnpm build in the OpenClaw source checkout.
2. Patched the installed @openclaw/discord runtime bundle with the recursive timeout heartbeat logic.
3. systemctl --user restart openclaw-gateway.
4. Monitored journalctl --user -u openclaw-gateway -f for 2+ minutes.

Evidence after fix: Runtime log excerpt from the real Discord gateway run:

19:32:32 [discord] client initialized as 1483184501986164748; awaiting gateway readiness
19:32:32 WebSocket OPEN event fired
19:32:33 message: op=0 t=READY
19:32:34 message: op=11 t=null
19:33:15 message: op=11 t=null

Observed result after fix: Zero Gateway heartbeat ACK timeout entries; Discord reached READY and stayed connected with repeated heartbeat ACKs instead of reconnecting.

What was not tested: Long-running 24h+ stability, multi-guild load, and Windows native runtime were not covered by this after-fix run. The original #77668 reporter offered to rerun 5 macOS launchd restart cycles once this lands.

Testing

• pnpm exec oxfmt --write --threads=1 CHANGELOG.md extensions/discord/src/internal/gateway-lifecycle.ts extensions/discord/src/internal/gateway-lifecycle.test.ts extensions/discord/src/internal/gateway.test.ts — passed.
• pnpm test extensions/discord/src/internal/gateway-lifecycle.test.ts extensions/discord/src/internal/gateway.test.ts — passed, 2 files / 24 tests.
• pnpm exec oxfmt --check --threads=1 CHANGELOG.md extensions/discord/src/internal/gateway-lifecycle.ts extensions/discord/src/internal/gateway-lifecycle.test.ts extensions/discord/src/internal/gateway.test.ts — passed.
• git diff --check — passed.

Fixes #77668
Supersedes #77956

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: fix: schedule discord heartbeat checks after sends This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

[byungskers]

Good catch on the heartbeat timing! Switching from "setInterval" to "setTimeout" makes the ACK check accurately measure one full interval after the actual heartbeat send, which aligns better with Discord Gateway expectations. The fake-timer tests clearly demonstrate the fix.

[RyanSandoval]

I'm the original reporter of #77668 — happy to provide real-behavior proof to help unblock the triage: needs-real-behavior-proof label.

Deterministic repro signature on this host

• Affected version: OpenClaw 2026.5.3-1 (also reproduces on 2026.5.4 per other commenters on [Bug]: Discord gateway hang at 'awaiting gateway readiness' still reproduces on 2026.5.3-1 (macOS) — six closed dups, raw-ws test isolates failure to Carbon Client lifecycle #77668)
• OS: macOS 26.3.1 (Apple Silicon), Node v22.16.0, npm global install, launchd LaunchAgent
• Failure rate today (2026-05-05): 0 successful logins / 4 attempted boots; latest logged in to discord line in my log is 2026-05-03 09:57 (~54 hours ago) despite ~10 launchctl bootout+bootstrap cycles since
• Symptom matches the PR's diagnosis exactly:
  • [discord] client initialized as <bot_id>; awaiting gateway readiness fires
  • [discord] gateway: Gateway websocket closed: 1006 fires ~12 minutes later (consistent with a false heartbeat-ACK timeout firing one fixed interval after HELLO)
  • No logged in to discord ever
  • Outbound REST works perfectly (curl -H "Authorization: Bot $TOKEN" https://discord.com/api/v10/users/@me → 200 in ~250ms)
  • Inbound MESSAGE_CREATE events never reach the agent
• Isolation evidence (from [Bug]: Discord gateway hang at 'awaiting gateway readiness' still reproduces on 2026.5.3-1 (macOS) — six closed dups, raw-ws test isolates failure to Carbon Client lifecycle #77668): raw ws library opening wss://gateway.discord.gg/?v=10&encoding=json from the same Node binary + same node_modules + same bot token completes the WS handshake and receives op:10 HELLO in <1 second, every time. So it's not network, token, intents, rate limit, or Discord — confirming the failure is in the gateway-lifecycle code path this PR modifies.

Configuration that rules out other contributing factors

• commands.native: false and commands.nativeSkills: false (rules out the slash-deploy CPU spike from [Bug]: Discord gateway stuck at 'awaiting gateway readiness' — --verbose flag as workaround (v2026.4.2) #60559)
• agentRuntime.fallback: "none" (eliminates API fallback masking the real error)
• LaunchAgent plist: NSAppSleepDisabled=YES, ProcessType=Interactive (rules out App Nap)
• 3 plugins loaded: anthropic, discord, memory-core (minimal config — same hang on this minimal set)

Offer

If this PR lands, I will:

1. Update OpenClaw on this affected host
2. Run launchctl bootout + bootstrap 5 times in a row
3. Report success/failure rate as a follow-up comment here within an hour

That should give you the empirical data needed to clear the needs-real-behavior-proof label.

Thanks @bryce-d-greybeard for digging into this — same heartbeat-lifecycle race that @wena369 / @mfbergmann / @holgergruenhagen have been narrowing down on the issue thread.

[steipete]

Landed via squash onto main.

• PR head: bf239b8
• Merge commit: b5c33bc
• Verification:
  • pnpm test extensions/discord/src/internal/gateway-lifecycle.test.ts extensions/discord/src/internal/gateway.test.ts
  • pnpm exec oxfmt --check --threads=1 CHANGELOG.md extensions/discord/src/internal/gateway-lifecycle.ts extensions/discord/src/internal/gateway-lifecycle.test.ts extensions/discord/src/internal/gateway.test.ts
  • git diff --check
  • Real behavior proof check passed on the PR head after the body update.

Thanks @bryce-d-greybeard and @NikolaFC.