opencode-thrum-pro 0.1.12 → 0.1.14

package/assets/skills/using-monitors/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: using-monitors
-description: "Use when scheduling a reminder, watching a log, or running a periodic check that must reach an agent - thrum monitor start, cron --schedule, --match, --notify-on-success, --debounce, recurring nudge, script check with exit codes, why a monitor message did not arrive, how to verify a monitor delivered."
+description: "Use when scheduling a reminder, watching a log, or running a periodic check that must reach an agent - thrum monitor start, cron --schedule, --match, --notify-on-success, --debounce, recurring nudge, plan follow-up reminder, remind me to check on my plan, check whether blockers have moved, prompt my pane on a schedule, monitor script that runs thrum tmux send, edit the script not the monitor, change a reminder without recreating the monitor, script check with exit codes, why a monitor message did not arrive, how to verify a monitor delivered."
 ---
 
-# Thrum Monitors - Reminders And Script Checks
+# Thrum Monitors - Reminders, Pane Prompts And Script Checks
 
 ## Overview
 
@@ -14,6 +14,12 @@ kept line, a scheduled monitor sends all the lines of a run in one message. With
 and restarts with backoff when it exits. Monitors persist across daemon
 restarts and run only on the daemon that owns them.
 
+A monitor reaches an agent in two ways. Its matched lines arrive as inbox
+messages, read at the next inbox check. Its command can also be a script that
+runs `thrum tmux send` to put a short prompt into the agent's own pane, which
+starts a turn. Keep the wording and logic of anything that will change in a
+script file: you then edit the script, and the monitor stays as it is.
+
 Every flag below appears in `thrum monitor start --help`. Re-read the help
 before relying on a flag not listed here.
 
