opencode-thrum-pro 0.1.3 → 0.1.5

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

@@ -21,7 +21,11 @@ every agent in your `roster`:
    never capture ad-hoc or key on fixed prompt phrases. A failed or empty
    capture is NOT a dead or idle pane: fall back and re-read; never skip a
    roster member because its capture failed. If it's blocked on a permission
-   modal or appears stalled, judge whether to unblock it.
+   modal or appears stalled, judge whether to unblock it. A member that is
+   *persistently* unwatchable (fails every capture path, isolated,
+   unreachable) is escalated to your `parent` every cycle until a coordinator
+   or human removes it from your roster — never dropped, never silently
+   given up on (see Escalation).
 2. **Watch its context% and warn.** Read its ctx% from YOUR OWN tmux
    capture of its status bar — **never from a figure it claims about
    itself** (a message, a memory-footer line, anywhere). If it's getting
@@ -50,8 +54,10 @@ every agent in your `roster`:
 - 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) — never `thrum tmux key`,
-  which is local-socket-only and errors on a remote agent. This grants only
+  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.
@@ -115,6 +121,30 @@ 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.
 
+### An unwatchable roster member: escalate every cycle until it is removed
+
+A roster member you **cannot watch at all** — capture fails by every path
+(local proxy *and* SSH fallback), the agent is fully isolated, or its owning
+daemon is unreachable so you cannot even message it — is NOT a member you may
+drop, mark dead, or fall silent on. It stays in your roster and it stays your
+duty.
+
+- **Escalate it to your `parent` every cycle it remains unwatchable —
+  repeatedly, not once.** A single "fully isolated" notice that you then stop
+  repeating is exactly the silent-give-up this archetype exists to prevent:
+  the roster member goes dark with nobody positioned to notice. Re-send the
+  escalation on each tick it is still unwatchable. (This is a standing
+  per-cycle duty, unlike the one-shot declared-intent nudge.)
+- **You never remove it from your own roster.** Roster membership is
+  coordinator-owned config in `watch_params.json`, which you only ever read.
+  Only a **coordinator or the human** may remove an agent from your roster —
+  the signal that it no longer needs watching. Until that removal lands in
+  `watch_params.json`, you keep escalating.
+- **Do not borrow the empty-roster shutdown rule here.** "Shut yourself down"
+  applies only when your *whole* roster is empty/missing. One unwatchable
+  *member* out of several is not that case: keep watching the rest, keep
+  escalating the unwatchable one.
+
 ## Declared-intent reminders (duty #4)
 
 Each cycle, for each roster member, judge whether the last assistant turn
@@ -197,18 +227,22 @@ stability check, writes one report file, and emits one matchable summary
 line. It is mechanical only — no auto-escalate, no auto-key — exactly the
 scope this section already describes; judgment stays in your own turn.
 
-**Setup (one-time per watcher instance):** `CLAUDE_PLUGIN_ROOT` is a
-Claude-Code-hook-only env var — it is NOT present in `thrum monitor`'s
-scheduled-process environment, so the script cannot locate itself inside
-the plugin tree at run time. Copy both scripts out of the skill's
-`resources/` into your own agent directory first:
-
-```bash
-cp "${CLAUDE_PLUGIN_ROOT}/skills/persistent-watcher-archetype/resources/thrum-watch-pane-capture.sh" \
-   "${CLAUDE_PLUGIN_ROOT}/skills/persistent-watcher-archetype/resources/thrum-capture-fallback.sh" \
-   .thrum/agents/<you>/
-chmod +x .thrum/agents/<you>/thrum-watch-pane-capture.sh .thrum/agents/<you>/thrum-capture-fallback.sh
-```
+**Setup (one-time per watcher instance):** the script cannot locate itself
+inside the plugin tree at run time — `thrum monitor`'s scheduled-process
+environment has none of the plugin-root env vars a hook invocation gets
+(`CLAUDE_PLUGIN_ROOT`, codex's `PLUGIN_ROOT`), and neither is reliably set
+in an ordinary interactive turn either, so a shell `cp` against either
+variable is not runtime-safe in any host. Copy both scripts out of the
+skill's `resources/` into your own agent directory using your Read/Write
+tools instead — the same skill-relative resolution every other `resources/`
+reference in this plugin already uses, with no env var and no
+runtime-versioned path involved:
+
+1. Read `resources/thrum-watch-pane-capture.sh` (relative to this skill) and
+   Write its exact content to `.thrum/agents/<you>/thrum-watch-pane-capture.sh`.
+2. Read `resources/thrum-capture-fallback.sh` and Write its exact content to
+   `.thrum/agents/<you>/thrum-capture-fallback.sh`.
+3. `chmod +x .thrum/agents/<you>/thrum-watch-pane-capture.sh .thrum/agents/<you>/thrum-capture-fallback.sh`
 
 Then register the monitor against that absolute copy path —
 **`--notify-on-success` is MANDATORY, not optional decoration**: a

package/assets/skills/persistent-watcher-archetype/resources/thrum-capture-fallback.sh

@@ -63,12 +63,16 @@ ssh_destination() {
 
 run_local() {
   case "$MODE" in
-    # "${EXTRA_ARGS[@]:-}" not "${EXTRA_ARGS[@]}": a DECLARED-EMPTY array
-    # subscripted with [@] is a fatal unbound-variable under `set -u` on
+    # "${EXTRA_ARGS[*]:-}" not "${EXTRA_ARGS[*]}": a DECLARED-EMPTY array
+    # subscripted with [*] is a fatal unbound-variable under `set -u` on
     # bash <4.4 (a real bug, not a style choice -- `key` mode with zero
     # key args crashes on this fleet's /bin/bash 3.2.57 without the ":-").
+    # key mode delivers named tmux keys via `thrum tmux send --keys` (the
+    # peer-routed replacement for the retired local-only tmux-key primitive);
+    # EXTRA_ARGS (one key per element) is comma-joined into a single --keys
+    # value inside a subshell so IFS="," never leaks into the caller.
     capture) thrum tmux capture "$AGENT" 2>&1 ;;
-    key)     thrum tmux key "$AGENT" "${EXTRA_ARGS[@]:-}" 2>&1 ;;
+    key)     thrum tmux send "$AGENT" --keys "$(IFS=,; printf '%s' "${EXTRA_ARGS[*]:-}")" 2>&1 ;;
   esac
 }
 
