@mu-crew/mu 1.6.0 → 3.0.0

package/docs/ARCHITECTURE.md

@@ -31,8 +31,8 @@ programmatic SDK are thin facades over the same core modules.
 │  │ mux/     │  │ schema   │  │ jj       │  │  capture        │  │
 │  │ tmux     │  │ queries  │  │ sapling  │  │  apply/sync     │  │
 │  │ herdr    │  │ tracks   │  │ git      │  │  doctor         │  │
-│  │ detect   │  │ claim    │  │ none     │  │                 │  │
-│  │ state    │  │          │  │          │  │                 │  │
+│  │ state    │  │ claim    │  │ none     │  │                 │  │
+│  │ sources  │  │          │  │          │  │                 │  │
 │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────────┬────────┘  │
 └───────┼─────────────┼─────────────┼─────────────────┼───────────┘
         ▼             ▼             ▼                 ▼
@@ -111,8 +111,38 @@ it mu is just an agent runner.
   `ROI = impact / effort` drives prioritization.
 - **One edge type**: `blocks`. `A → B` means A must close before B can
   start. Multiple edge types create ambiguity that defeats the purpose.
-- **Status lifecycle**: `OPEN → IN_PROGRESS → CLOSED`. Postponed or
-  won't-do rationale belongs in notes; `CLOSED` alone satisfies blockers.
+- **Status lifecycle**: `OPEN → IN_PROGRESS → CLOSED`. Status alone
+  decides edge satisfaction: any `CLOSED` task satisfies its blockers.
+- **Substate** qualifies status and never touches edges:
+  `OPEN/todo|parked`, `IN_PROGRESS/active`,
+  `CLOSED/done|wontfix|duplicate|superseded`. Rule: **store intent,
+  derive graph facts** — ready and blocked stay derived from edges.
+  `OPEN/parked` is excluded from `ready` but stays in `goals`.
+
+#### Substate integrity: deferred FK + apply-time pair repair
+
+The legal pairs live in the `task_substates` lookup table, seeded from
+code on every open (machine-local, never synced). `tasks` has a
+composite FK `(status, substate) → task_substates`,
+`DEFERRABLE INITIALLY DEFERRED`, which is the only guard on the pair.
+It is checked at COMMIT, so apply's one-field-at-a-time UPDATEs pass as
+long as the pair is legal when the transaction ends. That is why
+`applyOp` wraps each task put in `db.transaction` (and undo already runs
+in one): in autocommit the first per-field UPDATE would fail the FK.
+
+Every lifecycle write sets `status` and `substate` in one UPDATE, so
+one op carries both under one HLC. A pair can still split across ops:
+a status-only op from a v10 peer, an unknown substate from a newer
+peer, or a concurrent close and park on two machines. Before commit,
+`repairTaskPair` (`src/apply.ts`) sets the substate to the one implied
+by the newest op in the LOG that writes a substate, resolved against
+the row's current status, and falls back to the status default when
+that pair is illegal. Substate is therefore NOT per-field LWW.
+Reading the log instead of the row makes the result a pure function of
+the op set plus the row's status, so every peer converges on the same
+row whatever the arrival order. For the same reason the repair records
+**no op**: each peer computes the identical repair from the identical
+log. Recording one would only add a second writer racing the first.
 - **Notes** are append-only per task; survive across LLM sessions and
   agent restarts. The fix for context loss at the *task* level rather
   than the agent level.
@@ -121,7 +151,7 @@ it mu is just an agent runner.
 
 | View      | Returns                                                                |
 | --------- | ---------------------------------------------------------------------- |
-| `ready`   | OPEN tasks with no unresolved blockers — work that can start *now*     |
+| `ready`   | `OPEN/todo` tasks with no unresolved blockers — work that can start *now* |
 | `blocked` | OPEN tasks waiting on something                                        |
 | `goals`   | Tasks with no dependents — graph endpoints                             |
 
@@ -291,17 +321,16 @@ That difference is expressed as a **capability**, not a name check:
 | --- | --- | --- |
 | `NewWindowOptions.command` etc. | carries the command | **refused** if non-empty |
 | `startAgentInPane()` | not implemented | implemented |
-| liveness / readiness wait | mu polls scrollback | the mux blocks until ready |
+| liveness / readiness wait | mu checks pane life, startup errors, then murmur readiness when available | the mux blocks until ready |
 
 `spawnAgent` branches on `mux.startAgentInPane !== undefined`. When it
-is absent (tmux) the command rides along on the creation verb and the
-path is exactly what it always was. When present, mu creates the pane
-bare, then calls `startAgentInPane` — and **skips**
-`awaitSpawnLiveness` / `awaitSpawnReadiness`, because such a backend
-returns only once it has itself detected the agent and judged it ready
-for input, which is strictly stronger than what scrollback polling can
-prove. `MU_SPAWN_LIVENESS_MS` / `MU_SPAWN_READINESS_MS` are therefore
-tmux-tier knobs.
+is absent (tmux), the command rides along on the creation verb. The
+liveness check verifies that the pane survived and scans for startup
+errors; when murmur is available, readiness also waits for the pane's
+`@murmur_pane_state`. Without murmur, readiness is skipped and the first
+send uses its input-timing checks. When `startAgentInPane` is present,
+mu creates the pane bare, calls it, and skips the tmux checks because
+the backend returns only after the agent is ready.
 
 The creation verbs **refuse** a non-empty command on a backend that
 cannot honour it rather than dropping it silently: a dropped command
