From eddb94555afd988d214de66490c8d06507a1c35c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 4 Apr 2026 15:21:42 +0100
Subject: [PATCH] docs: refresh heartbeat task batching refs

---
 docs/automation/index.md        |  2 +-
 docs/gateway/heartbeat.md       | 35 ++++++++++++++++++++++++++++++++-
 docs/gateway/troubleshooting.md |  4 +++-
 3 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/docs/automation/index.md b/docs/automation/index.md
index 03a259cabe2..bacdd5d7768 100644
--- a/docs/automation/index.md
+++ b/docs/automation/index.md
@@ -91,7 +91,7 @@ See [Hooks](/automation/hooks).
 
 ### Heartbeat
 
-Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records. Use `HEARTBEAT.md` to define what the agent checks.
+Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records. Use `HEARTBEAT.md` for a small checklist, or a `tasks:` block when you want due-only periodic checks inside heartbeat itself.
 
 See [Heartbeat](/gateway/heartbeat).
 
diff --git a/docs/gateway/heartbeat.md b/docs/gateway/heartbeat.md
index a8ce33f4f23..921f192541d 100644
--- a/docs/gateway/heartbeat.md
+++ b/docs/gateway/heartbeat.md
@@ -21,7 +21,7 @@ Troubleshooting: [Scheduled Tasks](/automation/cron-jobs#troubleshooting)
 ## Quick start (beginner)
 
 1. Leave heartbeats enabled (default is `30m`, or `1h` for Anthropic Claude CLI or legacy token auth) or set your own cadence.
-2. Create a tiny `HEARTBEAT.md` checklist in the agent workspace (optional but recommended).
+2. Create a tiny `HEARTBEAT.md` checklist or `tasks:` block in the agent workspace (optional but recommended).
 3. Decide where heartbeat messages should go (`target: "none"` is the default; set `target: "last"` to route to the last contact).
 4. Optional: enable heartbeat reasoning delivery for transparency.
 5. Optional: use lightweight bootstrap context if heartbeat runs only need `HEARTBEAT.md`.
@@ -344,6 +344,39 @@ Example `HEARTBEAT.md`:
 - If a task is blocked, write down _what is missing_ and ask Peter next time.
 ```
 
+### `tasks:` blocks
+
+`HEARTBEAT.md` also supports a small structured `tasks:` block for interval-based
+checks inside heartbeat itself.
+
+Example:
+
+```md
+tasks:
+
+- name: inbox-triage
+  interval: 30m
+  prompt: "Check for urgent unread emails and flag anything time sensitive."
+- name: calendar-scan
+  interval: 2h
+  prompt: "Check for upcoming meetings that need prep or follow-up."
+
+# Additional instructions
+
+- Keep alerts short.
+- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.
+```
+
+Behavior:
+
+- OpenClaw parses the `tasks:` block and checks each task against its own `interval`.
+- Only **due** tasks are included in the heartbeat prompt for that tick.
+- If no tasks are due, the heartbeat is skipped entirely (`reason=no-tasks-due`) to avoid a wasted model call.
+- Non-task content in `HEARTBEAT.md` is preserved and appended as additional context after the due-task list.
+- Task last-run timestamps are stored in session state (`heartbeatTaskState`), so intervals survive normal restarts.
+
+Task mode is useful when you want one heartbeat file to hold several periodic checks without paying for all of them every tick.
+
 ### Can the agent update HEARTBEAT.md?
 
 Yes — if you ask it to.
diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md
index 2fa73bcdb41..09c0c547aa4 100644
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -243,13 +243,15 @@ Look for:
 
 - Cron enabled and next wake present.
 - Job run history status (`ok`, `skipped`, `error`).
-- Heartbeat skip reasons (`quiet-hours`, `requests-in-flight`, `alerts-disabled`).
+- Heartbeat skip reasons (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
 
 Common signatures:
 
 - `cron: scheduler disabled; jobs will not run automatically` → cron disabled.
 - `cron: timer tick failed` → scheduler tick failed; check file/log/runtime errors.
 - `heartbeat skipped` with `reason=quiet-hours` → outside active hours window.
+- `heartbeat skipped` with `reason=empty-heartbeat-file` → `HEARTBEAT.md` exists but only contains blank lines / markdown headers, so OpenClaw skips the model call.
+- `heartbeat skipped` with `reason=no-tasks-due` → `HEARTBEAT.md` contains a `tasks:` block, but none of the tasks are due on this tick.
 - `heartbeat: unknown accountId` → invalid account id for heartbeat delivery target.
 - `heartbeat skipped` with `reason=dm-blocked` → heartbeat target resolved to a DM-style destination while `agents.defaults.heartbeat.directPolicy` (or per-agent override) is set to `block`.