# pi_wake_agent.py — Multi-Agent Wake Timer

**Location:** `/mnt/dolphinng5_predict/pi_wake_agent.py`  
**Branch:** `tools/pi_wake_agent`  
**Status:** v1.0 — 38 tests passing

---

## Overview

Reusable multi-agent wake-up timer with self-cron/daemon/succession modes. Designed for the DOLPHIN fleet (pi_nvnemo, cmd, mimo, codex, etc.) to send doorbell injections via zellij and durable messages via h5i bus.

---

## Installation

```bash
cd /mnt/dolphinng5_predict
python3 pi_wake_agent.py --install --interval 30m --session pi_test --msg "Wake up!"
```

---

## Modes

| Mode | Flag | Description |
|------|------|-------------|
| Install cron | `--install` | Recurring wake via system cron |
| One-shot | `--once` | Single wake after interval (no cron) |
| Daemon | `--daemon` | Long-lived process, no cron |
| Succession | `--succession` | Run N times at interval, then self-clean |
| Run (internal) | `--run` | Called by cron, executes wake |
| Remove | `--remove` | Remove cron entry |
| List | `--list` | Show active cron entries |
| Status | `--status` | Show cron + one-shot timers |
| Validate | `--validate` | Check zellij sessions exist |

---

## Options

| Option | Description |
|--------|-------------|
| `--interval DURATION` | Default: 1h. Formats: 30m, 1h, 90m, 2h, 10s |
| `--session SESSION` | Zellij session name (repeatable) |
| `--sessions "A,B,C"` | Comma-separated list |
| `--msg "MESSAGE"` | Wake message (default: "Operator says CONTINUE. Pi here!") |
| `--count N` | Number of runs for `--succession` |
| `--debug` | Enable debug logging |
| `--help` | Show help |

---

## Examples

```bash
# Recurring 1-hour wake for one session
pi_wake_agent.py --install --interval 1h --session cc_UV_dev0_Fb

# Multi-session 30-minute wake
pi_wake_agent.py --install --interval 30m --sessions "cc_UV_dev0_Fb,cc_UV_dev1_48" --msg "Wake up!"

# One-shot in 2 hours
pi_wake_agent.py --once --interval 2h --session cc_UV_dev0_Fb --msg "Time's up!"

# Run 3 times at 1-hour intervals, then self-clean
pi_wake_agent.py --succession --count 3 --interval 1h --session cc_UV_dev0_Fb --msg "Scheduled wake"

# Daemon mode (long-lived, no cron)
pi_wake_agent.py --daemon --interval 1h --session cc_UV_dev0_Fb

# Remove timer
pi_wake_agent.py --remove --session cc_UV_dev0_Fb --interval 1h

# List / status
pi_wake_agent.py --list
pi_wake_agent.py --status

# Validate sessions exist
pi_wake_agent.py --validate --session cc_UV_dev0_Fb
```

---

## Key Features

### Non-Blocking h5i Bus
Messages sent to Fable via `h5i msg send` are **fire-and-forget**:
- Runs in background thread
- 5-second timeout
- Silently ignores failures
- Never blocks the wake cycle

### Self-Cleaning Succession
```bash
pi_wake_agent.py --succession --count 3 --interval 1h --session S
```
Runs exactly 3 times at 1-hour intervals, then removes its own cron entry.

### Multi-Session
```bash
# Repeatable --session
pi_wake_agent.py --install --interval 1h --session s1 --session s2

# Comma-separated --sessions
pi_wake_agent.py --install --interval 1h --sessions "s1,s2,s3"
```

### Daemon Mode
Runs indefinitely as a long-lived process (no cron needed):
```bash
pi_wake_agent.py --daemon --interval 1h --session S
```

---

## h5i Bus Protocol Compliance

Every wake injection:
1. Identifies as `[pi_nvnemo via zellij]`
2. Includes `Run: h5i-bus msg inbox` directive
3. Sends 5× ENTER keypresses (1s delay) for reliable submission
4. Sends parallel h5i bus message for durability

Per [AGENT_TERMINAL_DIRECT_INTERVENTION_PROCEDURES.md](AGENT_TERMINAL_DIRECT_INTERVENTION_PROCEDURES.md).

---

## Testing

```bash
cd /mnt/dolphinng5_predict
python3 -m pytest test_pi_wake_agent.py -v
```
**38 tests passing** covering:
- Unit tests: interval parsing, cron comments, session parsing
- Integration: install/remove/list, one-shot, succession, run mode
- Edge cases: invalid intervals, missing sessions, invalid counts

---

## Cron Entry Format

```
*/30 * * * * cd /mnt/dolphinng5_predict && export H5I_AGENT=pi_nvnemo && /mnt/dolphinng5_predict/pi_wake_agent.py --run --sessions 'pi_test' --msg '...' # pi_wake_agent:pi_test:30m
```

Comment format: `pi_wake_agent:<sessions>:<interval>`

---

## Logs

- **File:** `/tmp/pi_wake_agent.log`
- **Rotation:** 10MB max, 5 files
- **Format:** `[YYYY-MM-DD HH:MM:SS] [LEVEL] message`

---

## Related Files

- `/mnt/dolphinng5_predict/pi_wake_agent.py` — Main script
- `/mnt/dolphinng5_predict/test_pi_wake_agent.py` — Test suite (38 tests)
- `/mnt/dolphinng5_predict/prod/docs/AGENT_TERMINAL_DIRECT_INTERVENTION_PROCEDURES.md` — Protocol
- Branch: `tools/pi_wake_agent`