@mu-crew/mu 3.6.1 → 3.7.0

package/docs/architecture/control-socket.md

@@ -28,8 +28,8 @@ reply carries `v: 1`; the client (`src/ctl/client.ts`) throws
 | op | does |
 | --- | --- |
 | `hello` | identity plus `ops` (served ops) and `extVersion` (the mu version the extension was built from) |
-| `status` | `state` (`busy` / `idle` / `needs_input`), `since`, `runs`, `pending` |
-| `send` | `pi.sendUserMessage`; when busy, `mode` is `steer` or `followUp` (default) |
+| `status` | `state` (`busy` / `idle`), `since`, `runs`, `pending` |
+| `send` | `pi.sendUserMessage`; when busy, `mode` is `steer` or `followUp` (default). Replies with the `status` fields measured before the dispatch, so `runs` is the baseline for a later `wait` |
 | `wait` | resolves on pi's `agent_settled` after `afterRuns`, with the run's `lastText` |
 | `abort` | `ctx.abort()` (pi's Esc) |
 | `fresh` | new session plus prompt as one operation, through the internal `/mu-fresh` command; replies once the new run starts; refused with `busy` unless `force` |

package/docs/architecture/mux.md

@@ -104,7 +104,10 @@ as a capability, not a name check:
 - **tmux.** After `MU_SPAWN_LIVENESS_MS` (default 1500, `0` skips) mu
   verifies the pane survived and scans its tail for provider or auth
   startup errors. mu does not wait for murmur to claim the pane: state
-  reads before the first claim report `unknown`.
+  reads before the first claim report `unknown`. A pi agent skips the
+  fixed wait: mu checks the pane on every handshake tick (a dead pane
+  rolls back at once) and scans for startup errors when the handshake
+  ends.
 - **herdr.** mu creates a bare pane and calls `startAgentInPane`, which
   subsumes both checks.
 - **pi, either backend.** After the agent starts, mu polls its control

package/docs/guide/delegate.md

@@ -51,15 +51,19 @@ From a script or other shell, run what the tool runs:
 
 ```bash
 mu agent spawn helper-1 -w scratch
-mu agent send helper-1 -w scratch --fresh 'Investigate why foo.spec.ts fails. Report the cause.'
-mu agent wait helper-1 -w scratch --json
+runs=$(mu agent send helper-1 -w scratch --fresh --json 'Investigate why foo.spec.ts fails. Report the cause.' | jq .runs)
+mu agent wait helper-1 -w scratch --after-runs "$runs" --json
 ```
 
+`--after-runs` waits for the first run past the count the send
+reported, so a run that settles before the wait starts still counts.
+
 Use `--fresh`: a plain send to a reused agent carries the previous
 task's context.
 
 `mu agent wait` fires when the agent leaves busy (including to
-`needs_input`), never on an already idle agent. For pi, the `--json`
+`needs_input`), never on an already idle agent unless it finished a run
+past `--after-runs`. For pi, the `--json`
 row carries:
 
 - `outcome`: `done`, `empty`, `error`, `died`, `timeout`, or `pending`.

package/docs/guide/dispatch.md

@@ -114,12 +114,15 @@ mu task wait auth/build auth/docs --first --on-stall exit --json
   commits. If the worker closed without committing, it says so.
 - Exit codes: `0` met, `5` timeout, `6` the owner's pane died,
   `7` the owner sat in `needs_input` for `--stuck-after` seconds
-  (default 120). Exit 7 is the default; `--on-stall warn` keeps
+  (default 120, or 5 for a pi worker read over its control socket). Exit 7 is the default; `--on-stall warn` keeps
   polling instead.
 
 Exit 7 has several causes: the worker finished but did not close, it
-asked a question, or it hit a prompt. In each case, run
-`mu agent read <owner>` first.
+asked a question, or it hit a prompt. In each case, run the exit's
+`Next:` first. For a pi owner, it starts with
+`mu agent wait <owner> --after-runs <runs-1> --json`, which prints the
+last answer at once. Then it shows `mu agent read <owner>`, for the
+dialogs and crashes that only the pane shows.
 
 Pipeline the work: merge one task, run your tests on the merged tree,
 then dispatch the next task. Waiting for a whole wave hides partial

package/docs/guide/getting-started.md

@@ -126,7 +126,7 @@ The exit code tells you what happened:
 | `0` | the task closed | merge the work |
 | `5` | `--timeout` expired (default 600 s) | wait again |
 | `6` | the worker's pane died and the task went back to `OPEN` | spawn and claim again |
