@mu-crew/mu 3.1.0 → 3.2.0

package/AGENTS.md

@@ -55,9 +55,12 @@ mu/
 │   ├── VISION.md          # design pillars
 │   ├── VOCABULARY.md      # canonical terms (single source of truth)
 │   └── ARCHITECTURE.md    # module layout, TUI architecture, key seams
+├── extension/             # the mu pi extension (built to dist/extension/mu-pi.js)
+│   ├── mu-pi.ts           # serves $MU_CTL_SOCK inside a spawned pi (control socket server)
+│   └── delegate.ts        # parent-side mu_delegate / mu_delegate_cancel tools (shell out to mu)
 ├── src/                   # all source (root files: SDK + shared infra; one
 │                          # level of subdirs OK for cohesive clusters — see
-│                          # `src/cli/`, `src/agents/`, `src/tasks/`, `src/mux/`)
+│                          # `src/cli/`, `src/agents/`, `src/tasks/`, `src/mux/`, `src/ctl/`)
 │   ├── db.ts              # SQLite schema + openDb (single CREATE-IF-NOT-EXISTS block; v11)
 │   │                      # also owns SYNCED_ENTITIES / PORTABLE_TABLES / MACHINE_LOCAL_TABLES
 │   ├── mux.ts             # multiplexer backend hub (re-exports src/mux/*)
@@ -78,6 +81,9 @@ mu/
 │   │   ├── kick.ts        # reaper events + cleanup of dead agent rows
 │   │   ├── adopt.ts       # adoptAgent: register an existing pane as a managed agent
 │   │   ├── wait.ts        # waitForAgents: block on task-less agents finishing (busy → any other state)
+│   │   ├── transport.ts   # send routing: ctl for pi agents, mux paste otherwise, no fallback; expectsCtl
+│   │   ├── abort.ts       # abortAgent: stop a pi turn through the control socket
+│   │   ├── delegate.ts    # delegateOutcome: one wait result → done / empty / died / timeout / pending
 │   │   └── errors.ts      # typed agent error classes (AgentNotFoundError, AgentDiedOnSpawnError, …)
 │   ├── tasks.ts           # task SDK hub (re-exports src/tasks/*)
 │   ├── tasks/             # cohesive cluster of task-graph internals
@@ -105,6 +111,8 @@ mu/
 │   ├── sync.ts            # peer status + the ambient flush/ingest hook + --from reader + --repair
 │   ├── fleet-hazards.ts   # mixed-fleet doctor checks (DB inside MU_SYNC_DIR, network mount, case collisions)
 │   ├── file-lock.ts       # generic cross-process advisory lock via atomic fs.mkdir
+│   ├── ctl/               # control socket client: path.ts (ctlSocketPath), protocol.ts (v1, CTL_OPS), client.ts (ctlRequest / ctlProbe)
+│   ├── link.ts            # mu link pi: extension shim + skill symlink + inspectLinks for doctor
 │   ├── logs.ts            # typed READER over `ops` + appendLog / emitEvent (the one write path triggers can't cover)
 │   ├── log-render.ts      # the ONE op → prose formatter (renderOp); shared by CLI + TUI
 │   ├── vcs.ts             # VcsBackend hub (re-exports src/vcs/*: jj/sl/git/none impls)
@@ -121,6 +129,9 @@ mu/
 │   ├── cli/               # one file per verb-namespace; thin wrappers over the SDK
 │   │   ├── workstream.ts  # workstream init / list / destroy
 │   │   ├── agents.ts      # agent spawn / send / read / list / show / close / kick / wait / adopt
+│   │   ├── agents-remote.ts # agent remote-env (prints ssh forward + env; runs nothing)
+│   │   ├── dispatch-hints.ts # dispatch-time Next: hints for pi agents (--fresh / --steer / abort)
+│   │   ├── link.ts        # mu link pi (filesystem only; runs outside handle())
 │   │   ├── tasks.ts       # `mu task` hub (re-exports wireTaskCommands / cmdMyNext / cmdMyTasks / unescapeNoteText)
 │   │   ├── tasks/         # sub-cluster of the `mu task` namespace
 │   │   │   ├── queries.ts    # list / next / owned-by + cmdMyTasks / cmdMyNext (back `mu me tasks` / `mu me next`)

package/README.md

@@ -19,7 +19,7 @@ mu task add --title "Design auth" --impact 80 --effort-days 2
 mu task add --title "Build auth"  --impact 80 --effort-days 5 --blocked-by design_auth
 
 mu agent spawn worker-1 --workspace
