@mu-crew/mu 3.8.0 → 3.9.0

package/docs/ARCHITECTURE.md

@@ -74,7 +74,7 @@ them, and is the only code that imports ink:
 **CLI and SDK surface.** Each operation is a typed SDK function plus a
 thin Commander wrapper. Public functions take operator-facing names and
 resolve them to surrogate ids exactly once. Typed errors map to exit
-codes 0-5. The same page covers testing layers and packaging:
+codes 0-7. The same page covers testing layers and packaging:
 [architecture/sdk.md](architecture/sdk.md).
 
 ## Module map
@@ -90,11 +90,12 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | --- | --- |
 | `src/db.ts` | better-sqlite3 connection (WAL); schema v11 (11 tables, 3 views) in `applySchema`; installs capture; owns `SYNCED_ENTITIES`, `PORTABLE_TABLES`, `MACHINE_LOCAL_TABLES`; refuses older (`SchemaTooOldError`) or newer (`SchemaTooNewError`) DBs, exit 4 |
 | `src/hlc.ts` | hybrid logical clock, serialized as sortable TEXT |
-| `src/capture.ts` | TEMP triggers recording each portable write as an op |
+| `src/capture.ts` | TEMP triggers recording each portable write as an op, and refusing natural-key changes |
 | `src/op-context.ts` | `withOpContext` (intent, actor, group); `withCaptureSuppressed` echo guard |
 | `src/apply.ts` | apply one op: per-field LWW, tombstones, substate pair repair, `reprojectDeferredOps` |
 | `src/undo.ts` | inverse ops for one group; refuses a superseded group |
 | `src/rebuild.ts` | replay the whole log into a new DB file |
+| `src/compact.ts` | `mu db compact` (blank redundant note-tombstone payloads) and `mu db forget` (drop a torn-down workstream's ops); this machine only |
 | `src/legacy-ops.ts` | classifier for historical log-only intents; rebuild copies them unprojected |
 | `src/drift.ts` | cheap invariant (every row has an op) and `--deep` rebuild-diff |
 | `src/logs.ts` | typed reader over `ops`; `appendLog` and `emitEvent`, the writes triggers cannot cover |
@@ -121,13 +122,14 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | `src/agents/spawn-lock.ts` | per-session lock around topology and row insert |
 | `src/agents/transport.ts` | send routing: ctl for pi agents, mux paste otherwise, no fallback; `expectsCtl` |
 | `src/agents/abort.ts` | stop a pi turn through the control socket; abort + send (`--interrupt`) |
-| `src/agents/delegate.ts` | `delegateOutcome`: one wait result to `done` / `empty` / `died` / `timeout` / `pending` |
+| `src/agents/delegate.ts` | `delegateOutcome`: one wait result to `done` / `empty` / `error` / `died` / `timeout` / `pending` |
 | `src/agents/wait.ts` | block until task-less agents leave `busy` |
 | `src/agents/adopt.ts` | register an existing pane as an agent |
 | `src/agents/kick.ts` | `mu agent kick`: signal a wedged pane's foreground process group |
 | `src/agents/errors.ts` | typed agent errors |
 | `src/agent-state.ts` | runtime state from ctl, herdr or murmur; `unknown` with a reason |
 | `src/reconcile.ts` | ghost prune and orphan surfacing |
+| `src/mux/index.ts` | cluster barrel that `src/mux.ts` re-exports |
 | `src/mux/types.ts` | `MuxBackend` interface; `MuxError`, `PaneNotFoundError`, `NoMultiplexerError` |
 | `src/mux/detect.ts` | `MU_MUX` → `HERDR_ENV` → `$TMUX` → `PATH` ladder; `activeMux()` |
 | `src/mux/tmux.ts` | tmux backend: the `tmux()` wrapper, bracketed-paste send, pane validation |

package/docs/VISION.md

@@ -109,7 +109,7 @@ which task.
 A workstream is a mux session: a tmux session on tmux, a herdr workspace
 on herdr. Its agents are panes in that session, so
 `tmux a -t mu-<workstream>` shows the whole crew. Workstreams on one
-machine are separate sessions, partitioned in the DB by `session_id`.
+machine are separate sessions, partitioned in the DB by `workstream_id`.
 The crew survives detach and reattach.
 
 The multiplexer is a backend chosen by detection
@@ -161,7 +161,7 @@ win32-x64) or a C++ toolchain.
 - **Read views**: the `ready`, `blocked`, and `goals` views, and
   `mu state` as the state card.
 - **Typed verbs** that map to resource transitions (`task claim`,
-  `task close`, `agent spawn --workspace`, `workstream destroy`).
+  `task close`, `agent spawn --workspace`, `workstream teardown`).
 - **`--json` on every read verb**, so scripts use `jq`, not table parsing.
 - **`mu sql`** underneath, as the explicit escape hatch.
 
