@mu-crew/mu 3.0.0 → 3.2.0

package/docs/ARCHITECTURE.md

@@ -115,7 +115,7 @@ it mu is just an agent runner.
   decides edge satisfaction: any `CLOSED` task satisfies its blockers.
 - **Substate** qualifies status and never touches edges:
   `OPEN/todo|parked`, `IN_PROGRESS/active`,
-  `CLOSED/done|wontfix|duplicate|superseded`. Rule: **store intent,
+  `CLOSED/done|rejected|wontfix|duplicate|superseded`. Rule: **store intent,
   derive graph facts** — ready and blocked stay derived from edges.
   `OPEN/parked` is excluded from `ready` but stays in `goals`.
 
@@ -624,7 +624,9 @@ returning. Two steps, in order:
 - **Reality wins**: the mux is the source of truth for what panes
   exist. Reconciliation closes the gap on every `mu agent list`.
 - **Agent state is reported, not scraped or persisted.** `src/agent-state.ts`
-  reads herdr's `paneStatus()` on herdr. On tmux, one `list-panes -a`
+  probes a pi agent's control socket ([§ Control socket](#control-socket)),
+  in parallel for all pi agents. For other CLIs it reads herdr's
+  `paneStatus()` on herdr. On tmux, one `list-panes -a`
   reads `@murmur_pane_state` and `@murmur_pane_since` for every local
   agent. Only agents without a local option use `murmur status --json`;
   that result is cached for 10 seconds. See murmur's
@@ -642,6 +644,67 @@ returning. Two steps, in order:
 
 ---
 
