Summary

• Problem: scheduled heartbeat turns could be accepted by the scheduler but never reach a real model turn when reply work was already active around the same session/agent.
• Why it matters / User impact: affected 5.x installs can look like heartbeat is configured and wake requests are accepted, but the heartbeat tick can be consumed as handled without the main agent session receiving the heartbeat prompt. That matches the reporter-visible failure mode where a manual wake can return OK while no model inference reaches the main agent session.
• Root cause: the source-of-truth busy-state lifecycle was split across the heartbeat scheduler boundary and reply-turn admission. runHeartbeatOnce checked queued lanes / active reply work before calling getReplyFromConfig, but downstream reply admission intentionally rejects heartbeat turns when another reply run wins the same session slot. Because that admission rejection surfaced back to the heartbeat runner as an empty reply, the scheduler emitted ok-empty / returned ran instead of the retryable requests-in-flight result. The existing active embedded-run path had the same root contract failure: background heartbeat work could enter a reply path that intentionally drops heartbeat turns rather than queueing them.
• Why this is root-cause fix: heartbeat scheduling is the source-of-truth owner for deciding whether background heartbeat work dispatches or retries. This patch restores that invariant at the scheduler boundary: scheduled heartbeat dispatch now defers before model dispatch when same-agent embedded work is active, and it rechecks the resolved run session after getReplyFromConfig returns an empty result so a reply-admission race is converted into requests-in-flight instead of a phantom ran. That fixes the state-owner contract rather than masking the symptom with a provider-specific retry, timeout, or fallback.
• Fix classification: Root cause fix.
• Solution: return the existing retryable requests-in-flight status when heartbeat dispatch collides with active embedded/reply work, including the race where activity appears after preflight but before reply admission.
• What changed: heartbeat runner now checks active embedded-run session keys alongside active reply runs before dispatch, and treats an empty reply result as busy when the run session is still active after the reply runtime returns.
• What did NOT change: heartbeat cadence calculation, public config shape, provider/model routing, outbound delivery contracts, persisted session formats, and visible user-turn queue policy are unchanged. Manual/immediate wakes still keep their existing semantics for other active sessions; the fix only prevents busy heartbeat work from being marked completed without a model turn.
• Related open PR scan: this is an update to the existing linked PR fix #85871: [Bug]: Heartbeat scheduler silently fails to fire on 5.20 and all 5.x versions (regression from 4.23) #88970, not a new competing PR. The current discussion/review evidence points this PR at issue [Bug]: Heartbeat scheduler silently fails to fire on 5.20 and all 5.x versions (regression from 4.23) #85871 and RF-001; no separate canonical PR is used as the source of truth for this heartbeat busy-state boundary.
• Patch quality notes: the retry/default-looking changes are limited to the heartbeat scheduler guardrail. The requests-in-flight result is the existing wake-layer retry contract, and the test-only return undefined simulates the actual reply-admission skip that previously became phantom ran; it is not a production fallback, catch-all, or symptom-masking default.
• Maintainer-ready confidence: High for the gateway scheduler starting and reaching dispatch on current head, and high for the busy/retry boundary. Medium for the reporter's exact Ubuntu/Ollama deployment because local proof used an available local provider/model and shortened the interval instead of waiting a full production 5-minute cadence.
• Architecture / source-of-truth check: the heartbeat runner remains the source-of-truth dispatch boundary for scheduled heartbeat work. The patch reads the existing active reply/embedded-run registries; it does not add downstream string matching, mirrored busy state, provider-specific behavior, or persistence migrations.

Linked context

• Fixes [Bug]: Heartbeat scheduler silently fails to fire on 5.20 and all 5.x versions (regression from 4.23) #85871.
• Existing PR: fix #85871: [Bug]: Heartbeat scheduler silently fails to fire on 5.20 and all 5.x versions (regression from 4.23) #88970.
• Current review finding addressed: RF-001 asked for proof beyond a narrow unit path. The updated proof starts a real gateway, observes scheduler startup, observes heartbeat dispatch after startup, and separately proves the busy defer/retry behavior.

Real behavior proof

• Behavior addressed: the live gateway heartbeat scheduler starts and reaches agent/model dispatch, and scheduled heartbeats defer instead of being silently consumed while same-agent work is active.

• Real environment tested: local OpenClaw gateway started through pnpm gateway:dev with isolated runtime state, a short every: 2s heartbeat, target: none, and a real configured provider/model. The busy/retry boundary was exercised through the actual scheduler wake path with active embedded work registered for agent:main:main.

• Exact steps or command run after this patch:

  • daily-fix run-validation --name live-heartbeat-gateway-current -- bash heartbeat-live-gateway-proof.sh
  • daily-fix run-validation --name heartbeat-busy-retry-current -- pnpm exec tsx heartbeat-scheduled-embedded-proof.ts

