@mu-crew/mu 1.6.0 → 2.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  │  │          │  │          │  │                 │  │
 │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────────┬────────┘  │
 └───────┼─────────────┼─────────────┼─────────────────┼───────────┘
         ▼             ▼             ▼                 ▼
@@ -291,17 +291,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
@@ -579,15 +578,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 +592,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 v10 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.
 
@@ -645,10 +643,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 +658,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 +668,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 +754,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 +770,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

@@ -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
@@ -469,11 +470,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 +1043,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                         |
@@ -1226,7 +1227,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 +1251,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
@@ -1703,7 +1704,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 +1720,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 +1844,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 +1956,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
@@ -2449,7 +2448,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 +2460,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 +2502,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 +2553,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` |

package/docs/VISION.md

@@ -137,19 +137,11 @@ lives behind `MuxBackend` in `src/mux/`. Two implementations, not an
 anticipatory abstraction: a third earns its way in on its own
 friction evidence.
 
-### 6. Pi-first, and what the mux knows
+### 6. Pi-first, with reported agent state
 
-Mu's own status detection (`busy` / `needs_input` / `needs_permission`)
-is pi-only, plus a Braille-spinner fallback that catches most TUI
-wrappers. `--cli <name>` accepts other strings, but on the tmux
-backend no other CLI ships with a detector, so an unrecognized pane
-tends to read `needs_input`.
-
-A mux that classifies panes itself changes this. The herdr backend
-reports agent state natively across the agent kinds it knows, so on
-that backend mu takes the mux's word and skips scrollback scraping
-entirely. Detection is a property of the **mux backend**, not a fixed
-property of mu.
+mu does not infer agent state from pane text. The herdr backend reports
+state through the mux. On tmux, murmur's pi extension reports state from
+inside the agent process; without murmur, state is `unknown` with a reason.
 
 `--cli` and `MU_<UPPER_CLI>_COMMAND` stay useful for swapping the pi
 binary: set `MU_PI_COMMAND=<name>` once and every spawn picks it up.
@@ -244,9 +236,9 @@ mu does not own:
 - **Tool routing decisions.** Pi (and any other CLI you spawn) owns
   tool allowlists, MCP servers, extensions. Mu doesn't proxy or
   inspect them.
-- **Output interpretation.** Mu reads pane contents to detect
-  `busy / needs_input / idle / done` (a 4-state classification).
-  It does not parse model output for facts, claims, or tool calls.
+- **Output interpretation.** Mu does not parse pane contents for agent
+  state, facts, claims, or tool calls. murmur or herdr reports runtime
+  agent state.
   The `--evidence` payload is whatever the agent says it is; mu
   records it without interpretation.
 
@@ -344,12 +336,10 @@ orchestrator stays in charge.
    `~/.local/state/mu/mu.db`. Cross-machine state moves as
    append-only JSONL segments in a shared folder; you own transport.
 
-3. **Pi-first.** mu's own status detection targets pi. `--cli pi` is
-   the meaningful default; `--cli` accepts other strings as a key for
-   the `MU_<UPPER_CLI>_COMMAND` env var resolver. On tmux no other CLI
-   has a detector; on a backend that classifies panes itself (herdr),
-   mu defers to it. Either way we optimize for
-   false-negative-then-poll over false-positive-then-act.
+3. **Pi-first.** `--cli pi` is the meaningful default; `--cli` accepts
+   other strings as a key for the `MU_<UPPER_CLI>_COMMAND` env var
+   resolver. Agent state comes from murmur on tmux and herdr on herdr;
+   absence is `unknown` rather than an inferred value.
 
 4. **Send is delivered, not acknowledged.** `mu agent send` gets the
    text into the pane and warns loudly when it cannot confirm

package/docs/VOCABULARY.md

@@ -46,16 +46,14 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **owner**             | The **worker** name in `tasks.owner`. Set by claim. NULL when the task is unowned OR was claimed via `--self` (anonymous, attributed via `ops.actor` instead). Owners are **machine-local** — they reference `agents`, so ownership never syncs. | "claimer", "assignee"                              |
 | **anonymous claim**   | A claim made via `--self` where the **actor** isn't a registered **worker**. `tasks.owner` stays NULL; the actor is recorded in `ops.actor` for the auto-emitted `task.claim` op. The orchestrator-doing-direct-work pattern. | "self-claim" (in code; "anonymous claim" in prose), "unowned claim" |
 | **release**           | Verb: clear `tasks.owner`                                                | "unclaim", "unassign"                              |
-| **free**              | Verb: mark an agent's `status = 'free'` (idle, available)                | "park", "idle" (verb)                              |
-| **status**            | Persisted enum on `agents` (busy/needs_input/free/...)                   | "state" (use only "lifecycle state")               |
-| **lifecycle state**   | A position in the agent state machine                                    | "state" alone, "phase"                             |
+| **agent state**       | Runtime state reported by the **state source**: `busy`, `needs_input`, `needs_permission`, or `unknown`. It is not persisted in mu. | "agent status", "lifecycle state" |
 | **role**              | `full-access` or `read-only` capability flag                             | "permission" (avoid), "tier"                       |
 | **persistent**        | Agent that stays alive across tasks                                      | "long-lived" (only in prose)                       |
 | **one-shot**          | Agent that exists for a single task and then terminates                  | "ephemeral", "transient"                           |
 | **workspace**         | A VCS-isolated checkout (jj workspace / sl worktree / git worktree / cp). **In mu, "workspace" is always the VCS sense** — never the mux sense. herdr calls its session-level container a "workspace" too; in mu docs and code that is a **mux session**. | "branch" (it has one but isn't one), "checkout" (only for `none` backend), the herdr sense |
 | **ghost**             | An `agents` row whose `pane_id` no longer exists in the **mux**. Pruned by **reconcile**, which runs in `mu agent list` and `mu doctor`. | "dead agent" (a dead agent may still have a pane), "stale row" |
 | **reaper**            | The part of reconcile that releases a **ghost**'s tasks: `IN_PROGRESS → OPEN`, owner cleared. Makes `mu task wait` exit 6. | "garbage collector", "janitor" |
-| **needs attention**   | The condition `mu task wait --stuck-after` detects: an IN_PROGRESS task whose **owner** has sat in `needs_input` for >= N seconds. Deliberately cause-NEUTRAL — the predicate cannot distinguish a worker that finished without closing, one waiting on an answer, or one at an approval prompt, and those need opposite responses. So every surface names the observation and points at `mu agent read <owner>`. A worker asking a question is desirable behaviour, so never phrase this as worker negligence. Formerly `agent_close_discipline_gap`, which presumed the first cause; now `agent_attention_required`. | "stuck" / "stalled" (the `stuck` JSON field and exit-7 `STALL_DETECTED` keep their names for compatibility), "close discipline", "negligent worker" |
+| **needs attention**   | The condition `mu task wait --stuck-after` detects: an IN_PROGRESS task whose **owner** has been in `needs_input` for at least N seconds according to murmur's `since`. `unknown` never counts. The predicate cannot distinguish a worker that finished without closing, one waiting on an answer, or one at an approval prompt, so every surface points at `mu agent read <owner>`. | "stuck" / "stalled" (the `stuck` JSON field and exit-7 `STALL_DETECTED` keep their names for compatibility), "close discipline", "negligent worker" |
 | **workspace orphan**  | A directory under `<state-dir>/workspaces/<workstream>/` with no row in `vcs_workspaces`. Blocks subsequent `--workspace` spawns. Surfaced by `mu workspace orphans -w X`, `mu state -w X`, and `mu doctor`'s `ws-dirs` row. | "stray dir", "leftover workspace"                  |
 | **stranded** | A **workspace orphan** whose parent *workstream* row is also gone. Reported separately because no workstream-scoped verb can reach it — `mu workspace orphans --all` and `mu doctor` are the only surfaces. | "double orphan", "abandoned" |
 | **missing workspace dir** | The INVERSE of a **workspace orphan**: a `vcs_workspaces` row whose `path` is not on disk (usually a hand-run `rm -rf` where `mu workspace free` was wanted). More dangerous than an orphan, because every read surface reports the row as a healthy workspace and the next send fails inside the VCS backend rather than at the row that lied. `mu doctor`'s `ws-rows` row. | "broken workspace", "dangling row" |
@@ -64,7 +62,7 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **stale workspace**   | A workspace whose `parent_ref` is N commits behind the project's default branch HEAD (per the workspace's local refs cache). Rendered as a color-coded `behind` column (green ≤2, yellow 3–9, red ≥10) in `mu workspace list` and `mu state`; ≥10 triggers a one-line warn in `mu state`, `mu task claim --for`, and `mu agent send` (or refusal on the two dispatch verbs with `--strict-staleness`). Pure observation — mu never auto-fetches. | "out of date", "drifting"                          |
 | **refresh**           | `mu workspace refresh <agent>` — rebase the agent's workspace onto a fresh base (default = backend's tracked main; `--from <ref>` overrides) WITHOUT touching the agent or pane. Refuses on dirty WC; surfaces conflicts as exit 5 with a resolve-in-place hint. The `none` backend errors (no VCS to rebase). | "recycle", "reset" (overloaded)                     |
 | **backend**           | Implementation of `MuxBackend` or `VcsBackend`. Always qualify which (**mux backend** / **VCS backend**) when both are in scope. | "driver", "provider"                               |
-| **detector**          | Per-CLI pattern matcher for busy/permission/ready, used when the **mux backend** cannot report status itself. On tmux that is always (`detectPiStatus` in `src/detect.ts`, covering vanilla pi + any TUI wrapper using Braille spinner glyphs); on herdr the mux classifies panes natively across its known agent kinds, so the detector is bypassed. The seam is the optional `MuxBackend.paneStatus?()`: absent means "ask the detector". herdr's states map `working` → `busy`, `blocked` → `needs_permission`, and `idle` / `done` / `unknown` → `needs_input` — `unknown` never becomes `free`, since herdr documents that it does not prove completion, and no detector of either kind may mint `free`. Other CLIs spawned via `--cli <other>` may misclassify on tmux; trust scrollback over the emoji. | "matcher", "parser"                                |
+| **state source**      | The system that reports **agent state**: herdr's `paneStatus()` on herdr, or murmur on tmux. mu reads local murmur pane options in one tmux call and uses `murmur status --json` only for remote workers. No source yields `unknown` with a reason. | "scraper" |
 | **op**                | The atomic unit of change: one row in the `ops` table, written by a trigger inside the same transaction as the mutation it records. Carries `(hlc, machine_id, group_id, actor, intent, entity, key, op, payload)`. A **semantic partial update** — the payload holds only the columns that actually changed, which is what makes per-field merge free. | "event", "delta", "change" (all overloaded)         |
 | **ops log**           | The `ops` table: the single append-only record of every change, and the substrate **sync**, **undo**, and history are all queries or replays over. Canonical and ACID because it lives in `mu.db` alongside the tables it records. | "event log", "journal", "WAL" (reserved by SQLite)  |
 | **intent**            | The semantic label on an **op** (`task.close`, `task.reparent`, `agent.spawn`). Set once per public SDK function via **op context**, not per mutation. `mu log` renders prose from it through one formatter. | "verb" (overloaded by CLI verbs), "action"          |
@@ -165,36 +163,25 @@ window.
 
 ---
 
-## Status, lifecycle, and the verbs that touch them
-
-### Agent status enum (persisted in `agents.status`)
-
-Glyphs are named, not spelled out: the codepoints live in
-`src/glyphs.ts` (`AGENT_STATUS_GLYPH`) and a table that duplicates
-them has drifted from production once already.
-
-| Value             | Glyph slot            | Meaning                                        |
-| ----------------- | --------------------- | ---------------------------------------------- |
-| `spawning`        | nf-fa-hourglass_start | Pane created, agent process booting            |
-| `busy`            | nf-fa-play            | Actively working (detector saw busy marker)    |
-| `needs_input`     | nf-fa-moon_o          | Idle prompt visible, waiting for input         |
-| `needs_permission`| nf-fa-lock            | Permission prompt visible (e.g., "Allow once") |
-| `free`            | nf-fa-check_circle    | Available; retained for persisted/runtime status compatibility |
-| `managed`         | —                     | Under external orchestration; mu observes only |
-| `unreachable`     | nf-fa-question_circle | Transport down, status uncertain               |
-| `terminated`      | nf-fa-times_circle    | Process gone, awaiting reaping                 |
-
-All of them are classic Nerd Font `nf-fa-*` (Font Awesome 4)
-codepoints, single-codepoint and one cell wide, so `cli-table3`
-columns line up. `busy` is deliberately the same glyph murmur's dash
-paints for a `running` pane — they drive the same panes, so one symbol
-means one thing on both surfaces. Non-agent state glyphs (blocked,
-dirty, stale, ok/warn/fail, filter toggles) come from the `GLYPH`
-record in the same file.
-
-**Source of truth:** the substrate — the **mux backend**, plus the
-**detector** when that backend cannot classify panes itself. The DB is
-a cache; `mu agent list` reconciles on every call.
+## State, lifecycle, and the verbs that touch them
+
+### Agent state
+
+Agent state is runtime data and is not persisted. The codepoints live in
+`src/glyphs.ts` (`AGENT_STATE_GLYPH`).
+
+| Value | Glyph slot | Meaning |
+| --- | --- | --- |
+| `busy` | nf-fa-play | Actively working |
+| `needs_input` | nf-fa-moon_o | Waiting for input |
+| `needs_permission` | nf-fa-lock | Waiting for a human answer |
+| `unknown` | nf-fa-question_circle | No state source or no usable reading; the reason accompanies the state |
+
+The state source is herdr on the herdr backend and murmur on the tmux
+backend. mu maps murmur `working` to `busy`, `blocked` to
+`needs_permission`, and `idle`, `done`, and `crashed` to `needs_input`.
+The retained `agents.status` column is deprecated and always contains
+`spawning`; no runtime read uses it.
 
 ### Agent lifecycle verbs