From 7d925de00d584524f013b4ac1fe1a9ddc09746e5 Mon Sep 17 00:00:00 2001
From: Godopu <godopu16@gmail.com>
Date: Sun, 21 Jun 2026 06:37:28 +0000
Subject: [PATCH] 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.
---
 .../tmux-agent-orchestrate-monitor/SKILL.md   | 21 ++++++++++++++++++-
 .../scripts/reconcile.sh                      |  3 ++-
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/skills/tmux-agent-orchestrate-monitor/SKILL.md b/skills/tmux-agent-orchestrate-monitor/SKILL.md
index 6a4958b..7b6c576 100644
--- a/skills/tmux-agent-orchestrate-monitor/SKILL.md
+++ b/skills/tmux-agent-orchestrate-monitor/SKILL.md
@@ -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
diff --git a/skills/tmux-agent-orchestrate-monitor/scripts/reconcile.sh b/skills/tmux-agent-orchestrate-monitor/scripts/reconcile.sh
index d2b829a..c8afae6 100755
--- a/skills/tmux-agent-orchestrate-monitor/scripts/reconcile.sh
+++ b/skills/tmux-agent-orchestrate-monitor/scripts/reconcile.sh
@@ -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',