# pi_wake_agent — DOLPHIN fleet wake timer (Pi)

Reusable multi-agent wake timer. Wakes zellij sessions (Dolphin fleet:
pi_nvnemo, cmd, mimo, codex, ...) on a recurring / one-shot / daemon /
succession schedule, delivering doorbell injections via zellij + durable
messages via the h5i bus.

## Files (the watcher)
- `pi_wake_agent.py`   — the wake timer (source: `/mnt/dolphinng5_predict/pi_wake_agent.py`,
  branch `tools/pi_wake_agent`).
- `PI_WAKE_AGENT_TOOL.md` — tool spec + usage: `--install/--once/--daemon/`
  `--succession --count N --remove/--list/--status/--validate`; intervals
  (`30m`, `1h`, `10s`, ...); `--session`/`--sessions "A,B"`; `--msg`.
- `test_pi_wake_agent.py`   — 38 unit tests (interval parsing, cron comments, session parsing).

## Example — wake a session every 15 min (monitor .68, stop+diag on fault)
python3 pi_wake_agent.py --install --interval 15m --session <zellij-session> \
  --msg "RECHECK .68: stale_snapshot/preemption_refusal/TP-arm vs MAX_HOLD; stop+diag if fault"

Manage: `--list`, `--status`, re-enable with `--install`, cancel with `--remove`.

## Notes
- The 20 m doorbell is currently DISABLED by operator order (crontab entry
  `pi_wake_agent:pi_test:20m` removed; backup at `/root/.cache/crontab/crontab.bak`).
- It is a wake/ping timer, NOT an autonomous monitor/stop-and-diag agent: the
  woken agent performs the checks. For autonomous stop+diag on fault, pair it
  with a host-local cron guard (`/etc/cron.d/.68_guard` + `p68_guard.sh`) which
  actually stops the unit + dumps diagnostics.
- Cross-ref: §3.4 "Pi Wake Agent (multi-agent wake timer)" in
  `AGENT_ONBOARDING_GENERAL_DOCUMENT.md`.

## Committer
`pool4 <pool4@normey.net>`