@mu-crew/mu 1.6.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.
@@ -106,18 +121,21 @@ npx skills add mu-crew/mu          # auto-detects pi / claude-code / codex / etc
 **Requirements:**
 - Node 22.12–26 (see `.nvmrc`), matching `engines` in `package.json`.
 - A terminal multiplexer: tmux ≥ 3.0, or [herdr](https://github.com/herdrdev/herdr)
-  (`mu doctor` reports which one is active). Spawn, send, read and
-  status detection work on both; the remaining herdr gaps are narrow
-  and listed in
+  (`mu doctor` reports which one is active). Spawn, send, and read work
+  on both. Agent state comes from herdr on herdr and from murmur on tmux;
+  the remaining herdr gaps are listed in
   [docs/USAGE_GUIDE.md § 20](docs/USAGE_GUIDE.md#20-multiplexer-backends-tmux-and-herdr).
 - pi (the agent CLI mu orchestrates)
 - For `--workspace`: jj, sl, or git on PATH (or `--backend none`)
 
-**Optional — [murmur](https://github.com/mu-crew/murmur), for
-more than one machine.** Every coding agent on every machine in one
-attention-sorted list. mu deliberately does not track hosts or watch
-other machines; murmur does both, as a separate binary that 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
@@ -130,13 +148,9 @@ murmur peer add dev  # an ssh target; identity is discovered
 murmur peer list     # which hosts are reachable, and when last seen
 ```
 
-Nothing to configure on mu's side: mu already exports
-`MU_MANAGED_AGENT` / `MU_AGENT_NAME` / `MU_WORKSTREAM`
-into every pane it spawns, so murmur marks those agents
-`orchestrated` — "crew" — and hides them unless they are blocked or
-crashed, since a supervisor consumes anything else. Useful for
-picking a host before spawning a remote worker, and for spotting a
-blocked agent on a machine you are not looking at.
+mu exports `MU_MANAGED_AGENT`, `MU_AGENT_NAME`, and `MU_WORKSTREAM`
+into every pane it spawns. murmur uses them to identify crew agents.
+See murmur's [stable contract](https://github.com/mu-crew/murmur/blob/main/ARCHITECTURE.md#contract).
 
 **Update:** `npm install -g @mu-crew/mu@latest` for the CLI;
 `npx skills update mu` for the skill.