+## Control socket
+
+mu drives a pi agent through a unix socket served by mu's own pi
+extension inside the agent's interactive pi. The pane stays pi's TUI;
+a human attached to it shares the same session. No `pi --mode rpc`, no
+screen scraping, no daemon: the server lives and dies with the pi
+process.
+
+**Path derivation** (`src/ctl/path.ts`). `ctlSocketPath(ws, agent)` is
+`<state dir>/sock/<ws>/<agent>.sock`, where the state dir is
+`dirname($MU_DB_PATH)` or the default. Past 103 bytes (macOS
+`sun_path`) it becomes `<state dir>/sock/h/<sha1(ws/agent)[:16]>.sock`.
+Nothing is stored: spawn injects the path as `MU_CTL_SOCK`, and every
+later verb derives it again.
+
+**Protocol v1** (`src/ctl/protocol.ts`, imported standalone by the
+extension). JSON lines, one request per connection. Every reply carries
+`v: 1`; the client throws `CtlVersionError` on anything else.
+
+| op | does |
+| --- | --- |
+| `hello` | identity plus `ops` (served ops) and `extVersion` (mu version the extension was built from) |
+| `status` | `state` (`busy` / `idle` / `needs_input`), `since`, `runs`, `pending` |
+| `send` | `pi.sendUserMessage`; when busy, `mode` `steer` or `followUp` (default) |
+| `wait` | resolves on pi's `agent_settled` after `afterRuns`, with the run's `lastText` |
+| `abort` | `ctx.abort()` (pi's Esc) |
+| `fresh` | new session + prompt as one operation via the internal `/mu-fresh` command; replies once the new run starts; refused with `busy` unless `force` |
+
+An op the extension does not serve returns `unknown op: <op>` with its
+`ops`; mu raises `AgentExtensionOutdatedError` (exit 4, next steps
+`/reload` via mux or respawn), and `mu doctor` flags an `extVersion`
+older than the installed mu.
+
+**Extension lifecycle** (`extension/mu-pi.ts`). Inert unless
+`MU_CTL_SOCK` is set. pi re-creates extension runtimes per session, so
+the server, run counters and an in-flight `fresh` live in a
+process-global map (`Symbol.for("mu.pi.ctl")`). Session replacement
+(`new` / `resume` / `fork` / `reload`) keeps the socket; quit closes it.
+Binding guards against stealing: if the path already answers (a nested
+`pi -p` inherited `MU_CTL_SOCK`), the extension leaves it alone. It
+listens on a private name and hard-links it into place, records the
+inode, and unlinks the public path only if that inode is still its own.
+On `session_start` a server whose path was deleted or replaced closes
+and rebinds, which is how `/reload` recovers a lost file.
+
+**No silent fallback** (`src/agents/transport.ts`). A pi agent
+(`expectsCtl`) whose socket does not answer is `AgentCtlUnreachableError`
+for send and abort, and `unknown` with reason `ctl missing` /
+`ctl refused` for state. mu never pastes into it or asks murmur instead.
+The mux paste path serves non-pi CLIs, adopted panes without ctl, slash
+commands (`sendUserMessage` does not run them), and explicit `--via mux`.
+
+**Remote agents.** The user's `ssh` command carries
+`-L <local derived path>:<remote path>` plus `MU_CTL_SOCK=<remote path>`
+in the remote env; `mu agent remote-env` prints both and runs nothing.
+mu always connects to the local path, so local and remote share one
+transport. ssh leaves the local socket file behind when it dies; it
+probes `refused`, and close or the reaper deletes it.
+
+---
+
 ## Modules (actual src/ layout)
 
 Mostly-flat `src/`: root `.ts` modules plus cohesive subclusters
@@ -661,6 +724,9 @@ separately below.
 | `src/apply.ts`        | **The apply path** — capture's counterpart: given one op, local or from a peer, make the tables reflect it. Also owns `reprojectDeferredOps` ([§ ambient sync hook](#the-ambient-sync-hook)). |
 | `src/undo.ts` + `src/cli/undo.ts` | **Undo as inverse ops**: inverses for one `group_id`, derived from log provenance, refusing a superseded group (exit 4; `--force` overrides). Bare form lists undoable groups (`-n` widens), a prefix previews, `--yes` applies. |
 | `src/project-root.ts` | `detectProjectRoot` — the launch-cwd ladder bare `mu` uses to guess which workstream to focus. Pure filesystem walk; no DB. |
+| `extension/mu-pi.ts` + `extension/delegate.ts` | **The mu pi extension**, built to `dist/extension/mu-pi.js`. Child side (`serveCtl`): serves `$MU_CTL_SOCK` in a pi mu spawned. Parent side (`registerDelegate`, hidden when `MU_MANAGED_AGENT` is set or `MU_DELEGATE=0`): the `mu_delegate` / `mu_delegate_cancel` tools, which shell out to the `mu` CLI (spawn, send, `wait --json`, read, abort, close) and only format the CLI's `outcome` into a follow-up message. Imports nothing from pi; only the protocol from mu. |
+| `src/ctl/*.ts`        | **Control socket** client side ([§ Control socket](#control-socket)): `path.ts` (`ctlSocketPath`, `remoteCtlSocketPath`, `MU_CTL_SOCK`), `protocol.ts` (v1 request/reply types, `CTL_OPS`, line framing; imports nothing from mu so the extension can load it), `client.ts` (`ctlRequest`, `ctlProbe`, typed version / unknown-op errors). |
+| `src/link.ts` + `src/cli/link.ts` | **Link** — `mu link pi`: `linkPi` writes the extension shim (or `--copy`), `linkSkill` symlinks the skill, `inspectLinks` reports `ok` / `missing` / `stale-copy` / `foreign` / `dangling` for doctor. Filesystem only: the verb runs outside `handle()` (no DB). |
 | `src/rebuild.ts` + `src/cli/rebuild.ts` | **Rebuild** — disaster recovery: `rebuildInto` replays the whole log into a NEW DB file via `applyOp`. The verb renders the report: counts, `--json`, an `mv`-swap `Next:` step, a warning that `agents` / `vcs_workspaces` are not reconstructible. |
 | `src/legacy-ops.ts` | Permanent compatibility classifier for historical log-only intents whose entity looks projectable. Rebuild copies them without projection; segment flush never emits them. |
 | `src/drift.ts`        | **Drift detection**, two tiers: `checkDrift` (`mu doctor --deep`) rebuilds into a temp DB and diffs field-by-field; `checkCheapDriftInvariant` (the default) asserts every live row has ≥1 op naming its key. Plus `driftRemediation`. |
@@ -678,7 +744,7 @@ separately below.
 | `src/agent-state.ts`  | Runtime agent-state resolver. Reads herdr's native state or murmur's local pane options and remote JSON; maps source states, returns `unknown` with a reason, and caches remote murmur reads for 10 seconds. |
 | `src/reconcile.ts`    | Ghost prune + orphan surface; "reality wins"                              |
 | `src/agents.ts`       | Hub: CRUD + send / read / list / close + liveness + reaper. Re-exports `src/agents/*`; pane-title composition (`composeAgentTitle`) lives here. |
-| `src/agents/*.ts`     | Agent-lifecycle internals: `spawn.ts` (spawn, CLI resolution, liveness wait *or* backend `startAgentInPane`, pane create-or-reuse, rollback), `spawn-lock.ts` (per-session lock around topology+finalize), `wait.ts`, `adopt.ts`, `kick.ts` (signal a wedged pane's pgid), `errors.ts`. |
+| `src/agents/*.ts`     | Agent-lifecycle internals: `spawn.ts` (spawn, CLI resolution, liveness wait *or* backend `startAgentInPane`, pane create-or-reuse, rollback), `spawn-lock.ts` (per-session lock around topology+finalize), `wait.ts`, `adopt.ts`, `kick.ts` (signal a wedged pane's pgid), `abort.ts` (stop a pi turn via the control socket), `transport.ts` (send routing: ctl for pi agents, mux paste otherwise, no fallback), `delegate.ts` (`delegateOutcome`: one wait result → `done` / `empty` / `died` / `timeout` / `pending`, surfaced by `mu agent wait --json`), `errors.ts`. |
 | `src/dag.ts`          | Shared DAG read/render helpers: `loadFullDag` plus pure `renderForest` / `renderTaskTree`, reused by `mu task tree` and the TUI DAG popup. |
 | `src/tasks/*.ts`      | Task-graph internals: `core.ts` (row shapes, id resolution), `id.ts`, `queries.ts` (reads), `edit.ts` (+ delete cascade preview), `edges.ts` (+ cycle check), `status.ts` (TaskStatus), `sort.ts`, `claim.ts` (atomic CAS), `lifecycle.ts` (close/open), `wait.ts`, `errors.ts`. |
 | `src/tracks.ts`       | Parallel-tracks union-find with diamond merge                                             |
@@ -785,7 +851,7 @@ DB must never sit in `MU_SYNC_DIR`:
 4. **Executes the operation** — agent ops shell out to tmux (and to
    jj/sl/git for workspaces); task ops are pure SQL.
 5. **Reconciles with reality** — read paths prune ghosts and surface
-   orphans; runtime agent state is read from murmur or herdr without a DB write.
+   orphans; runtime agent state is read from the control socket (pi), murmur or herdr without a DB write.
 6. **Records ops** — automatically, per [§ The ops log](#the-ops-log-read-this-first);
    machine-local changes go through `emitEvent`. `mu log --tail`
    subscribers see the new ops on the next 1-second poll.
@@ -1013,9 +1079,10 @@ Single npm package `mu` (see `package.json`):
 - `dist/index.js` + `dist/index.d.ts` — programmatic API + types for SDK callers
 - `skills/mu/SKILL.md` — bundled skill (the only non-`dist` asset shipped)
 
-`tsup` bundles two entries (`index`, `cli`) from `src/`. No runtime
-build step on the user's machine. There is no pi-extension entry — pi
-is a peer dep — and no bundled `agents/*.md` or `prompts/*.md`:
+`tsup` bundles three entries: `index` and `cli` from `src/`, and
+`extension/mu-pi` (the pi extension `mu link pi` points at). No runtime
+build step on the user's machine. pi stays a peer dep — the extension
+types pi's API structurally — and there is no bundled `agents/*.md` or `prompts/*.md`:
 per-role agent guidance lives in the user's project repo.
 
 The dependency list lives in `package.json`; the rule for adding

package/docs/USAGE_GUIDE.md

@@ -389,8 +389,8 @@ table/key/field is the reproduction. See
 `mu` refuses to open a pre-v11 DB (`SchemaTooOldError`, exit 4) or a DB
 newer than it understands (`SchemaTooNewError`, exit 4) and leaves the
 file alone. The retained `scripts/migrate.ts` sidecar auto-detects v7,
-v8, v9, or v10 and writes a fresh v11 DB. It never migrates in place.
-Legacy `REJECTED` tasks become `CLOSED/wontfix` and `DEFERRED` tasks
+v8, v9, v10, or v11 and writes a fresh v11 DB. It never migrates in place.
+Legacy `REJECTED` tasks become `CLOSED/rejected` and `DEFERRED` tasks
 become `OPEN/parked`; their original op payloads remain unchanged.
 Pre-1.0 archives restore as live workstreams under their original
 `source_workstream` names unless you pass `--drop-archives`.
@@ -422,7 +422,26 @@ To update the source-installed copy: pull from upstream, then
 `npm install -g .` from inside the checkout. The `prepare` script
 rebuilds before linking the new dist/.
 
-### Install the bundled skill
+### Link pi (`mu link pi`)
+
+For pi agents, one verb installs both pieces mu needs:
+
+```bash
+mu link pi            # extension shim + skill symlink; then restart pi (or /reload)
+mu link pi --copy     # inline the extension instead (pinned; relink after upgrades)
+```
+
+- `~/.pi/agent/extensions/mu.ts` — a one-line shim that re-exports the
+  installed `dist/extension/mu-pi.js`, so `npm install -g` upgrades the
+  extension with no relink.
+- `~/.agents/skills/mu` — a symlink to the package's `skills/mu`.
+
+mu refuses to replace a real directory at the skill path (exit 4), and
+replaces a symlink pointing elsewhere (e.g. a dev checkout) only with
+`--force`. `--extension-only` / `--skill-only` install one piece.
+`MU_PI_HOME` overrides the home directory both paths are rooted at.
+
+### Install the bundled skill (other agents)
 
 Mu ships a skill at `skills/mu/SKILL.md` that teaches the LLM running
 inside an agent pane how to use mu. The canonical install path is the
@@ -839,9 +858,15 @@ Next:
 
 **When to use which:** `mu workstream init <name>` the moment
 coordination *is* the work — multiple agents, dependencies, gated
-review. `scratch` for a single driveable helper.
-[`pi-subagents`](https://github.com/nicobailon/pi-subagents) when you
-only need a one-shot result back.
+review. `scratch` for a single driveable helper. A **delegate** when
+you only need a one-shot answer back: the `mu_delegate` tool (shipped
+in the extension `mu link pi` installs) spawns a scratch agent, sends
+the task, returns at once, and delivers the answer as a follow-up
+message. From a shell it is `mu agent spawn -w scratch` + `send` +
+`mu agent wait --json` (see [`mu agent wait`](#mu-agent-wait-the-task-less-counterpart-to-mu-task-wait)).
+Unlike a hidden subagent, the delegate's pane stays attachable: watch
+it, steer it, abort it, or pass `keep: true` and keep talking to it.
+Each delegate costs one pane and one pi process.
 
 ### The log ledger: durable watcher dedupe + memory
 
@@ -1370,7 +1395,37 @@ From any shell with mu on `$PATH`:
 mu agent send worker-1 "echo hello from outside"
 ```
 
-mu uses the **canonical bracketed-paste protocol** internally:
+**Which transport.** A pi agent (`--cli pi`, a command whose argv0
+is `pi` / `pi-meta`, or any agent whose control socket file exists)
+gets the text through its **control socket**: the
+mu pi extension calls `pi.sendUserMessage` inside the pane's own pi, so
+nothing is pasted or scraped. When pi is busy the message queues as a
+follow-up; `--steer` interrupts the current run instead. If the socket
+does not answer, the send fails with `AgentCtlUnreachableError` (exit 1)
+and pastes nothing; `--via mux` pastes explicitly. A pi started before
+you upgraded mu still runs the old extension: an op it lacks (say
+`--fresh`) fails with `AgentExtensionOutdatedError` (exit 4). Type
+`/reload` in its pane (`mu agent send <name> '/reload' --via mux`) to
+load the new extension and keep the session, or respawn it. `mu doctor`'s
+`ctl` row flags such agents before you hit the error. Text starting with
+`/` (`/new`, `/compact`) is a TUI command that `sendUserMessage` would
+hand to the model as plain text, so it always goes through the mux.
+Non-pi CLIs always go through the mux. `--json` reports `transport:
+"ctl"|"mux"` (and pi's `state` for ctl). An adopted pi pane was started
+without `MU_CTL_SOCK`; `mu agent adopt` warns and prints the path to
+restart pi with.
+
+**Fresh session + prompt.** For a pi agent, `mu agent send <name>
+--fresh '<prompt>'` starts a new session and sends the prompt into it
+as one operation inside pi (the extension's internal `/mu-fresh`
+command runs `newSession` and sends from the new session). It returns
+once the prompt's run has started, so a send right after it lands in
+the new session. Use it instead of sending `/new` then the prompt. A
+busy pi refuses with exit 4 (`mu agent abort` first, or `--force` to
+abandon the running turn). Non-pi CLIs have no control socket: use the
+two-step `/new` + prompt there and verify the prompt landed.
+
+For the mux path, mu uses the **canonical bracketed-paste protocol**:
 
 0. wait for the pane to stop being mid-modal (`MU_SEND_READINESS_MS`,
    default 15000; 0 disables)
@@ -1630,8 +1685,9 @@ mu task unpark polish               # OPEN/parked → OPEN/todo
 
 Every task carries a **substate** next to its status, rendered as a pair.
 `OPEN` is `todo` or `parked`; `IN_PROGRESS` is `active`; `CLOSED` is
-`done`, `wontfix`, `duplicate`, or `superseded`. `--as` picks the closed
-substate. Anything but `done` requires `--why`, stored as a note in the
+`done`, `rejected`, `wontfix`, `duplicate`, or `superseded`. `--as` picks
+the closed substate: `rejected` when the proposal itself was declined,
+`wontfix` when it is valid but not worth doing. Anything but `done` requires `--why`, stored as a note in the
 same transaction. Any `CLOSED/*` satisfies a blocker, so a non-`done`
 close prints the dependents it unblocked.
 
@@ -1739,8 +1795,20 @@ Mirrors `mu task wait`'s shape: `--any`/`--first` fire on the first
 agent (default: all must finish); `--first` prints the firing agent's
 ref; `--json` carries `nextSteps`; refs may be qualified
 `<workstream>/<name>`. Exit codes: `0` met, `5` timeout, `6` a watched
-agent's pane died. On tmux, murmur supplies the state. `unknown` never
-fires the wait; run `mu doctor` for the missing-source reason.
+agent's pane died (for a pi agent: its control socket stopped
+answering). For pi agents the wait is one request to the mu extension,
+answered when pi settles, so it returns immediately rather than on the
+next poll, and `--json` adds each settled pi agent's `lastText`: the
+text of its final assistant message, verbatim (`""` when the run ended
+without text; capped at 64 KiB). For other CLIs murmur (tmux) or herdr
+supplies the state, and `lastText` is absent; read the pane instead.
+Every `--json` agent row also carries `outcome`: `done` (settled with
+text), `empty` (settled without text, or no `lastText` source), `died`,
+`timeout`, or `pending` (`--any` fired on another agent). The
+`mu_delegate` tool in the mu pi extension is this verb plus spawn and
+send: it formats `outcome` into a follow-up message.
+`unknown` never fires the wait; run `mu doctor` for the missing-source
+reason.
 
 **Don't reach for this verb to catch a worker that asked a question.**
 It fires on `busy → needs_input`, so it does detect the case — but it
@@ -1984,13 +2052,47 @@ Reconciliation runs on every `mu agent list` / `mu`. Two steps:
    registry. **Not** auto-adopted; mu lists them under "Orphan panes"
    with the `mu agent adopt <pane-id>` hint
 
+### A pi worker on another machine
+
+`mu agent remote-env` prints the ssh pieces; mu itself runs no ssh:
+
+```bash
+eval "$(mu agent remote-env worker-1 --shell)"   # sets MU_SSH_ARGS, MU_REMOTE_ENV
+mu agent spawn worker-1 --command \
+  "ssh $MU_SSH_ARGS dev -t 'cd ~/ws/worker-1 && $MU_REMOTE_ENV \$SHELL -ilc \"pi --approve\"'"
+```
+
+`$SHELL -ilc` runs pi in an interactive login shell, so the remote
+`~/.zshrc` / `~/.bashrc` (PATH, provider env) loads; ssh's own
+non-interactive shell skips it. `MU_SSH_ARGS` also forces a direct
+connection (`-o ControlMaster=no -o ControlPath=none`): a multiplexed
+ssh never binds the local end of the forward.
+
+`MU_SSH_ARGS` forwards the remote pi's control socket to the local path
+mu always connects to, so send, state, `mu agent wait` and
+`mu agent abort` behave as for a local agent. The host needs
+`mu link pi`, and its sshd must allow the forward
+(`AllowStreamLocalForwarding`). Full recipe and traps:
+`skills/mu/REMOTE_WORKERS.md`.
+
 ### A worker is wedged on an unbounded tool subprocess
 
 A worker ran `find / -maxdepth 6 ...` (30-60 minutes on a populated
 home directory) or a busy-wait loop. `mu agent send` queues steering
 messages until the tool returns; `tmux send-keys C-c` against the
 pane doesn't propagate (the wrapping pi/claude/codex CLI catches it
-as TUI input). The escape hatch:
+as TUI input). For a pi agent, abort the turn first:
+
+```bash
+mu agent abort worker-1                      # Esc through the control socket; waits for pi to settle
+```
+
+`mu agent abort` kills the running tool (the bash child dies with it)
+and returns once pi settles (exit 5 after `--timeout`, default 30s).
+An idle agent is left alone. A follow-up queued before the abort does
+NOT run: pi puts it back into the pane's editor box, unsent. Re-send
+it if you still want it. Non-pi agents, or a pi whose socket is
+gone, need the signal escape hatch:
 
 ```bash
 mu agent kick worker-1                       # SIGINT (graceful, default)
@@ -2400,10 +2502,10 @@ mv "$DB" "${DB}.old-kept" && mv "${DB}.v11" "$DB"
 mu doctor
 ```
 
-The script auto-detects v7, v8, v9, or v10, opens it read-only, compares
+The script auto-detects v7, v8, v9, v10, or v11, opens it read-only, compares
 its SHA-256 before and after, and never overwrites a target unless
 `--force` is explicit. v9/v10 history is retained unchanged; legacy
-statuses map onto substates (`REJECTED` → `CLOSED/wontfix`, `DEFERRED` →
+statuses map onto substates (`REJECTED` → `CLOSED/rejected`, `DEFERRED` →
 `OPEN/parked`) while projecting into v11, and no migration notes are
 written. Where an undo or a note hid the legacy status, the script
 records a `migrate.substate` op; `--recover <db>` reruns that recovery
@@ -2504,7 +2606,7 @@ to `mu sql`, twice in one session". File it in [ROADMAP.md](ROADMAP.md).
 
 | Doc                                          | What's in it                                            |
 | -------------------------------------------- | ------------------------------------------------------- |
-| [README.md](../README.md)                    | Project overview, install, comparison vs `pi-subagents` |
+| [README.md](../README.md)                    | Project overview, install, comparison vs hidden subagents |
 | [CHANGELOG.md](../CHANGELOG.md)              | Release notes                                           |
 | [ROADMAP.md](ROADMAP.md)                     | What's next, with promotion criteria + rejected ideas   |
 | [VOCABULARY.md](VOCABULARY.md)               | Canonical terms — source of truth for every word        |
@@ -2575,7 +2677,7 @@ The backend is resolved once per process and cached.
 | Attach hint | `tmux a -t mu-<ws>` | `herdr session attach mu-<ws>` |
 | Pane borders | 4-side border showing agent name + status glyph | no-op — herdr owns its pane chrome; mu-managed panes carry the label instead |
 | Layout | `select-layout` | no-op — herdr splits are explicit, geometry is yours |
-| Agent state | murmur pane options for local agents; `murmur status --json` for remote agents | herdr reports state via `paneStatus()` |
+| Agent state | pi agents: the control socket. Others: murmur pane options for local agents; `murmur status --json` for remote agents | pi agents: the control socket. Others: herdr reports state via `paneStatus()` |
 | Focus | mu creates detached | `--no-focus` on every mutating call, always. `detached: false` still gets you a detached workspace; run `herdr workspace focus` yourself. |
 | Isolation seam | `MU_TMUX_SOCKET` (`-L <name>`) | `MU_HERDR_SESSION` (`--session <name>`, its own socket) |
 | `mu agent send` / `read` | six-step paste/Enter protocol | one atomic `agent prompt --wait` |

package/docs/VISION.md

@@ -34,9 +34,9 @@ tasks.
 
 Existing tools force a choice:
 
-- **Pi-subagents** is great for one-shot focused delegation but the
-  children it spawns are short-lived, pi-only, and not driveable from
-  outside their parent pi session.
+- **Hidden subagents** (pi-subagents, the Claude Code and Codex task
+  tools) delegate one-shot work to a child you cannot see, steer, or
+  keep talking to; its transcript collapses into a result.
 - **Tmux-orchestration tools** spawn agents in panes but leave
   coordination to chat transcripts or filesystem conventions.
 - **Task trackers** (GitHub Issues, Linear, even tg) model the work but
@@ -65,6 +65,11 @@ The pi extension is a UX skin. Everything mu does must work from a
 shell with no pi anywhere. A feature that requires the extension
 doesn't ship.
 
+Delegation is CLI: `mu agent spawn -w scratch` + `mu agent send` +
+`mu agent wait --json`. The `mu_delegate` tool adds only the callback
+that puts the answer into the parent conversation, and that is
+presentation.
+
 ### 2. One DB is canonical
 
 All state lives in `~/.local/state/mu/mu.db`. SQLite WAL; multiple
@@ -307,9 +312,12 @@ orchestrator stays in charge.
   It runs agents that do those things.
 - **Not a chat protocol.** Agents communicate through the work graph
   (notes, claim, status) and the **ops log** read through `mu log`.
-- **Not a replacement for pi-subagents.** Different problem (persistent
-  crew vs one-shot focused delegation). Install both; they share the
-  agent-frontmatter format.
+- **Not a hidden-subagent runner.** A one-shot **delegate** is an
+  ordinary agent in a visible pane: attach, steer, abort, or keep
+  talking to it. The cost is one pane and one pi process per delegate;
+  a hidden subagent is lighter for many tiny calls. mu bets that
+  visibility and steering are worth that for agent work. No agent
+  types: the brief is ad-hoc text.
 - **Not a hosted service.** Local-first SQLite. Zero ops, no accounts.
   Your machine is the deployment.
 - **Not a verifier.** The verbs trust the caller. `task close
@@ -348,9 +356,10 @@ orchestrator stays in charge.
    `mu log --tail` for confirmation. This is by design — the
    alternative requires a protocol every CLI would have to speak.
 
-5. **Recursion is opt-in.** Default `maxSubagentDepth: 0`. Children
-   get the `mu` binary on PATH but the bundled skill says "you are
-   not the orchestrator."
+5. **Recursion is opt-in.** The `mu_delegate` tool is hidden in
+   agents mu spawned (`MU_MANAGED_AGENT`), so a delegate cannot spawn
+   delegates through it. Agents get the `mu` binary on PATH, but the
+   bundled skill says "you are not the orchestrator."
 
 6. **Subscriptions are polling-based.** `mu log --tail` polls
    SQLite once per second. SQLite handles the concurrency; latency

package/docs/VOCABULARY.md

@@ -16,21 +16,21 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **mux backend**       | An implementation of the `MuxBackend` interface (`src/mux/tmux.ts`, `src/mux/herdr.ts`). Owns everything backend-specific: session/window/pane topology, the send protocol, scrollback capture, **pane id** validation, and **actor** identity fallback. Sibling of **VCS backend**; same `src/vcs/` shape. | "driver", "provider", "adapter"                  |
 | **mux session**       | The mux-level container holding one workstream's panes. On tmux it is a **tmux session** named `mu-<workstream>`; on herdr it is a herdr *workspace* labelled `mu-<workstream>`. Use the generic term in cross-backend prose and the specific term when the backend matters. | "mux workspace" (collides with mu's VCS **workspace**), "session" alone |
 | **mux detection**     | The ladder that picks the active **mux backend**: `MU_MUX` override → `HERDR_ENV=1` → `$TMUX` → whichever binary is on `PATH` (tmux wins a tie as the incumbent) → `NoMultiplexerError`. `HERDR_ENV` outranks `$TMUX` because it is the narrower signal: only a herdr-managed pane sets it, and herdr may itself be running inside tmux. | "auto-detect" (vague), "probe"                   |
-| **scratch workstream**| The reserved workstream named `scratch` for off-the-cuff agent use — spin up a helper you'll keep talking to without crew/DAG ceremony. Explicit `-w scratch` (no implicit fallback); auto-created on first spawn; `mu workstream init scratch` is rejected (loud). Agents in it are still **agents**, NOT pi-subagents. Task-less is fine; the DAG stays opt-in. | "throwaway ws", "temp workstream", "subagent" |
+| **scratch workstream**| The reserved workstream named `scratch` for off-the-cuff agent use — spin up a helper you'll keep talking to without crew/DAG ceremony. Explicit `-w scratch` (no implicit fallback); auto-created on first spawn; `mu workstream init scratch` is rejected (loud). Agents in it are still **agents**; a **delegate** is a scratch agent started for one task. Task-less is fine; the DAG stays opt-in. | "throwaway ws", "temp workstream", "subagent" |
 | **tmux session**      | The literal tmux session a workstream lives in — the tmux flavour of a **mux session** | "session" alone (ambiguous)                        |
 | **window**            | The mid-level grouping inside a **mux session** (tmux window / herdr tab); identified by `window_name` | "tab" (except as the frontmatter field name)       |
 | **pane**              | One shell view inside a **window**; identified by **pane id**            | "terminal", "shell"                          |
 | **pane id**           | The mux's stable handle for a **pane**. Shape is backend-specific — tmux `%15`, herdr `w1:p1` — so validation lives on the **mux backend**, never as a global regex. Stable for the pane's lifetime; never reused after close. Distinct from a tmux pane *index* (`0`, `1`, …), which is volatile and must never be stored. | "pane number", "pane index"                       |
 | **pane title**        | The string identifying which **agent** occupies a pane. **Equals the agent's name.** Set via `select-pane -T` on tmux, and via `herdr pane rename` (the pane *label*) on herdr. A fallback for **actor** identity — `$MU_AGENT_NAME` is consulted first. | "pane name"                          |
 | **window name**       | The **window**'s name. **Equals the agent's `tab:` value** (groups one or more agents). | "tab name" (in code; `tab:` only in frontmatter) |
-| **agent**             | A named worker running in a pane; identity = `$MU_AGENT_NAME`, falling back to **pane title**; row in `agents` table | "subagent" (reserved for pi-subagents), "worker" (only the specific role) |
+| **agent**             | A named worker running in a pane; identity = `$MU_AGENT_NAME`, falling back to **pane title**; row in `agents` table | "subagent" (means a hidden child in other tools), "worker" (only the specific role) |
 | **worker**            | An **agent** in its role-as-task-claimer. Synonym for the registered side of identity — a row in `agents`, owns tasks via the FK. | (when ambiguous, prefer **agent**)                 |
 | **remote worker**     | A worker whose process and workspace are on another machine while its pane and orchestrator DB remain local. The durable inventory record is a task-note line in the exact `REMOTE: <host>:<path>` shape; pair it with `REMOTE_BASE: <agent>:<sha>` so `mu task claim --for <agent>` can print the one-shot poll-and-close step. `mu state` lists `REMOTE:` lines and `mu state --json` exposes them as `remoteWorkers`. | "remote agent record", "host registry" |
 | **actor**             | The party that *caused* a state change. May or may not be a registered worker. Recorded in `ops.actor` for every op. The orchestrator running mu from a top-level shell is an actor but not a worker. | "caller", "author" (only on notes)            |
 | **crew**              | *Informal* collective noun for the agents in a workstream                | (no API surface; prose only)                       |
 | **task**              | A node in the DAG. Has mandatory `impact` and `effort_days`. Has a **task status** and a **substate**, shown as a pair (`OPEN/parked`, `CLOSED/wontfix`). | "issue", "ticket", "item"                          |
 | **task status**       | The lifecycle phase, one of 3: **OPEN** = not started; **IN_PROGRESS** = claimed and active; **CLOSED** = ended. Status alone decides edge satisfaction: any `CLOSED/*` satisfies a `--blocked-by` edge. | "state"                                            |
-| **substate**          | What the **task status** means for this task. Never null; each status has a default. `OPEN`: `todo` (default), `parked`. `IN_PROGRESS`: `active`. `CLOSED`: `done` (default), `wontfix`, `duplicate`, `superseded`. Rendered as a pair `STATUS/substate`; a default substate renders as the bare status. Valid pairs live in the `task_substates` table. Never affects edges. Refer to a non-`done` close as a *closed substate*. | "resolution", "reason", "sub-status" |
+| **substate**          | What the **task status** means for this task. Never null; each status has a default. `OPEN`: `todo` (default), `parked`. `IN_PROGRESS`: `active`. `CLOSED`: `done` (default), `rejected` (the proposal was declined), `wontfix` (valid, not worth doing), `duplicate`, `superseded`. Rendered as a pair `STATUS/substate`; a default substate renders as the bare status. Valid pairs live in the `task_substates` table. Never affects edges. Refer to a non-`done` close as a *closed substate*. | "resolution", "reason", "sub-status" |
 | **park**              | Verb: set an `OPEN` task to `OPEN/parked` with a required `--why` note. A parked task leaves **ready** and `next`, `claim` refuses it without `--force`, and it stays in **goals**. Its dependents stay blocked. Refuses `IN_PROGRESS` (release first) and `CLOSED` (open first). | "defer", "snooze", "shelve" |
 | **unpark**            | Verb: return an `OPEN/parked` task to `OPEN/todo`.                        | "resume", "reactivate"                             |
 | **task DAG** / **graph** | The directed acyclic graph of tasks. | "task list", "todo", "tree" (it's a DAG, not a tree) |
@@ -65,7 +65,7 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **stale workspace**   | A workspace whose `parent_ref` is N commits behind the project's default branch HEAD (per the workspace's local refs cache). Rendered as a color-coded `behind` column (green ≤2, yellow 3–9, red ≥10) in `mu workspace list` and `mu state`; ≥10 triggers a one-line warn in `mu state`, `mu task claim --for`, and `mu agent send` (or refusal on the two dispatch verbs with `--strict-staleness`). Pure observation — mu never auto-fetches. | "out of date", "drifting"                          |
 | **refresh**           | `mu workspace refresh <agent>` — rebase the agent's workspace onto a fresh base (default = backend's tracked main; `--from <ref>` overrides) WITHOUT touching the agent or pane. Refuses on dirty WC; surfaces conflicts as exit 5 with a resolve-in-place hint. The `none` backend errors (no VCS to rebase). | "recycle", "reset" (overloaded)                     |
 | **backend**           | Implementation of `MuxBackend` or `VcsBackend`. Always qualify which (**mux backend** / **VCS backend**) when both are in scope. | "driver", "provider"                               |
-| **state source**      | The system that reports **agent state**: herdr's `paneStatus()` on herdr, or murmur on tmux. mu reads local murmur pane options in one tmux call and uses `murmur status --json` only for remote workers. No source yields `unknown` with a reason. | "scraper" |
+| **state source**      | The system that reports **agent state**: the **control socket** for pi agents; otherwise herdr's `paneStatus()` on herdr, or murmur on tmux. mu reads local murmur pane options in one tmux call and uses `murmur status --json` only for remote workers. No source yields `unknown` with a reason; a pi agent whose socket does not answer is `unknown` (`ctl missing` / `ctl refused`), never a murmur reading. | "scraper" |
 | **op**                | The atomic unit of change: one row in the `ops` table, written by a trigger inside the same transaction as the mutation it records. Carries `(hlc, machine_id, group_id, actor, intent, entity, key, op, payload)`. A **semantic partial update** — the payload holds only the columns that actually changed, which is what makes per-field merge free. | "event", "delta", "change" (all overloaded)         |
 | **ops log**           | The `ops` table: the single append-only record of every change, and the substrate **sync**, **undo**, and history are all queries or replays over. Canonical and ACID because it lives in `mu.db` alongside the tables it records. | "event log", "journal", "WAL" (reserved by SQLite)  |
 | **intent**            | The semantic label on an **op** (`task.close`, `task.reparent`, `agent.spawn`). Set once per public SDK function via **op context**, not per mutation. `mu log` renders prose from it through one formatter. | "verb" (overloaded by CLI verbs), "action"          |
@@ -74,7 +74,7 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **apply** | Verb: land one **op** into the portable tables, honouring the **merge rules**. `applyOp` / `applyOps` in `src/apply.ts`. Always runs capture-suppressed (`applying=1`), so applying never mints a new op — that is the echo guard. Idempotent: applying the same op twice changes nothing, which is what makes `mu sync --repair` merely "re-read that peer's **segment** from zero". Distinct from **ingest**, which is the sync-side loop that reads a segment and calls apply per op. | "merge" (that's the rule set), "import", "replay" (replay is undo) |
 | **merge rules** | The per-entity conflict policy the **apply** path implements. note/message = **grow-only set**; task/workstream = **per-field LWW**; edge = **LWW-element-set**; KNOWN machine-local entities (`MACHINE_LOCAL_ENTITIES`: agent, workspace, event, broadcast) are rejected as a bad peer; an UNRECOGNISED entity is a forward-compatible no-op — recorded, projected nowhere, never a defect, because a reader may legitimately be older than a writer in a mixed fleet. One rule per entity, chosen so that convergence needs no coordination between machines. | "conflict resolution" (implies prompting a human), "CRDT" (only loosely true) |
 | **per-field LWW** | Last-writer-wins applied PER FIELD, not per row: each field of a task independently keeps the value written by the newest **HLC** that touched THAT field. Free, because ops are **semantic partial updates**. Row-level LWW is explicitly rejected — with agent crews on two machines, a crew closing a task while the operator edits its impact is concurrent by construction, and row-level would silently discard one edit. | "row LWW", "column versioning" (implies version vectors we don't need) |
-| **grow-only set** | An entity that is only ever inserted, never updated: **notes** and log messages. Two machines therefore cannot disagree about a note's content, so there is nothing to resolve — apply is insert-if-absent. Identity is `(task, author, content)`, since a note's surrogate id is assigned per machine and cannot identify it across machines. | "append-only log" (that's the ops log), "set" |
+| **grow-only set** | An entity that is only ever inserted, never updated: **notes** and log messages. Two machines therefore cannot disagree about a note's content, so there is nothing to resolve — apply is insert-if-absent. Identity is `(task, author, content, created_at)`, since a note's surrogate id is assigned per machine and cannot identify it across machines. `created_at` is part of it because machine-written text repeats (the reaper's "previous owner gone", dispatch's "CLAIM: dispatch"), and each repeat is a separate note. | "append-only log" (that's the ops log), "set" |
 | **LWW-element-set** | The rule for **edges**: set membership where both the add and the remove carry an **HLC**, so a remove and a later re-add converge in either arrival order. An edge has no fields worth merging — it is present or absent. | "add-wins set", "2P-set" (a 2P-set can't re-add) |
 | **tombstone** | An `op='del'` row. There is NO tombstone table: a tombstone is an ordinary op carrying an **HLC**, so out-of-order arrival is just "compare HLCs", the same comparison the update path makes. A late **put** older than a seen tombstone loses; a tombstone older than a seen put loses. | "deletion marker", "grave" |
 | **teardown** | Removing a workstream: `mu workstream teardown` kills its **mux session** and deletes its rows, writing **tombstone** ops so the history survives in the **ops log**. **Reversible** — `mu undo <group>` restores every row it removed, so no backup is warranted before running it. Dry-run by default; `--yes` commits. `mu workstream list --torn-down` lists past teardowns with the **group** to undo. NOT called "destroy": that word says irreversible, which is wrong, and it drove real operators to hoard pre-flight DB copies. What teardown does not restore is what was never in the DB: killed panes and freed **workspace** dirs. | "destroy", "delete workstream", "nuke", "purge" |
@@ -104,7 +104,10 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **operation**         | A canonical mu verb (e.g. `mu task add`). Each verb is a thin CLI wrapper over a typed function in `src/*.ts` — the SDK and the CLI share one surface. | "command" (overloaded), "action"             |
 | **reconcile**         | Verb: re-derive registry rows from substrate reality (the **mux**). Always runs in `mu agent list` and `mu doctor`. | "sync", "refresh"                              |
 | **adopt**             | Verb (`mu agent adopt`): register an existing pane as a managed **agent**. The inverse of `mu agent list`'s 'orphan' state. Pane must be in the workstream's **mux session**. | "import", "absorb"                       |
-| **pi-subagents**      | A different package by Nico Bailon for in-pi focused delegation. Mu and pi-subagents are complementary, not competing. | conflating with mu                                 |
+| **control socket** / **ctl** | The per-agent unix socket the mu pi extension serves inside a pi agent's own interactive session (`$MU_CTL_SOCK`). mu derives its path from workstream and agent name, so nothing is stored. Carries `hello`, `status`, `send`, `wait` (resolves on pi's `agent_settled`), `abort` and `fresh` (new session + prompt) as JSON lines. The pane stays pi's normal TUI. **ctl state** is whether it answers: `ok`, `missing` or `refused`. A running pi keeps the extension it loaded at start; an **outdated extension** lacks an op this mu sends (`AgentExtensionOutdatedError`, exit 4) or reports an older `extVersion` in `hello` (doctor warns). pi's `/reload` re-imports it. | "rpc" (pi's `--mode rpc` replaces the TUI; mu does not use it), "daemon" |
+| **delegate**          | A **scratch workstream** agent started for one task: spawn, send the task, return at once, and hand its answer back when its control-socket `wait` resolves. The `mu_delegate` tool in the mu pi extension does this in one call; the CLI equivalent is `mu agent spawn -w scratch` + `mu agent send` + `mu agent wait --json`. The pane stays visible: attach, steer, abort, or keep talking to it. No agent types; the brief is ad-hoc text. | "subagent", "child agent", "worker" (a worker claims DAG tasks) |
+| **lastText**          | The text of the final assistant message of a pi agent run. The mu pi extension records it on `agent_end` and returns it verbatim in the control-socket `wait` reply; `mu agent wait --json` passes it through. mu never interprets it. | "result", "answer file", "output" (alone) |
+| **hidden subagent**   | A child agent in other tools (pi-subagents, pi's example subagent extension, Claude Code and Codex task tools) that runs out of sight: no pane to attach to, no way to steer it or keep talking to it, and its transcript collapses into a result. Usually comes with built-in agent types. mu's counterpart is the **delegate**. | "subagent" alone in mu prose |
 | **TUI**               | The interactive ink-based dashboard launched by bare `mu` in a TTY or explicitly by `mu state --tui`. Lives in `src/cli/tui/`. Read-only against SQLite (yanks, never executes). | "GUI", "interactive mode"                         |
 | **dashboard**         | The TUI's main screen — the grid of cards above the status bar. | "home screen", "main view"                         |
 | **card**              | A glanceable summary tile on the dashboard, identified by its toggle digit (0-9). Wrapped in a TitledBox. | "panel", "section" (overloaded)                    |
@@ -180,8 +183,9 @@ Agent state is runtime data and is not persisted. The codepoints live in
 | `needs_permission` | nf-fa-lock | Waiting for a human answer |
 | `unknown` | nf-fa-question_circle | No state source or no usable reading; the reason accompanies the state |
 
-The state source is herdr on the herdr backend and murmur on the tmux
-backend. mu maps murmur `working` to `busy`, `blocked` to
+The state source is the control socket for pi agents, else herdr on the
+herdr backend and murmur on the tmux backend. The extension's `busy`
+maps to `busy` and `idle` to `needs_input`. mu maps murmur `working` to `busy`, `blocked` to
 `needs_permission`, and `idle`, `done`, and `crashed` to `needs_input`.
 The retained `agents.status` column is deprecated and always contains
 `spawning`; no runtime read uses it.
@@ -192,6 +196,9 @@ The retained `agents.status` column is deprecated and always contains
 | --------------------- | --------------------------------------------------------------------------- |
 | `mu task release feature_a`| Clears the task owner for `feature_a`. The agent who claimed it is unaffected.  |
 | `mu agent close alice`      | Terminates alice's pane and removes from registry. Destructive.             |
+| `mu agent send alice --fresh '…'` | New pi session + prompt as one control-socket operation; returns once the prompt's run started. Refused while busy unless `--force` (abandons the turn). pi only. |
+| `mu agent abort alice`      | Stops a pi agent's current turn through its control socket (pi's Esc) and waits for it to settle. No-op when idle. Queued follow-ups return to the pane's editor unsent. Non-pi agents: use kick. |
+| `mu agent remote-env alice` | Prints (never runs) the ssh socket-forward args and identity env for a remote pi agent's `--command`, so its control socket answers at the local derived path. |
 | `mu agent kick alice`       | Signals (default SIGINT) the foreground process group of alice's pane TTY. For wedged tool subprocesses (`find /`, busy-wait); the wrapping CLI itself is untouched. Refuses when the foreground IS the wrapping CLI. |
 | `mu agent wait alice bob --first` | Blocks until an agent finishes (busy → any other state). The task-less counterpart to `mu task wait` for scratch/off-the-cuff helpers that own no task. `--any`/`--first` fire on the first; default all. Exit 0 met, 5 timeout, 6 a watched pane died. |
 | *(none)*              | There is no detach verb. Use tmux detach to leave a workstream attached session without killing panes. |
@@ -240,7 +247,7 @@ Don't use them in mu code or docs:
 
 | Avoided word     | Why                                                              | Use instead                                          |
 | ---------------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
-| "subagent"       | Pi-subagents owns this term in our ecosystem                     | "agent" (mu's unit) or quote `pi-subagents` explicitly |
+| "subagent"       | In other tools it means a hidden, opaque child agent; mu has none | "agent" (mu's unit), "delegate" (one-task scratch agent), or "hidden subagent" when contrasting |
 | "session"        | Pi has its own "session"; tmux has "session"; herdr has a third (server-level); ambiguous alone | "workstream" (mu's unit), "mux session" (cross-backend), or "tmux session" (literal) |
 | "workspace" (mux sense) | mu already uses "workspace" for a VCS-isolated checkout. herdr's session-level container is also called a workspace, and letting both senses in would make `mu workspace list` ambiguous | "mux session"; say "herdr workspace" only when describing herdr's own CLI |
 | "project"        | Means a `.pi/` project root; conflict with mu's organizational unit | "workstream"                                       |
@@ -283,6 +290,7 @@ exist to keep names canonical, not to replace `--help`.
 | `mu sync --repair <peer>` | Reset a **watermark** to re-read that peer's **segment** from zero. The universal repair, safe because ingest is idempotent via `UNIQUE (machine_id, hlc)`. Takes a `machine_id` or any unique prefix. |
 | `mu undo <group>` | Emit inverse ops for one **group**. Granular (touches only that action's rows), composable, and itself an op — so it syncs and is itself undoable. |
 | `mu rebuild <file>` | Materialize a fresh DB by replaying the **ops log** in HLC order. The disaster-recovery path; prints the swap command rather than overwriting in place. Replays EVERYTHING the log knows, including machine-local ops — a rebuild is local recovery, not **ingest**, so it does not filter to synced entities. Carries `machine_identity` (and its HLC clock) across, so the rebuilt DB is the SAME peer. `agents` / `vcs_workspaces` are NOT rebuilt — they have no capture triggers so leave no ops, and `pane_id` / absolute paths would be lies after recovery; the summary reports the loss and says to re-spawn. |
+| `mu link pi` | Install mu into pi: the **extension shim** (`~/.pi/agent/extensions/mu.ts`, a re-export of the installed `dist/extension/mu-pi.js`, marked `// mu:shim`) and a symlink `~/.agents/skills/mu` → the package's `skills/mu`. `--copy` inlines the extension (pinned). Never replaces a real directory; replaces a foreign symlink only with `--force` (`LinkConflictError`, exit 4). Root overridable via `MU_PI_HOME`. |
 | `mu db backup <file>` | `VACUUM INTO` copy of the whole DB. The "one file I can scp" convenience; real DR is **segments** + `mu rebuild`. |
 
 A one-off directory needs no flag — `MU_SYNC_DIR=/mnt/usb mu state`
@@ -375,7 +383,7 @@ reading commands ("alice claims design" sounds like a person;
 task). Role-based names also make `mu agent list` and tmux's window
 list legible at a glance.
 
-The roles align with pi-subagents' role taxonomy:
+Common roles:
 
   `worker`     long-lived implementer; the default
   `reviewer`   reads diffs/code; usually `--role read-only`
@@ -419,9 +427,9 @@ XDG-Base-Directory-Spec compliant. The state directory resolves as:
 - **Never** place `MU_DB_PATH` inside `MU_SYNC_DIR`. Syncing a live
   SQLite file (and its `-wal`/`-shm` sidecars) corrupts it. `mu doctor`
   checks for this.
-- mu does NOT consult any agent-template directory. If pi-subagents
-  is installed, its `~/.pi/agent/agents/` and `.pi/agents/` paths
-  are pi-subagents' concern — not mu's.
+- mu does NOT consult any agent-template directory (such as
+  `~/.pi/agent/agents/` or `.pi/agents/`). Roles are names and
+  briefs, never templates.
 
 ### Env vars (mu state location)
 
@@ -433,6 +441,7 @@ XDG-Base-Directory-Spec compliant. The state directory resolves as:
 | `MU_SESSION`      | Override active workstream name (when not auto-detectable)   | n/a |
 | `MU_MUX`          | Force the **mux backend**, bypassing **mux detection**. Load-bearing: every verb reaches its multiplexer through `activeMux()`, so an unknown value fails the invocation rather than silently running on tmux. | wins over all detection |
 | `MU_SYNC_DIR`     | Shared folder holding one **segment** per machine. Unset = sync off, zero cost. The WHOLE cluster configuration; there is no peer list. | n/a |
+| `MU_DELEGATE`     | `0` hides the `mu_delegate` tool in the mu pi extension (kill switch for benchmarks or a model it confuses). The `mu doctor` extension row says so. | n/a |
 
 ### Env vars passed to spawned children
 
@@ -449,9 +458,11 @@ XDG-Base-Directory-Spec compliant. The state directory resolves as:
 | `MU_HERDR_SESSION`           | Drive a NAMED herdr server (`--session <name>`, its own socket) instead of the user's default one. The herdr analogue of `MU_TMUX_SOCKET`, and the isolation seam any herdr integration test must use so the suite can never observe — or destroy — real panes. herdr **mux backend** only. |
 | `MU_<UPPER_CLI>_COMMAND`     | Override the executable launched for `--cli <cli>` (e.g. `MU_PI_COMMAND=pi-alt` makes `--cli pi` exec `pi-alt`; hyphens in the cli key become underscores in the env var name, so `--cli pi-meta` reads `MU_PI_META_COMMAND`). Accepts multi-word strings (`MU_PI_COMMAND="pi-alt --some-flag"`); tmux exec's via a shell. Reconcile also treats the resolved binary as agent-worthy when surfacing orphan panes. When this env var supplies the override (and `--command` did not), the spawn-success line surfaces the env-var name (`Spawned worker-1 (pi-meta via $MU_PI_META_COMMAND)`) so stale aliases are visible without `mu agent show`. |
 | `MU_SPAWN_LIVENESS_MS`       | **tmux-tier knob** (herdr's `agent start` blocks until the agent is ready, so there is nothing to poll for). After spawn, wait this many ms then verify the pane is still alive AND scan the tail of its scrollback for known startup-error patterns (provider auth failures — `No API key found for X`, `401 Unauthorized`, … — plus shell-level `command not found` / `No such file or directory` when the spawned binary vanished post-pre-flight). Default 1500. Set to 0 to disable (useful in CI). On detected death the DB row is rolled back and `AgentDiedOnSpawnError` is thrown with the captured scrollback; on a startup-error match (pane alive but parked at an error prompt) the row is rolled back and `AgentSpawnStartupError` is thrown with the matched line + remediation hints. The complementary pre-flight check (PATH lookup of `--cli`'s resolved binary BEFORE any side effect) is not env-tunable; on miss it throws `AgentSpawnCliNotFoundError` with no orphan workspace / pane / row. |
+| `MU_CTL_SOCK`                | Set by spawn in every agent pane: the agent's control socket path, derived from (state dir, workstream, agent). The mu pi extension serves it; mu connects to it. |
+| `MU_SPAWN_CTL_MS`            | Budget for spawn's control-socket handshake with a pi agent, polled every 250ms (default `30000`; `0` disables). On timeout spawn still exits 0, reports `ctl: missing\|refused`, and warns on stderr. `mu agent spawn --no-ctl` skips it per spawn. |
 
-These mirror pi-subagents' `PI_SUBAGENT_*` env vars in spirit but live
-in a separate namespace so the two can coexist in one pi session.
+They use the `MU_` namespace so they never collide with env vars other
+pi extensions set in the same session.
 
 ---
 

package/docs/specs/2026-09-29-task-substates.md

@@ -57,7 +57,7 @@ Consequences:
 | D8 | Apply resolves the pair before writing: a status-only op, or an unknown substate from a newer peer, falls back to the status default. The original payload stays in `ops`. | The foreign key fails the whole commit. Version skew must not break sync; the foreign key is there to catch our own bugs. |
 | D9 | Non-`done` close and `park` require `--why`, stored as an ordinary note in the same transaction. | Keeps the rationale, the one good part of the notes-only convention. |
 | D10 | Start with `parked` as the only non-default `OPEN` substate. No `--until`. | YAGNI. mu has no daemon to run the automatic un-park. Adding `triage` later is one seeded row. |
-| D11 | One shared legacy mapping: `REJECTED → CLOSED/wontfix`, `DEFERRED → OPEN/parked`. | Replaces `normalizeTaskStatus` (currently folds both onto `OPEN`). Apply, rebuild, undo and migration all use it, so recovery happens on every path. |
+| D11 | One shared legacy mapping: `REJECTED → CLOSED/rejected` (3.1.0; 3.0.0 used `wontfix`), `DEFERRED → OPEN/parked`. | Replaces `normalizeTaskStatus` (currently folds both onto `OPEN`). Apply, rebuild, undo and migration all use it, so recovery happens on every path. |
 | D12 | Migrate v10 → v11 through `scripts/migrate.ts`, not in `openDb`. | Keeps the "production never migrates in place" rule. SQLite cannot add a foreign key to an existing table, so a new target is required anyway. |
 
 ## Schema (v11)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.0.0",
+  "version": "3.2.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"
@@ -55,9 +55,9 @@
     "test:fast": "vitest run --config vitest.fast.config.ts",
     "test:watch": "vitest",
     "test:watch:fast": "vitest --config vitest.fast.config.ts",
-    "lint": "biome check src test scripts",
-    "lint:fix": "biome check --write src test scripts",
-    "format": "biome format --write src test scripts",
+    "lint": "biome check src test scripts extension",
+    "lint:fix": "biome check --write src test scripts extension",
+    "format": "biome format --write src test scripts extension",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
     "prepare": "npm run build",
     "test:stress": "tools/test-stress.sh"