@mu-crew/mu 3.13.3 → 4.0.0

package/docs/guide/delegate.md

@@ -2,16 +2,18 @@
 
 ## Delegate from pi
 
-`mu link pi` installs the `mu_delegate` and `mu_delegate_cancel` tools
-in every pi session. Ask pi in plain words:
+The mu pi package (`pi install npm:@mu-crew/mu`) installs the
+`mu_delegate` and `mu_delegate_cancel` tools in every pi session. Ask pi in plain words:
 
 - "Delegate a review of src/x.ts to a helper."
 - "Have three helpers investigate A, B, and C."
 
-pi calls `mu_delegate`. It spawns a pi agent in the reserved `scratch`
-workstream and returns at once with the delegate's name and attach
-command. The answer arrives later as a follow-up message; do not poll.
-Delegates called in one turn run in parallel.
+pi calls `mu_delegate`. It registers the call as a task (`kind=delegate`,
+see [Every call is a task](#every-call-is-a-task)), spawns a pi agent in
+the reserved `scratch` workstream and returns at once with the task, the
+delegate's name and attach command. The answer arrives later, with
+pi's next settle; do not poll. Delegates called in one turn run in
+parallel.
 
 | Option | Meaning |
 | ------ | ------- |
@@ -19,46 +21,107 @@ Delegates called in one turn run in parallel.
 | `label` | Names the delegate: `review` gives `delegate-review`. |
 | `brief` | Ad hoc persona or ground rules, sent first. Not enforced. |
 | `cwd` | Start directory. Default: the caller's. Must exist. |
-| `timeout` | Seconds to wait for the answer (default 3600). After it, the answer does not come back; the follow-up gives the `mu agent wait` command. |
-| `workspace` | Own VCS checkout, for delegates that edit files. The follow-up names its path. It isolates repository edits only. |
+| `timeout` | Seconds to wait for the answer (default 3600). After it, the answer does not come back to pi; it still lands on the delegate task, whose report names a wait command. |
+| `workspace` | Own git worktree, for delegates that edit files. The tool result names its path. It isolates repository edits only. |
 | `cli` | Key for `$MU_<CLI>_COMMAND` (default `pi`). Only keys set in pi's environment exist. |
 | `model` | pi `--model` value, appended to the cli's command (`sonnet`, `<provider>/<model>:high`, copied from `pi --list-models`). Varies models across a panel. tmux only: herdr refuses a command override. |
 | `keep` | Keep the pane after it finishes, to talk to it again. |
 | `record` | `{ task, workstream? }` (or `task: "<ws>/<task>"`): write the answer's verdict onto that task as a note. See [Record a verdict](#record-a-verdict). |
-
+| `wave` | A label for one fan-out; `mu delegates tally` counts its verdicts per judged task. |
+| `workstream` | Holds the delegate task and runs the delegate (default `scratch`). |
+
+- No tmux or herdr: the same tool runs the delegate as a child pi
+  (`mu delegates run <call-id>`), with no pane and no attach command.
+  Its report names the session file and, when it fails, the log tail.
+  `keep` is dropped. Cancel stops the child. `/reload` lets it finish
+  onto its task; quitting pi cancels it.
 - Watch or steer: run the attach command.
-- Stop: `mu_delegate_cancel`, or `mu agent abort <name> -w scratch`.
+- Stop: `mu_delegate_cancel` (a delegate name, a `queued-N` handle or a
+  call id), or `mu agent abort <name> -w scratch`. A cancel is recorded:
+  the task closes `wontfix` with a report.
 - The pane closes after a clean finish; died or timed-out panes stay
   as evidence.
-- pi's footer shows how many delegates this session is waiting on, and
-  `N results pending` for delegates that finished but whose answer has
-  not reached the conversation yet (queued behind the running turn).
-  Escape drops those queued answers from pi. The extension then writes
-  one line per answer into the conversation, without starting a turn,
-  pointing at a copy under `~/.cache/mu/delegate-answers/` and
-  at the delegate's own pi session file. An answer that lands after
-  Escape arrives as usual.
+- The answer reaches the model through the settle wait, never as a
+  copy in a pi message. When a delegate finishes, its answer is
+  recorded (verdict, report, close); the keep-driving settle wait then
+  returns it as a `delegate` event, and the continuation shows that
+  call's report (capped at 4000 characters, with the
+  `mu task notes <task> -w <ws>` pointer to the rest). A recorded check
+  with a verdict shows only its header: the verdict is on its task.
+- A delegate of a `wave` is shown with the rest of the wave: the settle
+  keeps waiting while siblings run, then shows ONE summary (counts per
+  verdict, a line per call, the answers). A refused call is listed for
+  reissue and never waited on. Any other event (a worker closing, a
+  dialog) ends that early and is shown after the summary so far.
+- When no settle wait will show an answer (pi is idle, `MU_NUDGE=0`, the
+  wait failed), the extension sends one **wake**: a pointer per answer,
+  no answer text, that starts a turn. A wake lost from pi's queue (the
+  dequeue key, alt+up) is sent once more; lost twice, or dropped by
+  Escape, it leaves one line per answer and starts nothing. The report
+  stays recorded either way, so the next settle shows it. Escape ends
+  only the wait running now: a later answer still wakes an idle pi.
+- `MU_DELEGATE_TRACE=1` logs every wake send and pi lifecycle
+  event to `~/.cache/mu/delegate-trace.log`, for finding a lost answer.
 - Each delegate costs a pane and a pi process. A session runs at most
   `MU_DELEGATE_MAX` at once (default 16). Further calls are queued, up
