@mu-crew/mu 3.13.3 → 4.1.0

package/docs/guide/getting-started.md

@@ -8,19 +8,20 @@ You need Node.js, the pi coding agent, tmux 3.0
 or later, and a git repository to work in. Run every command from
 inside a tmux session, in the root of that repository.
 
-## Install mu and link pi
+## Install mu and the pi package
 
-First, install mu and connect it to pi:
+First, install mu and install its pi package:
 
 ```bash
 npm i -g @mu-crew/mu
-mu link pi
+pi install npm:@mu-crew/mu
 mu doctor
 ```
 
-`mu link pi` installs the mu pi extension and the mu skill. In the
-output of `mu doctor`, the extension, skill, and `ctl` rows say `ok`.
-If pi was already running, restart it so it loads the extension.
+`pi install` loads the mu extension, skill, and recipe prompts as one
+package. Once a pi agent is running, the "mu ext" and `ctl` rows of
+`mu doctor` report the live extension; before that, "mu ext" says
+`unknown`. If pi was already running, restart it so it loads the package.
 
 ## Create a workstream
 
@@ -33,13 +34,11 @@ mu workstream init auth
 
 ```
 Created workstream auth (mux session mu-auth)
-Next:
-  Attach the session : tmux attach -t mu-auth
-  ...
+attach: tmux attach -t mu-auth
 ```
 
-Every verb ends with a `Next:` block of follow-up commands. We use
-them as we go.
+When a verb leaves a move to make (a wait a send owes, the `--if` apply
+of a preview), it ends with a `next:` line you can run as printed.
 
 ## Plan two tasks
 
@@ -53,11 +52,7 @@ mu task next -w auth
 ```
 
 ```
-┌────────┬────────┬────────────────────────┬────────┬────────┬──────┬───────┐
-│ name   │ status │ title                  │ impact │ effort │ ROI  │ owner │
-├────────┼────────┼────────────────────────┼────────┼────────┼──────┼───────┤
-│ design │ OPEN   │ Design the auth module │ 80     │ 2      │ 40.0 │ —     │
-└────────┴────────┴────────────────────────┴────────┴────────┴──────┴───────┘
+task	design	OPEN	impact=80 effort_days=2	Design the auth module
 ```
 
 Only `design` is ready. `build` appears when `design` closes.
@@ -67,12 +62,12 @@ Only `design` is ready. `build` appears when `design` closes.
 Spawn a pi agent with its own git worktree:
 
 ```bash
-mu agent spawn worker-1 -w auth --workspace
+mu agent spawn worker-1 -w auth --worktree
 ```
 
 ```
-Spawned worker-1 (pi) in window worker-1 of mu-auth, pane %15 with auto-workspace
-  workspace: ~/.local/state/mu/workspaces/auth/worker-1 (git)
+Spawned worker-1 (pi) in window worker-1 of mu-auth, pane %15 with its own worktree
+  cwd: ~/.local/state/mu-next/worktrees/auth/worker-1
 ```
 
 The worker runs in a new window of the `mu-auth` session. To watch
@@ -81,7 +76,7 @@ it, run `tmux attach -t mu-auth`. Detach with `Ctrl+b d`.
 ## Claim the task for the worker
 
 Assign the task before you send any text. The claim is what
-`mu task wait` watches.
+`mu wait` watches.
 
 ```bash
 mu task note design -w auth 'SCOPE: write docs/auth.md with the token design'
@@ -108,29 +103,26 @@ and closes the task.
 ## Wait for the task to close
 
 ```bash
-mu task wait design -w auth --first --on-stall exit
+mu wait task:design -w auth
 ```
 
 ```
-auth/design
-any-of 1 reached CLOSED in 41094ms
-Next:
-  Cherry-pick worker-1's commit onto your branch : git cherry-pick 26278f1...
-  Refresh worker-1's workspace onto current main : mu workspace refresh worker-1 -w auth
+{"ok":true,"data":{"firing":{"kind":"closed","ref":"task:auth/design"},...},"next":null}
 ```
 
 The exit code tells you what happened:
 
 | Exit | Meaning | Next move |
 | ---- | ------- | --------- |
-| `0` | the task closed | merge the work |
-| `5` | `--timeout` expired (default 600 s) | wait again |
+| `0` | the task closed (`firing.kind` `closed`), or the heartbeat cap passed (`heartbeat`, `timedOut: true`; default 1500 s) | merge the work, or run `data.resume` to keep waiting |
 | `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 `--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 |
