@mu-crew/mu 2.0.0 → 3.0.0

package/AGENTS.md

@@ -58,7 +58,7 @@ mu/
 ├── src/                   # all source (root files: SDK + shared infra; one
 │                          # level of subdirs OK for cohesive clusters — see
 │                          # `src/cli/`, `src/agents/`, `src/tasks/`, `src/mux/`)
-│   ├── db.ts              # SQLite schema + openDb (single CREATE-IF-NOT-EXISTS block; v10)
+│   ├── db.ts              # SQLite schema + openDb (single CREATE-IF-NOT-EXISTS block; v11)
 │   │                      # also owns SYNCED_ENTITIES / PORTABLE_TABLES / MACHINE_LOCAL_TABLES
 │   ├── mux.ts             # multiplexer backend hub (re-exports src/mux/*)
 │   ├── mux/               # cohesive cluster: one file per multiplexer
@@ -448,11 +448,12 @@ proves itself.
 
 ### "Update the schema"
 
-1. Current schema version is **v10** (`CURRENT_SCHEMA_VERSION` in
-   `src/db.ts`): 10 tables + 3 views. The schema is the
+1. Current schema version is **v11** (`CURRENT_SCHEMA_VERSION` in
+   `src/db.ts`): 11 tables + 3 views. The schema is the
    `applySchema(db)` block — idempotent CREATE-IF-NOT-EXISTS plus
-   targeted `DROP TABLE IF EXISTS`. `openDb` REFUSES any pre-v10 DB
-   with `SchemaTooOldError` (exit 4); there is no in-process
+   targeted `DROP TABLE IF EXISTS`. `openDb` REFUSES any pre-v11 DB
+   with `SchemaTooOldError` and any newer one with `SchemaTooNewError`
+   (both exit 4); there is no in-process
    migration ladder.
 2. Bump `CURRENT_SCHEMA_VERSION` in `src/db.ts` and mirror the new
    shape in `CURRENT_SCHEMA`. Prefer script-free bumps: additive

package/README.md

@@ -38,6 +38,9 @@ For the full copy-paste flow, see [Quick start](#quick-start).
 
 ## What mu is
 
+mu excels at organising large pieces of work and keeping your agents
+on track.
+
 - **Parallelism that doesn't trip over itself.** Per-agent VCS
   workspaces plus a task DAG with deterministic parallel-track
   detection keep agents off each other's toes.
@@ -77,6 +80,17 @@ For the full copy-paste flow, see [Quick start](#quick-start).
 
 ## When mu earns its overhead
 
+mu pays off when the work is bigger than one agent's context: many
+steps, dependencies between them, several agents, or a job that runs
+for days. The DAG holds the plan, so no single agent has to. Each
+agent claims one ready task, works in its own workspace, writes notes
+on the task as it goes (findings, decisions, dead ends), and closes
+it with evidence. Every claim, note and close is appended to the
+audit log. If an agent drifts, stalls, or loses its pane, the plan,
+the notes, and the history of who did what are still there. You, or
+the next agent, pick up where it stopped instead of explaining
+everything again.
+
 **Use mu for** — multi-phase investigations; tasks worth gating with
 review; parallel audit or implementation/reviewer splits with isolated
 workspaces; anything where "what was decided and why" needs to outlive
@@ -94,9 +108,10 @@ adds ceremony.
 ## Install
 
 ```bash
-# 1. The CLI.
-npm install -g @mu-crew/mu
+# 1. The CLI, and murmur for agent state on tmux (see below).
+npm install -g @mu-crew/mu @mu-crew/murmur
 mu --version
+murmur init && murmur link pi
 
 # 2. The skill (teaches your coding agent how to drive mu).
 npx skills add mu-crew/mu          # auto-detects pi / claude-code / codex / etc.
@@ -113,11 +128,14 @@ npx skills add mu-crew/mu          # auto-detects pi / claude-code / codex / etc
 - pi (the agent CLI mu orchestrates)
 - For `--workspace`: jj, sl, or git on PATH (or `--backend none`)
 
-**Agent state on tmux — [murmur](https://github.com/mu-crew/murmur).**
-mu owns the work; murmur reports what each agent is doing. Without murmur,
-agent state shows `unknown`; tasks, claims, `mu task wait`, workspaces,
-spawn, and send work the same. murmur also provides one attention-sorted
-list across machines and owns the ssh egress.
+**Agent state on tmux needs [murmur](https://github.com/mu-crew/murmur),
+even on one machine.** mu owns the work; murmur reports what each agent is
+doing. mu does not read panes itself, so without murmur every agent's state
+is `unknown`, and everything built on state goes quiet: `mu agent wait`
+never fires, `mu task wait --stuck-after` / `--on-stall exit` never detects
+a worker waiting on you, and spawn skips its readiness check. Tasks, claims,
+`mu task wait` on status, workspaces, spawn and send still work. murmur also
+provides one attention-sorted list across machines and owns the ssh egress.
 
 ```bash
 # on every node that runs agents