-  to four times the cap: the footer reads `16 delegates running, 4 queued`,
-  each starts when a slot frees, and `mu_delegate_cancel queued-N`
-  drops one. A queued call has no pane yet, so quitting pi or `/reload`
-  drops it; pi warns which ones never started.
+  to four times the cap: each starts when a slot frees, and `mu_delegate_cancel queued-N`
+  drops one. Past the queue a call is **refused**, not lost: its task
+  and brief exist, its state is `refused`, and it does not start on its
+  own. Reissue it with `mu_delegate_reissue { call_id }` in its pi
+  session once a slot frees: same call, same task, never a second
+  verdict. Only that live runtime can start or drain a call, so
+  `mu delegates reissue` refuses and names the tool. A refused call is not in murmur's pending
+  count. A queued call has no pane yet, so quitting pi or `/reload`
+  parks it as `refused` (reissue it); pi warns which ones.
 - A delegate that stops on an API error (overloaded, connection, auth)
   keeps its pane. The answer names the error and leaves the choice to
-  the model: re-issue, or record the check as unverified. The footer
-  counts it as `1 failed` until the pane is closed.
+  the model: re-issue, or record the check as unverified.
 - Every answer without a final text (API error, empty, timeout, died,
-  `mu_delegate_cancel`) names the delegate's pi session file and, when
-  it wrote anything, a copy of its last message so far under
-  `~/.cache/mu/delegate-answers/` (`*.partial.md`). Quitting pi or
-  `/reload` lists each running delegate's session file.
-- Answers arrive as follow-up messages when pi would otherwise stop,
-  never mid-turn. To get several at once, set pi's `followUpMode` to
-  `"all"`.
+  `mu_delegate_cancel`) records the delegate's pi session file and,
+  when it wrote anything, its last message so far, in the report.
+  Quitting pi or `/reload` lists each running delegate's session file.
+  A call whose pane is gone fails when the next runtime re-adopts it.
 
 `MU_DELEGATE=0` hides the tool ([env vars](../reference/env.md)).
 