@@ -32,11 +38,23 @@ thrum monitor delete <name|id>
 ```
 
 - `--name`, `--match` and `--to` are required; the command follows `--`.
+- The daemon accepts caller-relative target aliases on start/update and persists
+  the registered caller's concrete ID. Register the runtime with
+  `thrum quickstart`, or give an explicit recipient. Repair a legacy unresolved
+  alias with `thrum monitor update <id> --to @<agent>`, then restart; list/show
+  display its unresolved-target warning.
 - `--schedule` takes a 5-field cron expression. `update --schedule` changes the
   cron of a scheduled monitor at any time. Setting a first schedule or removing
   it (`--schedule ""`) switches the mode, which is refused while the monitor is
   running and allowed while it is stopped.
 - `--debounce` is leading-edge with a 30s minimum (default 1m).
+- `update` changes only the match, target, debounce and schedule. The command,
+  its arguments, `--cwd` and `--env` are fixed when the monitor starts, so text
+  written inline in the command can be changed only by deleting the monitor and
+  starting a new one. Text kept in a script file is changed by editing the file.
+- `--cwd` is the working directory the command runs in (default: the directory
+  you start the monitor from). `--env` adds one `KEY=VALUE` variable to the
+  command's environment and can be repeated.
 - `stop` leaves a stopped record that still holds the name; `delete` frees the
   name. Use a unique name per monitor.
 
@@ -45,6 +63,11 @@ thrum monitor delete <name|id>
 Each output line is tested against `--match` on its own. A line is truncated at
 2048 bytes with a marker appended.
 
+Read generated summaries as `<name>@<host>` and system notices as
+`[monitor:<name>@<host>]`; an unavailable hostname omits `@<host>`.
+Matched summaries show up to 160 characters of the deciding line; read the full
+matched output below, within the existing output and message limits.
+
 A scheduled (`--schedule`) job is a one-shot run, so its exit code is
 authoritative. It delivers ONE message at exit that carries every matched line,
 in order. A continuous job has no exit code per line, so it classifies and
@@ -52,11 +75,12 @@ delivers and classifies each matched line on its own, by its words.
 
 | Scheduled job                                                   | Delivered as                                  |
 | --------------------------------------------------------------- | --------------------------------------------- |
-| Non-zero exit, or the command failed to start                   | `[FAIL] <name>: exit code N` with the output tail, then the matched lines |
-| Exit 0, a matched line starts `ERROR:`, `FATAL:` or `FAIL:`     | `[FAIL] <name>: matched error pattern` + all matched lines |
-| Exit 0, highest prefix is `WARN:`, `WARNING:` or `ALERT:`        | `[WARN] <name>: matched WARNING` + all matched lines |
+| Non-zero exit                                                  | `[FAIL] <name>@<host>: exit code N` with the output tail, then the matched lines |
+| Command failed to start                                         | `[FAIL] <name>@<host>: <start error>` with details and an inspect command |
+| Exit 0, a matched line starts `ERROR:`, `FATAL:` or `FAIL:`     | `[FAIL] <name>@<host>: <matched line>` + all matched lines |
+| Exit 0, highest prefix is `WARN:`, `WARNING:` or `ALERT:`        | `[WARN] <name>@<host>: <matched line>` + all matched lines |
 | Exit 0, lines matched, no such prefix                           | All matched lines, in order, verbatim         |
-| Exit 0, nothing matched, `--notify-on-success`                  | `[OK] <name>: succeeded`                      |
+| Exit 0, nothing matched, `--notify-on-success`                  | `[OK] <name>@<host>: succeeded`                      |
 | Exit 0, nothing matched                                         | Nothing (logged only)                         |
 
 Cadence: the first non-zero scheduled run sends its `[FAIL]` notice; repeats of
@@ -93,8 +117,8 @@ past the retained prefix still sets the label.
 
 | Continuous job (no `--schedule`)                                | Delivered as                                  |
 | --------------------------------------------------------------- | --------------------------------------------- |
-| Contains `error`, `fatal`, `fail`, `permission denied`          | `[FAIL] <name>: matched error pattern` + line |
-| Contains `warn` or `warning`                                    | `[WARN] <name>: matched WARNING` + line       |
+| Contains `error`, `fatal`, `fail`, `permission denied`          | `[FAIL] <name>@<host>: <matched line>` + line |
+| Contains `warn` or `warning`                                    | `[WARN] <name>@<host>: <matched line>` + line       |
 | Contains a whole word `success`, `succeeded`, `complete`, `completed`, `done`, `ok` | Not delivered (logged only)   |
 | Any other matched line                                          | The line, verbatim                            |
 
@@ -111,13 +135,25 @@ Delivery limits:
 - The `[FAIL]` body for a non-zero exit carries only the last 500 bytes of
   output, so the message that matters goes last.
 
-## Prompt-Only Reminder
+## Choosing A Reminder Form
+
+| Need                                                              | Form                          |
+| ----------------------------------------------------------------- | ----------------------------- |
+| Fixed wording, enough that it is read at the next inbox check     | Inbox reminder                |
+| Must start a turn, or the wording will change as the work moves   | Pane prompt through a script  |
+| A probe that reports a finding only when something is wrong       | Script check                  |
+
+A reminder that arrives, in the inbox or in the pane, shows the schedule fired.
+It does not show that the work moved. Check the work itself (commits, queue,
+state) before treating the reminder as progress.
 
-A reminder is a monitor whose command only prints a fixed line. Give the line a
-stable prefix and match exactly that prefix.
+## Inbox Reminder
+
+An inbox reminder is a monitor whose command only prints a fixed line. Give the
+line a stable prefix and match exactly that prefix.
 
 ```bash