-| `7` | the worker sat in `needs_input` for 2 minutes | `mu agent read worker-1 -w auth`, then answer it |
+| `7` | the worker sat in `needs_input` for `--stuck-after` seconds (120, or 5 for a pi worker read over its control socket) | run its `Next:` (for a pi worker, `mu agent wait worker-1 --after-runs <runs-1> --json -w auth` returns the last answer; otherwise `mu agent read worker-1 -w auth`), then answer it |
 
 `--on-stall exit` is the default; it is spelled out above so older mu
 versions behave the same. With `--on-stall warn`, a stalled worker only

package/docs/guide/recovery.md

@@ -41,22 +41,27 @@ back to pasting.
 
 | State | Means | Fix |
 | ----- | ----- | --- |
-| `ctl missing` | no socket: the extension is not loaded | run `mu link pi`, then respawn the agent |
+| `ctl missing` | no socket: the extension is not loaded, or a new pi waits at its trust prompt | answer the [trust prompt](#a-new-pi-agent-shows-ctl-missing), or run `mu link pi`, then respawn the agent |
 | `ctl refused` | the socket exists but does not answer | respawn the agent; for a remote agent, check the ssh forward |
-| `extension X older than installed Y` | pi loaded an older mu build | type `/reload` in the pane, or respawn |
+| `extension X older than installed Y` or `extension lacks ops` | pi loaded an older mu build | send `/reload`, or respawn |
 
 To send `/reload` without attaching:
 
 ```bash
-mu agent send worker-1 -w auth '/reload' --via mux
+mu agent send worker-1 -w auth '/reload'             # extension serves op command
+mu agent send worker-1 -w auth '/reload' --via mux   # older: type it into the pane
 ```
 
-`/reload` keeps the pi session. A `send --fresh` or `abort` against an
+The error names the right form. `/reload` keeps the pi session. A `send --fresh` or `abort` against an
 outdated extension fails with exit 4 and prints the same two fixes.
 
-## A new pi agent is stuck at `needs_input`
+## A new pi agent shows `ctl missing`
 
-pi asks whether to trust a project folder on first start. Run
+pi asks whether to trust a project folder on first start. It asks
+before it loads extensions, so the agent has no control socket yet:
+mu shows `unknown (ctl missing)` and spawn warns after 30 s. A pi
+launched through a wrapper whose name is not `pi` or `pi-meta` shows
+`needs_input` instead. Run
 `/trust` in the pane once, or spawn with
 `--command 'pi --approve'`. `--approve` trusts every directory,
 including workspace forks, so use it only on your own code.

package/docs/guide/upgrade.md

@@ -25,15 +25,15 @@ For agents other than pi, see [README § Install](../../README.md#install).
 ## Reload running pi agents
 
 A running pi keeps the extension it loaded at start. After an upgrade,
-type `/reload` in each agent's pane, or respawn the agent. From a
-shell:
+send `/reload` to each agent, or respawn the agent. From a shell:
 
 ```bash
-mu agent send worker-1 -w auth '/reload' --via mux
+mu agent send worker-1 -w auth '/reload'             # extension serves op command
+mu agent send worker-1 -w auth '/reload' --via mux   # older extension
 ```
 
 Until then, the `ctl` row of `mu doctor` warns
-`extension X older than installed Y`. Ops the old extension lacks,
+`extension X older than installed Y` or `extension lacks ops`. Ops the old extension lacks,
 such as `send --fresh`, fail with exit 4.
 
 ## Upgrade from 3.1 or earlier

package/docs/reference/env.md

@@ -29,7 +29,7 @@ milliseconds; `0` disables a wait unless noted.
 | --- | --- | --- |
 | `MU_<CLI>_COMMAND` | Executable for `--cli <cli>`; hyphens become underscores (`--cli pi-meta` reads `MU_PI_META_COMMAND`). May hold arguments. `--command` wins; the spawn line names the env var when it supplied the command. | the cli value |
 | `MU_SPAWN_CTL_MS` | Budget for the control-socket handshake with a new pi agent, polled every 250ms. On timeout spawn still exits 0, reports `ctl: missing` or `ctl: refused`, and warns. `--no-ctl` skips it per spawn. | `30000` |
-| `MU_SPAWN_LIVENESS_MS` | tmux only. Wait this long, then check the pane is alive and its scrollback has no startup error (auth failure, `command not found`). Failure rolls back the row and throws `AgentDiedOnSpawnError` or `AgentSpawnStartupError`. | `1500` |
+| `MU_SPAWN_LIVENESS_MS` | tmux only. Wait this long, then check the pane is alive and its scrollback has no startup error (auth failure, `command not found`). Failure rolls back the row and throws `AgentDiedOnSpawnError` or `AgentSpawnStartupError`. A pi agent skips the wait: the pane is checked on each ctl handshake tick and scanned when it ends. | `1500` |
 | `MU_SPAWN_LOCK_TIMEOUT_MS` | How long a spawn waits for the per-workstream spawn lock. | `15000` |
 
 ## Send and state (tmux path)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.6.1",
+  "version": "3.7.0",
   "description": "A persistent, observable crew of pi agents running in one tmux or herdr session per workstream, coordinated through a built-in task DAG.",
   "publishConfig": {
     "access": "public"

package/skills/mu/SKILL.md

@@ -69,7 +69,8 @@ or inspection.
 
 For one-shot work inside pi, call `mu_delegate` (installed by `mu link pi`).
 Outside pi: spawn into the reserved `scratch` workstream (no task DAG,
-auto-created), `send --fresh`, then `mu agent wait --json` (`lastText`).
+auto-created), `send --fresh --json`, then `mu agent wait --after-runs <its runs> --json`
+(`lastText`); without `--after-runs` a run that ends first hangs the wait.
 Recipes call either form a **delegate call**.
 
 - `mu agent wait <names...> --first` waits for busy → idle instead of a
@@ -78,8 +79,10 @@ Recipes call either form a **delegate call**.
 - One agent per independent unit; `--workspace` for any helper that may edit,
   build, or test the shared repo.
 
-A helper stuck at `needs_input` right after spawn likely hit pi's
-project trust prompt: add `--approve` to `MU_<CLI>_COMMAND`. Move off
+A pi helper showing `unknown (ctl missing)` right after spawn (spawn
+warns after 30 s) likely sits at pi's project trust prompt (through a
+wrapper whose argv0 is not `pi`/`pi-meta` it shows `needs_input`): add
+`--approve` to `MU_<CLI>_COMMAND`. Move off
 `scratch` when work gains dependencies or review gates.
 
 ## Mental model

package/skills/mu/recipes/codemode-driver.md

@@ -67,8 +67,8 @@ const sh = async (c) => (await tools.bash({ command: c })).output;
 const rows = await Promise.all(findings.map(async (id, i) => {
   const a = `refuter-${i + 1}`;
   await sh(`mu agent spawn ${a} -w scratch`);
-  await sh(`mu agent send ${a} -w scratch --fresh '<brief for ${id}: ... end with VERDICT: ...>'`);
-  const w = JSON.parse(await sh(`mu agent wait ${a} -w scratch --json --timeout 1200`));
+  const { runs } = JSON.parse(await sh(`mu agent send ${a} -w scratch --fresh --json '<brief for ${id}: ... end with VERDICT: ...>'`));
+  const w = JSON.parse(await sh(`mu agent wait ${a} -w scratch --after-runs ${runs} --json --timeout 1200`));
   const text = w.agents?.[0]?.lastText ?? "";
   await sh(`mu agent close ${a} -w scratch`);
   return `${id}\t${(text.match(/VERDICT:.*$/m) ?? ["VERDICT: UNVERIFIED no verdict line"])[0]}`;

package/skills/mu/recipes/orchestrator-loop.md

@@ -54,12 +54,16 @@ keeps it.
 Use `--first --on-stall exit`: `--first` populates `.firing`, and
 `--on-stall exit` stops an unattended wait when a worker needs attention.
 Exit 6: the owner's pane died and the reaper reopened the task; exit 7:
-the owner sat in `needs_input`. Read that
-pane (`mu agent read <owner>`) and answer: the worker may be waiting on
-you.
-
-For an idle worker, read the pane, then answer, retry, or release its
-task. `MU_IDLE_THRESHOLD_MS` defaults to 5m. A remote owner: poll once
+the owner sat in `needs_input`. Run the exit's `Next:` and answer: the
+worker may be waiting on you. For a pi owner it leads with
+`mu agent wait <owner> --after-runs <runs-1> --json`, which returns the
+last answer at once. The pane read follows because dialogs and crashes
+show only in the pane.
+
+For an idle worker, read its last answer (the same `--after-runs`
+wait for pi, else the pane), then answer, retry, or release its task.
+`MU_IDLE_THRESHOLD_MS` defaults to 5m. A remote owner: for pi,
+`mu agent wait --after-runs` first, then poll once; otherwise poll once
 per turn ([remote-workers](remote-workers.md#step-5-poll-once-per-turn)).
 
 ## Merging

package/skills/mu/recipes/remote-workers.md

@@ -44,7 +44,8 @@ mu agent spawn worker-1 -w big --command \
 mu task claim t1 -w big --for worker-1 --evidence 'remote on dev'
 mu agent send worker-1 -w big --fresh '...'
 
-# 5. WAIT: run the claim's one-shot Next: command once per turn
+# 5. WAIT: pi: mu agent wait worker-1 -w big --after-runs <send's runs> --json,
+#    then the claim's Next: once. non-pi: run the claim's Next: once per turn
 
 # 6. COLLECT: fetch straight from the remote worktree
 git fetch "ssh://dev/~/ws/worker-1" HEAD && git cherry-pick FETCH_HEAD
@@ -72,13 +73,13 @@ retry next turn, not progress.
 
 ### Step 3: the control-socket forward
 
-Spawn reports `ctl ok` when all of these hold (`mu doctor` has a ctl
+Spawn reports `ctl: ok` when all of these hold (`mu doctor` has a ctl
 row per agent):
 
 - The host has the mu extension: run `mu link pi` there.
 - The ssh is direct. `$MU_SSH_ARGS` sets `ControlMaster=no
   ControlPath=none`; a multiplexed ssh never binds the forward and spawn
-  reports `ctl missing`.
+  reports `ctl: missing`.
 - sshd allows the forward. A refused forward kills the pane at spawn
   (`ExitOnForwardFailure=yes`). Check `AllowStreamLocalForwarding`.
 
@@ -88,6 +89,16 @@ plus a 10 s cache.
 
 ### Step 5: poll once per turn
 
+The claim's `Next:` mule poll is mandatory. It proves the commit is on
+the host and closes the task. For a pi worker, first block on
+`mu agent wait <name> --after-runs <runs> --json`, with `runs` from
+`mu agent send --json`. It settles exactly over the forwarded socket.
+Without `--after-runs`, a worker that is already idle blocks until
+`--timeout`. If the worker may already be done, pass `<runs-1>`: the
+wait then returns the last answer at once. Then run `Next:` once instead
+of on every turn. On exit 5 (timeout), or on a wait that returns while
+the worker asks a question, run `Next:` anyway.
+
 - Never `sleep` in a tool call. Aborting the loop can leave remote work
   and a capped channel running.
 - Set a deadline before dispatch. At expiry, read the pane, then release
@@ -123,14 +134,20 @@ the final gate before the push that matters.
 
 ## Traps
 
-### A spawn on an auth prompt looks healthy
+### A non-pi spawn on an auth prompt looks healthy
 
 With the channel busy, the attach ssh stopped at `Enter a passcode:`.
 Spawn succeeded, the agent showed `needs_input`, and the prompt went
-into the passcode field. Confirm a remote agent got the work
-(`mu agent read <name> -n 20`) before trusting it. Send nothing
+into the passcode field. This applies to non-pi CLIs and to
+`--via mux`, which paste into the pane. Confirm such an agent got the
+work (`mu agent read <name> -n 20`) before trusting it. Send nothing
 sensitive to an unconfirmed pane.
 
+A pi agent does not paste. Spawn reports `ctl: ok` only when pi
+answers on the socket; otherwise it warns `ctl: missing` or
+`ctl: refused`, and `mu agent send` fails instead of typing into the
+pane.
+
 ### Use the host's real CLI command
 
 If your local `$MU_PI_COMMAND` is a wrapper such as `pi-meta

package/skills/mu/recipes/tasks-or-calls.md

@@ -12,10 +12,14 @@ tool (another harness, a script):
 
 ```bash
 mu agent spawn refuter-1 -w scratch
-mu agent send refuter-1 -w scratch --fresh '<brief>'
-mu agent wait refuter-1 -w scratch --json   # answer in lastText
+runs=$(mu agent send refuter-1 -w scratch --fresh '<brief>' --json | jq .runs)
+mu agent wait refuter-1 -w scratch --after-runs "$runs" --json   # answer in lastText
 ```
 
+`--after-runs` takes the run count the send reported, so a run that
+finished before the wait started still counts. A plain wait would sit
+until `--timeout`.
+
 - **It starts empty.** The brief carries everything: the finding or
   claim, file paths, the criteria, and the answer line to end with
   (`VERDICT: ...`, `WINNER: ...`). See [brief](brief.md).