PR #63434: fix(heartbeat): widen empty-detection to skip API calls for comment-only HEARTBEAT.md (#61690)

• Repository: openclaw/openclaw
• Author: ravyg
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/63434

Description (problem / solution / changelog)

Summary

• Problem: A default-installed HEARTBEAT.md could fire a full heartbeat LLM call every interval even when the file was effectively just scaffold text.
• Root cause: docs/reference/templates/HEARTBEAT.md was changed in 198de10523 to wrap the scaffold body in a fenced ```markdown block so Mintlify would render the # lines as code instead of page headings. Runtime loadTemplate() strips frontmatter but not fenced markers, so those ``` lines are written verbatim into the user workspace. isHeartbeatContentEffectivelyEmpty() treated those marker lines as actionable content, so the preflight skip path never fired.
• What changed: isHeartbeatContentEffectivelyEmpty() now treats Markdown fence marker lines such as ``` and ```markdown as format-only noise, while still treating real content inside the fence as actionable. The PR also adds regression coverage for the current fenced template shape, the pre-fence legacy comment-only template shape, and runner-level skip behavior.
• What did NOT change: This PR does not add HTML comment, YAML frontmatter, or bare tasks: handling. Those patterns are not part of the shipped heartbeat template path that caused the regression.

Change Type

• Bug fix

Scope

• Gateway / orchestration

Linked Issue/PR

• Closes #61690
• Related #61347
• This PR fixes a bug or regression

Root Cause

• Root cause: the runtime heartbeat scaffold and the docs template share the same source file. After 198de10523, the shipped HEARTBEAT.md scaffold started including fenced Markdown markers for docs rendering, but runtime template loading still wrote those markers into workspaces.
• Missing detection / guardrail: isHeartbeatContentEffectivelyEmpty() skipped headers and blank lines but not fence marker lines, so a comment-only scaffold created from the current template looked non-empty.
• Why old installs also matter: pre-198de10523 installs may still have the old comment-only scaffold shape, so the regression tests keep both shapes covered.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Integration / runner test
• Target tests or files:
  • src/auto-reply/heartbeat.test.ts
  • src/agents/workspace.test.ts
  • src/infra/heartbeat-runner.returns-default-unset.test.ts
• Scenarios the tests lock in:
  • the current fenced default template body is treated as effectively empty
  • the legacy pre-fence comment-only template body is still treated as effectively empty
  • fenced content with a real task still runs and does not skip
  • new workspaces really do seed the fenced HEARTBEAT.md template body from docs/reference/templates/HEARTBEAT.md
• Why this is the smallest reliable guardrail: it covers the actual docs-template-to-workspace path plus the runner preflight gate, not just the helper in isolation.

User-visible / Behavior Changes

For users whose HEARTBEAT.md still contains only the shipped scaffold text, heartbeat ticks now return {status: "skipped", reason: "empty-heartbeat-file"} again instead of making an unnecessary LLM call. Fenced templates with real task content still run normally.

Diagram

Before (default shipped scaffold after 198de10523):
[interval tick] -> workspace HEARTBEAT.md contains ```markdown / ``` lines
                -> isHeartbeatContentEffectivelyEmpty: false
                -> full LLM call

After:
[interval tick] -> fence marker lines ignored as formatting noise
                -> scaffold-only HEARTBEAT.md classified empty
                -> {status: "skipped"}

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: local repo test environment
• Runtime: Node 22+, pnpm 10.x
• Model/provider: provider-agnostic; the fix is in heartbeat preflight gating before any LLM call

Steps

1. Inspect docs/reference/templates/HEARTBEAT.md and confirm the scaffold body is fenced with ```markdown.
2. Confirm src/agents/workspace.ts strips frontmatter but not fence markers when seeding the workspace template.
3. Run:
   • pnpm test src/auto-reply/heartbeat.test.ts
   • pnpm test src/agents/workspace.test.ts
   • pnpm test src/infra/heartbeat-runner.returns-default-unset.test.ts

Expected

• Current fenced scaffold-only HEARTBEAT.md skips heartbeat runs.
• Legacy comment-only scaffold still skips.
• Fenced heartbeat files with real tasks still run.

Actual

Matches expected.

Evidence

• Failing test/log before + passing after

pnpm test src/auto-reply/heartbeat.test.ts
pnpm test src/agents/workspace.test.ts
pnpm test src/infra/heartbeat-runner.returns-default-unset.test.ts

All passed locally on the final PR head.

Human Verification

• Verified scenarios:
  • current fenced template scaffold is classified empty
  • legacy pre-fence comment-only scaffold is classified empty
  • fenced scaffold with real tasks is not classified empty
  • workspace seeding still writes the fenced heartbeat template body from the docs template source
• What I did NOT verify: live end-to-end billing/provider behavior against a real model API. The change is confined to local preflight gating, and runner-level tests cover the skip path.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: fence marker lines are ignored even outside the shipped scaffold.
  • Mitigation: only the marker lines themselves are ignored; content inside the fence is still evaluated normally, and runner tests cover fenced actionable content.
• Risk: future template formatting changes could drift from runtime assumptions again.
  • Mitigation: workspace seeding and runner gating are now both covered by regression tests.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/agents/workspace.test.ts (modified, +16/-0)
• src/auto-reply/heartbeat.test.ts (modified, +36/-3)
• src/auto-reply/heartbeat.ts (modified, +9/-3)
• src/infra/heartbeat-runner.returns-default-unset.test.ts (modified, +66/-1)