-mu agent send worker-1 'Pick up the next ready task and design the auth module.'
+mu agent send worker-1 --fresh 'Pick up the next ready task and design the auth module.'
 mu                         # dashboard
 ```
 
@@ -48,6 +48,11 @@ on track.
   agents, tasks, ownership, notes and workspaces. A single
   append-only **ops log** records every change ever made to them, so
   panes can die and humans can come back later.
+- **Exact control of pi agents, in pi's own TUI.** mu's pi extension
+  serves a per-agent control socket inside each agent's interactive
+  pi, so send, state, wait and abort are exact — locally and on
+  remote hosts over the agent's own ssh. No screen scraping; the pane
+  stays pi's normal TUI, and you can attach and type into it.
 - **Stay out of the model's way.** Mu coordinates handoffs; it does
   not choose models, providers, or thinking effort. `--cli <key>`
   uppercases to `$MU_<KEY>_COMMAND`, so your shell rc owns the agent
@@ -67,9 +72,9 @@ on track.
   and the activity log, never agent-to-agent messaging.
 - **Not a verifier.** `task close --evidence "tests pass"` records
   the claim; mu doesn't run the tests.
-- **Not a replacement for [pi-subagents](https://github.com/nicobailon/pi-subagents).**
-  Mu agents are driveable panes; pi-subagents is for one-shot
-  focused delegation. See [vs `pi-subagents`](#vs-pi-subagents).
+- **No hidden subagents.** One-shot delegation runs in a visible pane
+  you can attach to, steer and keep talking to. See
+  [vs hidden subagents](#vs-hidden-subagents).
 - **Not a hosted service.** Local-first SQLite.
 - **DB-undoable, not substrate-undoable.** Every change is captured as ops
   under one group, so `mu undo <group> --yes` reverses exactly that
@@ -99,43 +104,46 @@ case: one helper or background watcher you still want to drive and
 observe.
 
 **Don't use mu for** — tiny direct edits; quick local inspection;
-one-shot focused delegation where you only need a returned answer
-(use `pi-subagents`); single-context work where durable coordination
-adds ceremony.
+single-context work where durable coordination adds ceremony.
+
+For one-shot delegation where you only need an answer back, use a
+**delegate**: the `mu_delegate` tool, or `mu agent spawn -w scratch` +
+`send` + `wait --json` from a shell. Installing mu gives you
+`mu_delegate`; it ships in the extension `mu link pi` installs.
 
 ---
 
 ## Install
 
 ```bash
-# 1. The CLI, and murmur for agent state on tmux (see below).
-npm install -g @mu-crew/mu @mu-crew/murmur
-mu --version
-murmur init && murmur link pi
-
-# 2. The skill (teaches your coding agent how to drive mu).
-npx skills add mu-crew/mu          # auto-detects pi / claude-code / codex / etc.
-# Add -g to install globally (~/.<agent>/skills/), -y to skip prompts.
+npm i -g @mu-crew/mu
+mu link pi            # pi extension (exact send/state/wait/abort) + the mu skill
+mu doctor
+```
+
+For pi, `mu link pi` replaces `npx skills add`. To drive mu from
+another coding agent (claude-code, codex, ...), install the skill
+instead:
+
+```bash
+npx skills add mu-crew/mu          # auto-detects the agent; -g global, -y no prompts
 ```
 
 **Requirements:**
 - Node 22.12–26 (see `.nvmrc`), matching `engines` in `package.json`.
 - A terminal multiplexer: tmux ≥ 3.0, or [herdr](https://github.com/herdrdev/herdr)
   (`mu doctor` reports which one is active). Spawn, send, and read work
-  on both. Agent state comes from herdr on herdr and from murmur on tmux;
-  the remaining herdr gaps are listed in
+  on both. The remaining herdr gaps are listed in
   [docs/USAGE_GUIDE.md § 20](docs/USAGE_GUIDE.md#20-multiplexer-backends-tmux-and-herdr).
 - pi (the agent CLI mu orchestrates)
 - For `--workspace`: jj, sl, or git on PATH (or `--backend none`)
 
-**Agent state on tmux needs [murmur](https://github.com/mu-crew/murmur),
-even on one machine.** mu owns the work; murmur reports what each agent is
-doing. mu does not read panes itself, so without murmur every agent's state
-is `unknown`, and everything built on state goes quiet: `mu agent wait`
-never fires, `mu task wait --stuck-after` / `--on-stall exit` never detects
-a worker waiting on you, and spawn skips its readiness check. Tasks, claims,
-`mu task wait` on status, workspaces, spawn and send still work. murmur also
-provides one attention-sorted list across machines and owns the ssh egress.
+**murmur is optional for pi agents.** mu reads a pi agent's state from
+its control socket. Non-pi CLIs (claude-code, codex) on tmux get state from
+[murmur](https://github.com/mu-crew/murmur); without it their state is
+`unknown`, so `mu agent wait` and stall detection never fire for them.
+On herdr, herdr reports it. murmur also gives you one attention-sorted
+"who needs me" list across machines, tmux badges, and jump-to-pane.
 
 ```bash
 # on every node that runs agents
