@mu-crew/mu 3.13.2 → 4.0.0

package/docs/guide/sql.md

@@ -1,36 +1,62 @@
 # How to query and script mu
 
-Use typed verbs with `--json` first. Use `mu sql` for ad-hoc joins,
-reports, and repairs that no verb covers.
+Use typed verbs with `--json` first. Use `mu db query` (alias `mu sql`) for
+ad-hoc joins and reports that no verb covers; a repair needs `--write`.
 
 ## Script with `--json`
 
 Every verb takes `--json`.
 
-- Collection reads print `{"items": [...], "count": N}`.
-- Single objects, such as `mu task show`, print an object with named
-  fields.
-- `mu sql --json` prints a bare array of rows.
-- `mu log --tail --json` prints one JSON object per line.
-- Errors go to stderr as `{error, message, nextSteps, exitCode}`.
+- Every verb prints ONE document on stdout: `{"ok": true, "data": ..., "next": null}`.
+- Collection reads put `{"items": [...], "count": N}` in `data`. The task
+  reads (`task list/next/owned-by/show/tree`, `me tasks`) cap the result at 4 KB:
+  `more` counts what is left and `retrieve` is the same command with `--all`
+  (`--full` on `owned-by`, whose `--all` means every workstream), which prints
+  everything whole. Task items use the SQL column names (`id` is the `local_id`,
+  `effort_days`, `workstream_id`, `owner_id`; `owner` only while
+  IN_PROGRESS), never `name`/`effortDays`/`roi`. `task add --json` returns its
+  `task` (and `tasks`) in the same shape.
+- Single objects, such as `mu task show`, put an object with named
+  fields in `data`.
+- `mu db query` and `mu sql` print this document by default (`--table` gives
+  the human table). A read puts `{items, count, more}` in `data`, the same
+  shape as task lists, with your row keys untouched. It stops at 4 KB of final
+  output, cells never cut: `more` counts the rows left out and `retrieve` is the
+  same query with `--all`, which prints every row whole. One row bigger than the
+  cap gives zero `items`, `more: 1` and `retrieve`. A write prints
+  `{changes, lastInsertRowid}` (a script `{statements, multiStatement}`); an
+  `UPDATE ... RETURNING` prints its rows whole, with no `retrieve`, since running
+  it again would write again. Errors are the failure document on stdout, with or
+  without `--json`.
+- `mu state` and bare `mu me` print the document by default too (no `--json` needed); a read over 4 KB is cut and names `mu state ... --full`.
+- `mu log --tail` (no `--json` needed) is the exception: one raw JSON object per line, keyed by the `ops` column names.
+- A failure is `{"ok": false, "error", "message", "next", "exit"}` on
+  **stdout** (plus, for usage errors, `usage`, at most 3 lines), with
+  the same non-zero exit code. `2>/dev/null` loses nothing.
 
 ```bash
-mu state -w auth --json
-mu task list -w auth --json | jq '.count'
+mu state -w auth
+mu task list -w auth --json | jq '.data.count'
+mu task show t1 -w auth --json | jq 'if .ok then .data.task else .message end'
 ```
 
-Exit codes: `2` usage error, `3` not found, `4` conflict, `5`
-timeout, a locked DB, or a multiplexer, VCS, drift, or `mu doctor`
-FAIL-row failure, `6` reaped pane, `7` stall.
+Exit codes: `1` any other failure (a spawn that failed, an unreachable
+control socket, a send whose delivery is unknown), `2` usage error, `3` not found, `4` conflict, `5`
+an abort or interrupt that timed out (pi still busy), a locked DB, or a multiplexer, VCS, drift, or `mu doctor`
+FAIL-row failure, `6` a watched owner died, `7` stall, `130`/`143`
+SIGINT/SIGTERM during a wait. A wait that hits its cap
+(`mu wait`, `mu task wait`, `mu agent wait`) is `0` with `timedOut: true`, not `5`.
 
 ## Read the schema
 
-The schema has 12 tables and 3 views (`ready`, `blocked`, `goals`).
+The schema (version 13) has 26 tables and 4 views (`ready`, `blocked`,
+`blockers`, `goals`). Views skip torn-down workstreams. `blockers` has one
+row per open edge: `task_local_id` is held up by `blocker_local_id`.
 Four tables travel between machines: `workstreams`, `tasks`,
 `task_edges`, and `task_notes`. List them all:
 
 ```bash
-mu sql "SELECT type, name FROM sqlite_master WHERE type IN ('table','view') ORDER BY type, name"
+mu db query "SELECT type, name FROM sqlite_master WHERE type IN ('table','view') ORDER BY type, name"
 ```
 
 Task ids (`local_id`) are unique per workstream only. Join
