@mu-crew/mu 3.4.0 → 3.6.0

package/docs/VISION.md

@@ -226,7 +226,9 @@ mu agent spawn reviewer-1 --cli pi_big
   calls. mu bets that visibility and steering are worth the cost. There
   are no agent types: the brief is plain text. A delegate's answer is
   not recorded in mu; only what the caller writes back (a note, a state
-  change) is.
+  change) is. The one extension-held list with no pane is the delegate
+  queue: bounded, shown in pi's footer, cancellable, and named at
+  shutdown when it is dropped.
 - **DB-undoable, not substrate-undoable.** `mu undo <group> --yes`
   restores rows. It does not revive killed panes or freed workspace
   directories. Reconciliation then reports ghosts and orphans.

package/docs/architecture/ops-log.md

@@ -96,13 +96,32 @@ prefix previews, and `--yes` applies.
 - `restore` records and applies under the **same** HLC. `applyOp`
   excludes an op's own HLC from provenance. A fresher HLC would make
   the row outrank the op and lose every field to an insert default.
-- **Note tombstones are self-describing.** Every other `del` carries
-  `'{}'`, because its key plus earlier puts describe the row. A note's
-  key embeds its rowid (`<ws>/<task>#<id>`), and a rebuild or
-  reprojection reassigns rowids. The `task_notes` delete trigger
-  therefore records `OLD.*`, and `planUndo` falls back to the
-  tombstone payload when folding the puts finds nothing. For the same
-  reason `src/drift.ts` matches notes on the task-key prefix.
+- **Note tombstones are self-describing only when they must be.** Every
+  other `del` carries `'{}'`, because its key plus earlier puts describe
+  the row. A note's key embeds its rowid (`<ws>/<task>#<id>`), and a
+  rebuild or reprojection reassigns rowids, so the puts can sit under an
+  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
+  the task-key prefix.
+
+## Rewriting history (local only)
+
+The log is append-only except for two operator verbs in `src/compact.ts`,
+both dry-run by default, both backing up beside the DB and running the
+drift check after:
+
+- **`mu db compact`** blanks note tombstones a put under the same key
+  already explains: the slim form capture writes now, applied to older
+  rows. Undo and sync unaffected.
+- **`mu db forget <workstream...>`** deletes every op of named
+  torn-down workstreams (keys `<ws>` and `<ws>/...`). Their rows are
+  already gone from the tables, so rebuild and drift stay consistent;
+  `mu undo` of those teardowns is gone on purpose.
+
+Neither touches sync segments. A peer is not affected: watermarks only
+read forward, so a peer never re-sends forgotten history.
 
 ## Rebuild
 

package/docs/guide/cleanup.md

@@ -44,6 +44,25 @@ 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.
 
+## Keep mu.db small
+
+Teardown keeps history so `mu undo` works, and that history is most of
+`mu.db`. `mu doctor` names the largest torn-down workstreams once they
+are worth reclaiming.
+
+```bash
+mu db compact                        # dry run: redundant note tombstones
+mu db compact --yes
+mu db forget hail-smoke reltest      # dry run: per workstream, ops and size
+mu db forget hail-smoke reltest --yes
+```
+
+`compact` changes nothing you can see. `forget` deletes those
+workstreams' history for good: `mu undo` can no longer restore them.
+Both write a backup next to the DB first (`mu.db.pre-forget-<time>`),
+which is the only way back, and run the drift check after. Only this
+machine's DB shrinks; sync segments are untouched.
+
 ## Find workstreams you can remove
 
 The `housekeeping` section of `mu doctor` lists two kinds:

package/docs/guide/delegate.md

@@ -30,8 +30,18 @@ Delegates called in one turn run in parallel.
   as evidence.
 - pi's footer shows how many delegates this session is waiting on.
 - Each delegate costs a pane and a pi process. A session runs at most