@@ -148,12 +156,14 @@ murmur peer add dev  # an ssh target; identity is discovered
 murmur peer list     # which hosts are reachable, and when last seen
 ```
 
-mu exports `MU_MANAGED_AGENT`, `MU_AGENT_NAME`, and `MU_WORKSTREAM`
-into every pane it spawns. murmur uses them to identify crew agents.
+mu exports `MU_MANAGED_AGENT`, `MU_AGENT_NAME`, `MU_WORKSTREAM` and
+`MU_CTL_SOCK` into every pane it spawns. murmur uses the first three to
+identify crew agents; mu's extension serves the control socket at the last.
 See murmur's [stable contract](https://github.com/mu-crew/murmur/blob/main/ARCHITECTURE.md#contract).
 
-**Update:** `npm install -g @mu-crew/mu@latest` for the CLI;
-`npx skills update mu` for the skill.
+**Update:** `npm install -g @mu-crew/mu@latest`. The `mu link pi` shim and
+skill symlink follow the installed package; restart running pi agents (or
+`/reload`) to load the new extension. With `npx skills`: `npx skills update mu`.
 
 **Install from source** (hacking on mu itself):
 
@@ -161,7 +171,7 @@ See murmur's [stable contract](https://github.com/mu-crew/murmur/blob/main/ARCHI
 git clone https://github.com/mu-crew/mu
 cd mu
 npm install -g .                        # `prepare` script auto-builds; `mu` lands on $PATH
-npx skills add ./skills/mu              # local-path source format
+mu link pi                              # links this checkout's extension + skill
 ```
 
 More install patterns (alias-to-dist for fastest dev iteration) in
@@ -279,12 +289,17 @@ backend: the pane is local, the process is remote.
 
 ```bash
 ssh dev 'git -C ~/repo worktree add ~/ws/worker-1'
+eval "$(mu agent remote-env worker-1 -w big --shell)"  # socket forward + env; runs nothing
 mu agent spawn worker-1 -w big --command \
-  'ssh dev -t "cd ~/ws/worker-1 && pi --approve"'
-# ... claim and send exactly as for a local agent, then collect:
+  "ssh $MU_SSH_ARGS dev -t 'cd ~/ws/worker-1 && $MU_REMOTE_ENV \$SHELL -ilc \"pi --approve\"'"
+# ... claim, send and abort exactly as for a local agent, then collect:
 git fetch "ssh://dev/~/ws/worker-1" HEAD && git cherry-pick FETCH_HEAD
 ```
 
+The ssh forwards the remote pi's control socket to the local path mu
+derives, so send, state and wait are exact without murmur. The host
+needs `mu link pi`.
+
 Local and remote agents mix freely in one workstream. You create the
 remote workspace yourself (`--workspace` is local-only) and mu keeps
 no record of it, so read
@@ -294,21 +309,29 @@ covers the traps, including the one where your own agent blocks your
 
 ---
 
-## vs `pi-subagents`
-
-|                          | [`pi-subagents`](https://github.com/nicobailon/pi-subagents) | `mu` |
-| ------------------------ | -------------------------------------------------------- | ---- |
-| Best for                 | "Send this focused task to a specialist, return a result" | "Keep a driveable agent/persistent crew in a multiplexer" |
-| Lifetime                 | one-shot per task                                        | from off-the-cuff `scratch` helper to long-lived crew |
-| Substrate                | `pi` subprocess + result files                           | tmux/herdr panes running pi sessions |
-| Built-in task graph      | no                                                       | yes: parallel-tracks union-find with diamond-merge |
-| Drivable from outside pi | no (extension-only)                                      | yes (`mu` is a real CLI) |
-
-The two play well together. Use `pi-subagents` when you want one
-focused answer back. Use mu's reserved `scratch` workstream when you
-want a low-ceremony helper you can keep talking to. For coordinated
-multi-agent work, graduate from `scratch` to a named workstream + task
-DAG. See [docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md).
+## vs hidden subagents
+
+Most agent tools delegate to a hidden subagent: a child process or
+in-process loop that pi-subagents, pi's example subagent extension,
+and the Claude Code and Codex task tools run out of sight. You get its
+result and lose the rest. A mu **delegate** is an ordinary agent in a
+pane.
+
+|                       | Hidden subagent                         | mu delegate |
+| --------------------- | --------------------------------------- | ----------- |
+| Visibility            | none while it runs                      | a pane; attach and watch live |
+| Steer mid-run         | no                                      | yes: `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 |
+| Agent types           | usually built in                        | none; the brief is ad-hoc text |
+| If the work grows     | re-brief a new agent                    | same task DAG and workspaces as any agent |
+| Cost                  | light                                   | one pane and one pi process each |
+
+The cost row is the trade-off. For many tiny calls a hidden subagent is
+lighter. mu bets that for agent work, seeing and steering the agent is
+worth a pane. For coordinated multi-agent work, graduate from
+`scratch` to a named workstream + task DAG. See
+[docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md).
 
 ---