feat: move heartbeat config to agent.heartbeat

docs/clawd.md

@@ -19,7 +19,7 @@ You’re putting an agent in a position to:
 Start conservative:
 - Always set `routing.allowFrom` (never run open-to-the-world on your personal Mac).
 - Use a dedicated WhatsApp number for the assistant.
-- Keep heartbeats disabled until you trust the setup (`heartbeatMinutes: 0`).
+- Keep heartbeats disabled until you trust the setup (omit `agent.heartbeat` or set `agent.heartbeat.every: "0m"`).
 
 ## Prerequisites
 
@@ -122,7 +122,7 @@ Example:
     thinkingDefault: "high",
     timeoutSeconds: 1800,
     // Start with 0; enable later.
-    heartbeatMinutes: 0
+    heartbeat: { every: "0m" }
   },
   routing: {
     allowFrom: ["+15555550123"],
@@ -148,14 +148,14 @@ Example:
 
 ## Heartbeats (proactive mode)
 
-When `agent.heartbeatMinutes > 0`, CLAWDIS periodically runs a heartbeat prompt (default: `HEARTBEAT`).
+When `agent.heartbeat.every` is set to a positive interval, CLAWDIS periodically runs a heartbeat prompt (default: `HEARTBEAT`).
 
 - If the agent replies with `HEARTBEAT_OK` (exact token), CLAWDIS suppresses outbound delivery for that heartbeat.
 
 ```json5
 {
   agent: {
-    heartbeatMinutes: 30
+    heartbeat: { every: "30m" }
   }
 }
 ```

docs/configuration.md

@@ -129,7 +129,9 @@ Controls the embedded agent runtime (model/thinking/verbose/timeouts).
     verboseDefault: "off",
     timeoutSeconds: 600,
     mediaMaxMb: 5,
-    heartbeatMinutes: 30,
+    heartbeat: {
+      every: "30m"
+    },
     maxConcurrent: 3,
     bash: {
       backgroundMs: 20000,
@@ -145,6 +147,11 @@ Controls the embedded agent runtime (model/thinking/verbose/timeouts).
 If you omit the provider, CLAWDIS currently assumes `anthropic` as a temporary
 deprecation fallback.
 
+`agent.heartbeat` configures periodic heartbeat runs:
+- `every`: duration string (`ms`, `s`, `m`); default unit minutes. Omit or set
+  `0m` to disable.
+- `model`: optional override model for heartbeat runs (`provider/model`).
+
 `agent.bash` configures background bash defaults:
 - `backgroundMs`: time before auto-background (ms, default 20000)
 - `timeoutSec`: auto-kill after this runtime (seconds, default 1800)

docs/heartbeat.md

@@ -12,8 +12,10 @@ Goal: add a simple heartbeat poll for the embedded agent that only notifies user
 - Keep existing WhatsApp length guidance; forbid burying the sentinel inside alerts.
 
 ## Config & defaults
-- New config key: `agent.heartbeatMinutes` (number of minutes; `0` disables).
-- Default: 30 minutes.
+- New config key: `agent.heartbeat` with:
+  - `every`: duration string (`ms`, `s`, `m`; default unit minutes). `0m` disables.
+  - `model`: optional override model (`provider/model`) for heartbeat runs.
+- Default: disabled unless `agent.heartbeat.every` is set.
 - New optional idle override for heartbeats: `session.heartbeatIdleMinutes` (defaults to `idleMinutes`). Heartbeat skips do **not** update the session `updatedAt` so idle expiry still works.
 
 ## Poller behavior
@@ -40,7 +42,7 @@ Goal: add a simple heartbeat poll for the embedded agent that only notifies user
 - Unit/integration: verbose logger emits start/end lines; normal logger emits a single line.
 
 ## Documentation
-- Add a short README snippet under configuration showing `heartbeatMinutes` and the sentinel rule.
+- Add a short README snippet under configuration showing `agent.heartbeat` and the sentinel rule.
 - Expose CLI triggers:
   - `clawdis heartbeat` (web provider, defaults to first `routing.allowFrom`; optional `--to` override)
     - `--session-id <uuid>` forces resuming a specific session for that heartbeat

docs/whatsapp.md

@@ -86,7 +86,7 @@ Status: WhatsApp Web via Baileys only. Gateway owns the single session.
 
 ## Heartbeats
 - **Gateway heartbeat** logs connection health (`web.heartbeatSeconds`, default 60s).
-- **Reply heartbeat** asks agent on a timer (`agent.heartbeatMinutes`).
+- **Reply heartbeat** asks agent on a timer (`agent.heartbeat.every`).
   - Uses `HEARTBEAT` prompt + `HEARTBEAT_TOKEN` skip behavior.
   - Skips if queue busy or last inbound was a group.
   - Falls back to last direct recipient if needed.
@@ -104,7 +104,8 @@ Status: WhatsApp Web via Baileys only. Gateway owns the single session.
 - `messages.messagePrefix` (inbound prefix)
 - `messages.responsePrefix` (outbound prefix)
 - `agent.mediaMaxMb`
-- `agent.heartbeatMinutes`
+- `agent.heartbeat.every`
+- `agent.heartbeat.model` (optional override)
 - `session.*` (scope, idle, store, mainKey)
 - `web.heartbeatSeconds`
 - `web.reconnect.*`