• Evidence after fix: live gateway log excerpt shows the gateway became ready, the scheduler emitted [heartbeat] started, and a heartbeat turn reached agent dispatch:

  READY=ok
  HEARTBEAT_STARTED=1
  HEARTBEAT_DISPATCH_AFTER_STARTED=1
  HEARTBEAT_RESULT_SIGNAL=0
  2026-06-10T02:46:14.313+08:00 [gateway] http server listening (8 plugins: acpx, browser, canvas, device-pair, file-transfer, memory-core, phone-control, talk-voice; 18.8s)
  2026-06-10T02:46:14.329+08:00 [gateway] ready
  2026-06-10T02:46:15.063+08:00 [heartbeat] started
  2026-06-10T02:46:40.733+08:00 [agent/embedded] [trace:embedded-run] core-plugin-tool stages: runId=9f3da39f-5bc1-4dc3-ba19-2a88326fdea2 sessionId=e287404c-562f-4139-baee-21beb02b705c phase=core-plugin-tools ... attempt:tools-allow:0ms
  

  The busy/retry proof then showed the first scheduled wake deferred before dispatch while active embedded work existed, and the retry dispatched after the busy run cleared:

  [proof] active embedded run registered: sessionId=proof-active-embedded-run sessionKey=agent:main:main
  [heartbeat] started
  [proof] scheduled wake attempt #1: source=interval intent=scheduled reason=interval activeBefore=["agent:main:main"] result={"status":"skipped","reason":"requests-in-flight"} dispatchCount=0
  [proof] active embedded run cleared after first busy skip: sessionId=proof-active-embedded-run
  [proof] model dispatch reached after busy cleared: dispatchCount=1
  [proof] scheduled wake attempt #2: source=interval intent=scheduled reason=interval activeBefore=[] result={"status":"ran","durationMs":160} dispatchCount=1
  [proof] PASS: scheduled heartbeat deferred while active embedded work existed, then wake retry dispatched after it cleared
  

• Observed result after fix: a real gateway heartbeat cycle no longer stayed silent after startup; it logged scheduler startup and reached agent/model dispatch on the configured interval. When same-agent embedded work was active, the scheduled wake returned the retryable requests-in-flight result before model dispatch, then retried and dispatched after the active run cleared.

• What was not tested: the reporter's exact Ubuntu/Ollama install and a full 5-minute interval / 10+ minute wall-clock wait. The local proof shortened the interval to exercise the same scheduler path without waiting multiple production cycles.

Tests and validation

• Target test file: src/infra/heartbeat-runner.skips-busy-session-lane.test.ts covers the reply-admission race where activity appears after heartbeat preflight and getReplyFromConfig returns an empty result; src/infra/heartbeat-runner.returns-default-unset.test.ts covers active embedded-run pre-dispatch deferral for the resolved heartbeat session and another same-agent session.
• Scenario locked in: scheduled heartbeat work that collides with same-session/same-agent active reply or embedded work returns the retryable requests-in-flight skip instead of phantom ran, then the wake retry can dispatch after the active run clears.
• Why this is the smallest reliable guardrail: the tests pin the scheduler/reply-admission boundary that lost heartbeat turns without mocking provider-specific Ollama behavior, changing public config/schema contracts, or rewriting visible user-turn queue policy.
• daily-fix run-validation --name heartbeat-busy-regression-current-head -- node scripts/run-vitest.mjs run src/infra/heartbeat-runner.skips-busy-session-lane.test.ts src/infra/heartbeat-runner.returns-default-unset.test.ts src/infra/heartbeat-wake.test.ts — passed: 3 files, 75 tests.
• daily-fix run-validation --name heartbeat-lint-current-head -- pnpm exec oxlint src/infra/heartbeat-runner.ts src/infra/heartbeat-runner.skips-busy-session-lane.test.ts — passed.
• daily-fix run-validation --name live-heartbeat-gateway-current -- bash heartbeat-live-gateway-proof.sh — passed; real pnpm gateway:dev startup logged READY=ok, [heartbeat] started, and HEARTBEAT_DISPATCH_AFTER_STARTED=1.
• daily-fix run-validation --name heartbeat-busy-retry-current -- pnpm exec tsx heartbeat-scheduled-embedded-proof.ts — passed; scheduled source=interval / intent=scheduled heartbeat returned requests-in-flight while agent:main:main had active embedded work, then the wake retry reached model dispatch and returned ran after the embedded run cleared.

Risk checklist

• Risk labels considered: compatibility, session-state.
• Risk explanation: merge risk is limited to scheduled heartbeat retry behavior when active reply/embedded work is already occupying the relevant heartbeat session or same-agent background-work boundary.
• Why acceptable: this aligns heartbeat behavior with the existing wake retry contract. A busy heartbeat is now retried by the scheduler instead of being counted as completed before a model turn happens.
• Public contract / config boundary: no public config schema, defaults, migration behavior, provider selection, channel delivery contract, or session-store format changes.
• Out of scope / not changed: no provider-specific Ollama workaround, no full 5-minute production wait in local proof, no channel delivery rewrite, no reply queue policy rewrite, and no legacy config migration change.

Current review state

• Which bot or reviewer comments were addressed?
  • RF-001 [P1]: addressed with current-head live gateway proof plus scheduler busy/retry proof.
• Remaining maintainer decision points:
  • The proof uses a shortened 2-second heartbeat interval rather than waiting 10+ minutes on the reporter's exact cadence.
  • The local provider/model differs from the reporter's Ollama deployment, but it exercises the same gateway scheduler and heartbeat dispatch path.