-  `MU_DELEGATE_MAX` at once (default 16); past that, the tool refuses
-  and the rest wait for answers.
+  `MU_DELEGATE_MAX` at once (default 16). Further calls are queued, up
+  to four times the cap: the footer reads `16 delegates running, 4 queued`,
+  each starts when a slot frees, and `mu_delegate_cancel queued-N`
+  drops one. A queued call has no pane yet, so quitting pi or `/reload`
+  drops it; pi warns which ones never started.
+- A delegate that stops on an API error (overloaded, connection, auth)
+  keeps its pane. The answer names the error and leaves the choice to
+  the model: re-issue, or record the check as unverified. The footer
+  counts it as `1 failed` until the pane is closed.
+- Answers arrive as follow-up messages when pi would otherwise stop,
+  never mid-turn. To get several at once, set pi's `followUpMode` to
+  `"all"`.
 
 `MU_DELEGATE=0` hides the tool ([env vars](../reference/env.md)).
 
@@ -52,7 +62,9 @@ task's context.
 `needs_input`), never on an already idle agent. For pi, the `--json`
 row carries:
 
-- `outcome`: `done`, `empty`, `died`, `timeout`, or `pending`.
+- `outcome`: `done`, `empty`, `error`, `died`, `timeout`, or `pending`.
+  `error` means the run stopped on an API error after pi's own retries;
+  `lastError` holds the message and the pane is kept.
 - `lastText`: the final message, capped at 64 KiB.
 
 Exit codes: `0` met, `5` timeout, `6` pane died. Non-pi agents have no

package/docs/guide/dispatch.md

@@ -114,7 +114,8 @@ mu task wait auth/build auth/docs --first --on-stall exit --json
   commits. If the worker closed without committing, it says so.
 - Exit codes: `0` met, `5` timeout, `6` the owner's pane died,
   `7` the owner sat in `needs_input` for `--stuck-after` seconds
-  (default 300).
+  (default 120). Exit 7 is the default; `--on-stall warn` keeps
+  polling instead.
 
 Exit 7 has several causes: the worker finished but did not close, it
 asked a question, or it hit a prompt. In each case, run

package/docs/guide/getting-started.md

@@ -126,10 +126,15 @@ The exit code tells you what happened:
 | `0` | the task closed | merge the work |
 | `5` | `--timeout` expired (default 600 s) | wait again |
 | `6` | the worker's pane died and the task went back to `OPEN` | spawn and claim again |
-| `7` | the worker sat in `needs_input` for 5 minutes | `mu agent read worker-1 -w auth`, then answer it |
+| `7` | the worker sat in `needs_input` for 2 minutes | `mu agent read worker-1 -w auth`, then answer it |
 
-Without `--on-stall exit`, a stalled worker only prints a warning and
-the wait keeps running.
+`--on-stall exit` is the default; it is spelled out above so older mu
+versions behave the same. With `--on-stall warn`, a stalled worker only
+prints a warning and the wait keeps running.
+
+A pi worker that ends its turn while it still owns an `IN_PROGRESS`
+task gets one reminder to close it or say why not, so exit 7 mostly
+means it is blocked or asking something.
 
 ## Merge the commit
 

package/docs/reference/env.md

@@ -67,8 +67,8 @@ pi agent's `--command`. mu never reads them back.
 | 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; `mu_delegate` refuses past it. A positive integer. | `16` |