-thrum monitor start --name standup-nudge --to @me \
+thrum monitor start --name standup-nudge --to @<your_agent_name> \
   --match '^REMINDER-STANDUP:' --schedule "0 9 * * 1-5" -- \
   echo "REMINDER-STANDUP: post the status update, then reply to the open review"
 ```
@@ -128,9 +164,94 @@ thrum monitor start --name standup-nudge --to @me \
   carries no action.
 - Add `--notify-on-success` only when a delivered line must be guaranteed for a
   run that matched nothing.
-- A delivered reminder shows the schedule fired. It does not show that the work
-  moved. Check the work itself (commits, queue, state) before treating the
-  reminder as progress.
+- An inline `echo` suits wording that will not change. For wording that will
+  change, use a pane prompt through a script.
+
+## Pane Prompt Through A Script
+
+Use this form for a recurring nudge that must start a turn, and for any reminder
+whose wording follows the work. The standard case is plan follow-up: a
+brainstormer or plan owner schedules a prompt that tells it to check how
+implementation of its plan is going and to notify the coordinator or the
+orchestrators working on the plan if blockers have not moved.
+
+The monitor runs a script file. The script runs
+`thrum tmux send <your-agent> "<prompt>"`: the daemon types the text into the
+pane and submits it. The prompt text and all logic live in the script.
+
+Put the script at a stable path you own, outside tracked source, that survives a
+restart of your session. Use its absolute path in the monitor command.
+
+```bash
+#!/usr/bin/env bash
+# plan-nudge.sh: prompt my own pane to follow up on my plan.
+# Edit AGENT and PROMPT when the plan moves. The monitor stays as it is.
+AGENT="<your-agent>"
+PROMPT="Check how implementation of <plan> is going. If the blockers have not moved since the last check, notify the coordinator or the orchestrators working on it."
+
+timeout 30 thrum tmux send "$AGENT" "$PROMPT" >/dev/null 2>&1
+rc=$?
+case "$rc" in
+  0) exit 0 ;;
+  3 | 4)
+    echo "WARN: PLAN-NUDGE send exit $rc, the prompt was typed into $AGENT but its submit is not confirmed; look at the pane"
+    exit 0
+    ;;
+  *)
+    echo "PLAN-NUDGE: thrum tmux send to $AGENT failed with exit $rc"
+    exit "$rc"
+    ;;
+esac
+```
+
+```bash
+chmod +x <script-dir>/plan-nudge.sh
+<script-dir>/plan-nudge.sh    # run once by hand: the prompt lands, nothing prints
+
+thrum monitor start --name plan-nudge-<your-agent> --to @<your-agent> \
+  --match 'PLAN-NUDGE' --schedule "0 */2 * * *" --cwd <your-worktree> -- \
+  <script-dir>/plan-nudge.sh
+```
+
+Exit codes of a text `thrum tmux send`, from its help:
+
+| Exit  | Meaning                                                           | Script does                          |
+| ----- | ----------------------------------------------------------------- | ------------------------------------ |
+| 0     | Delivered                                                         | Prints nothing, exits 0              |
+| 3     | Held: the text was typed, the confirming Enter was withheld       | Prints a `WARN:` line, exits 0       |
+| 4     | Verdict unknown: Enter may or may not have been sent              | Prints a `WARN:` line, exits 0       |
+| 1     | Any other error                                                   | Prints the finding, exits non-zero   |
+
+What the monitor then delivers to `--to`, per the scheduled-job table above:
+
+| Script outcome                         | Target receives                              |
+| -------------------------------------- | -------------------------------------------- |
+| Prompt delivered                       | Nothing in the inbox; the prompt in the pane |
+| Exit 3 or 4                            | One `[WARN]` message for that tick           |
+| Any other non-zero exit, or the `timeout` (124) | One `[FAIL] <name>@<host>: exit code N` message with the finding line |
+
+Rules:
+
+1. Keep the prompt to one or two sentences. It is a nudge; the plan and your
+   state hold the detail.
+2. When the plan moves (a blocker clears, a new one appears, a different
+   orchestrator owns the work), edit the script. The next tick uses the new
+   text. Do not run `thrum monitor update` and do not delete and recreate the
+   monitor for a change of wording or logic.
+3. Change the monitor only for what the monitor owns: `update --schedule` for a
+   new cadence, `update --to` for a new recipient of failure notices.
+4. Bound the send with `timeout`; a hung send holds the tick.
+5. Never call raw `tmux send-keys` from a monitor script. `thrum tmux send` is
+   the only way a script types into a pane.
+6. Target your own pane. Prompt another agent's pane only when that agent's
+   owner asked for it.
+7. Never send the text a second time from the script. After exit 3 or 4 the text
+   may already sit in the pane: look at the pane and submit or clear it. The
+   next tick sends again by itself.
+8. Keep the output quiet on success. A matching line on every tick fills the
+   inbox with the reminder the pane already received.
+9. Start the monitor with `--cwd` set to your own worktree, so the send runs
+   from the checkout that carries your identity.
 
 ## Script Check
 
@@ -138,7 +259,7 @@ A script check runs a bounded, synchronous probe and reports through its exit
 code and one structured line.
 
 ```bash
-thrum monitor start --name disk-check --to @me \
+thrum monitor start --name disk-check --to @<your_agent_name> \
   --match '^CHECK-DISK:' --schedule "*/15 * * * *" -- \
   bash -c 'u=$(df --output=pcent / | tail -1 | tr -dc 0-9)
   [ "$u" -lt 90 ] && exit 0
