feature: add heartbeat loop for periodic health checks

AGENTS.md

@@ -24,11 +24,13 @@ pi/
   extensions/               source of truth for pi agent extensions
     tool-guard.ts           🔒 tool call interception (blocks dangerous patterns)
     tool-guard.test.mjs     🔒 86 tests for tool-guard
+    heartbeat.ts            periodic health check loop
     auto-name.ts            session naming
     control.ts              inter-session communication
     ...
   skills/                   source of truth for agent skill templates
     control-agent/          orchestration agent
+      HEARTBEAT.md          health check checklist (deployed to ~/.pi/agent/)
     dev-agent/              coding agent
     sentry-agent/           monitoring/triage agent
   settings.json             pi agent settings
@@ -67,6 +69,7 @@ Agent runtime layout:
 ├── .pi/agent/
 │   ├── extensions/             deployed extensions
 │   ├── skills/                 agent-owned (can modify freely)
+│   ├── HEARTBEAT.md            periodic health check checklist (admin-managed)
 │   ├── baudbot-version.json     deploy version (git SHA, timestamp)
 │   └── baudbot-manifest.json    SHA256 hashes of all deployed files
 ├── workspace/                  project repos + git worktrees

CONFIGURATION.md

@@ -85,6 +85,14 @@ Set during `setup.sh` via env vars (or edit `~/.gitconfig` after):
 | `GIT_USER_NAME` | Git commit author name | `baudbot-agent` |
 | `GIT_USER_EMAIL` | Git commit author email | `baudbot-agent@users.noreply.github.com` |
 
+### Heartbeat
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HEARTBEAT_INTERVAL_MS` | Interval between heartbeat checks (milliseconds) | `600000` (10 min) |
+| `HEARTBEAT_FILE` | Path to heartbeat checklist file | `~/.pi/agent/HEARTBEAT.md` |
+| `HEARTBEAT_ENABLED` | Set to `0` or `false` to disable heartbeats | enabled |
+
 ### Bridge
 
 | Variable | Description | Default |

README.md

@@ -99,6 +99,17 @@ Slack → bridge (access control + content wrapping) → pi agent → tools (too
 
 Every layer assumes the previous one failed. The bridge wraps content and rate-limits, but tool-guard blocks dangerous commands even if wrapping is bypassed. Safe-bash blocks patterns even if tool-guard is evaded. The firewall blocks non-standard ports even if all software layers fail.
 
+### Heartbeat
+
+The control agent runs a periodic heartbeat loop (default: every 10 minutes) that checks system health:
+
+- Are all agent sessions alive?
+- Is the Slack bridge responsive?
+- Is the email monitor running?
+- Are there stale worktrees or stuck todos?
+
+The checklist lives in `HEARTBEAT.md` — edit it to add custom checks. The heartbeat extension (`heartbeat.ts`) handles scheduling, error backoff, and the `heartbeat` tool for runtime control. If the checklist is empty, no heartbeat fires (saves tokens).
+
 ## Architecture
 
 ```
@@ -115,6 +126,7 @@ baudbot_agent (unprivileged uid)
 ├── ~/.pi/agent/
 │   ├── extensions/                  deployed extensions (read-only)
 │   ├── skills/                      agent-owned (can modify)
+│   ├── HEARTBEAT.md                 periodic health check checklist
 │   └── baudbot-manifest.json        SHA256 integrity hashes
 ├── ~/workspace/                     project repos + worktrees
 └── ~/.config/.env                   secrets (600 perms)

bin/deploy.sh

@@ -140,6 +140,24 @@ else
   log "would copy: skills/"
 fi
 
+# ── Heartbeat ────────────────────────────────────────────────────────────────
+
+echo "Deploying heartbeat checklist..."
+
+HEARTBEAT_SRC="$STAGE_DIR/skills/control-agent/HEARTBEAT.md"
+HEARTBEAT_DEST="$BAUDBOT_HOME/.pi/agent/HEARTBEAT.md"
+
+if [ "$DRY_RUN" -eq 0 ]; then
+  # HEARTBEAT.md — always overwrite (admin-managed checklist)
+  if [ -f "$HEARTBEAT_SRC" ]; then
+    as_agent cp "$HEARTBEAT_SRC" "$HEARTBEAT_DEST"
+    as_agent chmod 644 "$HEARTBEAT_DEST"
+    log "✓ HEARTBEAT.md"
+  fi
+else
+  log "would copy: HEARTBEAT.md"
+fi
+
 # ── Slack Bridge ─────────────────────────────────────────────────────────────
 
 echo "Deploying slack-bridge..."

bin/test.sh

@@ -49,6 +49,7 @@ echo ""
 if [ "$FILTER" = "all" ] || [ "$FILTER" = "js" ]; then
   echo "JS/TS:"
   run "tool-guard"        node --test pi/extensions/tool-guard.test.mjs
+  run "heartbeat"         node --test pi/extensions/heartbeat.test.mjs
   run "bridge security"   node --test slack-bridge/security.test.mjs
   run "extension scanner" node --test bin/scan-extensions.test.mjs
   echo ""