+### Every call is a task
+
+Each `mu_delegate` call creates, in one transaction, a task of
+`kind=delegate` in `scratch` (or the `workstream` you name) with the
+prompt as its brief, plus a call row keyed by a session-qualified
+`call_id` (`pi:<session>:<n>`). The tool result names both:
+`{ task, state, call_id }`. A repeat of the same call id with the same
+request is a no-op; a changed request under it is refused (exit 4).
+
+| State | Meaning |
+| ----- | ------- |
+| `queued` | waits for a slot (the task is parked, so it never reaches `mu task next`) |
+| `starting`, `running` | the pane is coming up, then working |
+| `recording` | the answer is being written |
+| `done` | verdict, report and close are all on record |
+| `failed` | no answer, or the record failed: the task is closed `rejected`, the answer kept as its report, the pane kept |
+| `refused` | past the queue; parked; reissue it |
+| `cancelled` | closed `wontfix` with a report |
+
+```bash
+mu delegates list --caller pi:<session>       # every call and its state
+mu delegates list --all --wave review-1       # one wave
+mu delegates tally -w scratch --wave review-1 # CONFIRMED/REFUTED/UNVERIFIED per judged task
+mu task notes <task> -w scratch               # its brief, and its report: the full answer
+```
+
+The answer is the delegate task's `report`, whole; the settle shows it
+from there, so a lost wake (Escape, compaction, `/reload`) loses
+nothing: the next runtime of the same pi session (after `/reload`, or
+`pi -c` after quitting) re-adopts its `running` pane calls and records
+the answer, a delegate that finished meanwhile included. `tally`
+counts one result per call: a done answer by the label of its first
+`VERDICT:` line (none: UNVERIFIED), a failed or cancelled call as
+UNVERIFIED, queued, running and refused ones as pending. So a plain
+research call (an answer with no `VERDICT:` line) tallies UNVERIFIED
+and closes `answered with no VERDICT line`: the answer arrived, it
+just carries no label.
+
 ### Record a verdict
 
 For a refuter or check, pass `record` so the verdict lands on the task
@@ -66,61 +129,70 @@ it judged. The task must exist (`mu task show`), else the call fails
 and nothing spawns. When the answer arrives, the tool runs
 `mu task note <task> -w <ws> --author <delegate>` once:
 
-- Done: `REFUTER <label> (<delegate>, <elapsed>):`, then the last
-  `VERDICT:` line and every `EVIDENCE:` line after it. Without a
-  VERDICT line, the answer's last 1500 chars after `NO VERDICT LINE:`.
-  Capped at 4000 chars.
+- Done: `REFUTER <label> (<delegate>, <elapsed>):`, then the first
+  verdict line (`VERDICT:` at the start of a line, behind at most one
+  role word such as `REFUTER:`) and everything after it, a multi-line
+  `EVIDENCE:` body included, uncapped. Later `VERDICT:` lines are
+  evidence text, kept verbatim. Without a verdict line, the whole answer after
+  `NO VERDICT LINE:`.
 - Timeout, died, empty, error, or cancelled:
   `REFUTER <label>: no verdict (<outcome>)`.
 
-The follow-up still carries the full answer and ends with
-`Recorded on <ws>/<task> as a note.`, or the reason recording failed.
+The note, the delegate task's report and its close are written together,
+in that order, in one op group (`mu delegates finish`); the delegate
+task is closed before its pane. If the record fails the call is
+`failed`, never `done`, and the answer is kept as the report.
+
+The settle then shows the verdict and where the report is. A call whose
+record failed is shown with its whole report and the reason, so you can
+record it yourself.
 
 ## Delegate without pi
 
-From a script or other shell, run what the tool runs:
+From a script or another shell, spawn a helper bound to a task and wait
+for the run it starts:
 
 ```bash
-mu agent spawn helper-1 -w scratch
-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
+mu task add check_foo -w scratch -t 'Why does foo.spec.ts fail?' --note 'Investigate why foo.spec.ts fails. Report the cause.'
+mu agent spawn helper-1 -w scratch --task check_foo --send 'Do task check_foo. Read: mu task notes check_foo -w scratch'
+mu wait agent:scratch/helper-1
 ```
 
