opencode-thrum-pro 0.1.5 → 0.1.7

package/assets/skills/persistent-watcher-archetype/SKILL.md

@@ -42,25 +42,115 @@ every agent in your `roster`:
    (your own pane capture) — see "Declared-intent reminders" below for the
    full mechanics.
 
-## The modal bright line (non-negotiable)
-
-- Approve ONLY clearly-safe, recognized, non-`rm`/non-`--force` modals.
-- `rm`, `--force`, or an unrecognized command → refuse or escalate to your
-  `parent`. That filter is mechanical.
-- Within the safe set, judge the COMMAND TEXT, not the modal's phrasing: read
-  the command and approve if it is clearly-safe and recognized whatever wording
-  the modal uses, else cancel or escalate. Never key on fixed prompt phrases;
-  never approve blind.
+## The modal judgment rubric (non-negotiable)
+
+- Approve a modal when you can explain what the command does, it fits what
+  the requesting agent is visibly doing in its pane, and a mistake would be
+  recoverable. Otherwise escalate to your `parent` with a one-line reason.
+- Judge the TARGET, not the keyword: `rm -rf /tmp/<dir the agent just
+  created>` is routine cleanup; `rm -rf /tmp/*` is not. One `rm` of a stale
+  lock file by a coordinator mid-deploy is fine. A force-push, or a delete
+  whose target or purpose you can't tell, is an escalate.
+- Escalating is always allowed. Refusing only because a keyword appeared is
+  not.
+- Judge the COMMAND TEXT, not the modal's phrasing: read the command and
+  approve or refuse on what it actually does, whatever wording the modal
+  uses. Never key on fixed prompt phrases; never approve blind.
 - Verify by re-capture after acting — never trust exit status alone.
