@mu-crew/mu 3.0.0 → 3.2.0

package/skills/mu/REMOTE_WORKERS.md

@@ -21,7 +21,9 @@ concerns interactive attachment, not mu's automatic agent-state reads.
 --command 'ssh <host> -t "..."'` starts an ordinary tmux pane whose
 foreground process happens to be ssh. Everything mu does is
 pane-shaped, so `mu agent send`, `mu agent read`, and the reaper work
-unchanged across the network. murmur reports the remote process's agent state.
+unchanged across the network. A pi agent's control socket rides the
+same ssh as a `-L` forward, so its state is exact; murmur reports state
+only for non-pi agents.
 
 **One orchestrator DB; panes may be remote.** All state stays on your
 machine. Do not run a second mu on the host to "coordinate": ownership
@@ -29,7 +31,7 @@ is machine-local by construction — `tasks.owner_id` is an FK into the
 `agents` table, which never syncs — so a remote mu could not claim
 tasks in your DAG. Two half-views, no benefit.
 
-**murmur sees the REMOTE pane** — the opposite of the line above. Its
+**murmur, if you use it, sees the REMOTE pane** — the opposite of the line above. Its
 extension runs inside the agent's process, so it claims the pane on the
 HOST; mu's local pane holds an ssh client and reports nothing. Two
 addresses, one worker.
@@ -67,7 +69,7 @@ the only ssh channel**. While it is open, `git fetch`, `git push`,
 
 **Attach to look, then close immediately.** `mu agent close <name>`
 detaches without stopping a detached-tmux agent. mu reads agent state
-through murmur automatically; use mule for orchestrator commands because
+automatically (pi: the forwarded control socket); use mule for orchestrator commands because
 its separate ControlPath cannot contend with the attach pane. See
 § When the host limits concurrent sessions for diagnosis and the
 remote-agent setup.
@@ -115,13 +117,16 @@ ssh dev 'git -C ~/repo worktree add ~/ws/worker-1'
 mu task note t1 -w big "REMOTE: dev:~/ws/worker-1
 REMOTE_BASE: worker-1:$(ssh dev 'cd ~/ws/worker-1 && git rev-parse HEAD')"
 
-# 3. SPAWN — env vars go INSIDE the command (tmux -e stops at the hop)
+# 3. SPAWN — env goes INSIDE the command (tmux -e stops at the hop);
+#    remote-env prints it plus the control-socket forward (runs nothing)
+eval "$(mu agent remote-env worker-1 -w big --shell)"  # MU_SSH_ARGS, MU_REMOTE_ENV
+#    $SHELL -ilc: ssh's non-interactive shell skips ~/.zshrc (PATH, provider env)
 mu agent spawn worker-1 -w big --command \
-  'ssh dev -t "cd ~/ws/worker-1 && MU_MANAGED_AGENT=1 MU_AGENT_NAME=worker-1 MU_WORKSTREAM=big pi --approve"'
+  "ssh $MU_SSH_ARGS dev -t 'cd ~/ws/worker-1 && $MU_REMOTE_ENV \$SHELL -ilc \"pi --approve\"'"
 
 # 4. CLAIM + SEND — identical to a local agent
 mu task claim t1 -w big --for worker-1 --evidence 'remote on dev'
-mu agent send worker-1 -w big '...'
+mu agent send worker-1 -w big --fresh '...'
 
 # 5. WAIT — run the claim's one-shot Next: command once per turn
 # Set a deadline; at expiry read the pane, then release or re-dispatch.
@@ -141,31 +146,37 @@ Local and remote agents mix freely in one workstream. The DAG, tracks,
 — task status is a row in YOUR database, written by you, so a wait on
 it is exact.
 
-**Agent state comes from murmur.** Its extension runs inside pi on the
-host and reports state without reading the nested tmux screen. mu reads
-murmur's remote rows and caches them for 10 seconds. Remote rows can lag
-by murmur's collect floor (30 seconds ± 10 seconds) plus that cache;
-their `since` value is the row's `updated_at`, so idle and stall age is
-approximate.
-
-| waiting on | remote? |
-| --- | --- |
-| `mu task wait` (task status) | exact — a DB poll, once something closes the task |
-| the reaper | fires, but see below |
-| stall detection | exact state from murmur; approximate age |
-| `mu agent wait --first` | exact state from murmur |
-
-Without murmur, remote agent state is `unknown`. `mu agent wait` does not
-fire on `unknown`, and `unknown` never counts as a task stall. Run
-`mu doctor` for the missing-source reason.
+**Agent state comes from the forwarded control socket** for pi agents.
+`-L <local>:<remote>` in `$MU_SSH_ARGS` makes the remote pi's mu
+extension answer at the local path mu always uses, so send, state,
+`mu agent wait --first` and `mu agent abort` are exact, as for a local
+agent. Two prerequisites:
+
+- The host has the extension: run `mu link pi` there (or copy
+  `dist/extension/mu-pi.js` into its pi extensions dir).
+- The ssh is a direct connection. `$MU_SSH_ARGS` carries
+  `-o ControlMaster=no -o ControlPath=none`: with `ControlMaster auto`
+  in `~/.ssh/config` the pane's ssh joins an existing master and the
+  `-L` unix forward never binds locally (spawn reports `ctl missing`).
+- sshd allows the forward. `ExitOnForwardFailure=yes` makes a refused
+  forward kill the pane at spawn, loudly; check
+  `AllowStreamLocalForwarding` in the host's `sshd_config`.
+
+Spawn reports `ctl ok` when both hold; `mu doctor` has a ctl row per
+agent. When the ssh dies, ssh leaves the local socket file behind: it
+probes as `refused` (never a stale `ok`), and close or the reaper
+deletes it.
+
+Non-pi remote agents still get state from murmur, which lags by its
+collect floor (30 seconds ± 10 seconds) plus a 10-second cache. Without
+murmur their state is `unknown`, which `mu agent wait` and stall
+detection never fire on.
 
 The reaper is right for a direct spawn — the connection dying really
 does kill that agent — and wrong for a detached-tmux one, where the
 agent outlives the ssh but mu reaps the task anyway. See § A dropped
 connection reaps the task but NOT the commit.
 
-The division is: mu owns the work; murmur reports what the agent is doing.
-
 ### On step 2 — the note is load-bearing
 
 The task note survives connection loss and context compaction. Keep the
@@ -345,20 +356,23 @@ exists:
 ssh dev 'git -C ~/repo worktree remove ~/ws/worker-1'
 ```
 
