#11807: fix: Make HEARTBEAT.md creation match documentation
agents
stale
Cluster:
Heartbeat Functionality Improvements
fixes #11766 - Missing HEARTBEAT.md behaviour doesn't match documentation
## Summary
The documentation states that "If the file is missing, the heartbeat still runs and the model decides what to do." However, the actual behavior was that a missing HEARTBEAT.md disabled the heartbeat completely because OpenClaw silently created an empty one. This commit fixes the logic to match the documented behavior by creating HEARTBEAT.md only when the workspace is brand new, ensuring existing workspaces with missing HEARTBEAT.md files can still execute heartbeats as intended.
## Change
Moved the HEARTBEAT.md creation inside the `isBrandNewWorkspace` check to prevent overwriting or creating empty files in existing workspaces.
## Impact
This change technically is a behavioural change, but it now matches what the documentation promises, i.e. exactly what users expect.
## Testing
pnpm check and test passed
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adjusts workspace bootstrapping so `HEARTBEAT.md` is only created for *brand new* workspaces (inside the `isBrandNewWorkspace` branch) rather than being created opportunistically whenever it’s missing.
That aligns `ensureAgentWorkspace` (`src/agents/workspace.ts`) with the heartbeat runner behavior (`src/infra/heartbeat-runner.ts`), which explicitly proceeds when `HEARTBEAT.md` is absent (letting the model decide) but skips when the file exists and is “effectively empty.”
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk.
- The change is a small, localized logic adjustment in workspace bootstrapping that better matches the documented/expected heartbeat semantics. It removes an unintended side effect (creating an empty HEARTBEAT.md in existing workspaces) and is consistent with the heartbeat runner’s explicit behavior when the file is missing.
- No files require special attention
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#19482: fix(agents): only seed HEARTBEAT.md on brand-new workspaces
by CornBrother0x · 2026-02-17
87.3%
#12365: test(heartbeat): don't skip empty HEARTBEAT.md for cron wake events
by tyclaudius-ai · 2026-02-09
79.8%
#15575: fix(heartbeat): suppress prefixed HEARTBEAT_OK ack replies (#15505)
by TsekaLuk · 2026-02-13
77.7%
#3335: Fixes cron jobs
by hkirat · 2026-01-28
77.6%
#12786: fix: drop heartbeat runs that arrive while another run is active
by mcaxtr · 2026-02-09
76.9%
#21615: fix(tui): preserve main session model during heartbeat model override
by lailoo · 2026-02-20
76.0%
#12073: docs(heartbeat): clarify behavior when HEARTBEAT.md is missing
by tyclaudius-ai · 2026-02-08
75.6%
#13524: feat: conditional bootstrap file loading for heartbeat vs DM sessions
by tarun131313 · 2026-02-10
75.2%
#22277: fix: prevent heartbeat model override from bleeding into main session
by zhangjunmengyang · 2026-02-21
75.1%
#6522: fix(cron): deliver original message when agent response is heartbea...
by sidmohan0 · 2026-02-01
74.7%