fix(monitor): add status enum docs + subscribe security warning (FW-09, FW-15)

FW-09: SKILL.md defines valid last_visible_status values (running/stopped/
  terminated/archived). reconcile.sh now sets last_visible_status to
  'running' and uses last_visible_note for free-form comments.

FW-15: SKILL.md adds Security section for --subscribe on public brokers.
  Documents wildcard subscription risks, auto-kill spoofing, HMAC
  verification mitigation, and recommends --once/polling for PoC.
This commit is contained in:
2026-06-21 06:37:28 +00:00
parent 2cffcc46c5
commit 7d925de00d
2 changed files with 22 additions and 2 deletions
+20 -1
View File
@@ -111,6 +111,10 @@ Flags: `--once` (single pass), `--emit-diff` (print JSON), `--dry-run` (P1-E —
## Drift classes (what the script handles)
### Status Enum
The `status` and `last_visible_status` fields MUST be one of the following exact strings: `running`, `stopped`, `terminated`, `archived`.
Any unstructured comments or reasons for the status change should be placed in `last_visible_note` or `termination_mode`.
### A. tmux dead, YAML says running → auto-terminate
```
@@ -133,7 +137,7 @@ captured `*_session_id_own`, so the monitor must **not** overwrite it with
tmux: session=lab-paper-pdf2md-creator-agy, pid=...,
cmd=agy, cwd=$WORKSPACE_ROOT/paper-pdf2md
YAML: no such session
→ register as new entry: status=running, last_visible_status=auto-registered
→ register as new entry: status=running, last_visible_status=running, last_visible_note=auto-registered
→ comment: "lab-paper-pdf2md-creator-agy: tmux found but not in YAML. Auto-registered."
```
@@ -203,6 +207,21 @@ If `$HERMES_KANBAN_TASK` card has any comment containing "stop" or "stop monitor
- Do NOT call `git commit` / `git push`
```
## Security: --subscribe on Public Brokers
When using `--subscribe` with the default PoC public broker
(`broker.hivemq.com:1883`), be aware that:
1. **Wildcard subscription** means anyone can publish events to your job topics.
2. **Auto-kill on terminal events** means a spoofed `completed` or `error`
event from a third party can terminate your agent session.
3. **Mitigation**: Use `--subscribe` only on private TLS-enabled brokers
(production mode). For PoC, prefer polling-based monitor (`--once` or
no `--subscribe`) which reads YAML/tmux state directly without MQTT.
4. **HMAC verification**: Events are now verified via `verify_hmac()` in
`mqtt_common.py` (see FW-05). Ensure `auth_token` is set for each job
to enable signature validation — unauthenticated events will be dropped.
## Verification (one-shot)
```bash
@@ -343,7 +343,8 @@ if tmux_confirmed:
'start_command': f'tmux {server_opt}new-session -d -s "{name}" -x 140 -y 40 -c "{pm["cwd"]}" "{cmd_full}"',
'attach_command': f'tmux {server_opt}attach -t {name}',
'kill_command': f'tmux {server_opt}kill-session -t {name}',
'last_visible_status': 'auto-registered by monitor',
'last_visible_status': 'running',
'last_visible_note': 'auto-registered by monitor',
}
if agent == 'claude':
entry['tui'] = {'model': '(unknown — capture after first message)', 'provider': 'anthropic',