@@ -42,21 +68,21 @@ Edges and notes reference `tasks.id`, not `local_id`.
 Blocked tasks and the goals view, which replaced removed verbs:
 
 ```bash
-mu sql "SELECT b.local_id, b.title FROM blocked b JOIN workstreams w ON w.id = b.workstream_id WHERE w.name = 'auth'"
-mu sql "SELECT g.local_id, g.title FROM goals g JOIN workstreams w ON w.id = g.workstream_id WHERE w.name = 'auth'"
+mu db query "SELECT b.local_id, b.title FROM blocked b JOIN workstreams w ON w.id = b.workstream_id WHERE w.name = 'auth'"
+mu db query "SELECT g.local_id, g.title FROM goals g JOIN workstreams w ON w.id = g.workstream_id WHERE w.name = 'auth'"
 ```
 
 Search task titles:
 
 ```bash
-mu sql "SELECT t.local_id, t.status, t.title FROM tasks t JOIN workstreams w ON w.id = t.workstream_id
+mu db query "SELECT t.local_id, t.status, t.title FROM tasks t JOIN workstreams w ON w.id = t.workstream_id
         WHERE w.name = 'auth' AND LOWER(t.title) LIKE '%token%'"
 ```
 
 Every task that blocks `launch`, directly or not:
 
 ```bash
-mu sql "WITH RECURSIVE prereqs(id) AS (
+mu db query "WITH RECURSIVE prereqs(id) AS (
           SELECT t.id FROM tasks t JOIN workstreams w ON w.id = t.workstream_id
            WHERE t.local_id = 'launch' AND w.name = 'auth'
           UNION
@@ -65,15 +91,69 @@ mu sql "WITH RECURSIVE prereqs(id) AS (
         SELECT t.local_id, t.title, t.status FROM prereqs JOIN tasks t ON t.id = prereqs.id"
 ```
 
-`mu sql` runs writes too and prints the number of rows changed. Writes
-are captured as ops under one `sql.write` group per call, so `mu undo`
-reverts the whole call. `--confirm-rows N` counts rows removed by
+`mu db query` syncs like every other verb (when `MU_SYNC_DIR` is set): it
+ingests peer ops before the query and flushes its own writes after, even
+when the statement fails. It reads by default: a statement SQLite reports as
+not read-only (`INSERT`, `UPDATE`, `DELETE`, `REPLACE`, `WITH ... INSERT`,
+anything with `RETURNING`) is refused in one line, exit 2, until you add
+`--write`. A write prints the number of rows changed. Writes
+are captured as ops under one `sql.write` group per call, so `mu log --group`
+shows the whole call. `--confirm-rows N` counts rows removed by
 `ON DELETE CASCADE` too: deleting a task with one edge counts 2.
 
-`mu sql` refuses to change a natural-key column (`workstreams.name`,
+With `-w <ws>` (a spawned worker defaults to its own), the views `ready`,
+`blocked` and `blockers` cover that workstream only, with the same columns;
+`main.ready` is still the global one. The scope is the connection's own
+(`TEMP` views), so nothing is left in the file.
+
+`no such column: x` answers in one line with the closest columns and the real
+columns of every table the query names; the SQL is never rewritten.
+
+The whole call runs in one transaction that mu opens, so `BEGIN`,
+`COMMIT`, `END`, `ROLLBACK`, `SAVEPOINT` and `RELEASE` are refused, each
+statement checked by SQLite itself (a table or column named `begin` or
+`end` is fine, a leading `;` hides nothing); a failed statement rolls the call
+back. An `INSERT` that names an `id` of 0 or below is refused too (omit it), and
+so is an `UPDATE` of `id` (or `rowid`) on `workstreams`, `tasks`, `task_notes`
+and `task_edges`: ids are set once. Notes are append-only: an `UPDATE` of a
+note's `author`, `content`, `created_at` or `kind` is refused (add a new
+note), and so is an `UPDATE` of an edge's `created_at`. A rebuild or peer
+would replay either as a different row than the one you edited.
+
+What it will not touch: mu's capture bookkeeping, the schema and the
+connection. The rule is a policy, so nothing has to be detected:
+
+- No `CREATE`, `DROP` or `ALTER` of any kind, `TEMP` tables, views and
+  triggers included, and no `ANALYZE` or `REINDEX`. A trigger that outlives
+  one statement can fire inside mu's own bookkeeping.
+- No `ATTACH` or `DETACH`: the verb works on this one DB. Another mu DB
+  (a backup, a peer) is not for it to write.
+- `PRAGMA` only as a read: `table_info`, `table_xinfo`, `table_list`,
+  `index_list`, `index_info`, `index_xinfo`, `foreign_key_list`,
+  `foreign_key_check`, `integrity_check`, `quick_check`, and a bare
+  `user_version`, `foreign_keys`, `busy_timeout` or `database_list`.
+  Anything else is refused before it runs.
+- No write to `op_ctx`, `op_dying`, `ops`, `schema_version`, `machine_identity`,
+  `sqlite_sequence` (the AUTOINCREMENT counters; inserts still advance them) or
+  `sync_peers` (sync watermarks: `mu sync --repair <peer>` re-reads a peer).
+
+SQLite itself decides what a statement does (its `EXPLAIN` listing, trigger
+bodies included), never the text, so a table named `begin` is fine and a
+leading `;` hides nothing.
+
+Need DDL? `mu db backup`, edit the copy with `sqlite3` yourself, and leave the
+live DB to mu's verbs. `mu db forget` shrinks it.
+
+`mu db --shell [-w <ws>]` opens the `sqlite3` CLI on the same file,
+read-only and in safe mode, with the same scoped views. Plain `sqlite3`
+starts with `foreign_keys=0` and no capture context: use it to look, never to write.
+
+The whole-file commands stay under `mu db`: `backup`, `compact`, `forget`.
+
+`mu db query` refuses to change a natural-key column (`workstreams.name`,
 `tasks.workstream_id`, `tasks.local_id`, a note's task, or an edge's
 endpoints). The ops log files every change under that key, so changing