-`--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.
+The send's `next` names the exact ref (`agent:scratch/helper-1@<runs>#<inc>`),
+so a run that settles before the wait starts still counts, and a
+restarted pi is refused rather than read. The result's
+`data.snapshots[].lastText` is the answer (its tail if long; the whole
+text is in `sessionFile`), and `data.firing.kind` says how the run ended:
+`settled`, `input` (it stopped to ask), `dead` (exit 6) or `heartbeat`.
+Non-pi agents have no `lastText`; read the pane with
+`mu agent read helper-1 -w scratch -n 80`.
 
-`mu agent wait` fires when the agent leaves busy (including to
-`needs_input`), never on an already idle agent unless it finished a run
-past `--after-runs`. For pi, the `--json`
-row carries:
+Use a fresh agent or `send --fresh`: a plain send to a reused agent
+carries the previous task's context.
 
-- `outcome`: `done`, `empty`, `error`, `died`, `blocked`, `timeout`, or
-  `pending`. `error` means the run stopped on an API error after pi's
-  own retries; `lastError` holds the message and the pane is kept.
-  `blocked` means pi is waiting on an extension dialog (`blocked` holds
-  its kind and title); the run is not finished.
-- `lastText`: the final message, capped at 64 KiB.
-- `sessionFile`: the agent's pi session file, holding the full
-  transcript (absent for an ephemeral pi or an older extension).
+### With no multiplexer
 
-Exit codes: `0` met, `5` timeout, `6` pane died, `7` blocked on a dialog. Non-pi agents have no
-`lastText`; read the pane with `mu agent read helper-1 -w scratch -n 80`.
+`mu delegates run <call-id>` runs one registered call in a child
+`pi --mode rpc` in the foreground: no tmux, no herdr, no pane. Register
+the call first (`mu delegates register <call-id> --caller <id> --text -`),
+then run it; it sends once, waits, records the verdict, report and close
+on the call's task, and prints the child's log and session paths.
+SIGINT cancels. `mu_delegate` does this by itself when no tmux or
+herdr is installed (see above).
 
 ## Keep a helper
 
 Pass `keep: true`, or spawn a named agent in `scratch`. It is created
 on first spawn, needs no tasks, and cannot be `init`ed. Its `mu-scratch`
 session stays open after the last agent closes; remove it with
-`mu workstream teardown scratch --yes`.
+`mu workstream teardown scratch` (preview), then `--if <rev>`.
 
 ```bash
 mu agent spawn helper -w scratch
 mu agent send helper -w scratch 'Watch CI on PR 1234 and tell me when it is green'
 mu agent read helper -w scratch -n 50
-mu agent close helper -w scratch
+mu agent close helper -w scratch            # preview; prints rev=<n>
+mu agent close helper -w scratch --if <n>   # close it
 ```
 
 A watcher's chat context does not survive compaction. Log each tick
@@ -146,7 +218,7 @@ pane.
 | Steer mid-run           | no                       | `mu agent send`; stop with `mu agent abort` |
 | Keep talking after it answers | no                 | yes, with `keep: true` |
 | Transcript              | collapses into a result  | a normal pi session log |
-| If the work grows       | re-brief a new agent     | same task DAG and workspaces |
+| If the work grows       | re-brief a new agent     | same task DAG and worktrees |
 | Cost                    | light                    | one pane and one pi process |
 
 For many tiny calls, a hidden subagent is lighter. mu bets that seeing
@@ -155,13 +227,16 @@ and steering agent work is worth a pane.
 ## When to stop delegating
 
 Use delegates when you only need the answer: reviewing someone's PR or