@@ -146,6 +267,10 @@ thrum monitor start --name disk-check --to @me \
   exit 3'
 ```
 
+Inline `bash -c` suits a short probe whose text and threshold are fixed. Put a
+probe whose logic, threshold or wording will change in a script file and give
+the monitor the file's path, as in the pane prompt example.
+
 Rules:
 
 1. Bound every probe with `timeout <secs>`; a hung probe holds the tick.
@@ -161,7 +286,7 @@ Rules:
 | Outcome  | Script does                              | Target receives                    |
 | -------- | ---------------------------------------- | ---------------------------------- |
 | Quiet    | Exit 0, no matching line                 | Nothing                            |
-| Failure  | Non-zero exit, finding line last         | One `[FAIL] <name>: exit code N` message with the tail and the finding line |
+| Failure  | Non-zero exit, finding line last         | One `[FAIL] <name>@<host>: exit code N` message with the tail and the finding line |
 | Finding  | Exit 0, matching line(s)                 | The line(s), verbatim (labeled only by an `ERROR:`/`FATAL:`/`FAIL:` or `WARN:`/`WARNING:`/`ALERT:` prefix) |
 | Reminder | Exit 0, one stable-prefix instruction    | The line, verbatim                 |
 
@@ -174,7 +299,7 @@ Start the monitor with a unique name, `--to` the verifying agent, and a
 one-minute schedule, then read the delivered message back in full.
 
 ```bash
-thrum monitor start --name verify-<unique> --to @me --match '^VERIFY-<unique>:' \
+thrum monitor start --name verify-<unique> --to @<your_agent_name> --match '^VERIFY-<unique>:' \
   --schedule "* * * * *" -- echo "VERIFY-<unique>: delivery body check"
 thrum inbox --unread
 thrum message get <message-id>      # the complete delivered body
@@ -186,6 +311,10 @@ Confirm the body carries the prefix, the wording and no unexpected `[FAIL]`
 or `[WARN]` label. Delete the monitor when done; never alter a monitor another
 agent owns.
 