-it would desync sync, undo, and `mu doctor`. Add a new row instead.
+it would desync sync and `mu doctor`. Add a new row instead.
 
 ## Pass list flags
 

package/docs/guide/stop-a-worker.md

@@ -1,6 +1,6 @@
 # How to stop a worker
 
-Use the gentlest step that works, in this order: abort, kick, close.
+Use the gentlest step that works, in this order: abort, close.
 
 ## Abort the turn (pi agents)
 
@@ -14,53 +14,46 @@ keeps the session and its context. It works for remote agents too.
 
 - An idle agent is left alone (exit 0).
 - Exit 5 means pi was still busy after `--timeout` (default 30 s).
-  Go to the next step.
+  Close the agent.
 - A follow-up queued before the abort does not run. pi puts it back
   into the pane's editor, unsent. Send it again if you still want it.
 
 To give the agent new work after the abort, send with `--fresh`. See
 [Dispatch work to a worker](dispatch.md#pick-the-send-mode).
 
-## Kick the foreground process
-
-Use `mu agent kick` when abort failed, when the agent is not pi, or
-when pi's socket is gone:
-
-```bash
-mu agent kick worker-1 -w auth                    # SIGINT
-mu agent kick worker-1 -w auth --signal SIGTERM
-mu agent kick worker-1 -w auth --signal SIGKILL
-```
-
-mu finds the foreground process group on the pane's TTY and signals
-it. This is the fix for a worker stuck on an unbounded `find /` or a
-busy-wait loop. Typing Ctrl-C into the pane does not work, because
-the agent CLI catches it as input.
-
-- Kick refuses with `NoForegroundProcessError` when the foreground
-  process is the agent CLI itself. Close the agent instead.
-- Kick works on local panes only. On herdr it works on Linux only.
-
-To prevent the problem, scope worker prompts to the workspace. Do not
-ask for filesystem-wide `find` or `grep -r /`.
-
 ## Close the agent
 
 ```bash
-mu agent close worker-1 -w auth
+mu agent close worker-1 -w auth             # preview: writes and kills nothing, prints rev=<n>
+mu agent close worker-1 -w auth --if <n>    # apply that preview
 ```
 
-Close kills the pane and deletes the agent row. A clean workspace is
-freed with it. If the workspace has edits or commits, close refuses
-with exit 4. Then do one of these:
-
-- Run `mu workspace free worker-1 -w auth --commit` to commit pending
-  changes and free the workspace, then close. For git, if the commits
-  are on no branch, mu keeps them on a new branch
-  `mu/<workstream>/<agent>-<sha>`.
-- Run `mu agent close worker-1 -w auth --discard-workspace` to free
-  and close in one step. You lose the changes.
+Bare close only previews: it names the pane, the tasks the agent owns
+(an `IN_PROGRESS` one goes back to `OPEN`), the worktree's state and
+the `--if` command that applies it. Pass `--if <n>` to close. It
+refuses (exit 4, nothing killed) when the agent changed since the
+preview: a task claimed or released, a respawn under the same name.
+Another `mu` closing or spawning the same name makes it exit 4 too
+(`AgentLockBusyError`; nothing was done, retry). If the agent was
+replaced while the close was running, the replacement is left alone
+(`AgentReplacedError`).
+
+Close kills the pane and deletes the agent row. It is also the step
+for a non-pi agent, which has no socket to abort through. To prevent a
+worker stuck on an unbounded `find /` or a busy-wait loop, scope worker
+prompts to the worktree. Do not ask for filesystem-wide `find` or
+`grep -r /`. A clean worktree is removed with it, and unmerged commits
+are kept on a new branch `mu/<workstream>/<agent>-<sha>` that the close
+prints. If the worktree has uncommitted edits, close refuses with exit 4
+before it kills the pane, and the preview offers no apply command. Then
+do one of these:
+
+- Commit the edits in the worktree (`git -C <cwd> add -A && git -C <cwd>
+  commit`), then preview and close again.
+- Preview with `--discard` (`mu agent close worker-1 -w auth --discard`),
+  then apply it with `--if <n>` to drop the edits in one step. You lose
+  them, and no branch is made.
 
 If the worker owned a task, its pane is gone, so the reaper returns
-the task to `OPEN` on the next reconcile. A `mu task wait` on that task
+the task to `OPEN` on the next reconcile. A `mu wait` on that task
 exits 6.

package/docs/guide/sync.md

@@ -18,12 +18,20 @@ mu task add auth_fix -w app -t "Fix the auth redirect" -i 80 -e 2
 mu task close auth_fix -w app --evidence "shipped in #412"
 ```
 
+## Keep 3.x out of the sync folder
+
+4.0 writes v2 segments, which 3.x warns about on every command. So 4.0
+refuses a `MU_SYNC_DIR` where any segment opens with a v1 line (exit 4,
+nothing read or written): `MU_SYNC_DIR holds 3.x segments; give mu 4
+its own dir`. Point it at a new folder.
+
 ## Keep the DB out of the sync folder
 
 Never put `MU_DB_PATH` inside `MU_SYNC_DIR`. A live SQLite DB is three
 files (`mu.db`, `-wal`, `-shm`). A file syncer copies them out of
 order and can bring back a stale `-wal`, which corrupts the DB with no
-error. `mu doctor` fails the `db-vs-sync` row when you do this.
+error. Every `mu` verb refuses to run (exit 4, before it opens or
+writes anything) when the DB path is inside `MU_SYNC_DIR`.
 
 Also keep the DB off NFS, SMB, and sshfs. `mu doctor` warns in the
 `db-filesystem` row.
@@ -60,7 +68,7 @@ it, and `behind`: lines you hold but have not applied. A non-zero
 
 ```bash
 mu sync --repair c8ec                              # re-read a peer's file from the start
-mu sync --from /mnt/devserver/.local/state/mu/mu.db # read a peer's DB directly
+mu sync --from /mnt/devserver/.local/state/mu-next/mu.db # read a peer's DB directly
 MU_SYNC_DIR=/media/usb-stick mu state              # one-off folder
 ```
 
@@ -68,7 +76,7 @@ Ingest is idempotent, so `--repair` is safe at any time.
 
 ## Know what travels
 
-Workstreams, tasks, edges, and notes travel. Agents and workspaces
+Workstreams, tasks, edges, and notes travel. Agents and worktrees
 stay on their machine, because a pane id and a local path mean nothing
 elsewhere. So task ownership does not sync: a task claimed on the
 devserver shows no owner on your laptop.

package/docs/guide/upgrade.md

@@ -1,25 +1,43 @@
 # How to upgrade mu
 
+Coming from 3.x? Read [Upgrade from 3.x to 4.0](#upgrade-from-3x-to-40)
+first: `npm i -g @mu-crew/mu@latest` replaces your 3.x `mu`.
+
 ## Upgrade the package
 
 ```bash
 npm i -g @mu-crew/mu@latest
-mu link pi
+pi update --extensions    # only if the package is already registered in pi
 mu doctor
 ```
 
-`mu link pi` installs a one-line shim at
-`~/.pi/agent/extensions/mu.ts` that loads the installed extension, and
-links `~/.agents/skills/mu` to the package's skill. Later upgrades
-update both with no relink. `MU_PI_HOME` changes the home directory
-that both paths start from.
+pi loads mu as a package: one extension, one skill, and the recipe
+prompts, all from the declared `pi` manifest. There is no relink step.
+
+### Coming from the old `link pi` install
+
+Before the package, the old `link pi` verb wrote a shim at
+`~/.pi/agent/extensions/mu.ts` and a skill link at
+`~/.agents/skills/mu`. `pi update` registers nothing for that install,
+and a shim left in place loads a second copy of the extension next to
+the package. In this order:
+
+```bash
+npm i -g @mu-crew/mu@latest
+pi install npm:@mu-crew/mu    # once: registers the package
+mu pi migrate                 # report only
+mu pi migrate --apply         # move mu-owned files aside; nothing is deleted
+```
+
+Then restart pi agents or send them `/reload`.
 
-- `--copy` copies the extension instead of the shim. You then have to
-  relink after every upgrade.
-- `--force` replaces an extension or skill symlink that points
-  elsewhere, such as a dev checkout. mu replaces the link, never its
-  target, and never replaces a real skill directory (exit 4).
-- `--extension-only` and `--skill-only` install one part.
+Only a file mu can prove it generated is moved, into a `disabled/`
+folder pi does not read: a file byte for byte equal to the shim `link pi` generated (only its
+generated import URL may differ), or a skill
+link into this install's `skills/mu` (or a skill copy identical to a
+released one). Anything else (your own `mu.ts`, an edited copy, a link
+to somewhere else, even one named `mu`) is reported with its path and
+left for you. `MU_PI_HOME` changes the home directory both start from.
 
 For agents other than pi, see [README § Install](../../README.md#install).
 
@@ -29,46 +47,78 @@ A running pi keeps the extension it loaded at start. After an upgrade,
 send `/reload` to each agent, or respawn the agent. From a shell:
 
 ```bash
-mu agent send worker-1 -w auth '/reload'             # extension serves op command
-mu agent send worker-1 -w auth '/reload' --via mux   # older extension
+mu agent send worker-1 -w auth '/reload'   # extension serves op command; older: respawn
 ```
 
 Until then, the `ctl` row of `mu doctor` warns
 `extension X older than installed Y` or `extension lacks ops`. Ops the old extension lacks,
 such as `send --fresh`, fail with exit 4.
 
-## Upgrade from 3.1 or earlier
-
-Before 3.2.0, mu pasted text into pi panes. Now it sends through a
-control socket. Agents started before `mu link pi` have no socket, so
-sends to them fail with `ctl missing` instead of pasting. Restart those
-agents, or force the old path with `--via mux`.
+An agent started before the pi package was installed has no control
+socket, so a send to it fails with `ctl missing`. Restart it.
+
+## Upgrade from 3.x to 4.0
+
+4.0 is a breaking release with its own DB. It does not import a 3.x DB,
+and nothing converts one. 3.x keeps its state in `~/.local/state/mu`
+(`$XDG_STATE_HOME/mu`); 4.0 keeps its state in `~/.local/state/mu-next`
+(`$XDG_STATE_HOME/mu-next`), a name kept so the two never share a DB,
+socket or worktree. The release notes list every breaking change:
+[CHANGELOG](../../CHANGELOG.md).
+
+There is no flag day. Each machine switches when its human decides:
+
+1. Close the 3.x agents you no longer need (`mu agent close`); 4.0 cannot
+   see them.
+2. If you still need the old DB, [keep 3.x runnable](#keep-3x-runnable)
+   before you install: `npm i -g @mu-crew/mu@latest` replaces the `mu` on
+   your `PATH`.
+3. Install 4.0 as above (`npm i -g @mu-crew/mu@latest`, `pi install`,
+   `mu pi migrate --apply`). `mu --version` should print `4.x`.
+4. Give 4.0 its own sync folder, or none. Sync stays off until you set
+   `MU_SYNC_DIR`. If any segment in the folder opens with a 3.x (v1)
+   line, every 4.0 verb exits 4 with `MU_SYNC_DIR holds 3.x segments;
+   give mu 4 its own dir` before it reads or writes anything. Unset
+   or change `MU_SYNC_DIR` in a shell that also runs 3.x.
+5. Move workstreams one at a time, from the machine that holds each one,
+   with the [Move recipe](../../skills/mu/recipes/move.md). Only open
+   tasks move; owners, agents and history stay in the 3.x DB, an archive.
+   The recipe's one 3.x write is the last step: it parks each moved task
+   with `--why "moved to 4.0"`, so nobody works it twice.
+
+Rollback: `pi remove npm:@mu-crew/mu`, `npm i -g @mu-crew/mu@3`, then
+3.x's `link pi` to relink its shim. Nothing needs converting. For each
+moved workstream, run `mu task unpark <id> -w <ws>` on 3.x per task. Work
+done in 4.0 since the move stays in 4.0's DB.
+
+## Keep 3.x runnable
+
+`npm i -g @mu-crew/mu@latest` replaces the `mu` on your `PATH`, so the
+Move recipe needs 3.x from somewhere else. Install it into its own
+prefix, or run it once with npx:
 
-## Migrate an old DB
+```bash
+npm i --prefix ~/.local/share/mu3 @mu-crew/mu@3.13.3
+~/.local/share/mu3/node_modules/.bin/mu --version   # 3.13.3
 
-mu refuses a DB older than schema v11 with `SchemaTooOldError`, and a
-newer one with `SchemaTooNewError`. Both exit 4 and leave the file
-alone. `scripts/migrate.ts` converts a v7, v8, v9, or v10 DB into a new
-v11 file. It never writes in place.
+npx -y @mu-crew/mu@3.13.3 --version                # no install; slower to start
+```
 
-The npm package does not ship `scripts/` or `src/`, so run the recipe
-from a git checkout of mu at the version you upgraded to (`npm install`
-there first; `npx tsx` fetches tsx on first use).
+Use that path, or the `npx` command, as `<mu3>` in the recipe. 3.x reads its own state dir, so
+it finds the old DB with no flags. Use it to read the archive and to park
+moved tasks, not for new work: `mu pi migrate --apply` moved aside the
+shim 3.x's pi agents load. A harness that runs `mu` through your shell rc
+may pick the wrong one; see
+[Pin the mu the harness runs](other-agent-clis.md#pin-the-mu-the-harness-runs).
 
-```bash
-git clone --branch "v$(mu --version)" https://github.com/mu-crew/mu && cd mu && npm install
-DB=${MU_DB_PATH:-$HOME/.local/state/mu/mu.db}
-BACKUP="$HOME/mu-old-backup-$(date +%Y%m%d-%H%M%S).db"
-sqlite3 "$DB" ".backup '$BACKUP'"
-npx tsx scripts/migrate.ts "$BACKUP" --out "${DB}.v11"
-MU_DB_PATH="${DB}.v11" mu doctor --deep
-mv "$DB" "${DB}.old-kept" && mv "${DB}.v11" "$DB"
-mu doctor
-```
+## Old DBs
 
-Legacy `REJECTED` tasks become `CLOSED/rejected`, and `DEFERRED` tasks
-become `OPEN/parked`. Flags and the rules for what carries over are in
-[scripts/README.md](../../scripts/README.md).
+A v13 DB missing a later addition is completed on its first open, in one
+transaction: it either completes or leaves the file as it was. mu
+refuses a DB older than v13 with `SchemaTooOldError`, and a newer one
+with `SchemaTooNewError`. Both exit 4 and leave the file alone, so
+pointing 4.0 at a 3.x DB (`MU_DB_PATH`) is safe. Back up an old DB and
+move it aside.
 
 ## Run mu from a checkout
 
@@ -78,5 +128,5 @@ alias mu="node $PWD/dist/cli.js"
 ```
 
 Or run `npm install -g .` in the checkout. Its `prepare` script builds
-first. Run `mu link pi --force` to point the skill link at the
-checkout.
+first. To load the checkout as the pi package instead of the installed
+one, run `pi install /path/to/checkout`.

package/docs/reference/env.md

@@ -10,11 +10,10 @@ milliseconds; `0` disables a wait unless noted.
 | Name | Effect | Default |
 | --- | --- | --- |
 | `MU_DB_PATH` | SQLite file path. Wins over the state dir. | `<state-dir>/mu.db` |
-| `MU_STATE_DIR` | State directory. Also holds `compile-cache/` (V8 code cache for the CLI; `NODE_DISABLE_COMPILE_CACHE=1` turns it off). | `$XDG_STATE_HOME/mu` |
-| `XDG_STATE_HOME` | XDG state base; mu appends `mu/`. An empty or relative value is ignored. | `~/.local/state` |
+| `MU_STATE_DIR` | State directory. Also holds `compile-cache/` (V8 code cache for the CLI; `NODE_DISABLE_COMPILE_CACHE=1` turns it off). | `$XDG_STATE_HOME/mu-next` |
+| `XDG_STATE_HOME` | XDG state base; mu appends `mu-next/` (3.x owns `mu/`, so the two builds never share a DB). An empty or relative value is ignored. | `~/.local/state` |
 | `XDG_CACHE_HOME` | XDG cache base; mu appends `mu/`. Holds only disposable copies. An empty or relative value is ignored. | `~/.cache` |
-| `MU_SESSION` | Active workstream when `-w` is absent. Beats `MU_WORKSTREAM`. | current `mu-<name>` mux session |
-| `MU_SYNC_DIR` | Folder holding one segment per machine. This is the whole sync setup; there is no peer list. | unset: sync off |
+| `MU_SYNC_DIR` | Folder holding one segment per machine. This is the whole sync setup; there is no peer list. 4.0 refuses (exit 4, nothing read or written) a folder holding a segment that opens with a v1 line, i.e. a 3.x peer: give it its own folder. | unset: sync off |
 
 ## Multiplexer
 
@@ -22,12 +21,11 @@ milliseconds; `0` disables a wait unless noted.
 | --- | --- | --- |
 | `MU_MUX` | Force `tmux` or `herdr`, skipping mux detection. An unknown value fails the invocation. | detected |
 | `HERDR_ENV` | Read only. `1` (set by herdr in its panes) selects herdr; outranks `$TMUX`. | |
-| `TMUX`, `TMUX_PANE` | Read only. Either one (set by tmux in its panes) selects tmux. `$TMUX` gates reading the current session name, which resolves the workstream when `-w` and `MU_SESSION` are absent. `$TMUX_PANE` identifies the calling agent (`mu me`, `mu log`, task claim errors). | |
+| `TMUX`, `TMUX_PANE` | Read only. Either one (set by tmux in its panes) selects tmux. `$TMUX` gates reading the current session name, used only as the suggestion in the missing-`-w` error: it never routes a verb. `mu me` / `mu state --me` never read `$TMUX_PANE` (identity is the injected `MU_AGENT_NAME` or `PI_SESSION_ID`); only `mu task list --mine` and a few older self-readers still fall back to it when no `MU_AGENT_NAME` is injected. | |
 | `HERDR_WORKSPACE_ID` | Read only. Set by herdr in its panes; pane listing with no target reads this workspace first. | |
-| `HERDR_PANE_ID` | Read only. Set by herdr in its panes; fallback rung of actor identity after `MU_AGENT_NAME`. | |
-| `MU_TMUX_SOCKET` | Test isolation. Runs every tmux call on a private server (`-L <name>`) with `-f /dev/null`, so `~/.tmux.conf` is not loaded. tmux only. | unset: tmux's default server |
+| `HERDR_PANE_ID` | Read only. Set by herdr in its panes. | |
+| `MU_TMUX_SOCKET` | Run every tmux call on a private server (`-L <name>`) with `-f /dev/null`, so `~/.tmux.conf` is not loaded. The test suite uses it, and so can you to keep a crew off your own tmux server (a demo, a smoke test). Attach lines mu prints then carry `-L <name>`, and the dashboard's `a` nests a client on purpose when you are inside another tmux. tmux only. | unset: tmux's default server |
 | `MU_HERDR_SESSION` | Named herdr server (`--session <name>`). herdr only. Tests must set it to a non-default name. | herdr default session |
-| `MU_BANNER_QUIET` | `1` disables mu's pane border and banner decorations. tmux only. | unset |
 
 ## Spawn
 
@@ -37,16 +35,7 @@ milliseconds; `0` disables a wait unless noted.
 | `MU_SPAWN_CTL_MS` | Budget for the control-socket handshake with a new pi agent, polled every 250ms. On timeout spawn still exits 0, reports `ctl: missing` or `ctl: refused`, and warns. `--no-ctl` skips it per spawn. | `30000` |
 | `MU_SPAWN_LIVENESS_MS` | tmux only. Wait this long, then check the pane is alive and its scrollback has no startup error (auth failure, `command not found`). Failure rolls back the row and throws `AgentDiedOnSpawnError` or `AgentSpawnStartupError`. A pi agent skips the wait: the pane is checked on each ctl handshake tick and scanned when it ends. | `1500` |
 | `MU_SPAWN_LOCK_TIMEOUT_MS` | How long a spawn waits for the per-workstream spawn lock. | `15000` |
-
-## Send and state (tmux path)
-
-These apply to the tmux paste path only. For when that path runs, see
-[No silent fallback](../architecture/control-socket.md#no-silent-fallback).
-
-| Name | Effect | Default |
-| --- | --- | --- |
-| `MU_SEND_READINESS_MS` | Before pasting, wait out a pane's modal or re-init; after Enter, confirm it landed. `0` sends fire-and-forget. A busy pane is not waited on. | `15000` |
-| `MU_SEND_DELAY_MS` | Delay between the bracketed paste and Enter. | `500` |
+| `MU_AGENT_LOCK_TIMEOUT_MS` | How long `agent close` and `--worktree` staging wait for the per-agent lock before exit 4 (`AgentLockBusyError`, nothing done). | `15000` |
 
 ## Agents and timing
 
@@ -60,36 +49,38 @@ These apply to the tmux paste path only. For when that path runs, see
 | Name | Value |
 | --- | --- |
 | `MU_AGENT_NAME` | The agent's name; first rung of actor identity. |
-| `MU_WORKSTREAM` | The agent's workstream. With `MU_MANAGED_AGENT=1` it also resolves the workstream when `-w` and `MU_SESSION` are absent (no tmux lookup); without it, ignored. |
+| `MU_WORKSTREAM` | The agent's workstream. With `MU_MANAGED_AGENT=1` it is the scope of every verb that has no `-w` (no tmux lookup); without it, ignored. `MU_SESSION` is not read: a verb with no `-w` and no injected scope fails with `no workstream: pass -w <name>`. |
 | `MU_CTL_SOCK` | The agent's control socket path, derived from state dir, workstream, and agent. The mu pi extension serves it. |
 | `MU_MANAGED_AGENT` | `1`. Hides `mu_delegate` inside agents, so a helper cannot spawn helpers. |
+| `MU_DB_PATH`, `MU_STATE_DIR` | The absolute DB path and state dir the spawn used, so the worker's `mu` reads the same DB from any cwd. Local agents only. |
+| `SSH_AUTH_SOCK` | The caller's, when it is a socket (a detached tmux session would otherwise hand the pane a stale one). Local agents only. |
+| `MU_REMOTE` | `1`, only for an agent spawned with `--host`. Tells its pi extension there is no mu DB on that host: it skips the close nudge (you close the task) and the settle wait. |
 
-`mu agent remote-env <agent> --shell` prints `MU_SSH_ARGS` (the ssh
-socket forward) and `MU_REMOTE_ENV` (the four vars above) for a remote
-pi agent's `--command`. mu never reads them back.
+A `--host` agent gets exactly `MU_MANAGED_AGENT`, `MU_AGENT_NAME`,
+`MU_WORKSTREAM`, `MU_CTL_SOCK` (the host-side path) and `MU_REMOTE`, written
+into its profile's shell template (`{env}`). It never gets `MU_DB_PATH`,
+`MU_STATE_DIR` or `MU_SYNC_DIR`; its local pane gets none of the vars above.
 
-## pi extension and `mu link pi`
+## pi package and `mu pi migrate`
 
 | Name | Effect | Default |
 | --- | --- | --- |
 | `MU_DELEGATE` | `0` hides the `mu_delegate` tool. `mu doctor` reports it. | unset: shown |
-| `MU_DELEGATE_MAX` | Most delegates one pi session runs at once. Further calls queue, up to four times this; past that `mu_delegate` refuses. A positive integer. | `16` |
-| `MU_NUDGE` | `0` turns off the three nudges: the keep-driving nudge (one reminder when an orchestrator ends a turn with dispatched work still IN_PROGRESS), the close nudge (one reminder when a mu-spawned pi worker ends a turn still owning an IN_PROGRESS task), and the refute nudge (one notice when an orchestrator dispatched a task whose notes hold no `REFUTER`, `VERDICT:` or `REFUTE-EXEMPT:` line). A pi nested in an agent's pane (it found `MU_CTL_SOCK` served by another pi) gets none of them; a pi without UI (`pi -p`, json mode) gets no close or refute nudge. `mu doctor` reports it. | unset: on |
-| `MU_PI_HOME` | Root under which `mu link pi` writes `.pi/` and `.agents/`. | `$HOME` |
+| `MU_DELEGATE_TRACE` | `1` appends one JSON line per delegate wake send and pi lifecycle event to `<cache dir>/delegate-trace.log`. For debugging a lost wake. | unset: off |
+| `MU_DELEGATE_MAX` | Most delegates one pi session runs at once. Further calls queue, up to four times this; past that a call is recorded as `refused` and reissued with `mu_delegate_reissue` in its session. A positive integer. | `16` |
+| `MU_NUDGE` | `0` turns off the two nudges: the keep-driving settle wait (every completed settle of an orchestrator runs `mu wait` for the work it owns and continues the turn on an event) and the close nudge (one reminder when a mu-spawned pi worker ends a turn still owning an IN_PROGRESS task). A pi nested in an agent's pane (it found `MU_CTL_SOCK` served by another pi) gets neither; a pi without UI (`pi -p`, json mode) gets no close nudge. `mu doctor` reports it. | unset: on |
+| `MU_PI_HOME` | Root under which `mu pi migrate` looks for the old `.pi/` shim and `.agents/` skill link. | `$HOME` |
+| `PI_SESSION_ID` | Read only. The pi session's id: the caller identity `pi:<id>` of `mu_delegate` calls, a bare `mu wait`, `mu me` and `mu next --refute` when no managed agent is injected. | |
 | `PI_CODING_AGENT_DIR` | Read only. pi's agent dir, checked for a linked murmur extension. | `~/.pi/agent` |
-| `MU_EXTENSION_ENTRY` | Test only. Built extension the `mu link pi` shim imports. | `dist/extension/mu-pi.js` |
 
-## Output and TUI
+## Output
 
 | Name | Effect | Default |
 | --- | --- | --- |
 | `NO_COLOR` | Any value turns colour off; wins over everything. | unset |
 | `MU_FORCE_COLOR` | Truthy forces colour on. `""`, `0`, and `false` opt out. Checked before `FORCE_COLOR`. | unset |
-| `MU_NO_TUI` | `1` makes bare `mu` print help instead of opening the TUI. | unset |
-| `MU_TUI_DEBUG_MOUSE` | `1` logs mouse hit-tests to stderr. | unset |
-| `NODE_ENV` | Unset: the TUI loads React's production build. Set it (e.g. `development`) to get React's dev build and warnings. | unset |
 
 ## Tests
 
-`VITEST` or `NODE_ENV=test` makes `openDb()` refuse the real default DB.
+`VITEST` or `NODE_ENV=test` makes `openDb()` refuse the real default DB. The dashboard sets `NODE_ENV=production` for itself when it is unset, to get React's production build.
 `test/_setup.ts` clears inherited `MU_*` vars except `MU_TMUX_SOCKET`.