@@ -407,7 +436,7 @@ src/cli/tui/
 ├── tab-strip-layout.ts         # pure window-around-active layout helper
 ├── help.tsx                    # ?/F1 keymap overlay (scrollable on short panes)
 ├── use-popup-filter.tsx        # shared '/' substring filter hook + applyFilter + FilterPrompt
-├── use-status-filter.tsx       # task-status toggles (o/i/c) for task-list popups
+├── use-status-filter.tsx       # status toggles (o/i/c) + substate toggles (p/w) for task-list popups
 ├── use-notes-drill.ts          # shared notes-drill memo (5 task popups consume it)
 ├── use-popup-action-queue.ts   # consume mouse PopupAction queue once per render
 ├── cards/                      # 10 dashboard glance cards (one slot each)
@@ -579,15 +608,12 @@ surrogate INTEGER ids once and then stay on ids. See
 
 ## Reconciliation
 
-`mu agent list` always reconciles the registry against tmux reality before
-returning. Three steps, in order:
+`mu agent list` always reconciles the registry against mux reality before
+returning. Two steps, in order:
 
 1. **Prune ghosts.** For each `agents` row, if its `pane_id` no longer
-   exists in tmux, delete the row.
-2. **Detect status from scrollback.** For each surviving agent, capture
-   the pane and run the per-CLI detector. Update `agents.status` if
-   the detected value differs from the stored one.
-3. **Surface orphans.** For each tmux pane in the workstream's session
+   exists in the mux, delete the row.
+2. **Surface orphans.** For each pane in the workstream's mux session
    that has no matching `agents` row but whose pane title looks like
    an agent name, add it to the orphans list. **Do not auto-adopt** —
    `mu agent list` shows orphans under a separate "(orphans)" section and
@@ -596,19 +622,21 @@ returning. Three steps, in order:
 `src/reconcile.ts` is the only implementation. Key properties:
 
 - **Reality wins**: the mux is the source of truth for what panes
