@mu-crew/mu 3.2.0 → 3.2.1

package/docs/architecture/sdk.md

@@ -0,0 +1,185 @@
+# CLI and SDK surface
+
+Every user-visible operation is a typed SDK function plus a thin
+Commander wrapper. This page covers the boundary rules, errors, tests
+and packaging. Overview: [ARCHITECTURE.md](../ARCHITECTURE.md).
+
+## One surface, two callers
+
+`src/cli.ts` (`buildProgram`) and the namespace files under `src/cli/`
+are the verb surface: no generated registry, no DSL, no separate
+operation schema. Programmatic callers import the same functions from
+`src/index.ts`. Agents and scripts compose verbs with `--json`.
+
+A verb's path:
+
+1. The Commander block calls a `cmd<Verb>` wrapped in `handle()`.
+2. `handle()` opens the DB, runs ambient sync ingest
+   ([sync.md](sync.md#the-ambient-hook)), and calls the SDK function.
+3. The SDK function opens `db.transaction(fn)()` for multi-statement
+   writes. Agent ops call the mux (and jj, sl or git for workspaces);
+   task ops are pure SQL. Read paths reconcile against the mux.
+4. Capture triggers record ops in the same transaction
+   ([ops-log.md](ops-log.md)). Machine-local changes go through
+   `emitEvent`. `mu log --tail` sees them on its next 1-second poll.
+5. On error the transaction rolls back and the typed error reaches
+   `handle()`, which maps it to an exit code. Flush runs on both paths.
+
+Output is self-documenting: `src/output.ts` (`printNextSteps`,
+`errorNextSteps`) prints `Next:` hints, quoted by `src/shell-quote.ts`
+so they paste cleanly.
+
+## Surrogate-PK and SDK-boundary discipline
+
+Every entity table has this shape:
+
+```
+(
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,   -- surrogate; internal
+  <scope_id>    INTEGER NOT NULL REFERENCES <parent>(id) ON DELETE CASCADE,
+  <name>        TEXT NOT NULL,                        -- operator-facing; mutable
+  -- ... domain attributes
+  UNIQUE (<scope_id>, <name>)                         -- per-scope unique
+)
+```
+
+FKs reference `<parent>_id` (INTEGER), never the TEXT name. The name is
+an attribute: searchable, displayable, cheap to rename. The surrogate
+id is the identity.
+
+**TEXT by design:**
+
+- the workstream's own `name` (it is the mux session name; globally
+  unique);
+- `task_notes.author` and `ops.actor` (free-text labels such as
+  `"orchestrator"`);
+- `ops.entity` (open enum; a new entity needs no migration);
+- `agents.cli` (a new CLI needs no schema change);
+- every column of `ops`. The log is FK-free and addresses rows by
+  natural key, so an op outlives its row and its workstream.
+
+**The boundary rule** matches REST: the external API uses business
+identifiers, the internal layer uses primary keys.
+
+> **Public SDK functions take operator-facing names.**
+> **Internal helpers take surrogate ids.**
+> **Resolution happens at the public-function entry, exactly once.**
+
+```ts
+// PUBLIC: takes operator-facing names
+export function claimTask(
+  db: Db,
+  workstream: string,
+  localId: string,
+  opts?: ClaimOptions,
+): ClaimResult {
+  const wsId = resolveWorkstreamId(db, workstream);
+  const taskId = tryResolveTaskId(db, wsId, localId);
+  if (taskId === null) throw new TaskNotFoundError(localId);
+  const agentId = resolveCurrentAgentId(db, wsId);
+  return claimTaskById(db, taskId, agentId, opts);
+}
+
+// INTERNAL: takes surrogate ids; never re-resolves
+function claimTaskById(db, taskId, agentId, opts): ClaimResult { ... }
+```
+
+Resolving once gives three things: no double resolution; no
+workstream context needed below the boundary, because the FKs make
+scope implicit; and one place for error mapping.
+`WorkstreamNotFoundError` comes from `resolveWorkstreamId` in
+`src/db.ts`. `TaskNotFoundError` and `AgentNotFoundError` are raised by
+callers wrapping a `tryResolve*` null, so exit 3 holds whichever lookup
+missed.
+
+**Workstream scoping is mandatory at the CLI boundary.** TEXT names
+(`tasks.local_id`, `agents.name`) are unique per workstream, so the
+same name can exist in two. Every public function taking such a name
+also takes the workstream; internal SQL filters by
+`(workstream_id, name)`.
+
+**`--json` keeps operator-facing names.** Surrogate ids never appear in
+`--json`, error payloads, log lines or exports. Exposing them would
+bring back a global namespace.
+
+## State of truth
+
+- The DB (`~/.local/state/mu/mu.db`, or `MU_DB_PATH`) is canonical.
+  Everything else is a cache, including pane titles.
+- Writes go through the typed SDK functions, which validate, transact
+  and reconcile. Op capture is the triggers' job.
+- In-memory state lives only for one command's connection.
+- Multiple `mu` processes share the file safely through SQLite WAL.
+
+## Errors
+
+Errors are typed classes per layer (`src/agents/errors.ts`,
+`src/tasks/errors.ts`, `MuxError` with `TmuxError` / `HerdrError`, and
+so on). Nothing swallows them. `src/cli/handle.ts` maps them to exit
+codes:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | success |
+| 1 | generic error |
+| 2 | usage error (Commander's default) |
+| 3 | not found (agent, task, workspace) |
+| 4 | conflict (name collision, double claim, dirty tree, schema too old or new, outdated extension) |
+| 5 | substrate unavailable (no multiplexer, DB locked) |
+
+Errors carry structured context (operation, target, attempted action)
+so `mu doctor` can show them readably.
+
+## Testing layers
+
+Fast tier (`npm run test:fast`) excludes `*.integration.test.ts` and
+`*.smoke.test.ts`. It uses real SQLite in per-test temp DBs and a
+mocked mux (`installMux()` from `test/_mux.ts`). Integration tests use
+real tmux or herdr, and real git, jj or sl in `os.tmpdir()`; jj and sl
+tests skip when the binary is missing. Conventions live in
+[AGENTS.md](../../AGENTS.md) and `test/README.md`.
+
+| Area | What the tests pin |
+| --- | --- |
+| `src/capture.ts`, `src/op-context.ts` | payloads hold only changed columns (asserted by key count); echo suppression; cascade grouping; FK-CASCADE tombstone keys; the null-intent fail-safe |
+| `src/apply.ts` | injected HLCs, no sleeps: field convergence in both orders; same-field LWW determinism; all four put and del orderings; resurrection; grow-only notes; the set-to-NULL trap; `owner_id` stripping; replay idempotence |
+| `src/rebuild.ts` | round trip row by row per portable table (a count-only check passes on a garbage rebuild); tombstones; byte-identical ops; `machine_id` and clock carried |
+| `src/drift.ts`, `src/fleet-hazards.ts` | drift planted the way a capture bug would (`withCaptureSuppressed` plus a direct write), with equal weight on false positives |
+| `src/dormant.ts` | `updated_at` written directly; weighted to the boundary between `finished` and `abandoned` |
+| `src/disk-recon.ts` | a per-test `MU_STATE_DIR` with the on-disk shape built by hand, both directions |
+| `src/segments.ts`, `src/sync.ts` | two temp DBs and one shared dir; each robustness layer; machine-local ops never reaching a file |
+| `src/hlc.ts` | an injected clock: backward jumps, stalled milliseconds, concurrent minting |
+| `sync-session.integration` | 8 rounds of two machines: byte-identical portable content, no `--deep` drift, a quiet round adds zero ops |
+| `test/acceptance.integration.test.ts` | the end-to-end gate: 10 tasks, 3 agents |
+
+`npm run test:stress` repeats the suite with per-run timeouts,
+optionally in parallel (`MU_TEST_STRESS_MODE=parallel`).
+
+Two fixture traps:
+
+- A convergence fixture must share one creation op. Two independent
+  `task add` calls for the same id make the later creation win every
+  field.
+- An ordering-sensitive sync test must rename segments to pin ingest
+  order, since peers are discovered by `localeCompare` over random-UUID
+  filenames.
+
+Treat a test that passes alone and fails under load as a concurrency
+bug first. Drive wait and reaper tests from poll-loop seams, not fixed
+timers, and wait for stable Ink output instead of sleeping.
+
+## Distribution
+
+One npm package, `mu`. `tsup` bundles three entries:
+
+| Output | Role |
+| --- | --- |
+| `dist/cli.js` | `bin: { mu: ./dist/cli.js }` |
+| `dist/index.js`, `dist/index.d.ts` | SDK and types |
+| `dist/extension/mu-pi.js` | the pi extension `mu link pi` points at |
+
+`skills/` and `docs/` ship alongside. There is no build step on the user's
+machine. pi stays a peer dependency: the extension types pi's API
+structurally. Per-role agent guidance lives in the user's repo, not in
+mu. The rule for adding a dependency is in
+[ROADMAP § Anti-feature pledges](../ROADMAP.md#anti-feature-pledges).

package/docs/architecture/sync.md

@@ -0,0 +1,129 @@
+# Sync
+
+Machines share a workstream by exchanging ops through a shared folder
+(`MU_SYNC_DIR`) kept in step by any folder syncer, such as Syncthing. The ops
+themselves are described in [ops-log.md](ops-log.md). Overview:
+[ARCHITECTURE.md](../ARCHITECTURE.md). Why segments and not
+Litestream, cr-sqlite or a peer list, and why the DB must never sit in
+`MU_SYNC_DIR`:
+[ROADMAP § Rejected sync substrates](../ROADMAP.md#rejected-sync-substrates).
+
+## Segments
+
+`src/segments.ts` is the transport.
+
+- `flushSegment` appends this machine's unflushed ops to
+  `<MU_SYNC_DIR>/<machine_id>.jsonl`.
+- `ingestSegment` reads a peer segment from its watermark into
+  `applyOp`.
+- Peer discovery is implicit: every non-self `*.jsonl` is a peer. A
+  peer disappears only when its segment is deleted.
+
+**Single writer per file.** A machine appends only to its own segment,
+so nothing is contended and any folder syncer is adequate. Segments
+are regenerable, so there is no fsync. `src/file-lock.ts` stops two
+local `mu` processes from interleaving partial lines.
+
+**Only `SYNCED_ENTITIES` and only this machine's ops are flushed.**
+Pane ids and absolute paths never leave the machine, and peers never
+echo each other's history.
+
+**Payload encoding.** `ops.payload` is TEXT that is usually JSON, but
+`mu log "text"` writes prose. The encoder passes valid JSON through
+verbatim, so the crc covers those exact bytes, and JSON-encodes
+anything else, unwrapping on ingest.
+
+## Robustness layers
+
+Four checks stop ingest at the first bad record and advance the
+watermark only that far:
+
+| Layer | Catches |
+| --- | --- |
+| `JSON.parse` | a torn write (line lacks its trailing `,"crc"…}` framing) or a malformed shape (framing present). Same failure, different remediation: a cut transfer vs a writer bug |
+| crc32 per line | bit rot |
+| monotonic HLC | reorder, duplicate, truncation |
+| `.manifest` sidecar | truncation exactly on a line boundary |
+
+**Damage halts; refusal skips.** Halting is right for damage, where a
+gap looks the same as reordering. It is wrong for a well-formed line
+mu declines to project: a refusal leaves no hole, and halting would
+freeze the peer's watermark for good, since `mu sync --repair` only
+resets the watermark and re-reads into the same line. Ingest
+distinguishes three cases:
+
+| Line | Result |
+| --- | --- |
+| damaged | halt |
+| a known machine-local entity | reported defect, skipped |
+| an unrecognised entity | applied as a no-op, no defect (a reader behind the writer is normal in a mixed fleet) |
+
+`mu sync` suggests `--repair` only for defects a re-read can clear.
+
+**Sync never fails a command.** A truncated segment, a garbage segment,
+a sync dir that is a file, or a vanished directory warns on stderr and
+returns.
+
+## The ambient hook
+
+Sync is ambient, not a daemon: no watcher, no background process, no
+poll outliving a command. It happens because you already run `mu`
+constantly.
+
+The seam is `handle()` (`src/cli/handle.ts`), which every verb passes
+through and which is already async. `syncPass` is async because it
+takes the file lock, while most verb bodies are synchronous
+better-sqlite3 code. One `await` before `fn(db)` and one after cover
+every verb.
+
+- **Ingest before the body**, so the verb reads the freshest state.
+- **Flush after the body**, so this invocation's ops reach the segment
+  now.
+- **Flush on the error path too.** A verb may commit ops before
+  throwing. Those ops are canonical, so withholding them would make
+  this machine's history depend on the exit code.
+
+`src/sync.ts` holds `ambientIngest`, `ambientFlush`, `ambientSyncPass`,
+`peerStatuses`, `ingestFromDb` (`mu sync --from <path>`) and
+`repairPeer` (`mu sync --repair <peer>`, a unique prefix; ambiguity is
+exit 4).
+
+### Carve-outs
+
+| Surface | Behaviour | Why |
+| --- | --- | --- |
+| `MU_SYNC_DIR` unset | one `if` on one env var; no filesystem touch | the single-machine case pays nothing (measured: baseline; about 3ms with one peer) |
+| `mu sql` | opts out (`handle(..., { ambientSync: false })`) | an ingest changing a row count mid-inspection reads as a mu bug |
+| `mu sync` | opts out and runs the pass itself | otherwise the report prints "ingested 0" right after ingesting |
+| the TUI | slow tick only (10s), one pass per beat across tabs, `quiet: true` | the fast tick can go to 100ms; the TUI owns the screen, so problems show on the Doctor card |
+
+## Out-of-order arrival
+
+An `edge` or `note` put whose task has not arrived yet skips as
+`absent`, correctly. Ingest still advances the watermark past it, so
+without a second pass it would never land. Peers are discovered by
+`localeCompare` over random-UUID filenames, so the arrival order is a
+coin flip per fleet.
+
+`reprojectDeferredOps` (`src/apply.ts`) re-queries the log for note and
+edge puts that are resolvable now but unprojected. It skips ops whose
+parent task is gone and keys with a newer `del`, so a deleted edge is
+never resurrected and an orphan is not retried forever. It runs once
+per ingest pass, not per peer, because an edge in one segment may name
+a task in another. On a healthy DB it is two indexed queries returning
+zero rows.
+
+There is no retry queue. A queue would be a second source of truth and
+would not survive a short-lived `mu` process when the parent arrives
+days later.
+
+## Mixed-fleet hazards
+
+`src/fleet-hazards.ts` adds three checks to the default `mu doctor`,
+all no-ops when `MU_SYNC_DIR` is unset:
+
+| Check | Severity |
+| --- | --- |
+| `MU_DB_PATH` inside `MU_SYNC_DIR` | fail |
+| DB on a network mount | warn |
+| two workstream names differing only by case | warn |

package/docs/architecture/tui.md

@@ -0,0 +1,146 @@
+# TUI architecture
+
+The TUI is a read-only, live-updating dashboard of 10 cards on `ink`.
+It lives entirely under `src/cli/tui/`, the only place ink and react
+are imported (a [ROADMAP](../ROADMAP.md#anti-feature-pledges) pledge).
+CLI verbs stay the mutation API: the TUI yanks `mu` commands and the
+operator runs them. Overview: [ARCHITECTURE.md](../ARCHITECTURE.md).
+Press `?` in the TUI for the keymap.
+
+## Entry points
+
+- Bare `mu` launches the TUI when `process.stdout.isTTY` is true. It
+  loads every workstream and picks the initial tab with the focus
+  ladder in `src/cli/tui-launch-focus.ts`: `$MU_SESSION` → tmux session
+  name → cwd inside a workspace → cwd equal to a workspace's project
+  root (`src/project-root.ts`; latest activity breaks ties) → tab 0.
+  With no workstreams it prints `mu --help` plus
+  `Get started: mu workstream init <name>` and exits 0.
+- On non-TTY stdout (pipes, CI, most agent calls) bare `mu` prints help.
+  `MU_NO_TUI=1` forces that path inside a terminal.
+- `mu state` is the static card; `mu state --tui` selects the TUI.
+- The import stays dynamic (`await import("./cli/tui/index.js")`). A
+  static import of ink anywhere else would pull the TUI graph into the
+  help, version and `--json` paths.
+
+## Cluster shape
+
+| Files | Role |
+| --- | --- |
+| `index.ts`, `escapes.ts` | `runTui` entry; alt-screen and SGR mouse-mode lifecycle; pure escape bytes |
+| `app.tsx` | `<App>` root: popup state machine, global keymap, tabs, footer |
+| `state.ts` | `useDashboardSnapshot` poll loop (fast and slow tiers) |
+| `keys.ts`, `keymap-spec.ts`, `help.tsx` | pure key dispatch; the keymap source of truth that drives both dispatch and the `?`/F1 overlay |
+| `mouse.ts`, `use-popup-action-queue.ts` | vendored SGR mouse parser with double-click; one queued popup action per render |
+| `layout.ts`, `columns.ts`, `wrap-ansi.ts`, `use-terminal-size.ts` | responsive columns and row budgets; aligned clipping; ANSI-aware wrapping; resize hook |
+| `titled-box.tsx`, `popup-shell.tsx`, `list-row.tsx`, `padded-rows.tsx`, `status-bar.tsx`, `tab-strip*.ts(x)` | chrome primitives |
+| `format-helpers.ts`, `agent-display.ts` | shared formatters and agent-row display |
+| `use-popup-filter.tsx`, `use-status-filter.tsx`, `use-notes-drill.ts` | `/` filter; status (`o`/`i`/`c`) and substate (`p`/`w`) toggles; shared notes drill |
+| `yank.ts`, `tuicr.ts`, `lazygit.ts`, `tmux-attach.ts` | clipboard; the alt-screen handoffs |
+| `cards/*.tsx` | the 10 dashboard cards, plus `_placeholder.tsx` |
+| `popups/*.tsx` | one fullscreen popup per card, plus `dag.tsx` (`g`), `all-tasks.tsx` (`t`), the `task-list-popup.tsx` scaffold, `drill.tsx`, `task-detail.tsx`, `cursor-row.tsx`, `scroll.ts`, `viewport.ts`, `show-loader.ts` |
+
+## State machine
+
+`<App>` owns:
+
+- **Popup state:** `null` (dashboard) or one popup id. One popup at a
+  time; `Esc` or `q` returns to the dashboard.
+- **Card visibility:** toggled by `0`-`9`.
+- **Tick rate:** fast tick, 1s default, adjusted with `+` `-` `=` `0`.
+- **Active workstream tab:** `Tab` / `Shift-Tab` cycles when there are
+  two or more. A torn-down workstream keeps its tab position and
+  renders dimmed with strikethrough until the name is recreated. A
+  torn-down single workstream shows its normally hidden tab.
+- **Footer flash:** a transient status-bar message.
+
+Popups own their local state (cursor, filter, drill mode, local modes
+such as Workspaces' `list` / `commits` / `show`). They never mutate App
+state. They receive a read-only props bag: `snapshot`, `db`,
+`workstream`, `fastTickNonce`, `slowTickNonce`, `yank`, `onClose`,
+`onModeChange`, `onFilterEditingChange`, `onFooter`.
+
+## Polling tiers
+
+| Tier | Interval | Loader | Reads | Cost |
+| --- | --- | --- | --- | --- |
+| fast | 1s, adjustable | `loadWorkstreamSnapshotFast` | SQL only: tasks, tracks, workspace rows, recent events, workspace orphans | p50 < 1ms |
+| slow | 10s (`SLOW_TICK_MS`) | `loadWorkstreamSnapshotSlow` | subprocesses: agent liveness and state, workspace dirty status, recent commits, doctor summary | p50 hundreds of ms |
+
+`mergeSnapshotFastSlow` merges the last slow result into every fast
+render, so cards never flicker through loading. `r` / `F5` runs both
+tiers now. A tab switch clears the slow cache and fetches eagerly.
+`snapshotKey` returns the same `data` reference across no-op ticks, so
+React's diffing short-circuits. The slow tick also runs ambient sync
+([sync.md](sync.md#carve-outs)).
+
+## Render geometry
+
+`layout.ts`:
+
+- **Columns by width:** stacked below 120 columns, then 2 at 120, 3 at
+  180, 4 at 240. Stream cards (Commits, Activity log) trail; Commits
+  trails last.
+- **Row budgets:** each card has `min` / `max` / `chrome`. The allocator
+  distributes rows so a noisy list cannot crowd its siblings. Overflow
+  shows as `+N more · Shift+N` in the card's bottom border.
+- **Culling:** when even minimum budgets do not fit, cards drop by
+  priority (Doctor → Recent → Workspaces → …) and the screen shows
+  `+N cards hidden · resize taller`.
+
+`wrap-ansi.ts` wraps by visual width (`string-width`) and closes open
+SGR state on every exit path, so a fragment without a trailing
+`\x1b[0m` cannot bleed into ink chrome. Drill bodies are space-padded
+to the exact box width, or ink's `wrap="truncate"` ANSI miscount eats
+the right border.
+
+## Read-only, with handoffs
+
+Every popup row exposes one canonical `mu` command through `y`.
+`yank.ts` probes pbcopy, wl-copy, xclip, xsel and clip.exe, then falls
+back to OSC-52 over stderr.
+
+The handoffs leave the alt screen, disable mouse mode, run a
+foreground subprocess, and restore both on exit:
+
+- `t` in any `git show` drill runs `tuicr -r <sha>` in the project root
+  or workspace.
+- `l` in the Commits popup runs lazygit.
+- `a` in the Agents popup attaches to the agent's mux pane.
+
+A TUI gesture that mutates state needs a ROADMAP entry first.
+
+## Input
+
+Mouse support uses SGR mouse mode. `mouse.ts` parses
+`ESC[<button;x;y;M/m`, detects double-clicks, and exposes `useMouse()`.
+A double-click on a card emits `setCursor` then `drill` through the
+action queue, which consumes one action per render, so the cursor lands
+before the drill reads the focused row.
+
+`keys.ts` holds `dispatchGlobalKey` (dashboard), `dispatchPopupKey`
+(popup), and `shouldSwallowGlobalKey` (keys a popup consumes).
+
+## Drill recursion
+
+List popups drill with `Enter`. `DrillScrollView`
+(`popups/drill.tsx`) is the shared scrollable text leaf: Workspaces'
+git show, Agents' scrollback, Activity log payloads, and Doctor
+remediation. Task popups drill into `TaskDetailDrill`
+(`popups/task-detail.tsx`, the notes timeline). Tracks chains track →
+task list → `TaskDetailDrill`.
+
+`useDrillKeymap` owns scroll state. An optional `resetKey` resets
+scroll on identity change while a tick refresh keeps it, and
+`onScrollChange` serves the DAG popup's focused-root tracking. Body
+wrap metadata is shared so the scroll clamp and the painter cannot
+disagree. Subprocess-backed drills use `popups/show-loader.ts`, which
+keeps the prior body during a refetch.
+
+## Test seam
+
+See `test/README.md`. `test/_ink-render.ts` provides
+`createInkInputStream`, `createInkCaptureStream`, `simulateInput` and
+`latestRenderedFrame`: mount a popup or `<App>`, drive keys, assert on
+the visible frame and spy callbacks. Source greps are for narrow
+structural guards only, never behaviour.

package/docs/guide/README.md

@@ -0,0 +1,25 @@
+# mu guide
+
+Start with the tutorial, then open a how-to when you have that job.
+`mu <verb> --help` is the reference: flags, defaults, and exit codes.
+Terms are defined in [VOCABULARY.md](../VOCABULARY.md).
+
+1. [Getting started](getting-started.md): install mu, plan two tasks,
+   and ship one with a pi worker.
+
+How-to guides:
+
+- [Dispatch work to a worker](dispatch.md)
+- [Stop a worker](stop-a-worker.md)
+- [Delegate a task (mu_delegate)](delegate.md)
+- [Run a worker on another machine](remote.md)
+- [Recover from a broken state](recovery.md)
+- [Sync between machines](sync.md)
+- [Use the TUI dashboard](tui.md)
+- [Query and script mu](sql.md)
+- [Upgrade mu](upgrade.md)
+- [Choose a multiplexer backend](backends.md)
+- [Clean up](cleanup.md)
+
+For features mu does not have on purpose, see
+[ROADMAP.md § Explicitly rejected](../ROADMAP.md#explicitly-rejected).

package/docs/guide/backends.md

@@ -0,0 +1,61 @@
+# How to choose a multiplexer backend
+
+mu drives one multiplexer per command: tmux or
+[herdr](https://github.com/herdrdev/herdr). Spawn, send, read, and
+agent state work on both.
+
+## See which backend is active
+
+```bash
+mu doctor           # the environment block names it
+mu doctor --json    # .environment.mux.name
+```
+
+mu picks the backend from the first rule that matches:
+
+1. `MU_MUX=tmux` or `MU_MUX=herdr`. An unknown value fails with exit 1.
+2. `HERDR_ENV=1`: herdr. This wins over tmux variables, because a herdr
+   pane can host a tmux server.
+3. `$TMUX` or `$TMUX_PANE` is set: tmux.
+4. The first binary that runs, tmux before herdr.
+5. Neither: `NoMultiplexerError`, exit 5.
+
+## Know what differs
+
+| | tmux | herdr |
+| --- | --- | --- |
+| Workstream | session `mu-<ws>` | workspace labelled `mu-<ws>` |
+| Window | window | tab |
+| Pane id | `%15` | `w1:p1` |
+| Attach | `tmux attach -t mu-<ws>` | `herdr session attach mu-<ws>` |
+| pi agent state | control socket | control socket |
+| Other agents' state | murmur | herdr |
+| Send to non-pi agents | bracketed paste, then Enter | one atomic `agent prompt` |
+| Spawn | one command | bare pane, then `agent start` |
+| Pane borders, layout | set by mu | left to herdr |
+| Test isolation | `MU_TMUX_SOCKET` | `MU_HERDR_SESSION` |
+
+Where each agent's state comes from, per backend:
+[architecture/mux.md § Agent state](../architecture/mux.md#agent-state).
+
+## Know herdr's limits
+
+- `mu agent kick` works on Linux only. It reads the TTY from
+  `/proc/<pid>/fd/0`, which macOS does not have.
+- `mu agent read --lines` cannot recover rows that scrolled off a pane
+  on the alternate screen.
+- `MU_<CLI>_COMMAND` overrides apply on tmux only. herdr picks the
+  agent binary itself.
+- herdr creates every workspace detached. Run `herdr workspace focus`
+  yourself.
+
+## Expect loud failures, not silent ones
+
+If the multiplexer is down, `mu doctor` still prints a full report.
+Verbs that need the multiplexer, such as spawn, send, close, and
+reconcile, exit 5 with remediation steps. Verbs that only use it for
+decoration, such as identity lookup and `mu workstream list`, carry on.
+
+A herdr argument error raises `HerdrSyntaxError`, not a multiplexer
+error. It means herdr's CLI changed and mu needs a fix. The herdr
+server is fine.

package/docs/guide/cleanup.md

@@ -0,0 +1,74 @@
+# How to clean up
+
+## Close one agent
+
+```bash
+mu agent close worker-1 -w auth
+```
+
+A clean workspace is freed with the agent. If the workspace has edits
+or commits, close refuses with exit 4. Run
+`mu workspace free worker-1 -w auth --commit` first, or pass
+`--discard-workspace` to lose the changes. See
+[Stop a worker](stop-a-worker.md).
+
+## Tear down a workstream
+
+```bash
+mu workstream teardown auth          # dry run: prints what goes
+mu workstream teardown auth --yes    # kills the session, deletes the rows
+```
+
+Teardown kills the tmux session first, then deletes the agents, tasks,
+edges, notes, and workspaces. Running it again is a no-op.
+
+To sweep every workstream that has no tasks, agents, or workspaces,
+including `mu-*` tmux sessions with no DB row:
+
+```bash
+mu workstream teardown --empty
+mu workstream teardown --empty --yes
+```
+
+## Undo a teardown
+
+Teardown writes tombstone ops, so the ops log keeps everything. You do
+not need a backup first.
+
+```bash
+mu workstream list --torn-down
+mu undo 7a40e6cc --yes
+```
+
+The list shows one row per teardown, newest first. `← recreated since`
+means the name is in use again, so the undo would change nothing.
+Killed panes and freed workspace directories do not come back.
+
+## Find workstreams you can remove
+
+The `housekeeping` section of `mu doctor` lists two kinds:
+
+| Kind | Rule | Advice |
+| ---- | ---- | ------ |
+| finished | every task `CLOSED`, idle 14 days or more | safe to tear down |
+| abandoned | unclosed tasks, idle 60 days or more | read the open tasks first |
+
+It skips your current workstream, `scratch`, and any workstream with a
+live agent or a workspace. Teardown removes the plan, not the code: no
+commit or checkout is touched.
+
+## Free disk space
+
+```bash
+mu doctor --disk                    # bytes per workspace checkout
+mu workspace orphans -w auth        # directories with no DB row
+mu workspace free worker-1 -w auth  # delete one workspace
+```
+
+## Keep a copy of the graph
+
+```bash
+mu db backup /tmp/mu-backup.db      # VACUUM INTO; never overwrites
+mu task list -w auth --json
+mu task notes design -w auth --json
+```