-- To unblock a REMOTE roster member's modal, use `thrum tmux send <agent> " "`
-  (proxies by agent name to the owning peer daemon and appends Enter, so a
-  space+Enter confirms the default-focused option); for a specific selection
-  use `thrum tmux send <agent> --keys <K1,K2,...>`. `thrum tmux send` is
-  peer-routed, so it works identically local or remote (fleet-wide) — this is
-  the replacement for the retired local-only tmux-key primitive. This grants only
-  the leftmost/default option; the bright line above still applies. From the
-  CLI/peer-router path this send is QUEUED behind the conservative
-  monitor-silence wait, not instant — don't re-send while waiting it out.
+
+### Approving or dismissing a modal: keys only, never text
+
+> 🔴 **NEVER answer a modal with a text payload — not even a single
+> character, and never a bare positional argument to `thrum tmux send`.**
+> Plain text TYPES INTO the agent's input box; it does not act as a
+> keypress. If the modal isn't actually showing, or focus differs from what
+> you expect, that text lands in the agent's next command line and can
+> corrupt or execute something you never intended. The only correct
+> primitive is `--keys`, on every call, with no exceptions.
+
+The procedure, every time, no shortcuts:
+
+1. **Capture the pane fresh.** Never act on a stale capture from an earlier
+   cycle.
+2. **Recognize the modal and which option is currently focused** (`❯` or
+   equivalent marks the default). Judge it against the rubric above.
+3. **Choose keys, never text:**
+   - Default/focused option → `thrum tmux send <agent> --keys Enter`.
+   - A specific numbered option → the digit, e.g. `thrum tmux send <agent>
+     --keys 1`. Named keys (`Enter`, `Escape`, `Up`, `Down`, `Left`, `Right`,
+     `Tab`, digits) deliver in order, comma-separated or repeated
+     (`--keys Down,Enter` or `--keys Down --keys Enter`) — confirm the exact
+     syntax with `thrum tmux send --help` if in doubt, never guess it.
+   - To dismiss without selecting → `thrum tmux send <agent> --keys Escape`.
+   - This send is QUEUED behind the conservative monitor-silence wait, not
+     instant — don't re-send while waiting it out. A send that exits 3 (Enter
+     WITHHELD) or 4 (verdict unknown) must NOT be retried blind — capture the
+     pane first.
+4. **Re-capture and verify the modal is actually gone.** If it's still there,
+   don't give up and don't loop blindly retrying the same keys — work up an
+   escalating transport ladder, re-capturing to verify after EACH attempt:
+   a. `thrum tmux send <agent> --keys ...` — the daemon RPC you already tried
+      in step 3. It is peer-routed (works for a local member always, and for
+      a remote one when the `can_send_keys` capability is granted between
+      your box and theirs) — retry once in case the first send was dropped,
+      not blindly beyond that.
+   b. **Raw local tmux**, for a member on YOUR OWN box whose pane the daemon
+      RPC isn't reaching correctly: `tmux send-keys -t <session> <key>`, then
+      `tmux capture-pane -t <session> -p` to verify directly, bypassing the
+      daemon layer.
+   c. **SSH to the member's own box**, for a remote member or whenever (a)
+      fails with a proxy-failure signature (`rpcrouter: caller-peer lacks
+      required capability`, `peer unreachable`, `circuit open, dial skipped`)
+      — use the shipped pair of scripts, don't hand-roll the SSH call:
+      `resources/thrum-watch-pane-capture.sh`'s `build_topology_table` /
+      `resolve_roster_targets` resolves the target's SSH destination from
+      `thrum state get agent_pool:<agent>` (`.entry.value.box`) joined
+      against `thrum state show topology:<scope>` (`.entry.value.hostname`
+      / `.entry.value.ssh.target` / `.entry.value.ssh.user` /
+      `.entry.value.repo_path`), then hands those already-resolved values to
+      `resources/thrum-capture-fallback.sh <capture|key> <agent> <ssh_target>
+      <ssh_user> <repo_path> [keys...]`, which is the piece that actually
+      runs `ssh "<ssh_user>@<ssh_target>" "cd '<repo_path>' && thrum tmux
+      send '<agent>' --keys <keys>"` — `thrum-capture-fallback.sh` does no
+      resolution of its own, so calling it directly requires you (or the
+      caller) to already have those three values. A topology gap fails
+      closed (no SSH fallback attempted) rather than guessing a wrong
+      destination. There is no per-agent SSH field in the roster/agent Go
+      schema — the destination comes from this `thrum state` topology data.
+      (There IS a real `.thrum/ssh/config` on fleet boxes — the underlying
+      host-alias file, included via `~/.ssh/config`, that makes a bare `ssh
+      <box>` resolve at all — but it is not what these scripts read; they
+      read the resolved `ssh.target`/`ssh.user` values out of `thrum state`
+      instead.)
+   Only escalate to your `parent` after exhausting this ladder, or
+   immediately on an UNRECOGNIZED modal — and when you do, include the fresh
+   capture.
+- Cross-peer send-keys being capability-gated is a deliberate security
+  boundary (§ladder step a above), not a bug to route around by other means
+  without checking the failure signature first. A peer can always CAPTURE
+  another peer's panes read-only regardless of capability.
+
+**Worked example** — the standard two-variant Claude Code tool-confirmation
+modal (`internal/daemon/permission/patterns.go`, pattern `tool_confirmation`,
+dialect `claude-tui`), captured verbatim:
+
+```
+⏺ Bash(curl https://example.com)
+  ⎿  Do you want to proceed?
+     1. Yes
+     2. Yes, and don't ask again for Bash(curl)
+     3. No, and tell Claude what to do differently (Esc)
+```
+
+- **Approve once** → `--keys 1`.
+- **Deny, with feedback** → `--keys 3` (or `--keys Escape` on the two-option
+  Read-prompt variant, which has no "No, and tell Claude" line).
+- **NEVER `--keys 2`** — "Yes, and don't ask again" grants a standing
+  allow-rule beyond this one command; the modal judgment rubric above is a
+  per-command judgment, not a license to mint blanket permissions. This is
+  pinned by `ApproveKey: "1", // Yes (once) — NEVER "2"` in
+  `internal/daemon/permission/patterns.go` and tested by
+  `TestApproveKeyNeverForeverAllow`.
 
 ## Your own restart (auto-restart-at-ctx-threshold)
 
@@ -121,6 +211,22 @@ is the entire reason the watch exists — and a blocked coordinator cannot
 receive its own escalation. The escalation would arrive at the one inbox
 guaranteed not to be read.
 
+### 🔴 HUMAN-NEEDED escalation goes to the owner by message, never pane-only
+
+When you need a human decision, resolve the owner from CONFIG — never hardcode
+a name — and deliver it as a message, not pane text:
+
+    OWNER=$(jq -r '.permission_supervisors[] | select(startswith("@user:"))' .thrum/config.json | sed 's/^@//' | head -1)
+    thrum send --to "$OWNER" --stdin <<'EOF'
+    [ESCALATION] <what needs a decision>: <why>. Action needed: <what>.
+    EOF
+
+Writing the escalation only into your own pane is not delivery — nobody reads
+watcher panes. If you get no response within 15 minutes, resend and verify
+delivery (`thrum sent --unread`) before assuming it was seen. SAFE recognized
+modals stay approver-of-record and are approved directly, unchanged — this
+rule applies only to escalations that need a human decision.
+
 ### An unwatchable roster member: escalate every cycle until it is removed
 
 A roster member you **cannot watch at all** — capture fails by every path