-| `MU_NUDGE` | `0` turns off the keep-driving nudge: one reminder when an orchestrator ends a turn with dispatched work still IN_PROGRESS. `mu doctor` reports it. | unset: on |
+| `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 both nudges: the keep-driving nudge (one reminder when an orchestrator ends a turn with dispatched work still IN_PROGRESS) and the close nudge (one reminder when a mu-spawned pi worker ends a turn still owning an IN_PROGRESS task). `mu doctor` reports it. | unset: on |
 | `MU_PI_HOME` | Root under which `mu link pi` writes `.pi/` and `.agents/`. | `$HOME` |
 | `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` |

package/package.json

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

@@ -173,8 +173,8 @@ rules hold even when you skip it:
 - **Checks are calls, not tasks.** Refuters, claim checkers, judges and
   skeptics are [delegate calls](recipes/tasks-or-calls.md#delegate-call)
   (`mu_delegate`, or a `scratch` spawn without it), all issued in one
-  turn; their verdict lands on the task they judged. Start near 8 at
-  once; `mu_delegate` refuses past `MU_DELEGATE_MAX` (default 16).
+  turn; their verdict lands on the task they judged. `mu_delegate` runs
+  `MU_DELEGATE_MAX` (default 16) at once and queues the rest.
 - **Findings are tasks.** A reviewer's or auditor's findings become
   `mu task add --triage` tasks blocking the review, decided with
   `mu task accept` or `close --as rejected|duplicate`. A review nobody

package/skills/mu/recipes/orchestrator-loop.md

@@ -33,8 +33,14 @@ keeps it.
 
 - **[Delegate calls](tasks-or-calls.md#delegate-call)** (read-only): 10 to 20 at once is reasonable.
   Token spend and provider rate limits bind first; start near 8 and
-  raise after a clean wave. `mu_delegate` refuses past
-  `MU_DELEGATE_MAX` (default 16).
+  raise after a clean wave. `mu_delegate` runs at most
+  `MU_DELEGATE_MAX` (default 16) and queues up to four times that
+  (`queued-N`, started as slots free); past that it refuses.
+- **Answers arrive when you stop**, as pi follow-up messages, never
+  mid-turn. pi's `followUpMode: "all"` delivers every waiting answer in
+  one turn instead of one turn each; each answer names its delegate and
+  ends with its `VERDICT: <id>` line, so a batch still maps back. Record
+  every verdict in the batch before acting on any.
 - **Workers with workspaces** build and test: about one per CPU core,
   fewer when each runs the full suite. A remote host has its own
   session cap ([remote-workers](remote-workers.md)).

package/skills/mu/recipes/recovery.md

@@ -19,6 +19,9 @@ when done in the wrong order.
   mu never runs ssh or rsync; `mu sync` prints the line.
   `--repair <peer>` is always safe. Agents, workspaces, and task
   ownership never travel.
+- **`mu db forget <ws...>`** deletes torn-down workstreams' ops for
+  good (no undo); `mu db compact` only blanks redundant tombstones. Both
+  back up beside the DB first. Forget only what the human named.
 - **`mu doctor --deep` DRIFT** (exit 5) is a capture bug: back up and
   report it. Do not rebuild; the live rows may hold work the log missed.
 - The `doctor` `disk` section is report-only: an orphan dir may hold the

package/skills/mu/recipes/tasks-or-calls.md

@@ -24,9 +24,12 @@ mu agent wait refuter-1 -w scratch --json   # answer in lastText
   then the next runs them in series.
 - **It leaves no task.** Its `scratch` pane stays attachable while it
   runs. `mu_delegate` closes it after a clean finish and keeps it on a
-  crash or timeout (`keep: true` always keeps it); the bash form needs
-  `mu agent close <name> -w scratch`. You record its verdict on the task
-  it judged.
+  crash, timeout, or API error (`keep: true` always keeps it); the bash
+  form needs `mu agent close <name> -w scratch`. You record its verdict
+  on the task it judged.
+- **An API error is yours to decide.** Re-issue the call, or record the
+  check as `UNVERIFIED` on its task, then close the kept pane
+  (`mu_delegate_cancel`, or `mu agent close`).
 
 ## The rule
 
@@ -60,8 +63,9 @@ Before a wave, count what it will add: units + gates + expected
 findings. If the count is more than a few hundred for one change, the
 steps that only check things are probably tasks by mistake.
 
-Run calls within the delegate cap (`MU_DELEGATE_MAX`, default 16; see
-[orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)).
+`mu_delegate` runs 16 at once (`MU_DELEGATE_MAX`) and queues the rest
+up to four times the cap; see
+[orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency).
 
 Done when every agent a recipe step spawns is either a task in the DAG
 or a delegate call whose verdict is recorded on a task.