/heartbeat

> Agent wake-up protocol and health monitoring.

Purpose

Two functions in one. First: the startup ritual every agent runs when it wakes up — a 9-step cycle that establishes identity, checks approvals, fetches available work, selects a task, locks it, understands context, executes, updates status, and optionally delegates sub-work. Second: a monitoring heartbeat that detects stalled, crashed, or unresponsive agents and triggers recovery.

Usage

bash
# Run the wake-up cycle (agent runs this on startup)
/heartbeat

# Run heartbeat for a specific agent
/heartbeat --agent researcher

# Check health of all running agents
/heartbeat --check-all

# Set heartbeat interval
/heartbeat --interval 60s

# View heartbeat history
/heartbeat --history --last 10

# Force wake-up of a stalled agent
/heartbeat --wake researcher

Arguments

| Flag | Type | Default | Description | |------|------|---------|-------------| | --agent | string | self | Agent to run heartbeat for | | --check-all | flag | false | Health check all registered agents | | --interval | duration | 60s | Time between heartbeat pings | | --timeout | duration | 180s | Mark agent as stalled after this silence | | --history | flag | false | Show heartbeat event history | | --last | int | 10 | Number of history entries to show | | --wake | string | — | Force wake-up of a specific agent | | --on-stall | enum | warn | Action on stall: warn, restart, reassign, kill |

Workflow

Wake-Up Cycle (9 steps)

1. Identity — Load agent identity: name, role, capabilities, system prompt. Confirm workspace scope and permissions.
2. Approvals — Check for any pending approval requests (from /approve). Process approvals before starting new work.
3. Fetch tasks — Query task store for available tasks matching this agent's capabilities. Filter by priority and dependencies.
4. Select work — Pick the highest-priority task that isn't locked. Consider: deadline proximity, complexity match, budget remaining.
5. Checkout — Lock the selected task via /checkout. If lock fails (409), return to step 4.
6. Understand — Load task context: read referenced files, check parent chain, review related messages in inbox.
7. Execute — Perform the task. Use available commands within scope. Track token consumption.
8. Update — Write result to task store. Update status: in_progress → complete or blocked. Send result message to parent.
9. Delegate — If sub-tasks were identified during execution, create them via /delegate. Return to step 3 if more work available.

Health Monitoring

1. Ping — Each agent writes a heartbeat file with timestamp every --interval.
2. Check — Monitor reads all heartbeat files. Flag any agent whose last heartbeat exceeds --timeout.
3. Respond — Based on --on-stall: warn (log + alert), restart (kill + respawn), reassign (release tasks + redistribute), kill (terminate).

Output

Wake-up cycle output

markdown
## Heartbeat — researcher (agent-a1b2)

| Step | Status | Detail |
|------|--------|--------|
| 1. Identity | done | researcher / Market Analyst / scope: read-only |
| 2. Approvals | done | 0 pending |
| 3. Fetch tasks | done | 3 available tasks |
| 4. Select work | done | task-d4e5: "Analyze competitor pricing" (priority: high) |
| 5. Checkout | done | Lock acquired |
| 6. Understand | done | Loaded 4 context files (8,200 tokens) |
| 7. Execute | running | ... |

Health check output

markdown
## Agent Health — All Agents

| Agent | Status | Last Heartbeat | Current Task | Budget Used |
|-------|--------|---------------|--------------|-------------|
| researcher | healthy | 12s ago | task-d4e5 | 23,400/50,000 |
| writer | healthy | 8s ago | task-f6g7 | 11,200/30,000 |
| analyst | stalled | 4m 12s ago | task-h8i9 | 45,100/50,000 |
| coder | idle | 3s ago | — | 0/100,000 |

### Alerts
- analyst: STALLED (exceeded 180s timeout). Last activity: writing to processed/report.md. Action: warn.

Dependencies

• Agent registry
• /checkout — Task locking (step 5)
• /inbox — Message checking (step 2) and result delivery (step 8)
• /delegate — Sub-task creation (step 9)
• /budget — Budget tracking
• File system for heartbeat files