-a doc, a fact-check, a go/no-go. Nothing they find lands in the ops
-log, which is permanent and syncs to every machine.
+a doc, a fact-check, a go/no-go. Findings stay in the answers and
+never enter your workstream's task graph. Each call's prompt and
+answer are a `scratch` task, which is in the ops log and syncs like any
+task; `mu workstream teardown scratch` hides them and `mu db forget
+scratch` deletes them.
 
 Move to a workstream when the findings become work agents will fix, or
 the job has dependencies or several stages: see
 [Getting started](getting-started.md) and
-[How to dispatch work](dispatch.md). There, `mu task wait` keys on the
+[How to dispatch work](dispatch.md). There, `mu wait` keys on the
 task and has `--on-stall`. The agent-facing rules for both are in
 [recipes/findings.md](../../skills/mu/recipes/findings.md) and
 [recipes/tasks-or-calls.md](../../skills/mu/recipes/tasks-or-calls.md).

package/docs/guide/dispatch.md

@@ -2,9 +2,7 @@
 
 This guide assumes you finished [Getting started](getting-started.md).
 The agent-facing loop and its traps are in
-[recipes/orchestrator-loop.md](../../skills/mu/recipes/orchestrator-loop.md). For several workers in
-one repo, see [waves](../../skills/mu/recipes/waves.md); for runs that
-last hours, see [long runs](../../skills/mu/recipes/long-run.md).
+[recipes/orchestrator-loop.md](../../skills/mu/recipes/orchestrator-loop.md).
 
 ## Claim before you send
 
@@ -15,14 +13,14 @@ one-shot reviewer:
 mu task claim build -w auth --for worker-1
 ```
 
-`mu task wait` watches tasks, and the reaper returns a claimed task to
+`mu wait` watches tasks, and the reaper returns a claimed task to
 `OPEN` when its pane dies. An unclaimed task gets neither. If no task
 exists, create one with `mu task add --note '<brief>'`.
 
 - `--for` takes a worker name or a qualified `<workstream>/<name>`.
   The worker stays in its own workstream. Only the ownership crosses.
-- Inside a worker's pane, bare `mu task claim <id>` uses the pane
-  title as the worker name.
+- Inside a worker's pane, bare `mu task claim <id>` claims for
+  `$MU_AGENT_NAME`, which spawn injects.
 - To do the task yourself, use `mu task claim <id> --self`.
 
 ## Pick the send mode
@@ -53,23 +51,73 @@ socket. Pick the mode by what the agent is doing:
 - `/new`, `/reload` and `/compact [instructions]` run inside pi through
   the socket and report pi's answer (for example `Nothing to compact`).
   They refuse with exit 4 while pi is busy; `--force` overrides. Any
-  other slash command exits 2; add `--via mux` to type it into the pane.
+  other slash command exits 2.
 - If the socket does not answer, the send fails with exit 1 and
-  pastes nothing. `--via mux` pastes into the pane on purpose.
-
-After a claim, spawn, or wait, the `Next:` block prints the right send.
+  pastes nothing.
+- A send's `--json` carries `msgId`, `incarnation` and `delivery`
+  (`delivered`, or `unknown` in the error JSON of a send that got no
+  reply). Its `next` is ONE line, the exact wait: `mu wait 'agent:<ws>/<a>@<n>#<inc>'`.
+  The `#<inc>` pin refuses (exit 4) when the agent restarted: its run is gone, so
+  re-send the brief. `--wait` enters that wait at once: one JSON document, the wait's, with the
+  send's receipt as `data.sent`. A delivered send (also `spawn --send`, `spawn --task`,
+  `send --interrupt`, `task claim --for`) is registered for the caller, so a bare `mu wait`
+  finds it with no ref; `mu task claim <id> --for <w> --and-wait` dispatches and waits.
+- A send written to the socket but never answered is checked, not
+  repeated: mu asks once for the `msgId` and either reports success
+  (`receipt: confirmed-after-timeout`) or exits 1 with `next` the receipt
+  check `mu agent check <a> <msgId> -w <ws> --json` (only while the agent the
+  send went to is still registered). That verb prints `accepted runs=<n>
+  at=<iso>` (0), `not-accepted` (3) or `unreachable` (1). Only `accepted`
+  is an answer: **`not-accepted` is not "unsent"**. The extension keeps
+  its last 64 ids, so an old send reads `not-accepted` after eviction,
+  and a send that is still in flight can too. Look at the pane
+  (`mu agent read`) before any resend.
+
+After `mu task claim <id> --for <w>`, `next` is the send that hands the task over (`--fresh` for a pi worker).
 `mu agent spawn --send <text>` spawns and sends the first prompt in one