@@ -249,10 +249,17 @@ mu agent spawn reviewer-1 --cli pi_big
    The exceptions are `mu log --tail` and the TUI (`mu state --tui`, or
    bare `mu` on a TTY). Both are:
    - owned by a human or parent script and gone when it ends;
-   - read-only: TUI actions copy the `mu <verb>` command to the
-     clipboard and exit, so every write is a fresh CLI call;
-   - limited to stdin, stdout, and a poll timer: no sockets, watches, or
-     subprocesses;
+   - free of user actions: TUI keys copy the `mu <verb>` command to
+     the clipboard and exit, so every change the operator asks for is a
+     fresh CLI call. The TUI's slow tick still does the housekeeping
+     any `mu` invocation does: ambient sync (ingest peer ops, flush the
+     local segment) and reconcile (prune agents whose pane died, which
+     reopens their tasks with a `[reaper]` note, and refresh pane
+     titles);
+   - limited to stdin, stdout, and a poll timer: no sockets or watches.
+     The TUI's slow tick runs short-lived probes (mux liveness, VCS
+     status) and ambient sync, and its handoffs (lazygit, tuicr, attach,
+     clipboard) run one foreground child each; none outlives the TUI;
    - TTY-gated: pipes, CI, `--json`, and `MU_NO_TUI=1` never enter the
      TUI, and plain `mu state` prints the static card.
 
@@ -276,5 +283,5 @@ the work, pi plus manual tmux is more transparent than mu.
 
 Known gaps, none promoted yet: `--evidence` grounds but does not verify,
 mutations have no declared idempotency keys, most mutations have no dry
-run (`workstream destroy`, `task delete`, and `undo` do), and the `role`
+run (`workstream teardown`, `task delete`, and `undo` do), and the `role`
 field is stored but not enforced.

package/docs/VOCABULARY.md

@@ -15,7 +15,7 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | Term | Meaning | Don't use |
 | --- | --- | --- |
 | **workstream** | The unit of organization: one **mux session** and one DB partition. | "project", "session" (alone), "context" |
-| **scratch workstream** | The reserved workstream `scratch` for helpers outside any task DAG. Auto-created on first spawn with explicit `-w scratch`; `mu workstream init scratch` is rejected. | "throwaway ws", "temp workstream" |
+| **scratch workstream** | The reserved workstream `scratch` for helpers outside any task DAG. Auto-created on first spawn with explicit `-w scratch`; `mu workstream init scratch` is rejected. Its session keeps a `_mu` window, so it stays open after the last agent closes; `teardown --empty` skips it. | "throwaway ws", "temp workstream" |
 | **multiplexer** / **mux** | The terminal program that owns panes: **tmux** or **herdr**. "mux" in code (`src/mux/`, `MU_MUX`), "multiplexer" in prose; one is active per invocation. | "terminal", "emulator", "backend" (alone) |
 | **mux backend** | An implementation of `MuxBackend` (`src/mux/tmux.ts`, `src/mux/herdr.ts`). Owns everything backend-specific. | "driver", "provider", "adapter" |
 | **mux detection** | Picks the mux backend: `MU_MUX` → `HERDR_ENV=1` → `$TMUX` → binary on `PATH` (tmux wins a tie) → `NoMultiplexerError`. | "auto-detect", "probe" |