@@ -77,7 +81,7 @@ run_ssh() {
   dest="$(ssh_destination)"
   case "$MODE" in
     capture) cmd="thrum tmux capture '$AGENT'" ;;
-    key)     cmd="thrum tmux key '$AGENT' ${EXTRA_ARGS[*]:-}" ;;
+    key)     cmd="thrum tmux send '$AGENT' --keys $(IFS=,; printf '%s' "${EXTRA_ARGS[*]:-}")" ;;
   esac
   # Client-side expansion of REPO_PATH/cmd into the remote command string is
   # intentional -- that's how the resolved repo path and thrum invocation

package/assets/skills/persistent-watcher-archetype/resources/thrum-watch-pane-capture.sh

@@ -29,7 +29,7 @@
 #
 # DELIBERATE SCOPE LIMIT: this script is MECHANICAL ONLY — capture, detect,
 # emit. It never auto-escalates and never auto-approves/denies a modal
-# (never calls `thrum tmux key`/`thrum send`). The persistent-watcher-
+# (never sends keys or text — never calls `thrum tmux send`). The persistent-watcher-
 # archetype skill is explicit that judgment (approve/cancel/escalate/nudge)
 # happens in the watcher's OWN turn when it reads the wake message this
 # script's summary line triggers, not in a script. A bash script cannot

package/assets/skills/state-migration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: state-migration
-description: "Use when your agent-local thrum state is empty AND you have an existing State.md file in your agent directory - this is a ONE-TIME conditional onboarding that fires only on that exact combination. Do NOT use if thrum state already has entries (nothing to migrate) or if you have no State.md (brand-new agent, nothing to migrate). Triggers on: first session after the thrum state redesign lands, `thrum state list` returning empty while State.md exists on disk, being asked to migrate your personal state."
+description: "Use when your agent-local thrum state is empty AND you have an existing State.md file in your agent directory - this is a ONE-TIME conditional onboarding that fires only on that exact combination. Do NOT use if thrum state already has entries (nothing to migrate) or if you have no State.md (brand-new agent, nothing to migrate). Triggers on - first session after the thrum state redesign lands, `thrum state list` returning empty while State.md exists on disk, being asked to migrate your personal state."
 ---
 
 # Migrating personal State.md into `thrum state`