-call; `--next-free` takes the next free name when `<name>` is taken
+call; with `--task <id>` it is one journaled attempt (below); `--next-free` takes the next free name when `<name>` is taken
 (`worker-1` → `worker-2`; the stem is cut to keep the name within 32
 chars, and it gives up with exit 4 when no free name is near).
 
+### Spawn for a task
+
+`mu agent spawn <name> --task <id> --send <text>` spawns, **claims the task
+for the new agent**, sends the text and pins it as the task's `brief` (kept
+when the task has one), as one attempt. Without `--send` it sends the
+task's own `brief` note (with the CLOSE footer, as `mu task auto` does), or
+with no brief one line from its title that points at `mu task notes`. A journal (`spawn_receipts`) is
+written before each step, so the same command never sends a second prompt.
+
+- Same command again = replay: it returns the saved delivery
+  (`task.replay: true`, same `msgId`). `--attempt <key>` names the attempt
+  (default: the task id); a changed text or name under one key exits 4, and
+  reopened work needs a new key.
+- Fails **before** the prompt could be written (no ctl, Claude's trust
+  dialog, a claim that lost the task, the extension refused): its own pane,
+  claim and worktree are rolled back, the key is reusable.
+- Delivery **unknown** (written, no reply; the pane died after the write):
+  exit 1, the pane and the claim stay, `task.state` is `unknown`, and a
+  replay asks the extension once. Never reaped, never resent. Check it
+  with `mu agent check`, read the pane, then decide.
+- A replay after the agent was deleted, or its name reused, reports the
+  historical delivery with `task.stale` (`deleted` | `replaced`); the
+  replacement is never claimed or sent to.
+- The prompt goes only to the agent the spawn created (also plain
+  `spawn --send`): a replaced name, a closed task, or a task someone else
+  owns now refuses it (exit 4) with nothing sent.
+- Another mu process running the same attempt exits 4 (`SpawnAttemptBusyError`);
+  retry and the replay returns its outcome.
+
 ### Non-pi agents
 
-Agents other than pi have no control socket, so mu pastes the text
-into the pane. To start a new session, send `/new` (codex: `/clear`),
-then the prompt. If mu prints `warning: ... was NOT submitted`, the
-agent has not seen the text. Read the pane before you wait. On a slow
-tmux link, raise `MU_SEND_DELAY_MS` (default 500 ms).
+Agents other than pi have no control socket. On herdr, mu sends the
+text with herdr's atomic `agent prompt`. To start a new session, send
+`/new` (codex: `/clear`), then the prompt. If mu prints
+`warning: ... was NOT submitted`, the agent has not seen the text.
+Read the pane before you wait. On tmux, a send to a non-pi agent exits
+4 (`AgentSendUnsupportedError`): spawn it on herdr (`MU_MUX=herdr`), start
+it with the prompt as an argument, or use pi
+([other agent CLIs](other-agent-clis.md)).
 
 ## Write the brief
 
