@mu-crew/mu 3.13.3 → 4.1.0

package/docs/reference/naming.md

@@ -45,6 +45,11 @@ clears all blockers.
 `mu agent spawn <name> -w scratch`, and `mu workstream init scratch`
 is rejected. The `mu-` prefix is reserved too.
 
+Why the shape: tmux rewrites `.` to `_` in a session name and reserves `:` as a
+target separator, so a name holding either would make a session mu cannot look
+up again. mu adds `mu-` to name the session, so a `mu-` name would be
+double-prefixed.
+
 ## Workstream names
 
 Name a workstream `<project>-<purpose>`: `hail-auth`, `swayward-v2`,
@@ -54,7 +59,7 @@ groups by project. `workstream init` prints a hint for a name with no
 `-`.
 
 - **One workstream per effort.** Tear it down when the effort ships;
-  the ops log keeps the history and `mu undo` restores it. A long-lived
+  the ops log keeps the history. A long-lived
   catch-all becomes a log nobody reads: `mu state` hints once a
   workstream passes 300 tasks with fewer than 10% open.
 - **Ultrathink runs** get their own: `<project>-ut-<topic>`.
@@ -81,26 +86,28 @@ fixtures may use human names.
 
 ## File paths
 
-The state dir is `MU_STATE_DIR`, else `$XDG_STATE_HOME/mu`, else
-`~/.local/state/mu`.
+The state dir is `MU_STATE_DIR`, else `$XDG_STATE_HOME/mu-next`, else
+`~/.local/state/mu-next`. (`~/.local/state/mu` is 3.x's; the separate name keeps 4.0 off a 3.x DB.)
 
 | Path | Contents |
 | --- | --- |
 | `<state-dir>/mu.db` | The SQLite DB for every workstream |
-| `<state-dir>/workspaces/<workstream>/<agent>/` | Per-agent VCS workspace, created by `mu agent spawn --workspace` |
+| `<state-dir>/worktrees/<workstream>/<agent>/` | Per-agent git worktree, created by `mu agent spawn --worktree` |
+| `<state-dir>/delegate-sessions/<workstream>/<task>/` | A pane delegate's pi session (kept out of the caller's `/resume` list). `mu delegates prune` removes it with the call |
+| `<state-dir>/delegate-process/<hash>/` | A mux-free delegate's receipt, `pi.log` and pi session. `mu delegates prune` removes it with the call |
 | `<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 |
 
 Never put `MU_DB_PATH` inside `MU_SYNC_DIR`: syncing a live SQLite
-file and its `-wal` and `-shm` sidecars corrupts it. `mu doctor` checks
-for this.
+file and its `-wal` and `-shm` sidecars corrupts it. Every verb
+refuses to run (exit 4) when it happens.
 
 The cache dir is `$XDG_CACHE_HOME/mu`, else `~/.cache/mu`. Anything in
 it can be deleted at any time.
 
 | Path | Contents |
 | --- | --- |
-| `<cache-dir>/delegate-answers/` | Copies of delegate answers an Escape dropped from pi's queue, and `*.partial.md`: a delegate's last message before it timed out, died, failed or was cancelled (the delegate's pi session file keeps the original) |
+| `<cache-dir>/delegate-trace.log` | One JSON line per delegate wake send and pi lifecycle event, under `MU_DELEGATE_TRACE=1` |
 
 mu reads no agent-template directory (`~/.pi/agent/agents/`,
 `.pi/agents/`). A role is a name and a brief.

package/docs/reference/surface-contract.md

@@ -0,0 +1,153 @@
+# Surface contract
+
+The contract mu 4.0 is built to: what every result, wait, delegate and
+CLOSE block promises an agent caller, and the budgets on what it reads.
+Terms are in [VOCABULARY](../VOCABULARY.md), the module map in
+[ARCHITECTURE](../ARCHITECTURE.md), the reasons in the
+[design history](../history/mu-next-design/README.md). Where this page
+and the source disagree, the source is right and this page is a bug.
+
+A change that alters a contract here updates this page, ARCHITECTURE
+(module map) and VOCABULARY (term) in the same commit as the code. No
+module-map row, runnable guide snippet or `next` hint exists for code
+that has not shipped.
+
+## What ships
+
+Schema 13, `CAPTURE_VERSION` 5, 26 classified tables and 4 views
+(`PORTABLE_TABLES`: `workstreams`, `tasks`, `task_edges`, `task_notes`;
+every other table is machine-local, see `src/db.ts`). The verbs and
+their guarantees:
+
+- **Output.** `{ok,data,next}` on stdout for every `--json` verb and
+  every failure; `next` is computed once per result (`computeNext`).
+  Task, log, state and notes reads are capped records.
+- **Wait.** `mu wait` (typed refs, first event, one JSON result,
+  `resume`, `--all`, `--until-text`, `--wave`, `--blockers-of`,
+  `--on-stall exit|warn|steer|release`); `mu task wait` is its alias over
+  task refs; `mu agent wait` is the agent-keyed form over the same engine. Producers
+  (`spawn`, `send`, `claim --for`) arm a registered wait from real state.
+- **Tasks and agents.** Batch `task add`, `--blocks`, note kinds,
+  `--if <rev>` fences on membership changes and destructive verbs,
+  task-bound spawn with receipts and replay, `mu agent check`, soft
+  teardown with a preview revision, `mu human-needed`.
+- **Executor.** `mu task auto` and `mu next` (`--dry`, `--hold`,
+  `--workers`, `--refute`), `dispatch_host`.
+- **Delegates.** A `mu_delegate` call is a `kind=delegate` task with a
+  durable `call_id` (`mu delegates`, wave tally, `mu_delegate_reissue`),
+  and `mu delegates run <call-id>` runs one with no multiplexer.
+- **CLOSE block.** A pi worker's final `CLOSE:` lines are applied once
+  per settled run by the wait engine (`src/close-block.ts`).
+- **Remote.** Host profiles, remote spawn, `agent collect`, the close
+  rule, remote command gates, recovery records.
+- **Surfaces.** In-process `mu db query` (alias `mu sql`), five-tab
+  read-only dashboard, pi package (3.x's link verb is gone), `mu pi migrate`.
+
+- **Settle wait.** The pi extension's keep-driving nudge is the settle
+  wait (`extension/nudge.ts`): every completed settle of an orchestrator
+  runs `mu wait --first --on-stall exit --json` as its callers (no shell
+  line parsed, no once-per-prompt latch) and continues the turn with the
+  event. It stops when nothing is owed, a `mu human-needed` stop is open,
+  the user cancels, or the wait fails. A cancelled wait drains through
+  `MuRunOpts.drainMs`. Skipped under `MU_REMOTE=1` and in a nested pi.
+  Delegate answers arrive through it (`v_settle_delivery`): a `delegate`
+  event's continuation carries that call's report (capped, with the
+  `mu task notes` pointer); a wave's waits for its siblings and shows ONE
+  summary. The pi message is only a **wake** (a pointer, no answer text)
+  when no settle wait will show an answer.
+
+- **Delegates without a multiplexer.** `mu_delegate` registers in any
+  unmanaged pi. A spawn that fails `NoMultiplexerError` (only that error)
+  runs the call through `mu delegates run <call-id>`: one child
+  `pi --mode rpc`, no pane, no agents row, `transport: process`,
+  `attach: null`. Admission, record and cancel are unchanged; `keep` is
+  dropped; `/reload` leaves the run going; quit cancels it.
+
+## Fixed contract
+
+**Output.** Success `{ok:true,data,next}`; error `{ok:false,error,message,next,exit}`
+on stdout with the real non-zero exit. `next` is `NextPlan`
+`{mode:'seq'|'alt',commands:string[]}` or `null`; a `seq` is never
+truncated. Op payloads keep history names; output keys equal SQL
+column names, `id` is `local_id`. Ordinary result <= 4 KB, list record
+<= 400 chars, a cut says `more=N`/`cut=N` and names the exact
+retrieval command. Whole pinned brief, report and verdict are exempt
+from the cap (they are the content). Text record: escaped, one record
+per line; the exemption allows no multiline framing. NDJSON only for
+explicitly streaming logs; `mu wait` is one object.
+
+**Wait.** One `mu wait` over refs the caller owns. Default **first**
+event (`--first-of` alias); `--all` / `--all-of` keeps the all-of
+completion loop. Result `data`: `event` (alias `firing`: `kind`, `ref`,
+`incarnation`, `runs`), `exit`, `snapshots`, `resume`, `timedOut`,
+`cursor`. Event kinds: `closed settled input dead stall delegate
+pane-exit exited pane-text heartbeat interrupted`. `exited` is a remote
+command gate's own numeric status (`exit` is that code, 23 stays 23; under
+`--all` the first nonzero). Timeout is `ok:true` with `timedOut`
+and exit 0; dead 6, stall 7, interrupt 130. Heartbeat cap 1500 s.
+`--until-idle`, `--until-text <re>` (bounded RegExp over authoritative
+ctl `lastText` or the task report, never pane text for a settle; an agent
+with no answering ctl socket matches its pane tail and ends the wait as the
+distinct `pane-text` event, never `settled`; invalid or oversized rejects), `--status`, `--stuck-after`, `--on-stall exit|steer|release`
+(steer and release only on `auto` tasks on this `dispatch_host`;
+release reopens, never closes). SIGINT/SIGTERM emit one final snapshot;
+**SIGKILL cannot, and no output is promised.** Unknown is never idle.
+`send --wait` / `claim --for <w> --and-wait` enter the wait (one JSON document, the producer's
+receipt as `data.sent` / `data.claimed`); spawn, send and claim arm a registered wait from real
+state, not shell parsing (`v_wait_arming`: `src/cli/wait-arm.ts`).
+
+**Delegates.** Every `mu_delegate` call is a `kind=delegate` task in the
+caller's workstream or `scratch`, with durable `call_id`, optional
+`wave`, and states `queued starting running recording done failed
+refused cancelled`. A refusal past the cap is recorded and reissuable,
+never dropped. The verdict is written to the judged task before the
+delegate's report and close. The full multi-line evidence stays on the
+judged task; the answer is the delegate task's report. Pi echo is
+optional, one summary per wave. Admission control, arriving-answer
+safety and `murmur:pending {source,count}` are unchanged.
+
+**Next.** One rule set over current state computes `next` on every
+call (`computeNext`); the dashboard asks the same function. Agents
+follow state-advancing hints far more often than read hints, so `next`
+holds only state-advancing moves (a send's exact wait, a preview's
+apply, a claim's brief, `mu next` over authorised work, the wait over
+owned refs) and is usually null; reads are never hinted. Every command
+is executable as printed: POSIX-quoted, real ids, no `<…>`, `...` or
+`a|b`; a move mu cannot fill is omitted. Safe moves rank before
+destructive ones, and a destructive move carries `--if <rev>`. Never a
+resend.
+
+**Guards.** `--if <rev>` on membership-changing and destructive verbs;
+teardown and `agent close` print a preview revision first. A wrong id
+returns read-only candidates, never a fuzzy write. An ambiguous ctl
+delivery returns a receipt to check (`msgId`), never a resend.
+
+**Sync.** Every verb ingests peer ops before its body and flushes its
+own after, on the error path too; `mu db query` writes flush as well. A
+DB inside `MU_SYNC_DIR` is refused before anything is opened, and so is
+a `MU_SYNC_DIR` holding a 3.x segment (exit 4, nothing written).
+
+**CLOSE block.** Final lines of a settled pi run's `lastText`, `task=`
+the agent's own task; applied once per (agent, incarnation, runs) as
+report + close in one op group; malformed writes "no close (malformed)".
+`mu task close` stays. No automatic human decisions: the loop stops
+only for a caller-scoped human-needed task or when nothing it owns runs.
+
+**Budgets (pinned by tests).** SKILL 600 words, each recipe 250, all
+recipes 4,000 (`test/prose-budget.test.ts`; the remote recipe's separate
+200-word target is not met and not tested); per-verb `--help` description at most 3 lines at 80 columns
+(`test/help-budget.test.ts`); each `next` and error one line
+(`src/messages.ts`). They do not cap canonical docs such as this page.
+
+## Where each part lives
+
+Every shipped unit has its modules in the
+[ARCHITECTURE module map](../ARCHITECTURE.md#module-map) and its what-and-why
+in the [CHANGELOG](../../CHANGELOG.md) (unit ids such as `v_wait_surface`
+appear in both). Machine-local tables (`spawn_receipts`, `host_channels`,
+`human_needs`, `wait_registrations`, `wait_resumes`, `wait_action_receipts`,
+`remote_recovery`, and the older `delegate_calls`, `wait_cursors`,
+`agent_settles`, `host_profiles`, `task_auto`, `worktrees`) are classified in
+`MACHINE_LOCAL_TABLES` (`src/db.ts`); `test/entities.test.ts` fails on an
+unclassified one. The build-time ownership table and reconciliation notes
+are in git history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.13.3",
+  "version": "4.1.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"
@@ -45,10 +45,24 @@
     "dist",
     "skills",
     "prompts",
-    "docs",
+    "docs/guide",
+    "docs/reference",
+    "docs/VOCABULARY.md",
+    "docs/ARCHITECTURE.md",
     "README.md",
     "AGENTS.md"
   ],
+  "pi": {
+    "extensions": [
+      "./dist/extension/mu-pi.js"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts/*.md"
+    ]
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
@@ -56,31 +70,39 @@
     "test:fast": "vitest run --config vitest.fast.config.ts",
     "test:watch": "vitest",
     "test:watch:fast": "vitest --config vitest.fast.config.ts",
-    "lint": "biome check src test scripts extension",
-    "lint:fix": "biome check --write src test scripts extension",
-    "format": "biome format --write src test scripts extension",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "lint": "biome check src test scripts extension tools",
+    "lint:fix": "biome check --write src test scripts extension tools",
+    "format": "biome format --write src test scripts extension tools",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit && tsc -p tools/eval/tsconfig.json --noEmit",
     "prepare": "npm run build",
-    "test:stress": "tools/test-stress.sh"
+    "test:stress": "tools/test-stress.sh",
+    "eval": "node tools/eval/main.ts"
   },
   "dependencies": {
     "better-sqlite3": "^13.0.3",
     "cli-table3": "^0.6.5",
     "commander": "^15.0.0",
-    "execa": "^10.0.1",
-    "ink": "^7.1.1",
+    "ink": "^8.0.0",
     "picocolors": "^1.1.1",
-    "react": "^19.3.0",
-    "react-devtools-core": "^8.0.0",
+    "react": "^19.3.1",
     "signal-exit": "^4.1.0",
     "string-width": "^8.2.2"
   },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",
     "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^26.6.2",
     "@types/react": "^19.3.0",
     "@typescript/native": "npm:typescript@^7.0.2",
+    "execa": "^10.0.1",
     "fast-check": "^4.10.1",
     "tsup": "^8.5.1",
     "typescript": "npm:@typescript/typescript6@^6.0.2",

package/prompts/mu-debug.md

@@ -3,6 +3,8 @@ description: "Debug with mu: independent hypotheses from separate evidence, each
 argument-hint: "<symptom>"
 ---
 Debug this with mu. Load the mu skill, then read its
-`recipes/hypothesis-panel.md` in full and follow it.
+`recipes/tasks-or-calls.md` in full. One delegate call per independent
+hypothesis, each reading separate evidence and ending in `PREDICTS:`; a
+refuter attacks each survivor; fix the one that holds, then a review gate.
 
 Symptom: $@

package/prompts/mu-refute.md

@@ -3,6 +3,7 @@ description: "Find, refute, synthesize with mu: audit or fact-check with a refut
 argument-hint: "<what to audit or check>"
 ---
 Run a find-refute-synthesize pass with mu. Load the mu skill, then read
-its `recipes/refute.md` in full and follow it.
+its `recipes/findings.md` in full and follow it. Finders record findings,
+one refuter call per finding, report from the task graph.
 
 Scope: $@

package/prompts/mu-research.md

@@ -3,6 +3,8 @@ description: "Deep research with mu: fan out searches, check every claim, cited
 argument-hint: "<question>"
 ---
 Research this with mu. Load the mu skill, then read its
-`recipes/deep-research.md` in full and follow it.
+`recipes/tasks-or-calls.md` in full. One searcher call per angle, each claim
+as `CLAIM:` with source and quote, one checker call per claim; the report
+keeps confirmed claims only.
 
 Question: $@

package/prompts/mu-review.md

@@ -3,6 +3,7 @@ description: "Review panel with mu: parallel focused reviewers, refuted findings
 argument-hint: "[diff, PR, branch, or path]"
 ---
 Run a review panel with mu. Load the mu skill, then read its
-`recipes/review-panel.md` in full and follow it.
+`recipes/findings.md` in full. One reviewer call per angle on the target,
+duplicates merged, each finding refuted before it is reported.
 
 Target: ${@:-the uncommitted changes in this repo}

package/prompts/mu-rules-audit.md

@@ -1,8 +1,9 @@
 ---
-description: "Rules audit with mu: check a change against AGENTS.md rule by rule, or mine missing rules"
-argument-hint: "[check <target> | mine]"
+description: "Rules audit with mu: check a change against AGENTS.md rule by rule, a checker per rule"
+argument-hint: "[diff, PR, branch, or path]"
 ---
 Run a rules audit with mu. Load the mu skill, then read its
-`recipes/rules-audit.md` in full and follow it.
+`recipes/findings.md` in full. One checker call per AGENTS.md rule, then a
+skeptic pass; each violation is a finding.
 
-Mode and target: ${@:-check the uncommitted changes in this repo}
+Target: ${@:-the uncommitted changes in this repo}

package/prompts/mu-sweep.md

@@ -3,6 +3,7 @@ description: "Sweep with mu: the same change over many files or call sites, one
 argument-hint: "<change, and where>"
 ---
 Run a sweep with mu. Load the mu skill, then read its
-`recipes/fan-out.md` in full and follow it.
+`recipes/orchestrator-loop.md` in full. Enumerate the units with a command,
+one task per unit under an umbrella, a shared brief on the umbrella.
 
 Change: $@

package/prompts/mu-tournament.md

@@ -3,7 +3,9 @@ description: "Tournament with mu: competing attempts judged in pairs against a r
 argument-hint: "<what to choose or build>"
 ---
 Run a tournament with mu. Load the mu skill, then read its
-`recipes/tournament.md` in full and follow it. Ask me for the rubric
-first if the task does not imply one.
+`recipes/tasks-or-calls.md` in full. Ask me for the rubric first if the task
+does not imply one. Attempts are tasks, each naming what it rejected; each
+pairwise judge is a call, order swapped on a close one. Wild divergence means
+an under-specified brief: reframe and re-run.
 
 Task: $@

package/prompts/mu-until.md

@@ -3,6 +3,8 @@ description: "Loop with mu until a check is clean (tsc, lint, tests), with a sto
 argument-hint: "<stop rule, e.g. npx tsc --noEmit exits 0>"
 ---
 Loop with mu until this holds. Load the mu skill, then read its
-`recipes/loop-until-done.md` in full and follow it.
+`recipes/orchestrator-loop.md` in full. Write the stop rule and a
+no-progress rule on the umbrella first; one task per round; you run the
+check.
 
 Stop rule: $@

package/prompts/ultrathink.md

@@ -3,7 +3,7 @@ description: "Run a large or risky job the mu way: DAG, fan-out, adversarial rev
 argument-hint: "<job>"
 ---
 Ultrathink this job with mu. Load the mu skill, then read its
-`recipes/ultrathink.md` in full and follow it. Every unit, review, and
+`recipes/orchestrator-loop.md` in full and follow it. Every unit, review, and
 round goes in the task DAG; checks (refuters, judges, skeptics) are
 delegate calls. Keep driving until the stop rule holds.