package/assets/skills/using-the-dashboard/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: using-the-dashboard
+description: "Use when you want to present an interactive board to the human user (status, options, NEEDs with A/B/C picks), or when you see a dashboard mention and wonder what is actually usable today. Carries the CLI surface, the write/read discipline, and the live-vs-coming honesty table."
+---
+
+# Using the Agent Dashboard
+
+The Dashboard is an agent's way to put an **interactive board** in front of the
+human user: typed widgets (status rows, cards, lists), optional HTML regions,
+and **action-picks the user answers by clicking an option and optionally typing
+nuance**. It replaces the "agent runs a TUI" pattern — it is out-of-band from
+the messaging channel, so it never blocks messages and answers never scroll
+away.
+
+This is the COMMONS skill: role-agnostic surface + discipline. Role overlays
+(`coordinator-dashboard-human-loop`, `brainstormer-dashboard-needs`) add the
+role-specific loop on top. When an overlay and this skill conflict, the overlay
+wins for role-specific behavior.
+
+## 🔴 Honesty table — what is usable TODAY
+
+Check this BEFORE you promise the human anything. Stale promises are worse
+than no dashboard.
+
+| Capability | Status |
+|---|---|
+| `dashboard.set/get/show/clear/delete` RPCs (daemon-side) | **LANDED** on trunk (merge `6c7539236f83`); usable only against daemons BUILT after that merge — verify your daemon's build before relying on the RPCs |
+| `thrum dashboard` CLI (set/show/get/update/delete/clear/results) | **LANDED** on trunk (merge `108511a0`); usable only against a `thrum` binary BUILT after that merge — verify your CLI's build before relying on these commands |
+| Web UI Dashboard tab (where the human SEES a board) | **BUILT, NOT YET DEPLOYED** (E3 landed on trunk, merge `49712f87` — visible after the next deploy) |
+| Answer round-trip (user clicks → message + nudge to you) | **BUILT, NOT YET DEPLOYED** (E4 landed on trunk, merge `ea95318a` — visible after the next deploy) |
+
+**Consequence until the next deploy carries E3 and E4:** publishing a board
+is STILL a no-op for the human on any box running a pre-E3/pre-E4 binary —
+it renders NOWHERE there and, even where it renders, an answer cannot
+return to you, even though the UI and answer-round-trip code now both exist
+on trunk. Do NOT substitute a dashboard for a nudge or a direct message
+unless you know the box you're talking to has deployed a build containing
+BOTH E3 and E4. If the human cannot see the board or their answer cannot
+reach you, the question DOES disappear — the exact failure the dashboard
+exists to kill.
+
+**Consequence, now that E2 has landed:** the `thrum dashboard ...` command
+shapes below are runnable — but, per the E2 row above, only against a CLI
+binary built after `108511a0`. Against an older binary, or if you're
+calling the daemon directly, the raw RPCs (`dashboard.set` etc. over the
+daemon socket) remain the fallback surface.
+
+## The board model
+
+A dashboard is ONE structured document per agent: an envelope
+`{v, agent_id, title, updated_at, rev, widgets[]}`. Six widget types:
+`section` (labeled grouping), `stat-row` (label/value pairs),
+`card` (title + markdown body), `list` (ordered rows),
+`action-pick` (question + options + optional text — the interactive control),
+`html` (sanitized rich region, authored from a FILE).
+
+Semantics that matter to you as an author:
+
+- **Append-only + rev'd.** Every change appends a new snapshot; `rev` increments.
+  Your `update` keeps a widget's position; `delete` removes it; `clear` wipes
+  the board. Cleared/deleted content is **GONE** — the board is ephemeral, and
+  the DURABLE record of any decision is the answer MESSAGES, not the board.
+- **Widget cardinality (enforced):** action-pick ≤8, html ≤4, section ≤8,
+  card ≤24, stat-row ≤12, list ≤4, total ≤64. Lists have NO row cap.
+- **Answer path:** when the user answers an action-pick, you get a **nudge**
+  and the answer lands as a thrum MESSAGE (payload type `dashboard.answer`,
+  carrying `question_id`, the option `pick`, optional `text`). You read
+  answers with `thrum dashboard results`, then flip the widget's status via
+  `thrum dashboard update` so the board shows it resolved.
+- **User deletes are SILENT.** If a widget you posted disappears, the user
+  dismissed it — you are NOT nudged. Notice it on your next `show`; do not
+  repost it reflexively (the user saw it and removed it on purpose).
+- **No dashboard yet is not an error.** `dashboard.get`/`dashboard.show`
+  succeed with `found: false` and an empty envelope when nothing has been
+  posted for you yet — do not treat that as a failure to recover from.
+- **Concurrent writes are guarded by `expected_rev`, not merged.** If you pass
+  `expected_rev` and it no longer matches the board's current `rev`, the write
+  is rejected with `dashboard changed (rev %d, you expected %d) — re-read with
+  dashboard show and resubmit`. Fix: re-fetch the current document and
+  resubmit with the fresh `rev`. Omitting `expected_rev` skips the check
+  entirely (last-writer-wins) — fine for your own solo edits, risky if
+  something else writes the same board.
+
+## CLI surface (runnable now, against a `thrum` binary built after `108511a0`)
+
+```bash
+# Publish/replace whole widgets (upsert by widget id — targets update in place)
+cat > /tmp/board.md <<'EOF'
+{"title": "My board", "widgets": [ ... ]}
+EOF
+thrum dashboard set --doc-file /tmp/board.md
+thrum dashboard set --stdin < /tmp/board.md
+
+# HTML regions come from FILES ONLY — never inline (backticks in shell strings EXECUTE)
+thrum dashboard set --html-file /tmp/panel.html --html-id my-panel
+
+# Read
+thrum dashboard show                 # compact outline: what's on the board, what's PENDING/ANSWERED
+thrum dashboard get <widget-id>      # full widget JSON
+thrum dashboard results              # user answers (after your nudge), newest N selected, displayed oldest-first
+thrum dashboard results --unanswered # only questions with no answer yet
+
+# Mutate
+thrum dashboard update <widget-id> --doc-file /tmp/new-widget.json   # in place, keeps position
+thrum dashboard delete <widget-id>
+thrum dashboard clear                # wipe the whole board (content is GONE)
+```
+
+**Validation loop:** `set`/`update` either print `posted OK (rev N)` or fail
+with one of three error shapes: a per-widget schema error naming the exact
+widget id + field; a per-type cardinality error naming the widget TYPE + count
+(e.g. "too many action-pick widgets: 9 (max 8)"); or the aggregate/total-cap
+error, which names a CATEGORY TOKEN + count + max rather than a widget type
+(e.g. "too many widgets (total_widgets): 65 (max 64)" — "total_widgets" is the
+violation category, not a widget type: the per-type limits sum to 60 < 64, so
+a doc breaching 64 always breaches some per-type limit too, and there is no
+single offending widget type to name). On any of these: fix the file and
+resubmit — do not recompute the whole board inside one invocation.
+
+**Authoring rules with teeth:**
+
+- Widget `id`s are load-bearing — stable across updates; `update`/`delete`
+  and the answer join key off them (action-picks also carry `question_id`).
+- Text fields render as MARKDOWN (no raw HTML — that is the `html` widget's
+  job, sanitized). Keep compact fields single-line.
+- HTML files: no script/style/iframe/event-handlers — the render side strips
+  them, but author clean anyway.
+
+## When to reach for the dashboard (vs a nudge vs a message)
+
+- **Dashboard:** state the human will consume VISUALLY and possibly answer
+  interactively — rosters, queues of options, pipelines, NEEDs with discrete
+  choices. Persistent board the human checks on their own rhythm.
+- **Nudge:** something needs attention NOW and is small (one line). The
+  dashboard does not pulse or blink; urgent + tiny = nudge.
+- **Message:** conversation, anything needing prose back-and-forth, or anything
+  the record must keep forever (decisions live in messages).
+
+Anti-pattern: posting a board INSTEAD of answering a direct question. The
+dashboard is a surface you maintain, not a replacement for talking.
+
+## Refs to other skills
+
+- `coordinator-dashboard-human-loop` — coordinator overlay: owning a board for
+  the human, the human-loop mandate
+- `brainstormer-dashboard-needs` — brainstormer/researcher overlay: authoring
+  NEEDs as answerable action-picks
+- `using-the-queue`, `using-thrum-state` — sibling agent-tied local surfaces