@@ -105,7 +105,7 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | **op** | One `ops` row, written by a trigger in the mutation's transaction. Holds only changed columns. | "event", "delta", "change" |
 | **ops log** | The `ops` table: the append-only record that sync, undo, and history read. | "event log", "journal", "WAL" |
 | **log entry** | An op as rendered by `mu log`, through one formatter (`src/log-render.ts`). | "message", "event" |
-| **kind** | The operator's channel tag on a log entry (`mu log --kind`), stored as the op's `entity`. | "category", "type" |
+| **kind** | The operator's channel tag on a log entry (`mu log --kind`), stored as the op's `entity`. `workstream`, `task`, `edge`, and `note` are reserved. | "category", "type" |
 | **log ledger** | A convention: a custom `--kind` used as a watcher loop's durable dedupe record. | "state file" |
 | **intent** | The semantic label on an op (`task.close`), set once per SDK function via **op context**. | "verb", "action" |
 | **group** | The ops of one user action (`group_id`), undone as a unit. Any unique id prefix works. | "transaction", "batch" |
@@ -119,7 +119,7 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | **resurrection** | A put newer than a seen tombstone, which legitimately recreates the row. | "undelete", "revive" |
 | **provenance** | Which HLC last wrote a field, derived from the ops log by query, never stored. | "version vector" |
 | **inverse op** | The op that reverts another; an ordinary op, so undo syncs and is undoable. | "rollback" |
-| **superseded** (group) | A later group wrote the same field, so `mu undo` refuses (exit 4) without `--force`. | "stale" |
+| **superseded** (group) | A later group wrote the same field (other than `updated_at`), so `mu undo` refuses (exit 4) without `--force`. | "stale" |
 | **teardown** | Kill a workstream's mux session and delete its rows. `mu undo` restores rows, not panes or dirs. | "destroy", "nuke", "purge" |
 | **drift** | The ops log and live tables disagree. Always a bug. | "inconsistency", "corruption" |
 | **shallow / deep check** | Drift checks in `mu doctor` and `mu doctor --deep` (full rebuild). | "fsck" |
@@ -128,7 +128,7 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | **machine_id** | Per-state-dir uuid naming this DB's **peer** and **segment**. | "device id", "host id" |
 | **segment** | `<sync-dir>/<machine_id>.jsonl`: one machine's ops, single writer. | "replica", "shard" |
 | **peer** | Another machine, found by its segment; named by `machine_id` prefix. **Stale** after 24h unchanged. | "node", "remote" |
-| **watermark** | `sync_peers.last_applied_seq`: how many lines of a peer's segment have been applied. | "offset", "cursor" |
+| **watermark** | `sync_peers.last_applied_seq`: how many lines of a peer's segment file have been applied. A conflict copy has its own, keyed by its file stem. | "offset", "cursor" |
 | **flush** / **ingest** | Write my ops to my segment; apply peers' from their watermarks. Every invocation, when `MU_SYNC_DIR` is set. | "push", "pull" |
 | **reprojection** | After ingest, apply deferred ops whose parent arrived from another peer. | "retry queue" |
 | **mixed fleet** | Machines sharing state across different OSes or filesystems. | "cluster" |
@@ -222,5 +222,4 @@ deprecated, always `spawning`, and never read.
 | **pi session** | pi's conversation |
 | **agent session** | Colloquial for an agent's lifetime; avoid in code |
 
-New columns and variables say `workstream_id`, not `session_id`. The
-`agents.session_id` column keeps its name for schema stability.
+Columns and variables say `workstream_id`, never `session_id`.

package/docs/architecture/control-socket.md

@@ -134,5 +134,5 @@ when `MU_MANAGED_AGENT` is set (inside a mu-spawned pane) or
 `wait --json`, read, abort, close) and only format the CLI's
 `outcome` into a follow-up message. `delegateOutcome`
 (`src/agents/delegate.ts`) maps one wait result to `done`, `empty`,
-`died`, `timeout` or `pending`. The extension imports nothing from pi;
+`error`, `died`, `timeout` or `pending`. The extension imports nothing from pi;
 it types pi's API structurally.

