#12073: docs(heartbeat): clarify behavior when HEARTBEAT.md is missing
docs
gateway
stale
Cluster:
Heartbeat Functionality Improvements
Fixes #11766.
## Why
Docs previously implied that if `HEARTBEAT.md` is missing, heartbeats still run.
In practice, workspace bootstrap may create an empty `HEARTBEAT.md`, and the existing “empty file = skip” rule then prevents heartbeat API calls.
## What changed
- Clarified that **missing/empty** `HEARTBEAT.md` can result in **skip** due to bootstrap creating an empty file.
- Added explicit workarounds:
- `agents.defaults.skipBootstrap` to prevent bootstrap from creating the file
- heartbeat `prompt` override options
## Repro (current behavior)
1. Remove `HEARTBEAT.md`
2. Run a heartbeat poll
3. If bootstrap creates an empty `HEARTBEAT.md`, the heartbeat will be skipped under the documented “empty = skip” rule
Docs-only change (no code).
Most Similar PRs
#11807: fix: Make HEARTBEAT.md creation match documentation
by HenryLoenwind · 2026-02-08
75.6%
#12365: test(heartbeat): don't skip empty HEARTBEAT.md for cron wake events
by tyclaudius-ai · 2026-02-09
69.4%
#12837: fix(heartbeat): suppress HEARTBEAT_OK token delivery
by JBrady · 2026-02-09
67.2%
#19482: fix(agents): only seed HEARTBEAT.md on brand-new workspaces
by CornBrother0x · 2026-02-17
67.0%
#20563: fix: skip default HEARTBEAT_OK instructions when custom prompt is set
by clawalpha · 2026-02-19
66.5%
#17006: fix(heartbeat): skip delivery when showOk is false
by Limitless2023 · 2026-02-15
66.5%
#19270: fix: retry event-driven heartbeats blocked by requests-in-flight
by deggertsen · 2026-02-17
62.8%
#13574: fix(heartbeat): skip when session has active run
by 1kuna · 2026-02-10
62.7%
#20398: docs(automation): add multi-hop improvement loop pattern to cron-vs...
by skylinehk · 2026-02-18
62.6%
#9429: fix: skip session model override for heartbeat runs
by dbottme · 2026-02-05
62.6%