package/assets/skills/using-thrum-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-thrum-state
-description: "Use when reading or writing thrum state - checking your own agent-local current state at session start, updating your status/next-actions, reading a fleet fact like deploy state or topology before acting on it, citing a SHA or box fact in a decision, deciding whether a fleet row is fresh enough to trust, or responding to a freshness-sweep ping. Also use before writing any fleet row - deploy state, topology, worktree, agent pool, or a standing ruling - to confirm you are writing from a by-effect measurement, not a guess. Triggers on: citing a fleet fact, deploying, restarting a daemon, migrating schema, reconciling state at session start, receiving a stale-row ping."
+description: "Use when reading or writing thrum state - checking your own agent-local current state at session start, updating your status/next-actions, reading a fleet fact like deploy state or topology before acting on it, citing a SHA or box fact in a decision, deciding whether a fleet row is fresh enough to trust, or responding to a freshness-sweep ping. Also use before writing any fleet row - deploy state, topology, worktree, agent pool, or a standing ruling - to confirm you are writing from a by-effect measurement, not a guess. Triggers on - citing a fleet fact, deploying, restarting a daemon, migrating schema, reconciling state at session start, receiving a stale-row ping."
 ---
 
 # Using Thrum State

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-thrum-pro",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Thrum multi-agent coordination plugin for Open Code",
   "type": "module",
   "main": "./dist/index.js",