@@ -217,8 +323,8 @@ Register the loop as a `thrum monitor` instead — a daemon-scheduled job,
 independent of your session, that keeps running across your restarts.
 
 **A ready-to-use script ships with this skill** — `resources/thrum-watch-
-pane-capture.sh` (paired with `resources/thrum-capture-fallback.sh`,
-thrum-3mhrt). It is generic and roster-driven: it reads your own
+pane-capture.sh` (paired with `resources/thrum-capture-fallback.sh`).
+It is generic and roster-driven: it reads your own
 `watch_params.json`, captures each roster member's pane (local `thrum tmux
 capture` first, always — that already reaches remote agents by name via the
 normal rpcrouter proxy; see "SSH fallback" below for what the second script
@@ -246,10 +352,10 @@ runtime-versioned path involved:
 
 Then register the monitor against that absolute copy path —
 **`--notify-on-success` is MANDATORY, not optional decoration**: a
-`--schedule`d job delivers NOTHING on `--match` alone (thrum-ruz1z §5c —
-this fails completely silently, every status field reads healthy, and it
+`--schedule`d job delivers NOTHING on `--match` alone — this fails
+completely silently, every status field reads healthy, and it
 is exactly the trap a literal reading of the syntax below used to walk
-readers into):
+readers into:
 
 ```bash
 thrum monitor start --name <you>-pane-watch \
@@ -267,13 +373,54 @@ At the start of every cycle, confirm the monitor is still running
 (`thrum monitor list`) — if it's missing or dead, re-`thrum monitor start`
 it rather than assuming someone else will notice.
 
+**Roster snapshot monitor:** copy `resources/roster-watch.sh`,
+`resources/capture_archive.py`, and `resources/jev_watcher_filter.py` into `<worktree>/.thrum-watch/`, then
+`chmod +x <worktree>/.thrum-watch/roster-watch.sh` — a mode-preserving copy of
+this resource can land as `644` depending on the runtime plugin's own tree
+(don't rely on the source file's mode alone) — then register the monitor
+against that copied `roster-watch.sh`. Keep the helper beside the script; the
+roster archive path must not depend on a plugin or research worktree path at
+run time. Captures and their archive land under `.thrum/agents/<you>/watch-captures/`
+(redirect-resolved), not beside the deployed script itself.
+
+Register roster-watch.sh's own monitor the same way, matching its actual
+output lines (`"roster capture ready:"` for a normal tick, `"ROSTER
+INCIDENT:"` for a capture-failure incident):
+
+```bash
+thrum monitor start --name roster-watch-<you> \
+  --match "^(roster capture ready:|ROSTER INCIDENT:)" \
+  --to @<you> \
+  --env AGENT_NAME=<you> \
+  --notify-on-success \
+  --schedule '*/10 * * * *' \
+  -- <worktree>/.thrum-watch/roster-watch.sh
+```
+
+Set `use_jev: true` in the watcher's redirect-resolved `watch_params.json`
+to filter notifications. JEV is opt-in ONLY when a key is actually present:
+`use_jev: true` alone does not engage it. The helper reads API keys from the
+watcher worktree's repo-root `.env` (or `ROSTER_JEV_ENV_FILE` if set);
+environment variables take precedence. `OPENROUTER_API_KEY` is an optional
+provider fallback. If `use_jev: true` but neither `THRUM_TYPESAFE_KEY` nor
+`OPENROUTER_API_KEY` is found (env or that `.env` file), the watcher logs
+`JEV requested but no key found — skipped` and runs the plain non-JEV path
+for that tick — no manifest filter, no decision directory, and
+`jev_watcher_filter.py` never runs. Confident active permission prompts and
+blocking user-choice dialogs wake the watcher. Failed or uncertain decisions use
+the normal watcher path. Missing or false `use_jev` retains normal behavior.
+
+Keep --notify-on-success when changing use_jev. A compatible daemon
+suppresses the success confirmation only after a completed, confidently ordinary
+JEV tick; changing the boolean needs no monitor re-registration.
+
 ### SSH fallback (resilience net, not the primary path)
 
 `thrum tmux capture <agent>` already reaches remote agents by name via the
 rpcrouter proxy — that is how fleet-wide watching works today for a healthy
 peer. `thrum-capture-fallback.sh` exists for when that proxy path is
-broken on the caller's side (known bug classes: thrum-7vwgy same-host
-dual-daemon caller-identity collision; thrum-zkqut phantom-routing
+broken on the caller's side (known bug classes: a same-host
+dual-daemon caller-identity collision; a phantom-routing
 regression on a daemon build predating `EnsureProxies`). It is a strict
 FALLBACK, never primary and never SSH-first: `thrum-watch-pane-capture.sh`
 always tries the local proxy path first, and only retries via an SSH hop —