package/docs/architecture/mux.md

@@ -5,7 +5,7 @@ mu runs agents in multiplexer panes, tmux or herdr, behind one
 
 ## One mux session per workstream
 
-One workstream is one mux session and one `session_id` partition in
+One workstream is one mux session and one `workstream_id` partition in
 `~/.local/state/mu/mu.db`. Workstreams on one machine are independent
 mux sessions.
 
@@ -107,7 +107,9 @@ as a capability, not a name check:
   reads before the first claim report `unknown`. A pi agent skips the
   fixed wait: mu checks the pane on every handshake tick (a dead pane
   rolls back at once) and scans for startup errors when the handshake
-  ends.
+  ends. After an ok handshake the scan skips shell exec-failure lines
+  (`command not found`, `No such file or directory`): pi demonstrably
+  started, and a resumed session can show such lines as old tool output.
 - **herdr.** mu creates a bare pane and calls `startAgentInPane`, which
   subsumes both checks.
 - **pi, either backend.** After the agent starts, mu polls its control

package/docs/architecture/ops-log.md

@@ -103,7 +103,8 @@ prefix previews, and `--yes` applies.
   old key (drift-641). The `task_notes` delete trigger records `OLD.*`
   only when no put under the current key is in the log, and `'{}'`
   otherwise; `planUndo` folds the puts first and falls back to the
-  tombstone payload. For the same reason `src/drift.ts` matches notes on
+  tombstone payload, and `applyOp` deletes by the payload's content
+  identity, falling back to the put under the same key. For the same reason `src/drift.ts` matches notes on
   the task-key prefix.
 
 ## Rewriting history (local only)

package/docs/architecture/sdk.md

@@ -125,7 +125,9 @@ codes:
 | 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) |
+| 5 | substrate unavailable or unsafe (no multiplexer, mux or VCS failure, DB locked, ops-log drift, a `mu doctor` FAIL row, timeout) |
+| 6 | `mu task wait`: the reaper reopened a watched task (its pane died) |
+| 7 | `mu task wait`: a watched task stalled (`--on-stall exit`) |
 
 Errors carry structured context (operation, target, attempted action)
 so `mu doctor` can show them readably.

package/docs/architecture/sync.md

@@ -18,6 +18,9 @@ Litestream, cr-sqlite or a peer list, and why the DB must never sit in
   `applyOp`.
 - Peer discovery is implicit: every non-self `*.jsonl` is a peer. A
   peer disappears only when its segment is deleted.
+- A Syncthing conflict copy (`<machine>.sync-conflict-….jsonl`) is
+  ingested too, with its own watermark keyed by the file stem: it can
+  diverge from the original, so line counts are not comparable.
 
 **Single writer per file.** A machine appends only to its own segment,
 so nothing is contended and any folder syncer is adequate. Segments
@@ -35,8 +38,10 @@ anything else, unwrapping on ingest.
 
 ## Robustness layers
 
-Four checks stop ingest at the first bad record and advance the
-watermark only that far:
+The first three checks stop ingest at the first bad record and advance
+the watermark only that far. The fourth is whole-file: it reports the
+defect without halting, because every line still present is valid, and
+only a fresh copy of the file clears it:
 
 | Layer | Catches |
 | --- | --- |
@@ -54,8 +59,9 @@ distinguishes three cases:
 
 | Line | Result |
 | --- | --- |
-| damaged | halt |
+| damaged (including a blank line) | halt |
 | a known machine-local entity | reported defect, skipped |
+| a historical log-only intent (`workstream.export` prose from mu < 1.1) | skipped silently, as flush and `--from` skip it |
 | 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.
@@ -71,8 +77,9 @@ 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
+through and which is already async. It awaits `ambientIngest` and
+`ambientFlush`; the flush 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.
 
@@ -86,7 +93,8 @@ every verb.
 `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).
+exit 4). A prefix names a machine, so it resets the watermark of the
+peer's segment and of every conflict copy of it.
 
 ### Carve-outs
 

package/docs/architecture/tui.md

@@ -30,9 +30,10 @@ Press `?` in the TUI for the keymap.
 | `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 |
