SYS BOTS

# SYS_BOTS — Kingdom Sentinel Bot Roster
KID:CORE:SYS:BOTS|2.0:LIVE:2026-03-13:⌂

## Purpose

Sentinel bots are lightweight bash daemons that monitor specific Kingdom failure
modes and alert via RAVEN envelope when thresholds are crossed. They run on
launchd schedules, always exit 0, and never interrupt daemon operation.

## Bot Pattern (canonical)

```bash
set -euo pipefail
BOT_NAME="bot-name"
LOG="$FORGE_DIR/logs/${BOT_NAME}.log"
MAILBOX="$HOME/Desktop/THE_FORGE/@FORGE_CLAUDE_MAILBOX"

BOT_RESULT=0
trap 'if [ $BOT_RESULT -ne 0 ]; then
  # self-crash report to RAVEN
fi' EXIT

# check → if bad → printf RAVEN envelope > "$MAILBOX/${BOT_NAME}_ALERT_$(date +%Y%m%d-%H%M%S).md"
exit 0  # always
```

RAVEN envelope format:
```
---
TO: FORGE_CLAUDE
FROM: [bot-name]
SUBJECT: [subject]
PRIORITY: [URGENT|IMPORTANT|NORMAL|LOW]
---

[body]
```

## Full Roster (12 bots)

| Bot | Schedule | Monitors | Alert Priority | Shipped |
|-----|----------|----------|----------------|---------|
| `bot-dead-silence` | Daily 09:00 | SCRYER briefing >36h stale | URGENT | S166 |
| `bot-mailbox-health` | Every 60 min | Mailbox envelopes stuck >30min | IMPORTANT | S166 |
| `bot-spend-spike` | Every 30 min | API token spend >$8 in 2h | IMPORTANT | S166 |
| `bot-pulse-health` | Every 20 min | Overmind Pulse no activity >20min | URGENT | S166 |
| `bot-mission-stale` | Daily 09:00 | P1 missions idle >24h | IMPORTANT | S166 |
| `bot-ollama-watchdog` | Every 60 min | ollama + gemma3:4b availability | IMPORTANT | S166 |
| `bot-signal-jam` | Every 30 min | signals_queue pending jam >60min | IMPORTANT | S166 |
| `bot-disk-sentinel` | Every 60 min | Main disk <20% free | IMPORTANT/URGENT | S166 |
| `bot-launchd-roster` | Every 120 min | Critical plists unloaded | IMPORTANT | S166 |
| `bot-aeris-heartbeat` | — | Monitors Aeris heartbeat signal | — | S186 |
| `bot-git-drift` | — | Detects git drift / uncommitted accumulation | — | S186 |
| `bot-stream-gap` | — | Monitors for SCRYER stream gaps | — | S186 |

## File Locations

- **Scripts + plists:** `FORGE_CLAUDE/05_🔧_TOOLS/bots/`
- **Installer:** `05_🔧_TOOLS/bots/install-bots.sh` (idempotent, run to update)
- **Logs:** `FORGE_CLAUDE/logs/bot-*.log`
- **Alerts:** `~/Desktop/THE_FORGE/@FORGE_CLAUDE_MAILBOX/` root (RAVEN picks up)

## Launchd Labels

All 12 bots: `com.forge.bot-[name]`

## Critical Daemon Roster (bot-launchd-roster watches these)

```
com.aeris.overmind      — Overmind Pulse (mission execution)
com.scryer.watcher      — SCRYER signal detection
com.forge.raven         — RAVEN message routing
com.sinner-king.console — Sinner King Console (Electron)
com.forge.raven.web     — RAVEN web UI
com.forge.token-api     — Token Sentinel API
com.scryer.brief        — REVEILLE daily briefing
```

## Thresholds (tunable in each bot script)

| Bot | Key Threshold | Variable |
|-----|--------------|----------|
| bot-dead-silence | 36h | `STALE_THRESHOLD_HOURS` |
| bot-mailbox-health | 30min | `STUCK_THRESHOLD_MINUTES` |
| bot-spend-spike | $8 / 2h | `SPIKE_THRESHOLD_DOLLARS`, `WINDOW_HOURS` |
| bot-pulse-health | 20min | hardcoded in SQL window |
| bot-mission-stale | 24h | hardcoded in SQL window |
| bot-ollama-watchdog | 3s timeout | curl `--max-time` |
| bot-signal-jam | 60min, >3 signals | hardcoded in SQL + bash |
| bot-disk-sentinel | 20% / 10% | `WARN_THRESHOLD`, `CRITICAL_THRESHOLD` |
| bot-launchd-roster | n/a | `CRITICAL_ROSTER` array |

## Adding a New Bot

1. Copy an existing bot as template (bot-dead-silence.sh is cleanest)
2. Add plist to `bots/` directory (label: `com.forge.bot-[name]`)
3. Add to `BOTS=()` array in `install-bots.sh`
4. Run `bash install-bots.sh`
5. Add row to this doc

---
*Shipped: S166 (original 9) | S186 (+3: aeris-heartbeat, git-drift, stream-gap) | Society of Minds #5*
*LAST UPDATED: 2026-03-13 (S186)*