-  exist. The DB records what we last *observed*. Reconciliation closes
-  the gap on every `mu agent list`.
-- **Status detection is backend-dependent**, expressed as the optional
-  `MuxBackend.paneStatus?()`. A backend that omits it (tmux) means "ask
-  the detector": `src/detect.ts` scrapes scrollback (`busy` /
-  `needs_input` / `needs_permission` via a known pi marker, with a
-  Braille-spinner fallback for other CLIs). A backend that implements it
-  (herdr) classifies panes natively across every agent kind it
-  recognises, and mu takes its word — `src/detect.ts` is bypassed
-  entirely on that backend. herdr's `working` → `busy`, `blocked` →
-  `needs_permission`, `idle` / `done` / `unknown` → `needs_input`.
-  `unknown` must never become `free`: herdr documents that it does not
-  prove completion, and no detector of either kind may mint `free`.
+  exist. Reconciliation closes the gap on every `mu agent list`.
+- **Agent state is reported, not scraped or persisted.** `src/agent-state.ts`
+  reads herdr's `paneStatus()` on herdr. On tmux, one `list-panes -a`
+  reads `@murmur_pane_state` and `@murmur_pane_since` for every local
+  agent. Only agents without a local option use `murmur status --json`;
+  that result is cached for 10 seconds. See murmur's
+  [stable contract](https://github.com/mu-crew/murmur/blob/main/ARCHITECTURE.md#contract).
+- **Mapping:** murmur `working` → `busy`, `blocked` →
+  `needs_permission`, and `idle` / `done` / `crashed` → `needs_input`.
+  herdr supplies mu's runtime states directly.
+- **Absence is `unknown`.** Readings carry reasons such as `murmur not
+  installed`, `murmur pi extension not linked`, `murmur has no row`,
+  `ambiguous: N hosts`, `remote snapshot stale`, and `pane gone`.
+- **`agents.status` is deprecated.** Inserts write `spawning` to satisfy
+  the schema. No code updates or reads the column as runtime state.
 - **No silent adoption**: orphans are reported, never claimed.
 - **`mu doctor` calls the same routine** and reports counts.
 
@@ -627,7 +655,7 @@ separately below.
 
 | Module                | Responsibility                                                                            |
 | --------------------- | ----------------------------------------------------------------------------------------- |
-| `src/db.ts`           | Connection (better-sqlite3, WAL), **schema v10** (10 tables + 3 views), `resolveWorkstreamId`. Installs capture on every writable open. Owns `SYNCED_ENTITIES` / `MACHINE_LOCAL_ENTITIES` / `PORTABLE_TABLES` / `MACHINE_LOCAL_TABLES`. Refuses a pre-v10 DB (exit 4). |
+| `src/db.ts`           | Connection (better-sqlite3, WAL), **schema v11** (11 tables incl. the `task_substates` lookup + 3 views), `resolveWorkstreamId`. Installs capture on every writable open. Owns `SYNCED_ENTITIES` / `MACHINE_LOCAL_ENTITIES` / `PORTABLE_TABLES` / `MACHINE_LOCAL_TABLES`. Refuses a pre-v11 DB (`SchemaTooOldError`) or a newer one (`SchemaTooNewError`), both exit 4. |
 | `src/hlc.ts`          | The **HLC** (VOCABULARY § HLC), serialized as sortable TEXT `<wall_ms:15>.<counter:6>.<machine_id>`. `nextHlc` / `receiveHlc` / `compareHlc` / `parseHlc` / `formatHlc`. Clock state lives in `machine_identity`. |
 | `src/capture.ts`      | **Op capture**: builds the triggers that record every write to a portable table as an op in the same transaction. |
 | `src/apply.ts`        | **The apply path** — capture's counterpart: given one op, local or from a peer, make the tables reflect it. Also owns `reprojectDeferredOps` ([§ ambient sync hook](#the-ambient-sync-hook)). |
@@ -645,10 +673,10 @@ separately below.
 | `src/disk-recon.ts`   | **Disk↔DB reconciliation** — the only module that reads the STATE DIR and compares it to the DB, in both directions: a `vcs_workspaces` row whose path is gone (`ws-rows`), a dir with no row (`ws-dirs`, reusing `listAllOrphanWorkspaces`), plus residue nothing references (`ws-empty` / `db-copies` / `exports` / `locks`). Emits `FleetHazard` so doctor's renderer, `--json` and the TUI card need no new shape. Default tier is `readdir` + `stat` at depth 2 (~1ms); `measureWorkspaceUsage` recurses for bytes and is `--disk` only, because its cost scales with the checkouts. **Report-only by construction** — every finding carries its cleanup command and the module runs none of them. |
 | `src/op-context.ts`   | The **op context** seam: `withOpContext(db, {intent, actor, group}, fn)` labels every op in a scope, restored in a `finally`. Nested scopes inherit the group, which puts a cascade under one `mu undo`. `withCaptureSuppressed` is the echo guard. |
 | `src/mux.ts`          | **Mux backend hub** — re-exports `src/mux/*`, same shape as `src/vcs.ts`. The public `MuxBackend` surface every call site imports. |
-| `src/mux/*.ts`        | **Multiplexer backends**: `types.ts` (the `MuxBackend` interface + `MuxError` / `PaneNotFoundError`), `detect.ts` (`MU_MUX` → `HERDR_ENV` → `$TMUX` → `PATH` ladder + test seam), `tmux.ts`, `herdr.ts`. The backend owns topology, the send protocol, capture, **pane id** validation (tmux `%15` vs herdr `w1:p1`), the identity fallback, and optionally native pane status (`paneStatus?()`) and agent start (`startAgentInPane?()`) — so no global pane-id regex and no per-call-site branching. The send protocol is where the two diverge most: tmux needs a six-step paste/Enter dance to survive a modal swallowing the Enter, while herdr's `agent prompt --wait` is one atomic call. |
+| `src/mux/*.ts`        | **Multiplexer backends**: `types.ts` (the `MuxBackend` interface + `MuxError` / `PaneNotFoundError`), `detect.ts` (`MU_MUX` → `HERDR_ENV` → `$TMUX` → `PATH` ladder + test seam), `tmux.ts`, `herdr.ts`, and `input-timing.ts`. The backend owns topology, capture, **pane id** validation (tmux `%15` vs herdr `w1:p1`), identity fallback, and optional native agent state (`paneStatus?()`) and agent start (`startAgentInPane?()`). `input-timing.ts` reads pane text only to decide when tmux input can be submitted; it does not report agent state. |
 | `src/tmux.ts`         | Re-export of the tmux backend, kept for genuinely tmux-only concerns: the `MU_TMUX_SOCKET` test seam and the shared `sleep` / `setSleepForTests` poll seam. Everything else imports `src/mux.ts` and goes through `activeMux()`. |
-| `src/detect.ts`       | Pi status detector (`busy` / `needs_input` / `needs_permission`) + Braille-spinner fallback. Used when the mux cannot classify panes itself — i.e. always on tmux, never on herdr. |
-| `src/reconcile.ts`    | Ghost prune + status detect + orphan surface; "reality wins"                              |
+| `src/agent-state.ts`  | Runtime agent-state resolver. Reads herdr's native state or murmur's local pane options and remote JSON; maps source states, returns `unknown` with a reason, and caches remote murmur reads for 10 seconds. |
+| `src/reconcile.ts`    | Ghost prune + orphan surface; "reality wins"                              |
 | `src/agents.ts`       | Hub: CRUD + send / read / list / close + liveness + reaper. Re-exports `src/agents/*`; pane-title composition (`composeAgentTitle`) lives here. |
 | `src/agents/*.ts`     | Agent-lifecycle internals: `spawn.ts` (spawn, CLI resolution, liveness wait *or* backend `startAgentInPane`, pane create-or-reuse, rollback), `spawn-lock.ts` (per-session lock around topology+finalize), `wait.ts`, `adopt.ts`, `kick.ts` (signal a wedged pane's pgid), `errors.ts`. |
 | `src/dag.ts`          | Shared DAG read/render helpers: `loadFullDag` plus pure `renderForest` / `renderTaskTree`, reused by `mu task tree` and the TUI DAG popup. |
@@ -660,7 +688,7 @@ separately below.
 | `src/log-render.ts`   | **The ONE op → prose formatter.** `renderOp` maps an intent (+ key + payload fields) to `{verb, subject, detail}`; plus `renderOpLine`, `opSubject`, `parseOpKey`. Pure and colour-free, so CLI and TUI share one phrasing. |
 | `src/vcs/*.ts`        | One backend per file (`git.ts`, `jj.ts`, `sl.ts`, `none.ts`) plus `types.ts` (the `VcsBackend` interface), `helpers.ts`, and `index.ts` (detection precedence `jj` → `sl` → `git` → none; `backendByName`). |
 | `src/workspace/*.ts`  | Per-agent VCS workspaces, a registry on top of `vcs.ts`: `core.ts` (row shapes, paths, errors), `crud.ts`, `decorate.ts` (staleness + dirty), `orphans.ts`. |
-| `src/glyphs.ts`       | **The ONE glyph vocabulary.** `AGENT_STATUS_GLYPH` + `agentStatusGlyph()` for agent status, the `GLYPH` record for every other state symbol (blocked, dirty, stale, ok/warn/fail, filter toggles), and `superscriptDigit` for TUI card-header keys. All classic Nerd Font `nf-fa-*` — single-codepoint and one cell wide, so `cli-table3` columns line up. Keyed by MEANING, so re-pointing a symbol is a one-line edit. `busy` matches murmur's dash `running`: same panes, same symbol. |
+| `src/glyphs.ts`       | **The ONE glyph vocabulary.** `AGENT_STATE_GLYPH` + `agentStateGlyph()` for runtime agent state, the `GLYPH` record for every other state symbol (blocked, dirty, stale, ok/warn/fail, filter toggles), and `superscriptDigit` for TUI card-header keys. All classic Nerd Font `nf-fa-*` — single-codepoint and one cell wide, so `cli-table3` columns line up. |
 | `src/output.ts`       | NextStep type + `printNextSteps` + `errorNextSteps` plumbing for self-documenting output |
 | `src/shell-quote.ts`  | `shellQuote` — POSIX single-quoting for tokens interpolated into copy-pasteable next-step hints. |
 | `src/state.ts`        | SDK seam for `mu state`: `loadWorkstreamSnapshotFast` (pure SQL, TUI 1s tick), `loadWorkstreamSnapshotSlow` (subprocesses), `mergeSnapshotFastSlow`, `loadWorkstreamSnapshot`. Also parses exact `REMOTE:` task-note inventory and `REMOTE_BASE:` dispatch metadata. Opt-in: `withDirty`, `withDoctor`, `withRecentCommits`, `withAllTasks`. |
@@ -670,7 +698,7 @@ separately below.
 | `src/cli/tui/*.tsx`   | The interactive ink TUI, lazy-imported by `src/cli/state.ts`. **The only place ink/react are imported** — a ROADMAP pledge. Per-file roles: [§ TUI architecture](#tui-architecture). |
 | `src/cli/tasks/*.ts`  | Sub-cluster of the `mu task` namespace: `queries.ts` (list/next/owned-by + `mu me tasks` / `mu me next`), `lifecycle.ts` (close/open), `edit.ts`, `edges.ts` (+ delete cascade preview), `claim.ts`, `tree.ts`, `wire.ts` (Commander glue). |
 | `src/index.ts`        | SDK entrypoint (re-exports)                                                               |
-| `skills/mu/SKILL.md`  | Bundled skill teaching the LLM the model + verb list + jq pipelines                       |
+| `skills/mu/SKILL.md`  | Bundled skill teaching the LLM the orchestration model and operational traps; `mu --help` owns the verb reference. |
 
 ### What the rows above leave out
 
@@ -756,9 +784,8 @@ DB must never sit in `MU_SYNC_DIR`:
    better-sqlite3's `db.transaction(fn)()` wrapper.
 4. **Executes the operation** — agent ops shell out to tmux (and to
    jj/sl/git for workspaces); task ops are pure SQL.
-5. **Reconciles with reality** — for read-paths that need accuracy
-   (`mu agent list`, state views), queries tmux for live pane
-   state and updates the DB (ghost prune + status detect).
+5. **Reconciles with reality** — read paths prune ghosts and surface
+   orphans; runtime agent state is read from murmur or herdr without a DB write.
 6. **Records ops** — automatically, per [§ The ops log](#the-ops-log-read-this-first);
    machine-local changes go through `emitEvent`. `mu log --tail`
    subscribers see the new ops on the next 1-second poll.
@@ -773,7 +800,6 @@ The extension points. A new impl of each is small.
 | Seam                | Add a new impl by...                                                                                                          |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | `VcsBackend`        | Implementing `detect / createWorkspace / freeWorkspace / isClean / commitsBehind / rebaseTo / commitsSinceBase / recentCommits / showCommit` (~80–150 LOC; jj/sl/git/none are working examples)        |
-| Per-CLI `Detector`  | Adding patterns to `detectPiStatus` (vanilla pi `to interrupt)`; pi-meta + every TUI wrapper covered by Braille spinner glyph fallback `[\u2800-\u28FF]`)                  |
 | New typed verb      | An SDK function in the relevant `src/*.ts`; a `cmd<Verb>` in the matching `src/cli/<namespace>.ts`; one commander block in `buildProgram()`, wrapped in `handle()` and routed through `printNextSteps` |
 | New schema migration| Bump `CURRENT_SCHEMA_VERSION` in `src/db.ts` and mirror the shape in `CURRENT_SCHEMA`. Keep startup migration-free; extend the retained fresh-target sidecar only when an old released schema needs a bridge. Recipe: [scripts/README.md](../scripts/README.md) |
 | New syncable field  | Add the column to a portable table, extend the capture trigger's changed-column comparison, confirm the apply path writes it. The UPDATE trigger MUST emit only changed columns — a full-row payload silently regresses field merge to row-level LWW |

package/docs/ROADMAP.md

@@ -85,41 +85,6 @@ These have a clear design but haven't yet hit promotion criterion
 1 (friction in ≥2 real workflows). They earn implementation when
 real use surfaces them.
 
-### Per-CLI status detection (claude, codex, …)
-
-**Partly superseded on the herdr backend**, which classifies panes
-natively across the agent kinds it knows — mu takes its word there and
-skips scrollback scraping entirely. This item stays live for the tmux
-backend, where mu has to do its own detecting.
-
-mu is a pi orchestrator. The Braille-spinner fallback catches every
-TUI wrapper using standard spinner glyphs (U+2800–U+28FF), so
-pi-meta + solo + many vanilla TUIs (claude, codex) work without a
-per-CLI detector.
-
-For patterns the spinner fallback misses (permission prompts,
-specific busy markers), a per-CLI `Detector` registry keyed by
-CLI name (~50 LOC per CLI) is the obvious shape. Promote when a
-real specific-prompt-misclassification surfaces.
-
-Pattern sketch:
-
-| CLI    | Busy patterns                          | Permission patterns                                       |
-| ------ | -------------------------------------- | --------------------------------------------------------- |
-| Claude | `to interrupt`, `\(.*[↑↓].*tokens\)`   | `Allow once`, `Allow for this session`, `Esc to cancel`   |
-| Codex  | `esc to interrupt)`, `to cancel`       | `enter to confirm`, `enter to submit \| esc to cancel`    |
-| Pi     | (well-known mu-defined marker)         | (well-known mu-defined marker) — shipped                  |
-
-Critical subtleties any new detector must keep:
-
-- **Tail-window extraction**: take last ~100 lines, strip trailing
-  blanks, then take last ~20. Already implemented for pi in
-  `src/detect.ts`; the registry version factors it out.
-- **Permission detection uses a narrower window than busy
-  detection** to prevent already-answered prompts re-triggering.
-- **Permission overrides busy** — if a permission prompt is
-  visible, agent is `NeedsPermission`, not `Busy`.
-
 ### A third mux backend (zellij, wezterm, kitty)
 
 **Not promoted.** tmux and herdr are two real implementations, which
@@ -152,76 +117,22 @@ Listed so we don't pretend they're settled.
 
 ---
 
-## murmur, and remote agents (noted 2026-08-28, revised 2026-09-02)
-
-[murmur](https://github.com/mu-crew/murmur) is a sibling tool at
-`~/hacking/murmur`, on npm as `@mu-crew/murmur`: every coding
-agent on every machine in one attention-sorted list you can jump
-from. It is **built and in daily use** — the original note here
-described it as four design documents, and two of its conclusions
-moved since:
-
-- **Current state only, not an event log.** Each node publishes one
-  complete snapshot; a peer's answer is replaced in one write and
-  absence means absence. No history, watermarks or HLC. murmur's own
-  architecture says a generic `put`/`del` op-log "would simply *be*
-  `mu`" — so the two differ in substrate now, not just scope.
-- **No control channel, ever.** murmur observes and jumps; "not a
-  remote terminal" is a stated non-goal. The phase-2 prompt/abort
-  surface this note once counted on will not come from there.
-
-**What it would give mu**, both prerequisites for `mu spawn --on
-<host>`: **global agent addressing** (`agents.pane_id` is
-machine-local; murmur's `(host_id, agent_id)` is not, and identity is
-kept separate from `session/window/pane` so it survives a move), and
-**remote observation** (read the fold, get agents on other machines
-for free — including ones mu never spawned). It would not give mu the
-control channel; remote *driving* is unbuilt in both tools.
-
-**The cheap seam already works.** murmur's pi extension reads
-`MU_MANAGED_AGENT` / `MU_AGENT_NAME` / `MU_WORKSTREAM` / `MU_ROLE`
-off the pane and marks such agents `orchestrated` — "crew" — hidden
-unless `blocked` or `crashed`, since a supervisor consumes anything
-else. mu already exports the first three (`src/agents/spawn.ts`,
-`paneEnv`) and did nothing. Zero lines: the baseline any tighter
-coupling has to beat. `MU_ROLE` is the one murmur reads and mu does
-NOT set, so a crew row's role column is always null — a one-line fix
-if that column ever proves useful, not a reason to couple further.
-
-**No conflict with the sync design.** § Rejected sync substrates and
-§ Explicitly rejected both stand: murmur is a **separate binary**
-owning the ssh egress, and if mu ever consumes it, it does so by
-reading a local store, never by growing a network stack. A merge must
-keep the mu half transport-free. murmur independently reached mu's
-two conclusions from mu's own code: ambient rather than daemon (a
-collect rides ordinary invocations, rate-limited with jitter so the
-status bar cannot drive an ssh fan-out) and sync must never fail a
-command (every peer error caught and categorised).
-
-**Why not merge now.** Remote observation is the easy half and is now
-shipped; orchestration is the hard half and murmur removes none of
-it. Repos and credentials must exist on the target, worktree setup is
-a local filesystem operation, cherry-pick handoff assumes artifacts
-move between machines, and "which node runs this task" is a scheduler
-question mu does not have.
-
-**The step that tests it** is now available, not scheduled: make mu a
-*client* — drop its own status tracking and read murmur's snapshot.
-Small change, real experiment. But `paneStatus()` / `src/detect.ts`
-is not hurting, and trading a working local detector for a
-cross-machine dependency needs a reason from real use (promotion
-criterion 1), not the mere existence of the alternative. Keep the
-*observe* vs *orchestrate* seam in mind even then — it is what lets
-murmur watch agents mu never spawned, and a merge should say why it
-beats that.
-
-**Doors already open**, free: same language and runtime (TypeScript
-on npm, since pi is an npm package), `(host_id, agent_id)` addressing
-mu would need anyway, and the `MU_*` env contract.
-
-**Do not** start the merge, add ssh to mu, or fold murmur's schema
-into `mu.db` on the strength of this note. It records an intention
-and its preconditions.
+## murmur and remote agents
+
+[murmur](https://github.com/mu-crew/murmur) is a separate binary for
+current agent state across machines. It owns collection and ssh egress;
+mu remains transport-free and owns the task DAG, claims, workspaces, and
+panes.
+
+**Done in 2.0:** mu reads murmur for agent state. See
+[Agent state from murmur](specs/2026-09-28-agent-state-from-murmur.md).
+
+---
+
+### Next schema change
+
+Drop the deprecated `agents.status` column at the first v11 migration.
+In 2.0 it remains for schema compatibility and always contains `spawning`.
 
 ---
 
@@ -275,3 +186,7 @@ Listed so we don't rediscover them.
 - **A "hosted" mu** — your machine is the deployment.
 - **Anthropomorphic agent names (`alice`, `bob`)** — use
   role-based names (`worker-1`, `reviewer-1`).
+- **Pane scraping as an agent-state fallback** — absence of a state source is `unknown`, not a guessed state.
+- **Storing runtime agent state in `mu.db`** — the copy goes stale; murmur or herdr owns the current reading.
+- **Reading murmur's `state.db`** — use murmur's stable public contract, not its private schema.
+- **murmur as a hard dependency** — installs that only use the task graph do not need murmur or its native dependencies.

package/docs/USAGE_GUIDE.md

@@ -8,7 +8,7 @@ A practical, copy-pasteable tour of mu. Terms are canonical — see
 > **Status:** 1.0 (pre-release). Typed verbs span 7 namespaces
 > (`workstream`, `agent`, `task`, `workspace`, `log`, `me`, `db`) plus
 > bare top-level verbs (`state`, `doctor`, `sql`, `undo`, `sync`,
-> `rebuild`). Every verb accepts `--json`. Schema v10. See
+> `rebuild`). Every verb accepts `--json`. Schema v11. See
 > [CHANGELOG.md](../CHANGELOG.md).
 
 **In a hurry? Start at [§ 0. Common scenarios](#0-common-scenarios).**
@@ -240,6 +240,7 @@ environment
   $TMUX            : set
   $TMUX_PANE       : %21
   $MU_SESSION      : auth
+  agent state      : ok agent state from murmur 1.0.0
 
 db
   path             : /tmp/mu-play.db
@@ -385,11 +386,12 @@ table/key/field is the reproduction. See
 
 ### 0.6 Upgrading an older DB
 
-`mu` refuses to open a pre-v10 DB (`SchemaTooOldError`, exit 4) and
-leaves the file alone. The retained `scripts/migrate.ts` sidecar
-auto-detects v7, v8, or v9 and writes a fresh v10 DB. It never migrates
-in place. Legacy `REJECTED` / `DEFERRED` tasks become `OPEN` with a
-migration note while their original op payloads remain unchanged.
+`mu` refuses to open a pre-v11 DB (`SchemaTooOldError`, exit 4) or a DB
+newer than it understands (`SchemaTooNewError`, exit 4) and leaves the
+file alone. The retained `scripts/migrate.ts` sidecar auto-detects v7,
+v8, v9, or v10 and writes a fresh v11 DB. It never migrates in place.
+Legacy `REJECTED` tasks become `CLOSED/wontfix` and `DEFERRED` tasks
+become `OPEN/parked`; their original op payloads remain unchanged.
 Pre-1.0 archives restore as live workstreams under their original
 `source_workstream` names unless you pass `--drop-archives`.
 
@@ -469,11 +471,11 @@ alias mu="node $PWD/dist/cli.js"
 See [README.md § Install](../README.md#install) for the full set of
 install patterns.
 
-mu requires a terminal multiplexer. tmux ≥ 3.0 is the complete
-backend and what the rest of this guide assumes; herdr is supported
-for topology but not yet for spawn/send/read (see
-[§ 20](#20-multiplexer-backends-tmux-and-herdr)). Make sure you're
-inside a session before proceeding:
+mu requires a terminal multiplexer. tmux ≥ 3.0 is the backend the rest
+of this guide assumes; herdr also supports spawn, send, and read (see
+[§ 20](#20-multiplexer-backends-tmux-and-herdr)). On tmux, install
+murmur for runtime agent state. Make sure you're inside a session before
+proceeding:
 
 ```bash
 tmux       # if you're not already in one
@@ -1042,7 +1044,7 @@ convention):
 | Slot | Card          | Toggle | Popup     | Content                                              |
 | ---- | ------------- | ------ | --------- | ---------------------------------------------------- |
 | 0    | Commits       | `0`    | `Shift+0` | Recent project-root commits (git / jj / sl)          |
-| 1    | Agents        | `1`    | `Shift+1` | Active agents + status + cli + role                  |
+| 1    | Agents        | `1`    | `Shift+1` | Active agents + runtime state + cli + role           |
 | 2    | Tracks        | `2`    | `Shift+2` | Parallel tracks (union-find clusters)                |
 | 3    | Ready (Tasks) | `3`    | `Shift+3` | Ready-to-claim tasks (no open blockers)              |
 | 4    | Activity log  | `4`    | `Shift+4` | Recent ops rendered as prose                         |
@@ -1207,6 +1209,7 @@ for the newly active workstream.
 | filter    | `Esc`                        | cancel (clear query)                                           |
 | filter    | `Enter`                      | commit (keep filter, return to nav)                            |
 | task popup| `o` / `i` / `c`              | toggle OPEN / IN_PROGRESS / CLOSED                              |
+| task popup| `p` / `w`                    | toggle OPEN/parked / closed-not-done (DAG + All-tasks)         |
 | All-tasks | `b`                          | blocked filter cycle (all → only → hide)                      |
 | All-tasks | `s`                          | cycle sort key (roi → recency → age → id)                       |
 | git-show  | `t`                          | launch `tuicr -r <sha>` (alt-screen handoff)                   |
@@ -1226,7 +1229,7 @@ and recoverable from any shell.
 
 ## 6. Spawn a crew
 
-For a demo with live status detection, spawn pi agents:
+For a demo with live agent state, install and link murmur, then spawn pi agents:
 
 ```bash
 mu agent spawn worker-1 --workstream auth-refactor          # default --cli is pi
@@ -1250,7 +1253,7 @@ What just happened:
    session
 3. mu set the pane title to `worker-1` via `tmux select-pane -T worker-1`
    — **this is the claim protocol identity**
-4. mu inserted a row in `agents` with `pane_id=%15`, `status=spawning`
+4. mu inserted a row in `agents` with `pane_id=%15`; the deprecated `status` column remains `spawning`
 
 If the DB insert fails after the pane was created, mu kills the pane
 to avoid leaking. If the same name was already taken, mu rejects
@@ -1615,13 +1618,30 @@ enforce these — they're for the agents reading them.
 ## 12. Close out a task
 
 ```bash
-mu task close design                # OPEN/IN_PROGRESS → CLOSED
+mu task close design                # OPEN/IN_PROGRESS → CLOSED/done
 mu task close umbrella --if-ready   # close ONLY if every blocker
                                     # is CLOSED; else no-op + list
                                     # the still-blocking ids
+mu task close spike --as wontfix --why "superseded by the v2 design"
 mu task open design                 # CLOSED → OPEN (e.g. closed by mistake)
+mu task park polish --why "after the release"   # OPEN → OPEN/parked
+mu task unpark polish               # OPEN/parked → OPEN/todo
 ```
 
+Every task carries a **substate** next to its status, rendered as a pair.
+`OPEN` is `todo` or `parked`; `IN_PROGRESS` is `active`; `CLOSED` is
+`done`, `wontfix`, `duplicate`, or `superseded`. `--as` picks the closed
+substate. Anything but `done` requires `--why`, stored as a note in the
+same transaction. Any `CLOSED/*` satisfies a blocker, so a non-`done`
+close prints the dependents it unblocked.
+
+To keep dependents waiting, park the task instead of closing it. A
+parked task leaves `mu task next` and the ready set, and `mu task claim`
+refuses it without `--force`. It stays in goals, and a track whose non-closed
+tasks are all parked is marked `(parked)`. Park refuses `IN_PROGRESS`
+(release first) and `CLOSED` (open first). Filter with
+`mu task list --substate parked`.
+
 Both are idempotent (closing an already-CLOSED task prints a no-op and
 exits 0). Owner is left intact — use `mu task release <id>` to clear
 ownership when an agent bails mid-flight. `IN_PROGRESS` flips back to
@@ -1703,7 +1723,7 @@ mu sql "SELECT name FROM sqlite_master WHERE type IN ('table','view') ORDER BY t
 ### `mu agent wait`: the task-less counterpart to `mu task wait`
 
 Scratch helpers usually own no task, so `mu task wait` has nothing to
-watch. `mu agent wait` blocks on the agent's runtime status: an agent
+watch. `mu agent wait` blocks on the agent's runtime state: an agent
 **fires** when it goes **busy → any other state**. It must be observed
 busy first, so an already-idle agent does NOT fire instantly — you're
 waiting for *this* work to finish. Replaces `sleep` polling loops.
@@ -1719,8 +1739,8 @@ Mirrors `mu task wait`'s shape: `--any`/`--first` fire on the first
 agent (default: all must finish); `--first` prints the firing agent's
 ref; `--json` carries `nextSteps`; refs may be qualified
 `<workstream>/<name>`. Exit codes: `0` met, `5` timeout, `6` a watched
-agent's pane died. Status detection is pi-only (a non-pi pane always
-reads `needs_input`, so it never goes busy and the wait times out).
+agent's pane died. On tmux, murmur supplies the state. `unknown` never
+fires the wait; run `mu doctor` for the missing-source reason.
 
 **Don't reach for this verb to catch a worker that asked a question.**
 It fires on `busy → needs_input`, so it does detect the case — but it
@@ -1843,9 +1863,10 @@ For unattended waits, always pass `--on-stall exit`; otherwise the default
 warning leaves the wait polling. Two orthogonal flags govern the behaviour:
 
 * `--stuck-after <seconds>` — the **trigger**. An IN_PROGRESS task
-  whose owner has been in `needs_input` for `>= N` seconds is marked
-  as needing attention. Default `300` (5 min); pass `0` to disable
-  detection entirely (no warn AND no exit).
+  whose owner has been in `needs_input` for `>= N` seconds according
+  to the state source is marked as needing attention. `unknown` never
+  counts. Default `300` (5 min); pass `0` to disable detection entirely
+  (no warn AND no exit).
 * `--on-stall <action>` — the **action** when the trigger fires.
   Two values:
   * `warn` (default) — yellow attention warning to stderr (deduped per
@@ -1954,14 +1975,11 @@ You killed it from another tmux client, or its CLI crashed:
 mu agent list             # worker-1's row prunes itself (ghost detected)
 ```
 
-Reconciliation runs on every `mu agent list` / `mu`. Three steps:
+Reconciliation runs on every `mu agent list` / `mu`. Two steps:
 
 1. **Prune ghost rows** — DB row whose `pane_id` no longer exists in
-   tmux gets deleted
-2. **Detect status from scrollback** — for survivors, capture the
-   pane and re-derive status (busy / needs_input / needs_permission /
-   spawning) per the pi-status detector
-3. **Surface orphan panes** — panes in the workstream's session whose
+   the mux gets deleted
+2. **Surface orphan panes** — panes in the workstream's session whose
    `pane.command` looks like an agent CLI but that aren't in the
    registry. **Not** auto-adopted; mu lists them under "Orphan panes"
    with the `mu agent adopt <pane-id>` hint
@@ -2367,26 +2385,29 @@ winner, and the newer HLC takes it.
 
 ---
 
-## 15.7 Upgrading a v7, v8, or v9 DB
+## 15.7 Upgrading a v7, v8, v9, or v10 DB
 
-`mu` refuses to write a pre-v10 DB and leaves it untouched. Use the
+`mu` refuses to write a pre-v11 DB and leaves it untouched. Use the
 single retained sidecar against a backup:
 
 ```bash
 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'"
-npx tsx scripts/migrate.ts "$BACKUP" --out "${DB}.v10"
-MU_DB_PATH="${DB}.v10" mu doctor --deep
-mv "$DB" "${DB}.old-kept" && mv "${DB}.v10" "$DB"
+npx tsx scripts/migrate.ts "$BACKUP" --out "${DB}.v11"
+MU_DB_PATH="${DB}.v11" mu doctor --deep
+mv "$DB" "${DB}.old-kept" && mv "${DB}.v11" "$DB"
 mu doctor
 ```
 
-The script auto-detects v7, v8, or v9, opens it read-only, compares its
-SHA-256 before and after, and never overwrites a target unless `--force`
-is explicit. v9 history is retained unchanged; legacy statuses normalize
-only while projecting into v10, with one durable migration note per
-currently affected task. Valid v9 agents, workspaces, owners, peer
+The script auto-detects v7, v8, v9, or v10, opens it read-only, compares
+its SHA-256 before and after, and never overwrites a target unless
+`--force` is explicit. v9/v10 history is retained unchanged; legacy
+statuses map onto substates (`REJECTED` → `CLOSED/wontfix`, `DEFERRED` →
+`OPEN/parked`) while projecting into v11, and no migration notes are
+written. Where an undo or a note hid the legacy status, the script
+records a `migrate.substate` op; `--recover <db>` reruns that recovery
+on an already-migrated DB. Valid v9 agents, workspaces, owners, peer
 watermarks, and machine identity carry across, but pane ids and absolute
 workspace paths cannot be proven live until `mu doctor` reconciles them.
 The v7/v8 path keeps the older conservative omissions for agents and
@@ -2449,7 +2470,7 @@ rm -f /tmp/mu-demo.db
    set on spawn. Two agents cannot claim the same task.
 
 Everything else (`mu sql`, send/read, the bracketed-paste protocol,
-ghost reconciliation) is plumbing in service of those three.
+agent-state sources, ghost reconciliation) is plumbing in service of those three.
 
 ---
 
@@ -2461,7 +2482,6 @@ in real use:
 
 | Want                                          | Workaround                                                              | Status        |
 | --------------------------------------------- | ----------------------------------------------------------------------- | ------------- |
-| Multi-CLI status detection (per-CLI prompts)  | Braille spinner fallback covers pi/pi-meta + every TUI wrapper using standard spinner glyphs. Per-CLI permission-prompt patterns are pi-only. | partially shipped |
 | Pi extension (typed tools, HUD, wakeups)      | `mu state --tui` (interactive) covers the dashboard use-case; plain `mu state` (static) is the `watch` / `tmux display-popup` / `status-right` substrate. Other extension tools deferred. | partially shipped |
 | Markdown agent-definition discovery           | Spawn accepts `--cli` and `--command` directly; no template registry    | dropped       |
 <!-- doc-cli-drift:skip-start -->
@@ -2504,7 +2524,8 @@ your platform.
 
 mu drives exactly one multiplexer per invocation. tmux is the
 incumbent; [herdr](https://github.com/herdrdev/herdr) is the second
-backend, and spawn, send, read and status detection all work on it. The
+backend. Spawn, send, and read work on both; agent state comes from herdr
+on herdr and from murmur on tmux. The
 remaining gaps are narrow and listed under
 [Known limits on herdr](#known-limits-on-herdr) — the notable one is
 that `mu agent kick` is Linux-only there.
@@ -2554,7 +2575,7 @@ The backend is resolved once per process and cached.
 | Attach hint | `tmux a -t mu-<ws>` | `herdr session attach mu-<ws>` |
 | Pane borders | 4-side border showing agent name + status glyph | no-op — herdr owns its pane chrome; mu-managed panes carry the label instead |
 | Layout | `select-layout` | no-op — herdr splits are explicit, geometry is yours |
-| Status detection | scrollback scraping (`src/detect.ts`) | herdr classifies panes natively via `paneStatus()`; the scraper is bypassed |
+| Agent state | murmur pane options for local agents; `murmur status --json` for remote agents | herdr reports state via `paneStatus()` |
 | Focus | mu creates detached | `--no-focus` on every mutating call, always. `detached: false` still gets you a detached workspace; run `herdr workspace focus` yourself. |
 | Isolation seam | `MU_TMUX_SOCKET` (`-L <name>`) | `MU_HERDR_SESSION` (`--session <name>`, its own socket) |
 | `mu agent send` / `read` | six-step paste/Enter protocol | one atomic `agent prompt --wait` |