+| `keys.ts`, `keymap-spec.ts`, `help.tsx` | pure key dispatch; the keymap source of truth that drives both dispatch and the `?` 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 |
+| `popup-input.ts` | `usePopupInput`: popup keyboard, off while the help overlay covers the popup |
 | `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 |
@@ -45,9 +46,12 @@ Press `?` in the TUI for the keymap.
 `<App>` owns:
 
 - **Popup state:** `null` (dashboard) or one popup id. One popup at a
-  time; `Esc` or `q` returns to the dashboard.
+  time; `Esc` or `q` returns to the dashboard. `?` over a popup hides
+  it (`display="none"`) and turns its keyboard off rather than
+  unmounting it, so its cursor, filter and drill survive the overlay.
 - **Card visibility:** toggled by `0`-`9`.
-- **Tick rate:** fast tick, 1s default, adjusted with `+` `-` `=` `0`.
+- **Tick rate:** fast tick, 1s default, adjusted with `+` / `=` and
+  `-`. There is no reset key: `0` toggles the Commits card.
 - **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
@@ -98,7 +102,7 @@ the right border.
 
 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.
+back to OSC-52 written to `/dev/tty`, since ink owns stdout.
 
 The handoffs leave the alt screen, disable mouse mode, run a
 foreground subprocess, and restore both on exit:
@@ -114,16 +118,22 @@ A TUI gesture that mutates state needs a ROADMAP entry first.
 
 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.
+A double-click on a card opens its popup. A double-click on a popup row
+emits one `clickRow` action (the 0-based body row) through the action
+queue. The popup maps that row through its own scroll window and
+header strips (`clickedItem` in `popups/scroll.ts`), then focuses and
+drills the item. App cannot do the mapping: only the popup knows its
+window start and strip rows.
 
 `keys.ts` holds `dispatchGlobalKey` (dashboard), `dispatchPopupKey`
 (popup), and `shouldSwallowGlobalKey` (keys a popup consumes).
 
 ## Drill recursion
 
-List popups drill with `Enter`. `DrillScrollView`
+List popups drill with `Enter`. Each popup pins the drilled row's
+identity at `Enter` (task, agent, check, commit sha, log seq, track
+goals), so a refresh that reorders or extends the list cannot move an
+open drill to another row. `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`

package/docs/guide/backends.md

@@ -27,7 +27,7 @@ mu picks the backend from the first rule that matches:
 | 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>` |
+| Attach | `tmux attach -t mu-<ws>` | `herdr workspace focus <id>`, then `herdr` outside a herdr pane |
 | 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` |
@@ -44,8 +44,10 @@ Where each agent's state comes from, per backend:
   `/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 starts the agent binary itself (`herdr agent start --kind
+  <cli>`), so spawn refuses `--command` and `MU_<CLI>_COMMAND` with
+  exit 2 instead of running a different binary. Unset the variable, or
+  spawn with `MU_MUX=tmux`.
 - herdr creates every workspace detached. Run `herdr workspace focus`
   yourself.
 

package/docs/guide/cleanup.md

@@ -22,14 +22,18 @@ 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:
+To sweep every workstream that has no tasks, agents, or workspaces:
 
 ```bash
 mu workstream teardown --empty
 mu workstream teardown --empty --yes
 ```
 
+The sweep skips `scratch`, whose idle session is kept open on purpose.
+It never takes a `mu-*` session that has no workstream row in this DB:
+it may be a live workstream from another DB. The output names
+such sessions; tear one down by name once you know it is unused.
+
 ## Undo a teardown
 
 Teardown writes tombstone ops, so the ops log keeps everything. You do
@@ -40,7 +44,8 @@ mu workstream list --torn-down
 mu undo 7a40e6cc --yes
 ```
 
-The list shows one row per teardown, newest first. `← recreated since`
+The list shows one row per teardown, newest first. A `--empty` sweep
+writes one row per workstream, so undo each one. `← 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.
 

package/docs/guide/delegate.md