@@ -94,55 +142,66 @@ quoted heredoc: `mu agent send worker-1 - <<'EOF'`; see
 [brief](../../skills/mu/recipes/brief.md#quoting). To see only what the worker wrote after the claim, run
 `mu task notes build -w auth --since-claim`.
 
-## Give each worker a workspace
+## Give each worker a worktree
 
-`mu agent spawn --workspace` creates a jj, sl, or git worktree for the
-agent (`cp -a` outside a repo). You cherry-pick from it.
+`mu agent spawn --worktree` creates a git worktree for the agent and starts
+its pane there: the worker's cwd is its worktree. Outside a git repo it
+fails with exit 4. `--from <ref>` picks the starting commit and `--root <repo>`
+the repo; both default to the HEAD of the checkout you run in (a linked one included). You cherry-pick from it.
 
-Refresh the workspace between tasks. The rebase keeps the agent's pi
-context:
+Refresh the worktree between tasks. The rebase keeps the agent's pi
+context. Before a `--fresh` send:
 
 ```bash
-mu workspace refresh worker-1 -w auth
+cwd=$(mu agent list -w auth --json | jq -r '.agents[] | select(.name == "worker-1") | .cwd')
+git -C "$cwd" fetch && git -C "$cwd" rebase origin/HEAD
 ```
 
-It rebases onto the remote's main (`origin/HEAD`); without a remote,
-pass `--from main`. It refuses on a dirty tree. On a conflict it exits 5:
-git and sl abort the rebase and leave the workspace as it was, while jj
-keeps the rebase with the conflicts committed in place. After you resolve,
-run refresh again so mu records the new base. To throw the workspace away
-instead, run `mu workspace free worker-1 -w auth`.
-
-Claim and send warn when the worker's workspace is 10 or more commits
-behind main. `--strict-staleness` makes that a refusal (exit 4).
+Use `origin/HEAD` as the base, or local main when you merged locally. On a
+conflict, run `git -C "$cwd" rebase --abort` and tell the human. To throw
+the worktree away instead, preview `mu agent close worker-1 -w auth --discard`
+and apply it with `--if <n>`.
 
 ## Wait for the first task to close
 
 Wait on every in-flight task and handle the first one that closes:
 
 ```bash
-mu task wait auth/build auth/docs --first --on-stall exit --json
+mu wait task:auth/build task:auth/docs
 ```
 
-- `--first` prints the closed ref and fills `firing` in `--json`.
-  `--any` leaves `firing` null even on success.
-- `nextSteps[0]` is the cherry-pick command for the worker's new
-  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, 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 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
-progress.
+`mu wait` prints ONE JSON document, with no `--json` flag. Refs are typed
+(`task:`, `agent:`, `delegate:`); with none, it waits on what you started.
+
+- `data.firing` is the event: `closed`, `settled`, `input`, `dead`, `stall`,
+  `delegate`, or `heartbeat` on a timeout (`ok:true`, `timedOut`, exit 0).
+- `data.snapshots` are the refs' real states; `data.resume` is the command
+  that keeps waiting, with every flag you gave. Run it as printed: it takes
+  no other flag (only a matching `-w`). When two watched owners die in one
+  wait, only the first fires; follow `resume` to hear the second. A fresh
+  `mu wait` with the same refs starts a new anchor and reports the earlier
+  death as history.
+- `data.cursor` is what this result consumed per ref (`incarnation`, `runs`);
+  the next wait starts after it, so the same event is never reported twice.
+  `cursorCut` counts entries dropped to fit the 4 KB result.
+- `close:{applied:false, reason:"no CLOSE block…"}` on a settled worker
+  is not a failure: the worker sent no CLOSE block, often because it
+  closed its own task. Read the snapshot's task status.
+- `next` is the stored resume while something is still owed, else null.
+- Exit codes: `0` event or timeout, `6` the owner's pane died, `7` the owner
+  sat in `needs_input` for `--stuck-after` seconds (default 120, or 5 for a pi
+  worker read over its control socket), `130`/`143` SIGINT/SIGTERM (the
+  snapshot and `resume` are still printed). `--on-stall warn` flags the stall
+  on the snapshot and keeps waiting; `steer` sends the stalled pi worker you
+  spawned one fixed reminder and keeps waiting; `release` frees its task and
+  ends the wait. `data.action` (and a stderr line) says `sent`, `released`,
+  `refused` or `unknown`; both refuse a worker you did not spawn or a task not
+  permitted with `mu task auto`. `mu task wait` is the same wait over task
+  refs.
+- `--all` waits for every ref; `--until-text <re>` waits for a run's final
+  text; `--wave <name>` waits on your delegate wave in any workstream
+  (`-w` does not narrow it) and `data.tally` says `6/12 CONFIRMED, ...`;
+  a name none of your calls carry is `no such wave` (exit 3).
 
 ## Close and park tasks
 
@@ -153,8 +212,11 @@ mu task park polish -w auth --why "after the release"
 mu task release build -w auth
 ```
 
-- Closed substates other than `done` need `--why`. Every `CLOSED`
-  substate satisfies a blocker.
+- `close` needs `--evidence "<command + result>"` for `done`; the other
+  substates need `--why`, which is their evidence. `done` also refuses
+  while a blocker is open (exit 4, `mu task tree <id>` lists them); the
+  other substates may close over open blockers. Every `CLOSED` substate
+  satisfies a blocker.
 - Deciding a finding (`accept`, or `close --as rejected|wontfix|duplicate`)
   with a reason under 40 characters and no `VERDICT:` or `REFUTER` note
   prints a warning. The exit code stays the same. A `REJECTED` or `SUPERSEDED`
@@ -162,7 +224,40 @@ mu task release build -w auth
 - `--if-ready` closes only when every blocker is closed. Otherwise it
   lists the open blockers and exits 0.
 - A parked task leaves the ready set, and its dependents keep waiting.
+- `mu human-needed <reason>` records a parked `human` task for a decision only a
+  person can make. It never becomes ready and resolves only by `mu task close`
+  (unpark, claim and a CLOSE block are refused).
 - `release` clears the owner and returns `IN_PROGRESS` to `OPEN`.
 
+## Authorise tasks for the executor
+
+```bash
+mu task auto build --cli pi --max 2 -w auth
+mu task auto --blockers-of umbrella --cli pi -w auth
+mu task auto build --off -w auth
+```
+
+Ready is not permission: the executor acts only on an `auto` task, and only on
+the machine that authorised it. `--off` keeps the run counter.
+
+```bash
+mu next --dry -w auth              # the plan; no pane, socket or write
+mu next --hold -w auth             # dispatch, then wait; recover deaths and API errors
+mu next --workers 2 -w auth        # never more than 2 working; a CLOSED task's idle pane is free
+```
+
+`mu next` also recovers. A worker whose pane died is reaped and its task retried as a new
+attempt; a live worker whose run ended in an API error is sent its brief again in place (never
+reaped, never duplicated). Each retry costs one run of the ceiling; a remote worker's tree is never
+touched. At the ceiling, or for anything it will not guess, it reports an `attention` move.
+
+`mu next --refute [--refute-cli <key>]` also launches ONE checker per task a worker closed as `done`
+(a delegate call in `scratch`, wave `refute-<ws>`, briefed from the task's pinned brief and its
+report). Its `VERDICT:` is recorded on the task before the call closes; the checker never accepts,
+reopens or closes the work, and a wontfix/rejected close gets none. It needs a caller identity
+(`PI_SESSION_ID` or a managed agent) and a cli that speaks ctl (default: the task's own). A repeat
+`mu next --refute` reads a running checker and records its answer (or its death or timeout as
+UNVERIFIED); `--dry` lists the owed checks. `mu delegates tally --wave refute-<ws>` counts them.
+
 To wait on something outside the repo, such as an upstream release,
 block on a placeholder task and close it when the thing lands.