+| `7` | the worker sat in `needs_input` for `--stuck-after` seconds (120, or 5 for a pi worker read over its control socket) | read it (`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
-prints a warning and the wait keeps running.
+To keep waiting, run `data.resume` as printed (`mu wait --resume <id> -w auth`):
+it replays the stored wait whole, and refuses any other flag. With
+`--on-stall warn`, a stalled worker only prints a warning and the wait
+keeps running. `--on-stall steer|release` act on a worker you spawned;
+see [dispatch](dispatch.md).
 
 A pi worker that ends its turn while it still owns an `IN_PROGRESS`
 task gets one reminder to close it or say why not, so exit 7 mostly
@@ -138,8 +130,8 @@ means it is blocked or asking something.
 
 ## Merge the commit
 
-Run the cherry-pick command from the `Next:` block, then run your
-tests on the result:
+Inspect the worker's commits (`git -C <worktree> log --oneline`),
+cherry-pick what you want, then run your tests on the result:
 
 ```bash
 git cherry-pick 26278f1
@@ -149,11 +141,12 @@ Before the next task, rebase the worker's worktree onto the new main.
 The worker keeps its pi context:
 
 ```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
 ```
 
-The default target is the remote's main branch (`origin/HEAD`). In a
-repository without a remote, name the branch: `--from main`.
+In a repository without a remote, rebase onto local `main`. On a conflict,
+run `git -C "$cwd" rebase --abort` and resolve it by hand.
 
 ## Check the graph
 
@@ -166,20 +159,20 @@ claim, send, wait, and merge steps.
 
 ## Close the worker
 
-When you are done, free the worktree and close the agent:
+When you are done, close the agent:
 
 ```bash
-mu workspace free worker-1 -w auth
-mu agent close worker-1 -w auth
+mu agent close worker-1 -w auth           # preview; prints the --if command
+mu agent close worker-1 -w auth --if <n>  # close it
 ```
 
-`mu agent close` refuses while the worktree has commits or edits that
-mu has not freed. That protects work you have not merged.
+Close removes the worktree. It refuses while the worktree has uncommitted
+edits, which protects work you have not committed. If the worker made
+commits you have not merged, close keeps them on a branch
+`mu/auth/worker-1-<sha>` and prints its name.
 
 ## Next steps
 
 - [Dispatch work to a worker](dispatch.md) covers more than one
   worker and the `--fresh`, `--interrupt`, `--steer`, and plain send choices.
-- [Use the TUI dashboard](tui.md): run bare `mu` to see every
-  workstream at once.
 - [Clean up](cleanup.md) when the workstream is finished.

package/docs/guide/other-agent-clis.md

@@ -0,0 +1,102 @@
+# How to run mu with other agent CLIs
+
+mu is built around pi, but codex, cursor-agent and claude can be its workers
+or its orchestrator. They get less: they have no control socket, so mu
+cannot hand them a prompt on tmux, abort them, or read their final text, and
+nothing replaces `mu_delegate`. Tested with codex 0.164 and cursor-agent
+2026.10.22 on tmux ([report](../eval/harnesses.md)).
+
+## Pin the mu the harness runs
+
+Check this first. codex and cursor-agent pass mu's env (`MU_*`, `PATH`) on
+to their shell tool, but they run each command through your interactive
+shell rc, and the rc wins. If `~/.zshrc` puts another `mu` first on `PATH`,
+or exports `MU_SYNC_DIR` / `MU_DB_PATH`, the harness uses that `mu` and
+that DB. codex's `shell_environment_policy.set` does not help: it is applied
+before the rc runs. Pin it for each harness:
+
+- codex: `codex --disable shell_snapshot` (as `MU_CODEX_COMMAND`, or in a
+  wrapper).
+- cursor-agent: `ZDOTDIR=<a dir with an empty .zshrc> cursor-agent`.
+- Or keep the rc file from adding `mu` and `MU_*` at all.
+
+A wrapper that sets the env itself (`MU_SYNC_DIR=`, `MU_DB_PATH`,
+`MU_STATE_DIR`, then `exec mu "$@"`) holds its env under any rc. Name it
+something the rc does not shadow (`mun`). The skill and briefs still say
+`mu`, so pin `mu` as well.
+
+Then check from inside the harness:
+`command -v mu; mu --version; echo "<$MU_SYNC_DIR>"`.
+
+## Run one as a worker
+
+On tmux, mu cannot type into a non-pi pane, so `spawn --send` and `agent
+send` exit 4. Put the brief in a task note, start the agent with the prompt
+as its argument, then claim:
+
+```bash
+mu task note build -w auth - <<'EOF'
+<brief, ending with: mu task close build -w auth --evidence "...">
+EOF
+export MU_CODEX_COMMAND="codex --disable shell_snapshot --dangerously-bypass-approvals-and-sandbox"
+mu agent spawn worker-1 -w auth --cli codex --worktree \
+  --command "$MU_CODEX_COMMAND 'Do task build. Run: mu task notes build -w auth'"
+mu task claim build -w auth --for worker-1
+mu wait task:auth/build
+```
+
+On herdr, `--send` and `agent send` work (herdr's `agent prompt`, see
+[dispatch](dispatch.md#non-pi-agents)), but herdr refuses `--command`.
+
+- **Dialogs.** A new folder makes codex ask "Trust this folder?", and
+  unreviewed hooks ask again. On tmux mu cannot answer them. Pre-trust the
+  repo (`-c 'projects."<repo>".trust_level="trusted"'`; worktrees inherit the
+  root's trust), or attach and press the key.
+- **State** comes from murmur on tmux, from herdr on herdr. Wire murmur to
+  the harness's stop hook (cursor: `.cursor/hooks.json` `stop`, see murmur's
+  `docs/setup.md`). Without it the agent is `unknown` throughout. With it,
+  you see `needs_input` when a turn ends, but never `busy`.
+- **codex: use its `Stop` hook, not `notify`.** codex runs a hidden turn to
+  title each new thread, and `notify` reports that turn as finished about 2 s
+  into the worker's first turn. murmur then reads `done`, and `--stuck-after`
+  reports the running worker as stalled (3.x does the same). `Stop` fires only
+  for real turns. Drop `notify` from `~/.codex/config.toml` and put this in
+  `~/.codex/hooks.json`:
+
+  ```json
+  {"hooks": {"Stop": [{"hooks": [{"type": "command",
+    "command": "murmur notify --source codex --event-type agent-turn-complete"}]}]}}
+  ```
+
+  Keep `--event-type`: without it murmur reads a `Stop` payload as `blocked`.
+  codex asks you to trust a new hook once (`/hooks`), and `--disable hooks`
+  turns it off.
+- **Wait on the task, not the agent.** `mu wait task:<ws>/<id>` fires when the
+  worker closes it. `mu wait agent:<w>` fires only on busy → not busy, as in
+  3.x: an agent already idle, or one that goes from `unknown` to
+  `needs_input`, does not count. murmur's notify path never reports `busy`,
+  so on tmux that wait runs to its timeout. `--until-text <re>` matches the
+  pane's tail instead.
+- **Stalls** mean the owner has read `needs_input` for `--stuck-after` while
+  its task is still open. Read the pane (`mu agent read`) before you act.
+- **No abort, no CLOSE block.** Stop it with `mu agent close` (preview, then
+  `--if`). The brief must end with the worker's own `mu task close`.
+
+## Run one as the orchestrator
+
+Install the skill (`npx skills add mu-crew/mu`) and point the harness at it.
+It dispatches pi workers as usual (`spawn --worktree --task --send -`).
+
+- **Wait on refs.** A bare `mu wait` owns only what a pi session or a managed
+  pane started. From codex or cursor in a plain shell it is a usage error.
+  Name what you started: `mu wait task:<ws>/<a> task:<ws>/<b>`.
+- **Delegate through `scratch`**, since there is no `mu_delegate`. Spawn a pi
+  agent there (the first spawn creates the workstream; `init` refuses it),
+  `send --fresh --json -`, then wait on the exact ref the send prints. See
+  [tasks-or-calls](../../skills/mu/recipes/tasks-or-calls.md).
+
+## With no multiplexer
+
+Task, DAG, `sql`, `log` and `mu wait task:` verbs work. `workstream init`,
+`state`, and the agent verbs exit 5 and name the install. The child-pi
+delegate (`mu delegates run`) needs pi.

package/docs/guide/recovery.md

@@ -8,33 +8,25 @@ read the same rules in
 
 ```bash
 mu doctor           # exit 0 healthy (WARN rows too), 5 on drift or a FAIL row
-mu doctor --deep    # rebuild the ops log and diff every field
-mu doctor --disk    # add per-workspace byte usage
+mu doctor --deep    # rebuild the ops log and diff every field; PRAGMA quick_check on the DB
+mu doctor --disk    # add per-worktree byte usage
 ```
 
 ## An agent's pane died
 
-Run `mu agent list` or `mu state`. Each run reconciles the registry
+Run `mu agent list` or `mu state -w <ws>`. Each run reconciles the registry
 with the multiplexer:
 
 - An agent row whose pane is gone is a ghost. mu deletes the row, and
-  its `IN_PROGRESS` task returns to `OPEN`. A `mu task wait` on that
+  its `IN_PROGRESS` task returns to `OPEN`. A `mu wait` on that
   task exits 6.
 - A pane in the session that runs an agent CLI but has no row is an
-  orphan. mu lists it with an adopt hint and does not adopt it.
+  orphan. mu lists it and does not register it. Close the pane with
+  tmux or herdr, or ignore it.
 
-To register an orphan pane, or a pi you started by hand:
-
-```bash
-mu agent adopt %15 -w auth
-mu agent adopt %15 -w auth --name investigator
-```
-
-On herdr, pass its pane id instead (`mu agent adopt w1:p2 -w auth`).
-
-The pane title becomes the agent name. The pane must be in the
-`mu-<workstream>` session. An adopted pi has no control socket until
-you restart it with the `MU_CTL_SOCK` path that `adopt` prints.
+A `mu agent spawn --task` after a dead worker, with the same attempt
+key but a new request, is refused (`already ran with a different
+request`): pass `--attempt <new key>`.
 
 ## A pi agent shows `ctl missing` or `ctl refused`
 
@@ -43,19 +35,19 @@ back to pasting.
 
 | State | Means | Fix |
 | ----- | ----- | --- |
-| `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 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 `pi install npm:@mu-crew/mu`, 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` 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'             # extension serves op command
-mu agent send worker-1 -w auth '/reload' --via mux   # older: type it into the pane
+mu agent send worker-1 -w auth '/reload'   # extension serves op command
 ```
 
-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.
+An extension without op command cannot be reloaded by mu: respawn the
+agent. `/reload` keeps the pi session. A `send --fresh` or `abort`
+against an outdated extension fails with exit 4 and prints the fix.
 
 ## A new pi agent shows `ctl missing`
 
@@ -66,7 +58,7 @@ 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.
+including worktrees, so use it only on your own code.
 
 Claude asks the same on an untrusted folder, with "No, exit" as the
 default. Spawn warns and skips `--send`: attach the pane, answer it, then
@@ -80,22 +72,10 @@ needs restarting.
 
 ## You ran the wrong command
 
-Every action is one group of ops. Find it, preview the inverse, then
-apply:
-
-```bash
-mu undo                   # list recent groups
-mu undo 6380dd3d          # preview
-mu undo 6380dd3d --yes    # apply
-```
-
-- Any unique prefix of a group id works.
-- The undo is its own group, so undoing it again is redo.
-- If later work changed the same fields, undo exits 4 and names the
-  conflict. A later write to `updated_at` alone, such as `mu task note`,
-  does not count. `--force --yes` overrides and discards the newer work.
-- Undo restores rows only. Killed panes and freed workspace
-  directories do not come back.
+Every action is one group of ops. `mu log` shows the group ids, and
+`mu log --group <prefix>` shows what one action wrote. Any unique prefix
+of a group id works. mu has no general undo: fix a wrong change with the
+inverse verb.
 
 ## `mu doctor` reports drift
 
@@ -106,7 +86,7 @@ a write, the live table holds real work that a rebuild would discard.
 ```bash
 mu db backup /tmp/mu-drift-evidence.db     # 1. keep the evidence
 mu rebuild /tmp/mu-rebuilt.db              # 2. replay the log into a new file
-MU_DB_PATH=/tmp/mu-rebuilt.db mu sql "SELECT local_id, title FROM tasks"   # 3. compare
+MU_DB_PATH=/tmp/mu-rebuilt.db mu db query "SELECT local_id, title FROM tasks"   # 3. compare
 ```
 
 Decide which side is right, then report the drift as a bug with the
@@ -117,22 +97,23 @@ command.
 
 | Row | Means |
 | --- | ----- |
-| `ws-rows` | a workspace row whose directory is gone; the next send fails in the VCS |
-| `ws-dirs` | a workspace directory with no row; it blocks the next `--workspace` spawn with that name |
-| `ws-empty` | a workstream directory with no checkouts |
+| `ws-rows` | a worktree row whose directory is gone; a reused name trips over it. `mu agent close <agent>` forgets it |
+| `ws-staging` | a `--worktree` spawn killed (SIGKILL, crash) before its pane: its placeholder row and maybe a half-made worktree. The next `mu agent spawn` in that workstream removes them |
+| `ws-empty` | a workstream directory with no worktrees |
 | `db-copies` | stray `mu.db*` files that nothing reads, including the `pre-compact` / `pre-forget` backups |
 | `exports` | output left by the removed export verb |
 | `locks` | lock directories older than one hour, from a spawn or flush that died |
 
-To list workspace orphans with cleanup commands, run
-`mu workspace orphans -w auth`. An orphan has no row, so
-`mu workspace free` cannot remove it. Remove a git-backed orphan with
-`git worktree remove --force <path>` from the project root, and any
-other with `rm -rf <path>`.
+The worktree registry outlives the agent, so a worktree whose agent was
+reaped is still closed by name: `mu agent close <agent>` keeps unmerged
+commits on a branch and refuses dirty work (`--discard` drops it). A
+directory mu never registered has no row: inspect it, then remove it with
+`git worktree remove --force <path>` from the project root, or `rm -rf
+<path>` when it is not a worktree.
 
 ## Rename a workstream
 
-There is no rename verb, and `mu sql` refuses to change
+There is no rename verb, and `mu db query` refuses to change
 `workstreams.name`. The name is part of the key that every op is filed
 under, so a raw rename leaves the ops log on the old name: `mu doctor`
 reports drift, and sync or `mu rebuild` brings the old name back.
@@ -142,7 +123,7 @@ Re-create the workstream instead:
 mu db backup /tmp/mu-before-rename.db
 mu workstream init auth-refactor
 # re-add the tasks you still need, with -w auth-refactor
-mu workstream teardown auth-refator --yes
+mu workstream teardown auth      # preview, then --if <rev>
 ```
 
 Names start with a lowercase letter, use letters, digits, `_`, or

package/docs/guide/remote.md

@@ -1,74 +1,151 @@
 # How to run a worker on another machine
 
-The pane is local and the pi process is remote. mu runs no ssh
-itself. `mu agent remote-env` prints the ssh pieces, and you put them
-in the spawn command. The full recipe, with recording, collecting,
-and the traps, is in
+The pane is local and the pi process is remote. mu never connects and
+knows no ssh flags: a host profile holds your own command templates, and
+`mu agent spawn --host` fills them. The full recipe, with collecting and
+the traps, is in
 [skills/mu/recipes/remote-workers.md](../../skills/mu/recipes/remote-workers.md).
 Read it before your first remote spawn.
 
 ## Prepare the host
 
-On the remote host:
-
-1. Install mu and run `mu link pi`, so the remote pi loads the mu
-   extension.
+1. On the host, install pi and the mu package:
+   `pi install npm:@mu-crew/mu`. The host needs no mu DB: a remote worker
+   cannot run `mu task` verbs. It ends with a `CLOSE:` block. `mu wait`
+   applies it when it sees the run settle; `mu agent wait` does not. Re-run
+   the evidence first, or close the task yourself.
 2. Allow unix-socket forwards in the host's sshd:
    `AllowStreamLocalForwarding yes`.
-3. Create the worker's checkout yourself. `--workspace` works only
-   for local agents:
-
-   ```bash
-   ssh dev 'git -C ~/repo worktree add ~/ws/worker-1'
-   ```
+3. Have a git repo there for `--worktree` to branch from. One profile serves
+   every repo on the host: `--max-sessions` caps the machine, so never add
+   the same machine twice.
 
 Use one orchestrator DB on your machine. Do not run a second mu on the
-host for the same work: task ownership points into your local
-`agents` table.
+host for the same work: task ownership points into your local `agents`
+table.
 
-## Spawn the agent
+## Add a profile and check it
 
 ```bash
-eval "$(mu agent remote-env worker-1 -w auth --shell)"   # sets MU_SSH_ARGS, MU_REMOTE_ENV
-mu agent spawn worker-1 -w auth --command \
-  "ssh $MU_SSH_ARGS dev -t 'cd ~/ws/worker-1 && $MU_REMOTE_ENV \$SHELL -ilc \"pi --approve\"'"
+mu host init dev --ssh   # prints a starter `mu host add`; runs nothing
+mu host add dev --shell '<pane cmd>' --exec '<run cmd>' --fetch '<fetch cmd>' --max-sessions 1
+mu host check dev --root '~/repo'   # host answers, repo, pi, mu extension
 ```
 
-What each part does:
+## Spawn the agent
 
-- `MU_SSH_ARGS` forwards the remote pi's control socket to the local
-  path mu connects to. It includes `-o ControlMaster=no -o
-  ControlPath=none`, because a multiplexed ssh connection never binds
-  the local end of the forward.
-- `MU_REMOTE_ENV` sets the agent's identity inside the remote shell.
-  tmux `-e` variables do not cross the ssh hop.
-- `$SHELL -ilc` starts pi in an interactive login shell, so the
-  remote `~/.zshrc` or `~/.bashrc` loads PATH and provider keys.
-  Without it, ssh's non-interactive shell skips them and pi can die at
-  startup.
-- `pi --approve` skips pi's project-trust prompt. It trusts whatever
-  directory the pane starts in, so use it only on your own code.
+```bash
+mu agent spawn worker-1 -w auth --host dev --worktree --root '~/repo' --task build --send 'Read: mu task notes build -w auth'
+```
 
-If the spawn reports `ctl refused`, check `AllowStreamLocalForwarding`
-on the host.
+- The pane runs the profile's `--shell` template, filled with the remote
+  identity (`MU_MANAGED_AGENT`, `MU_AGENT_NAME`, `MU_WORKSTREAM`,
+  `MU_CTL_SOCK`, `MU_REMOTE`, never your DB, state or sync dir, which are unset in the pane), your
+  `--command` (default `pi`), the local and remote socket paths and the
+  remote cwd. The template starts the remote pi and forwards its control
+  socket to the local derived path.
+- `--worktree` makes a detached `git worktree add` in the remote repo
+  `--root` names (default: the profile's `--repo`; with neither the spawn
+  refuses) through its `--exec`, at
+  `~/.local/state/mu-next/remote-worktrees/<ws>/<name>` on the host. Its path,
+  base commit and the repo's absolute toplevel are the agent's `cwd`, `base`
+  and `repo`; close and recovery use that repo, never the profile's.
+  `--cwd` names an existing remote directory instead; without either, the
+  agent starts in `--root` (default the profile's repo), else the login
+  directory. Without a repo, templates get `.` for `{cwd}`. `--root` is part
+  of a `--task` attempt's identity: the same attempt in another repo conflicts.
+- `--task` is the same one journaled attempt as for a local agent: claim
+  for the new agent, then the brief, never sent twice.
+- mu reserves the host's channel before its first remote command and
+  keeps it while the pane lives (`--max-sessions` counts it). A full host
+  refuses the spawn up front and names the holder. A failed spawn removes
+  only the worktree it made (still clean, still at its base) and frees
+  the slot. If the host's answer was lost after it made the worktree (a
+  timeout), spawning the same name again takes that tree over while it is
+  clean, at its base and unused; anything else at the path refuses.
+- The pane is the transport: closing it, or its death, ends the agent
+  and frees the slot. tmux only; herdr refuses `--host` in one line.
+- A non-pi `--command` (`--host dev --command 'npm test'`, no `--cli pi`) is a
+  **command gate**, not a worker: its pane is kept after the command ends, and
+  `mu wait agent:auth/gate-1` returns the command's own exit status (the
+  `exit` of the result and of the process; 23 stays 23). Never a held
+  `ssh dev …`. The remote command writes a token-bound completion record that
+  mu reads once the pane has exited; no record, a signal or a lost transport is
+  exit 6, never 0. `mu agent close gate-1` frees the pane and removes that
+  record. No `--worktree`, no `--task`.
+- If the spawn reports `ctl refused` or `missing`, run
+  `mu host check dev --agent worker-1 -w auth`, then check
+  `AllowStreamLocalForwarding` on the host.
 
 ## Drive it like a local agent
 
-Claim, `mu agent send --fresh`, `mu agent wait`, and `mu agent abort`
-all go through the forwarded socket and behave as they do locally:
+`mu agent send`, `wait`, `abort` and `check` go through the forwarded
+socket and behave as they do locally. `mu state` shows remote workers
+as agent records with `host`, `cwd`, `base` and `collected_head`.
+
+## Collect and close
 
 ```bash
-mu task note build -w auth 'REMOTE: dev:~/ws/worker-1'
-mu task claim build -w auth --for worker-1
-mu agent send worker-1 -w auth --fresh 'Work on build. Read: mu task notes build -w auth'
+cd ~/repo                              # the local repo the commits come home to
+mu agent collect worker-1 -w auth      # runs the profile's --fetch, prints the merge
+git merge <sha>                        # mu prints the exact sha; it never merges
+mu agent close worker-1 -w auth        # preview, then --if <rev>
 ```
 
-The `REMOTE: <host>:<path>` note line is how `mu state` lists remote
-workers. Collect the work by fetching from the remote checkout:
+- `collect` runs the `--fetch` template locally, in the current directory's
+  git repo, under one channel. It pins the fetched commit as
+  `refs/mu/collect/<ws>/<agent>` (gc keeps it) and records it as the
+  agent's `collected_head`. A fetch that fails, or succeeds without leaving a
+  commit, records nothing. Collecting the same HEAD again says so.
+- The pane is the transport, so a live worker holds its host's channel. At
+  `--max-sessions 1`, `collect` is refused with the holder named; raise the
+  cap to collect while the worker runs.
+- `close` kills the pane first (that frees the channel), then removes the
+  remote worktree **only if** it is clean and its HEAD is the base or the
+  collected HEAD, and no process on the host is inside it. Its `git worktree
+  remove` never uses git's `--force`. A process inside it, or a host with
+  neither /proc nor lsof to check, refuses naming `close --force`, which
+  removes past either with a warning. A newer HEAD refuses with one line:
+  `collect` again, or `close --keep-branch` to keep the commits on the remote
+  branch `mu/<ws>/<agent>-<sha12>` and remove the worktree. Uncommitted files
+  always refuse (`--discard` and `--keep-branch` do not override that).
+- A `--cwd` agent has no remote worktree of its own: close never touches the
+  host. When a row is deleted (its pane died and the
+  reaper took it, a workstream teardown, a peer's workstream delete, even a raw
+  SQL delete) the database keeps a
+  machine-local `remote_recovery` record of the host, path and base (`mu sql
+  "select * from remote_recovery"`; `mu rebuild` loses it). A failed spawn whose
+  own rollback removed the tree (or found it gone) leaves none. With no agent row left,
+  `mu agent close <name> -w <ws>` (or `<ws>/<name>`) previews and closes THAT
+  worktree under the rule above (no pane, no task; the recorded host profile only), and
+  `mu agent collect <name>` fetches from it. Several records of one name need
+  `--recovery <id>`; a current agent of the name or path, a newer record of the same path, or a changed `--exec`, refuses (a changed default repo does not).
+
+## Host profiles
+
+A host profile stores your own command templates, so you stop retyping
+them. mu never connects and knows no ssh flags: it fills the templates and
+runs them with `/bin/sh -c`. `spawn --host` uses them (above); `agent
+collect` runs the `--fetch` template.
 
 ```bash
-git fetch "ssh://dev/~/ws/worker-1" HEAD && git cherry-pick FETCH_HEAD
+mu host init dev --ssh        # prints a starter `mu host add`; runs nothing
+mu host add dev --shell '<pane cmd>' --exec '<run cmd>' --fetch '<fetch cmd>' --max-sessions 1
+mu host check dev --root '~/repo'   # host answers, repo, pi, mu extension
+mu host show dev              # templates and the holders of its channels
 ```
 
-`mu agent kick` does not reach a remote process. Use `mu agent abort`,
-or close the pane.
+- Placeholders: `{env}` (the five `MU_*` identity variables only), `{cmd}`,
+  `{local_sock}`, `{remote_sock}`, `{cwd}`. Each value is one quoted word and
+  is exactly the text you passed, also inside your own `"..."` or `'...'`.
+  A template that hands command text to a second shell (ssh's remote login
+  shell) says so per placeholder: `{cmd:sh}`, `{cwd:sh}` quote the value for
+  that shell too. Write `{{` and `}}` for literal braces. Anything else in
+  braces is refused.
+- A command that times out, or whose caller is killed, takes its whole process
+  group with it before its channel is freed, so `--max-sessions` never
+  undercounts a live transport.
+- `--max-sessions N` counts every channel mu holds to the host. At the cap mu
+  refuses with one line naming the holder.
+- `host check --agent <name> -w <ws>` also probes that agent's forwarded
+  control socket.