@@ -95,7 +95,9 @@ Exit codes: `0` met, `5` timeout, `6` pane died. Non-pi agents have no
 ## Keep a helper
 
 Pass `keep: true`, or spawn a named agent in `scratch`. It is created
-on first spawn, needs no tasks, and cannot be `init`ed.
+on first spawn, needs no tasks, and cannot be `init`ed. Its `mu-scratch`
+session stays open after the last agent closes; remove it with
+`mu workstream teardown scratch --yes`.
 
 ```bash
 mu agent spawn helper -w scratch

package/docs/guide/dispatch.md

@@ -103,9 +103,11 @@ mu workspace refresh worker-1 -w auth
 ```
 
 It rebases onto the remote's main (`origin/HEAD`); without a remote,
-pass `--from main`. It refuses on a dirty tree. On a conflict it exits 5
-with a `cd` hint. To throw the workspace away instead, run
-`mu workspace free worker-1 -w auth`.
+pass `--from main`. It refuses on a dirty tree. On a conflict it exits 5:
+git and sl abort the rebase and leave the workspace as it was, while jj
+keeps the rebase with the conflicts committed in place. After you resolve,
+run refresh again so mu records the new base. To throw the workspace away
+instead, run `mu workspace free worker-1 -w auth`.
 
 Claim and send warn when the worker's workspace is 10 or more commits
 behind main. `--strict-staleness` makes that a refusal (exit 4).

package/docs/guide/recovery.md

@@ -7,7 +7,7 @@ read the same rules in
 [recipes/recovery.md](../../skills/mu/recipes/recovery.md).
 
 ```bash
-mu doctor           # exit 0 healthy, 5 on drift
+mu doctor           # exit 0 healthy (WARN rows too), 5 on drift or a FAIL row
 mu doctor --deep    # rebuild the ops log and diff every field
 mu doctor --disk    # add per-workspace byte usage
 ```
@@ -30,6 +30,8 @@ mu agent adopt %15 -w auth
 mu agent adopt %15 -w auth --name investigator
 ```
 
+On herdr, pass its pane id instead (`mu agent adopt w1:p2 -w auth`).
+
 The pane title becomes the agent name. The pane must be in the
 `mu-<workstream>` session. An adopted pi has no control socket until
 you restart it with the `MU_CTL_SOCK` path that `adopt` prints.
@@ -86,7 +88,8 @@ mu undo 6380dd3d --yes    # apply
 - Any unique prefix of a group id works.
 - The undo is its own group, so undoing it again is redo.
 - If later work changed the same fields, undo exits 4 and names the
-  conflict. `--force --yes` overrides and discards the newer work.
+  conflict. A later write to `updated_at` alone, such as `mu task note`,
+  does not count. `--force --yes` overrides and discards the newer work.
 - Undo restores rows only. Killed panes and freed workspace
   directories do not come back.
 
@@ -113,21 +116,29 @@ command.
 | `ws-rows` | a workspace row whose directory is gone; the next send fails in the VCS |
 | `ws-dirs` | a workspace directory with no row; it blocks the next `--workspace` spawn with that name |
 | `ws-empty` | a workstream directory with no checkouts |
-| `db-copies` | stray `mu.db*` files that nothing reads |
+| `db-copies` | stray `mu.db*` files that nothing reads, including the `pre-compact` / `pre-forget` backups |
 | `exports` | output left by the removed export verb |
 | `locks` | lock directories older than one hour, from a spawn or flush that died |
 
 To list workspace orphans with cleanup commands, run
-`mu workspace orphans -w auth`. Remove a git-backed orphan with
-`git worktree remove --force <path>` from the project root.
+`mu workspace orphans -w auth`. An orphan has no row, so
+`mu workspace free` cannot remove it. Remove a git-backed orphan with
+`git worktree remove --force <path>` from the project root, and any
+other with `rm -rf <path>`.
 
 ## Rename a workstream
 
-There is no rename verb. Every child table cascades on the name:
+There is no rename verb, and `mu sql` refuses to change
+`workstreams.name`. The name is part of the key that every op is filed
+under, so a raw rename leaves the ops log on the old name: `mu doctor`
+reports drift, and sync or `mu rebuild` brings the old name back.
+Re-create the workstream instead:
 
 ```bash