-`mu agent kick` signals the local pane's foreground process group —
-that is the ssh client, not the remote agent. Use `mu agent close` and
-respawn.
+To stop a remote pi agent's turn, `mu agent abort <name>`: it goes
+through the forwarded socket. `mu agent kick` signals the local pane's
+foreground process group — that is the ssh client, not the remote
+agent. For an unresponsive one, `mu agent close` and respawn.
 
 ---
 
 ## mu and murmur, and what you lose without it
 
-[murmur](https://github.com/mu-crew/murmur) provides agent state for
-mu's tmux backend. Without it, mu reports agent state as `unknown`.
-The DAG, claims, task completion waits, workspaces, spawn, send, read,
-the reaper, this remote recipe, and `git fetch` collection still work.
-Agent-state consumers such as `mu agent wait`, idle flags, and task-stall
-detection wait rather than treating `unknown` as completion or a stall.
+pi agents, local or remote, need no murmur: mu reads their state from
+the control socket. [murmur](https://github.com/mu-crew/murmur) provides
+agent state for non-pi agents (claude-code, codex) on tmux. Without it
+those report `unknown`; the DAG, claims, task completion waits,
+workspaces, spawn, send, read, the reaper, this remote recipe, and
+`git fetch` collection still work. Agent-state consumers such as
+`mu agent wait`, idle flags, and task-stall detection wait rather than
+treating `unknown` as completion or a stall.
 
 murmur also provides the tmux status pills, `prefix+a`, attachment hints,
 and `murmur peer list` for host reachability. The division is: **mu owns
@@ -371,13 +385,15 @@ work. Its interfaces used by mu are in murmur's
 | what should happen next | mu — the DAG |
 | who owns this task | mu — `claim` / `close` |
 | is the task done | mu — `task wait`, a DB poll |
-| what is this agent doing right now | murmur — pushed from inside pi |
+| what is this pi agent doing right now | mu — the control socket |
+| what is a non-pi agent doing right now | murmur |
 | is anything blocked on me, anywhere | murmur |
 | which host can I reach | murmur — `peer list` |
 
 **The seam is three env vars, and it is load-bearing.** `mu agent
 spawn` injects `MU_MANAGED_AGENT=1`, `MU_AGENT_NAME` and
-`MU_WORKSTREAM`; pi inherits them and murmur's extension reads them.
+`MU_WORKSTREAM` (plus `MU_CTL_SOCK` for mu's own extension); pi
+inherits them and murmur's extension reads them.
 That one mechanism gives you:
 
 1. `driver=orchestrated`, so crew stays out of the human's status bar
@@ -386,7 +402,7 @@ That one mechanism gives you:
 3. the attachment back-reference for a remote worker
 
 For a remote worker they go **inside** the ssh command (tmux `-e` stops
-at the hop). Miss them and the agent reports `driver=human`: it appears
+at the hop); `$MU_REMOTE_ENV` from `mu agent remote-env` carries them. Miss them and the agent reports `driver=human`: it appears
 in your own counts as if it were yours.
 
 ## Picking a host
@@ -519,21 +535,25 @@ Run the agent in its own tmux session on the host, and attach to
 the session can be released.
 
 ```bash
+eval "$(mu agent remote-env worker-1 -w big --shell)"  # MU_SSH_ARGS, MU_REMOTE_ENV
 # Agent runs DETACHED on the host; the ssh returns immediately
-ssh dev 'tmux new-session -d -s mu-worker-1 -c ~/ws/worker-1 \
-  "MU_MANAGED_AGENT=1 MU_AGENT_NAME=worker-1 MU_WORKSTREAM=big pi --approve"'
+ssh dev "tmux new-session -d -s mu-worker-1 -c ~/ws/worker-1 \
+  '$MU_REMOTE_ENV \$SHELL -ilc \"pi --approve\"'"
 
-# Attach a local pane to it; claim/send are then normal
-mu agent spawn worker-1 -w big --command 'ssh dev -t "tmux attach -t mu-worker-1"'
+# Attach a local pane to it (forwarding the socket); claim/send are then normal
+mu agent spawn worker-1 -w big --command "ssh $MU_SSH_ARGS dev -t 'tmux attach -t mu-worker-1'"
 
 # COLLECT: detach FIRST to free the session, then fetch
 mu agent close worker-1 -w big
 git fetch "ssh://dev/~/ws/worker-1" HEAD && git cherry-pick FETCH_HEAD
 
-# Reattach — same session, LLM context intact
-mu agent spawn worker-1 -w big --command 'ssh dev -t "tmux attach -t mu-worker-1"'
+# Reattach — same session, LLM context intact (same --command as above)
+mu agent spawn worker-1 -w big --command "ssh $MU_SSH_ARGS dev -t 'tmux attach -t mu-worker-1'"
 ```
 
+The pi keeps serving its socket at the remote path while detached; each
+attach re-creates the local end of the forward.
+
 Two consequences, both counterintuitive:
 
 - **An attached pane blocks concurrent ssh just as much as a direct

package/skills/mu/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mu
-description: Manage AI agents in terminal-multiplexer panes (tmux or herdr) — from a single off-the-cuff helper to a persistent crew coordinated through a built-in task graph. Use when the user asks to "create/spin up a subagent to X", "run X in the background", "do this in parallel", "use one subagent per X to do Y", "kick off a helper to watch/investigate/draft X", or to spawn, send work to, observe, or coordinate one or many agents — especially work you'll keep talking to, long-lived agents, background tasks, or anything that benefits from a dependency graph and parallel-track detection. For zero-ceremony single helpers use the reserved `scratch` workstream; for one-shot "fire and get a result back" prefer pi-subagents.
+description: Manage AI agents in terminal-multiplexer panes (tmux or herdr) — from a single off-the-cuff helper to a persistent crew coordinated through a built-in task graph. Use when the user asks to "create/spin up a subagent to X", "run X in the background", "do this in parallel", "use one subagent per X to do Y", "kick off a helper to watch/investigate/draft X", or to spawn, send work to, observe, or coordinate one or many agents — especially work you'll keep talking to, long-lived or background agents, or anything needing a dependency graph. For zero-ceremony helpers use the reserved `scratch` workstream; for one-shot "fire and get a result back" use the `mu_delegate` tool — its pane stays attachable.
 ---
 
 # mu — Multi-agent orchestration
@@ -32,11 +32,13 @@ both. `--json` exists on every verb:
 - **agent** — named worker in a pane (you may be one).
 - **mux** — the multiplexer mu drives: tmux, or herdr. One per
   invocation. `mu doctor` names the active one; `MU_MUX` forces it.
-  Spawn, send, and read work on both. Agent state comes from murmur
-  on tmux and from herdr on herdr; `mu agent kick` is Linux-only on herdr.
+  Spawn, send, and read work on both. `mu agent kick` is Linux-only on herdr.
+- **control socket (ctl)** — how mu drives a pi agent: the mu pi
+  extension (`mu link pi`) serves exact send, state, wait and abort
+  inside pi's own TUI. `ctl missing|refused` means it does not answer.
 - **task** — DAG node with mandatory `impact` (1–100) and
   `effort_days`. Shown as status/substate: `OPEN/todo|parked`,
-  `IN_PROGRESS/active`, `CLOSED/done|wontfix|duplicate|superseded`.
+  `IN_PROGRESS/active`, `CLOSED/done|rejected|wontfix|duplicate|superseded`.
   Any `CLOSED/*` satisfies `--blocked-by`.
 - **claim / release** — atomic take/clear of `tasks.owner`.
 - **note** — append-only task context; survives sessions.
@@ -48,26 +50,27 @@ both. `--json` exists on every verb:
 ## When to use mu
 
 Use mu for persistent helpers, parallel work, dependencies, gated review, or
-work that must survive context compaction. Use `pi-subagents` for one focused
-answer and no follow-up; stay in one context for tiny edits or inspection.
+work that must survive context compaction. Stay in one context for tiny edits
+or inspection.
 
 ### Off-the-cuff helpers (`scratch`)
 
-Use the reserved `scratch` workstream for a helper you will keep driving but
-that needs no task DAG. It auto-creates on spawn.
+The reserved `scratch` workstream holds helpers that need no task DAG; it
+auto-creates on spawn. `mu_delegate` (installed by `mu link pi`) is its tool
+form for one answer back; the CLI form is spawn + send + `mu agent wait --json`
+(`lastText`).
 
-- For task-less work, `mu agent wait <name> --first` waits for busy → idle;
-  exit 0 means met, 5 timeout, 6 pane died.
+- `mu agent wait <name> --first` waits for busy → idle; exit 0 met, 5
+  timeout, 6 pane died.
 - For a watcher, persist last-seen state in a log ledger: write `mu log -w
   scratch --kind pr-state 'pr=1234 sha=abc ci=red'`, then read `mu log -w
-  scratch --kind pr-state -n 1 --json`. Act only on change; chat context is not
-  durable.
-- Use one agent per independent unit and `--workspace` for any helper that may
-  edit, build, or test the shared repo.
+  scratch --kind pr-state -n 1 --json`. Act only on change.
+- One agent per independent unit; `--workspace` for any helper that may edit,
+  build, or test the shared repo.
 
-A helper stuck at `needs_input` immediately after spawn likely hit pi's project
-trust prompt. Add `--approve` to the existing `MU_<CLI>_COMMAND`; use
-`--command` only to replace that configured command deliberately.
+A helper stuck at `needs_input` right after spawn likely hit pi's project trust
+prompt: add `--approve` to `MU_<CLI>_COMMAND` rather than overriding it with
+`--command`.
 
 Move off `scratch` when work gains dependencies or review gates.
 
@@ -99,8 +102,8 @@ that a refusal with `--strict-staleness`.
 
 Agents can run on another machine: the PANE is local, the PROCESS is
 remote (`--command 'ssh <host> -t "..."'`), so `send`, `read`, and the
-reaper keep working unchanged. murmur reports the remote agent's state.
-**One orchestrator
+reaper keep working unchanged. A pi agent's control socket is forwarded
+over that ssh (`mu agent remote-env`). **One orchestrator
 DB; panes may be remote** — never run a second mu on the host, since
 `tasks.owner_id` is an FK into the machine-local `agents` table and a
 remote mu could not claim your tasks anyway. You create the remote
@@ -108,8 +111,7 @@ workspace yourself (`--workspace` is local-only).
 
 **Read [REMOTE_WORKERS.md](REMOTE_WORKERS.md) before spawning your first
 remote agent, and again before waiting on one; poll once per turn and run
-the claim's one-shot `Next:` command.** These are the other three traps
-that cost real time when learned late:
+the claim's one-shot `Next:` command.** Three more costly traps:
 - **On a session-capped host, route long commands and silent-failure
   polls through [mule](https://github.com/mu-crew/mule).** A refused
   bare `rev-parse` can return an empty sha that looks like progress;
@@ -161,8 +163,11 @@ Every turn:
    `--note 'REPRO: ...\nSCOPE: ...'` when the title alone is not
    enough. Agent state is runtime observation; task ownership is durable and
    waitable.
-4. Send terse instructions: task id, files/notes to read, workspace
-   path, validation command, scope guards, task note contract.
+4. Send each new task with `mu agent send <w> --fresh '...'` (new
+   session + prompt in one step; refuses while busy): task id,
+   files/notes to read, workspace path, validation command, scope
+   guards, task note contract. Follow the `Next:` block; it picks
+   `--fresh` vs `--steer` for you.
 5. End with a loud final-action block:
 
    ```text
@@ -214,11 +219,14 @@ Every turn:
   workstream; only task ownership crosses.
 - For an idle worker, read the pane to learn why it stopped, then answer,
   retry, or release its task. `MU_IDLE_THRESHOLD_MS` defaults to 5m.
-- `mu agent kick` targets a wedged foreground subprocess. It refuses to signal
-  the wrapping CLI; close the agent if that is what must stop.
-- Use `mu agent send`, not raw mux input: mu preserves literal text and confirms
-  submission. Single-quote prompts containing shell expansions, or use a quoted
-  heredoc.
+- **Never chain `/new` and a prompt as two sends to a pi agent:** the prompt
+  can land mid-reset and vanish (it did, twice). `--fresh` does both inside pi.
+- **Stop a worker:** `mu agent abort <w>` first for pi (exact, local or
+  remote, keeps context, waits for idle; exit 5 = still busy; queued
+  follow-ups return to the editor unsent). Then `mu agent kick` (pi
+  unresponsive, or non-pi; local panes only), then `mu agent close`.
+- Use `mu agent send`, not raw mux input. Single-quote prompts containing shell
+  expansions, or use a quoted heredoc.
 
 ## CLI gotchas
 
@@ -233,7 +241,7 @@ Every turn:
   5 timeout, 6 pane died.
 - **`task close --if-ready`** no-ops until every blocker is CLOSED; bare
   `task release` reopens IN_PROGRESS.
-- **`task close --as wontfix --why ...`** unblocks dependents (listed in
+- **`task close --as rejected|wontfix --why ...`** (declined | valid, not worth it) unblocks dependents (listed in
   the output). To keep dependents waiting, `task park --why` instead: parked
   leaves `next`, and `claim` refuses it without `--force`. Park refuses
   IN_PROGRESS — `task release` first.
@@ -303,12 +311,10 @@ If an agent pane dies, or `mu agent close` kills it mid-task, owned
 IN_PROGRESS tasks revert to OPEN with a `[reaper]` note and `task
 reap` op. No manual release after crashes.
 
-Agent state comes from [murmur](https://github.com/mu-crew/murmur) on
-tmux and from herdr on herdr. `unknown` means no state source; run
-`mu doctor` for the reason. mu needs murmur only for agent state:
-tasks, claims, workspaces, spawn, send, read, and task completion waits
-work without it. **mu owns the work; murmur reports what an agent is
-doing.** See [REMOTE_WORKERS.md](REMOTE_WORKERS.md) § mu and murmur.
+pi agents report state through the control socket; other CLIs through
+[murmur](https://github.com/mu-crew/murmur) on tmux or herdr on herdr.
+`unknown` means no state source; `mu doctor` says why. pi agents need
+no murmur. See [REMOTE_WORKERS.md](REMOTE_WORKERS.md) § mu and murmur.
 
 For high-stakes decisions:
 
@@ -342,28 +348,16 @@ Skipping close makes the orchestrator's wait hang. Won't do it:
 
 ## Follow-on prompts
 
-A new `mu agent send` appends to prior LLM context. For unrelated
-work, clear first (`/new` for pi/claude-code; `/clear` for codex):
-
-```bash
-mu agent send worker-1 '/new'
-mu agent send worker-1 'Claim and work on task_x. Read notes first...'
-```
-
-No `sleep` needed. `mu agent send` waits for the pane to finish any
-re-initialisation before pasting, and re-submits if the TUI swallowed
-the Enter. If a send cannot be confirmed it prints a `warning:` to
-stderr naming the pane; exit 0 with no warning means submitted.
-
-Budget is `MU_SEND_READINESS_MS` (default 15000; 0 = fire-and-forget).
-Sending to a BUSY agent is not delayed — that input queues normally.
+A plain `mu agent send` appends to prior context; use it to steer or
+answer. Unrelated work to pi: `mu agent send worker-1 --fresh 'Claim
+task_x...'`. claude-code/codex: send `/new` (codex: `/clear`), then the
+prompt; a send it cannot confirm prints a `warning:` on stderr.
 
 ## Guardrails
 
 Task ownership outranks runtime agent state. Coordinate through task notes and the
 activity log. Keep edges within one workstream, role-name agents, and reserve
-the `mu_` task-id prefix. Give workers bounded paths and commands; use `mu
-agent kick` if a subprocess wedges.
+the `mu_` task-id prefix. Give workers bounded paths and commands.
 
 ## See also