+A pane prompt sends nothing to the inbox when it works. Verify it by running
+the script once by hand and seeing the prompt in the pane, then by `thrum
+monitor show` reporting exit 0 after the first tick.
+
 ## Troubleshooting
 
 - Nothing arrived: `thrum monitor show` for state and last exit, `thrum
@@ -196,3 +325,12 @@ agent owns.
   with `ERROR:`/`FATAL:`/`FAIL:`, or (continuous job) the line contains a fail or
   error substring.
 - Name already in use: a stopped record holds it. `thrum monitor delete` it.
+- Pane prompt did not appear: `thrum monitor show` for the last exit, then run
+  the script by hand. Check that the script path is absolute and executable,
+  that the agent name in the script is current, and that the monitor's
+  `--cwd` is your worktree.
+- Pane prompt shows the old wording: the script was not saved, or the monitor
+  was started with a different script path than the one you edited.
+- `[WARN]` naming a held or unknown send: the text may sit unsubmitted in the
+  pane. Look at the pane and submit or clear the text. Do not send the text
+  again by hand; the next tick sends it.

package/assets/skills/using-tmux-ssh/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: using-tmux-ssh
+description: "Use when about to ssh to a host, run a command on a VM or remote box, start a long test or build on another machine, inspect a remote log, or recover after an ssh connection dropped or a remote command timed out. Use tmux-ssh for remote commands, saved-watch resume, and concurrent observation."
+---
+
+# Running Remote Commands With tmux-ssh
+
+`tmux-ssh` drives one persistent SSH login per host in a local tmux pane.
+Use it for every command on another machine or VM, short or long, including
+remote tests, builds, and log reads. Use `--read` and `--status` to observe;
+never use plain SSH polling or Monitor loops.
+
+## Resolve the bundled executable
+
+Resolve `resources/tmux-ssh` relative to the active `using-tmux-ssh` skill
+folder supplied by your runtime. Set `TMUX_SSH` to that absolute executable
+path, then read its live help:
+
+```bash
+TMUX_SSH='/absolute/path/to/using-tmux-ssh/resources/tmux-ssh'
+"$TMUX_SSH" --help
+```
+
+The runtime's loaded plugin root contains
+`skills/using-tmux-ssh/resources/tmux-ssh` for Claude, Codex, Cursor, and Muse;
+OpenCode contains `assets/skills/using-tmux-ssh/resources/tmux-ssh`. Locate the
+root from the active skill's path rather than assuming plugin root environment
+variables are set in an interactive shell. Nothing else from Thrum is
+required; local `tmux` and `ssh` must be installed.
+
+## Usage
+
+The examples below invoke the resolved executable through `"$TMUX_SSH"`. `HOST` is an
+SSH config alias or `user@host`.
+
+```bash
+"$TMUX_SSH" HOST                                  # connect if needed; print status
+"$TMUX_SSH" HOST 'uname -a'                        # finite command; return its exit code
+"$TMUX_SSH" HOST --timeout 900 'make test'          # bounded observation, in seconds
+"$TMUX_SSH" HOST --resume --timeout 900            # continue the saved watch; never resend
+"$TMUX_SSH" HOST --status                          # session and recorded state
+"$TMUX_SSH" HOST --read --settle                    # screen; usable during another call
+"$TMUX_SSH" HOST --abort                           # deliberately interrupt and clear the watch
+"$TMUX_SSH" HOST --kill                            # close SSH and clear saved state
+
+"$TMUX_SSH" HOST --send 'top'                      # interactive program
+"$TMUX_SSH" HOST --read
+"$TMUX_SSH" HOST --send --key C-c
+
+"$TMUX_SSH" HOST "tmux new -d -s JOB 'long-command >job.log 2>&1'"
+```
+
+Run mode waits for a command that ends. For editors, REPLs, attached tmux,
+and other programs that stay open, use `--send`/`--read`. Run mode refuses
+obvious interactive commands with code 2; use `--force-run` only deliberately.
+`--send` types into the current program and refuses a dead session rather
+than reconnecting and losing interactive state.
+
+Quote remote commands locally so variables expand on the intended machine.
+They execute in the remote login shell, which may be zsh; invoke `bash` for
+Bash syntax. For long or complex content, transfer a script using `scp` or
+`rsync` with the same connection options, then run a short command through
+`tmux-ssh`. The wrapper transports commands, not files.
+
+## Rules
+
+- **One command per host session.** Mutating calls share a local per-host lock
+  and wait up to 30 seconds by default. `--read` and `--status` observe without
+  that lock. Coordinate drivers across machines or different `TMUX_SSH_DIR`
+  values; these do not provide a global lock.
+- **Resume observation, never resubmit a queued or visible command.** Code 124
+  ends the wait; the command may still be running or waiting for input. Use
+  `--read`, then `--resume`, which retains the watch and never sends the command
+  again. Resume reuses the original timeout unless overridden. Other run calls
+  refuse while a watch remains.
+- **Interrupt deliberately.** `--interrupt-on-timeout` sends Ctrl-C when the
+  wait expires. `--abort` sends Ctrl-C and clears the watch; code 0 reports a
+  ready/finished/gone session, code 1 means the shell did not answer. Inspect
+  `--read` before further input. An abort receipt does not prove job success.
+- **Give long jobs an independent remote lifecycle.** Use detached remote
+  tmux, retaining the job name and logs. An ordinary call can reconnect a dead
+  SSH session, but a drop during foreground execution leaves completion unknown
+  and may terminate that command. Check the job and its results before deciding
+  to retry. `--kill` closes SSH; it does not stop an independent remote job.
+- **Interpret the diagnostic and completion evidence.** Remote command exit
+  codes are passed through and can overlap wrapper codes. Wrapper code 124 is
+  a wait timeout; 125 is refusal or 'completion unknown', so it alone cannot
+  prove nothing ran; 2 is a usage error; 3 means input state UNKNOWN after a
+  failed keystroke, dropped send, or failed watch persistence. Code 3 guards
+  later typing until `--kill`; `--read`, `--status`, and `--resume` still work.
+  Do not blindly retry unknown completion or input, or kill another driver's
+  session or lock merely because it looks stuck.
+
+## Connection options and pool leases
+
+Obtain the key, known-hosts file, target address, and actual remote OS hostname
+from the current lease. Keep these values outside the skill.
+
+```bash
+TMUX_SSH_OPTS='-i /path/to/lease-key -o IdentitiesOnly=yes -o UserKnownHostsFile=/path/to/lease-known-hosts -o StrictHostKeyChecking=yes' \
+TMUX_SSH_EXPECT_HOST='<remote-os-hostname>' \
+"$TMUX_SSH" user@<lease-address> 'uname -a'
+```
+
+Options precede built-in defaults, so SSH's first `-o` wins. Allowed characters
+are letters, digits, spaces, and `- _ . / = : , @ ~ + %`; paths cannot contain
+spaces. A live session retains its original options: deliberately close it
+with `--kill` before changing them. `--help`, `--status`, and `--kill` work
+with invalid options. `--expect-host` overrides `TMUX_SSH_EXPECT_HOST` and
+matches short/FQDN hostname forms case-insensitively; the SSH alias need not
+match the OS hostname.
+
+## Execution identity checks
+
+SSH is the pane's own process; a dropped connection leaves a dead pane, not a
+local shell. Run mode checks a live SSH pane, probes the recorded hostname,
+and wraps execution with a hostname check. Interactive input checks the live
+SSH pane because a program may own stdin. These checks catch mistaken targets;
+they are not an adversarial security boundary. Remote targets reporting the
+local hostname are refused; explicit `localhost`/`127.0.0.1` aliases permit
+intentional local use.