-mu sql "UPDATE workstreams SET name='auth-refactor' WHERE name='auth-refator'"
-tmux rename-session -t mu-auth-refator mu-auth-refactor
+mu db backup /tmp/mu-before-rename.db
+mu workstream init auth-refactor
+# re-add the tasks you still need, with -w auth-refactor
+mu workstream teardown auth-refator --yes
 ```
 
 Names start with a lowercase letter, use letters, digits, `_`, or

package/docs/guide/sql.md

@@ -20,8 +20,8 @@ mu task list -w auth --json | jq '.count'
 ```
 
 Exit codes: `2` usage error, `3` not found, `4` conflict, `5`
-timeout or a multiplexer, VCS, or drift failure, `6` reaped pane,
-`7` stall.
+timeout, a locked DB, or a multiplexer, VCS, drift, or `mu doctor`
+FAIL-row failure, `6` reaped pane, `7` stall.
 
 ## Read the schema
 
@@ -66,7 +66,14 @@ mu sql "WITH RECURSIVE prereqs(id) AS (
 ```
 
 `mu sql` runs writes too and prints the number of rows changed. Writes
-are captured as ops, so `mu undo` can revert them.
+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
+`ON DELETE CASCADE` too: deleting a task with one edge counts 2.
+
+`mu sql` 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.
 
 ## Pass list flags
 

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

@@ -55,7 +55,9 @@ 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.
+  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.
 

package/docs/guide/tui.md

@@ -67,9 +67,9 @@ pane. The dashboard comes back when the tool exits.
 `/` filters the popup's rows by substring as you type. `Enter` keeps
 the filter. `Esc` clears it.
 
-In task popups, `o`, `i`, and `c` toggle `OPEN`, `IN_PROGRESS`, and
-`CLOSED`. In the DAG and All-tasks popups, `p` toggles parked tasks and
-`w` toggles tasks closed as anything but `done`. In All tasks, `b`
+In the DAG and All-tasks popups, `o`, `i`, and `c` toggle `OPEN`,
+`IN_PROGRESS`, and `CLOSED`, `p` toggles parked tasks, and `w` toggles
+tasks closed as anything but `done`. In All tasks, `b`
 cycles the blocked filter and `s` cycles the sort: ROI, recency, age,
 id.
 

package/docs/guide/upgrade.md

@@ -16,8 +16,9 @@ that both paths start from.
 
 - `--copy` copies the extension instead of the shim. You then have to
   relink after every upgrade.
-- `--force` replaces a skill symlink that points elsewhere, such as a
-  dev checkout. mu never replaces a real directory there (exit 4).
+- `--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.
 
 For agents other than pi, see [README § Install](../../README.md#install).
@@ -50,7 +51,12 @@ 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.
 
+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).
+
 ```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'"

package/docs/reference/env.md

@@ -1,6 +1,8 @@
 # Environment variables
 
-Every env var mu reads or sets. mu has no config file. Durations are
+Every env var mu reads or sets, except standard ones it reads as any
+tool does (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `DISPLAY`,
+`WAYLAND_DISPLAY`). mu has no config file. Durations are
 milliseconds; `0` disables a wait unless noted.
 
 ## State and workstream
@@ -9,7 +11,7 @@ milliseconds; `0` disables a wait unless noted.
 | --- | --- | --- |
 | `MU_DB_PATH` | SQLite file path. Wins over the state dir. | `<state-dir>/mu.db` |
 | `MU_STATE_DIR` | State directory. | `$XDG_STATE_HOME/mu` |
-| `XDG_STATE_HOME` | XDG state base; mu appends `mu/`. | `~/.local/state` |
+| `XDG_STATE_HOME` | XDG state base; mu appends `mu/`. An empty or relative value is ignored. | `~/.local/state` |
 | `MU_SESSION` | Active workstream when `-w` is absent. | 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 |
 
@@ -19,7 +21,10 @@ 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`. | |
-| `MU_TMUX_SOCKET` | tmux socket name (`-L <name>`). tmux only. | `$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). | |
+| `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 |
 | `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 |
 
@@ -27,7 +32,7 @@ milliseconds; `0` disables a wait unless noted.
 
 | Name | Effect | Default |
 | --- | --- | --- |
-| `MU_<CLI>_COMMAND` | Executable for `--cli <cli>`; hyphens become underscores (`--cli pi-meta` reads `MU_PI_META_COMMAND`). May hold arguments. `--command` wins; the spawn line names the env var when it supplied the command. | the cli value |
+| `MU_<CLI>_COMMAND` | Executable for `--cli <cli>`; hyphens become underscores (`--cli pi-meta` reads `MU_PI_META_COMMAND`). May hold arguments. `--command` wins; the spawn line names the env var when it supplied the command. On herdr, spawn refuses both with exit 2. | the cli value |
 | `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` |

package/docs/reference/naming.md

@@ -37,9 +37,9 @@ clears all blockers.
 | Id | Shape | Unique within |
 | --- | --- | --- |
 | Agent name | `[a-z][a-z0-9_-]*`, ≤ 32 chars | workstream |
-| Task `local_id` | same | DB |
-| Workstream name | same; mux session is `mu-<name>` | DB |
-| Window (`--tab`) | `[A-Za-z][A-Za-z0-9 _-]*`, ≤ 32 chars | workstream |
+| Task `local_id` | `[a-z][a-z0-9_-]*`, ≤ 64 chars | workstream |
+| Workstream name | `[a-z][a-z0-9_-]*`, ≤ 32 chars; mux session is `mu-<name>` | DB |
+| Window (`--tab`) | not validated; passed to the mux as given. Avoid `:` and `.`, which tmux reads as target separators | workstream |
 
 `scratch` is reserved: it is created only by the first
 `mu agent spawn <name> -w scratch`, and `mu workstream init scratch`
@@ -87,7 +87,6 @@ The state dir is `MU_STATE_DIR`, else `$XDG_STATE_HOME/mu`, else
 | Path | Contents |
 | --- | --- |
 | `<state-dir>/mu.db` | The SQLite DB for every workstream |
-| `<state-dir>/workstreams/<workstream>/` | Per-workstream artifacts, created lazily |
 | `<state-dir>/workspaces/<workstream>/<agent>/` | Per-agent VCS workspace, created by `mu agent spawn --workspace` |
 | `<sync-dir>/<machine_id>.jsonl` | This machine's segment; `<sync-dir>` is `MU_SYNC_DIR` |
 | `<sync-dir>/<machine_id>.manifest` | `{count, last_hlc, sha256}` for segment verification |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.8.0",
+  "version": "3.9.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"

package/skills/mu/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: mu
-description: Fresh-context subagents and crews in tmux/herdr panes. Check before you commit: before acting on a claim, root cause, plan, fix or brief, have a `mu_delegate` call refute it. Also for a fresh delegate's second look at your own work or diff; parallel read-only research, investigation or fan-out over files; background helpers (watchers, soak runs, agents you keep talking to); persistent crews with a task graph, review gates and merges. Outside pi, delegate through the reserved `scratch` workstream.
+description: >-
+  Fresh-context subagents and crews in tmux/herdr panes. Check before you
+  commit: before acting on a claim, root cause, plan, fix or brief, have a
+  `mu_delegate` call refute it. Also for a fresh delegate's second look at
+  your own work or diff; parallel read-only research, investigation or fan-out
+  over files; background helpers (watchers, soak runs, agents you keep talking
+  to); persistent crews with a task graph, review gates and merges. Outside
+  pi, delegate through the reserved `scratch` workstream.
 ---
 
 # mu — Multi-agent orchestration
@@ -257,8 +264,8 @@ Close the task as your last action, or the orchestrator's wait hangs.
 ## Guardrails
 
 Task ownership outranks agent state. Coordinate through task notes and
-the activity log. Keep edges within one workstream and reserve the `mu_`
-task-id prefix. Give workers bounded paths and commands.
+the activity log. Keep edges within one workstream. Give workers
+bounded paths and commands.
 
 ## Recipes