@mu-crew/mu 1.6.0 → 3.0.0

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

@@ -28,13 +28,16 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **remote worker**     | A worker whose process and workspace are on another machine while its pane and orchestrator DB remain local. The durable inventory record is a task-note line in the exact `REMOTE: <host>:<path>` shape; pair it with `REMOTE_BASE: <agent>:<sha>` so `mu task claim --for <agent>` can print the one-shot poll-and-close step. `mu state` lists `REMOTE:` lines and `mu state --json` exposes them as `remoteWorkers`. | "remote agent record", "host registry" |
 | **actor**             | The party that *caused* a state change. May or may not be a registered worker. Recorded in `ops.actor` for every op. The orchestrator running mu from a top-level shell is an actor but not a worker. | "caller", "author" (only on notes)            |
 | **crew**              | *Informal* collective noun for the agents in a workstream                | (no API surface; prose only)                       |
-| **task**              | A node in the DAG. Has mandatory `impact` and `effort_days`. Status one of `OPEN`, `IN_PROGRESS`, `CLOSED` (see **task status** below). | "issue", "ticket", "item"                          |
-| **task status**       | One of 3 states. **OPEN** = ready to be claimed; **IN_PROGRESS** = claimed and active; **CLOSED** = finished and the only state that satisfies a `--blocked-by` edge. Record postponed or won't-do rationale in a **note**, then close the task. | "state"                                            |
+| **task**              | A node in the DAG. Has mandatory `impact` and `effort_days`. Has a **task status** and a **substate**, shown as a pair (`OPEN/parked`, `CLOSED/wontfix`). | "issue", "ticket", "item"                          |
+| **task status**       | The lifecycle phase, one of 3: **OPEN** = not started; **IN_PROGRESS** = claimed and active; **CLOSED** = ended. Status alone decides edge satisfaction: any `CLOSED/*` satisfies a `--blocked-by` edge. | "state"                                            |
+| **substate**          | What the **task status** means for this task. Never null; each status has a default. `OPEN`: `todo` (default), `parked`. `IN_PROGRESS`: `active`. `CLOSED`: `done` (default), `wontfix`, `duplicate`, `superseded`. Rendered as a pair `STATUS/substate`; a default substate renders as the bare status. Valid pairs live in the `task_substates` table. Never affects edges. Refer to a non-`done` close as a *closed substate*. | "resolution", "reason", "sub-status" |
+| **park**              | Verb: set an `OPEN` task to `OPEN/parked` with a required `--why` note. A parked task leaves **ready** and `next`, `claim` refuses it without `--force`, and it stays in **goals**. Its dependents stay blocked. Refuses `IN_PROGRESS` (release first) and `CLOSED` (open first). | "defer", "snooze", "shelve" |
+| **unpark**            | Verb: return an `OPEN/parked` task to `OPEN/todo`.                        | "resume", "reactivate"                             |
 | **task DAG** / **graph** | The directed acyclic graph of tasks. | "task list", "todo", "tree" (it's a DAG, not a tree) |
 | **edge**              | A `blocks` relationship between two tasks. The single edge type. `A blocks B` = A must close before B can start. | "dependency" (use only in prose)                   |
 | **track**             | An independent subtree of the DAG identified by parallel-track detection | "branch", "lane"                                   |
 | **diamond merge**     | When two tracks share a prerequisite, parallel-track detection collapses them into one track to prevent two agents from colliding on the shared dependency. | "join", "converge"                                 |
-| **ready**             | An OPEN task with no unresolved blockers. Exposed as the `ready` SQL view. | "unblocked", "available"                           |
+| **ready**             | An `OPEN/todo` task with no unresolved blockers (parked tasks are excluded). Exposed as the `ready` SQL view. | "unblocked", "available"                           |
 | **goals**             | Tasks with no outgoing blocks-edges (graph endpoints). Exposed as the `goals` SQL view. | "leaves", "targets"                               |
 | **sort key**          | Argument to `mu task list / next / ready --sort <key>`. One of `roi` (impact / effort_days, default for `next` / `ready`), `recency` (`updated_at` DESC — "what did I touch most recently"), `age` (`created_at` ASC — "what's gone stale"), `id` (`local_id` ASC, default for `task list`). The two time-based keys also render an `updated`/`created` relative-time column in the table view. | "order by", "sort by"                              |
 | **subtree** / **scope** | The set of tasks reachable from a root via blocks-edges                | "subgraph" (only for technical descriptions)       |
@@ -46,16 +49,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 +65,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 +166,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
 
@@ -211,8 +201,11 @@ a cache; `mu agent list` reconciles on every call.
 | Verb                                  | Effect                                                |
 | ------------------------------------- | ----------------------------------------------------- |
 | `mu task add <id> ...`                | Creates a new OPEN task. `--note <text>` appends an initial note in the same transaction; `--note-author <name>` overrides the note author. |
-| `mu task close/open <id>`             | Lifecycle transition                                 |
-| `mu task claim <task> [--for <agent>]`     | Atomic: sets `owner`, flips status to `IN_PROGRESS`   |
+| `mu task close <id> [--as <substate> --why <text>]` | Sets `CLOSED` (default `CLOSED/done`). A non-`done` `--as` requires `--why` and prints the dependents it unblocked. |
+| `mu task open <id>`                   | Reopens a task to `OPEN/todo`.                         |
+| `mu task park <id> --why <text>`      | `OPEN` → `OPEN/parked`. Leaves ready/next; stays in goals. |
+| `mu task unpark <id>`                 | `OPEN/parked` → `OPEN/todo`.                           |
+| `mu task claim <task> [--for <agent>] [--force]` | Atomic: sets `owner`, flips status to `IN_PROGRESS/active`. Refuses a parked task unless `--force`. |
 | `mu task release <task>`              | Clears `owner`. Auto-flips `IN_PROGRESS` → `OPEN` (so the task re-enters the ready set); `CLOSED` is preserved. `--reopen` forces `OPEN` from `CLOSED`. |
 | `mu task note <task> "..."`           | Appends to `task_notes`. Never edits prior notes.     |
 | `mu task notes <task> [--tail N \| --since <iso> \| --since-claim]` | List notes (oldest first). `--tail N` (alias `--last N`) prints last N; `--since <iso>` filters by `created_at`; `--since-claim` auto-resolves to the most recent `task claim` event timestamp. `--since` and `--since-claim` are mutually exclusive. |

package/docs/specs/2026-09-28-agent-state-from-murmur.md

@@ -0,0 +1,333 @@
+# Agent state from murmur (mu 2.0.0, murmur 1.0.0)
+
+Status: approved design, 2026-09-28. Task `crew/mu_status_from_murmur`.
+
+## Problem
+
+mu works out what an agent is doing by reading the last 20 lines of its
+pane (`src/detect.ts`), and stores the answer in `agents.status`. This fails
+in three ways:
+
+- **Remote workers.** The local pane holds an ssh client that renders a
+  nested tmux. `skills/mu/REMOTE_WORKERS.md` records wrong answers in both
+  directions in one session: a stall fired at 300 s on a worker that was
+  mid-turn, and `mu agent list` showed `needs_input` for a worker that was
+  working.
+- **Wrappers.** Each pi wrapper with different chrome has needed its own
+  patch (the Braille-spinner fallback).
+- **Stale copies.** The stored status is only as recent as the last
+  reconcile, and `mu agent show` needed a fix to re-detect before it printed.
+
+murmur's pi extension reports state from inside the agent on its own host,
+and it publishes the state on each pane (`@murmur_pane_state`) and across
+machines (`murmur status --json`). mu already exports the variables that
+murmur uses to recognise mu's workers (`MU_MANAGED_AGENT`, `MU_AGENT_NAME`,
+`MU_WORKSTREAM`).
+
+## Decision
+
+**murmur is the answer for agent state.** mu owns the work: the DAG, task
+owners, workspaces and panes. murmur owns what an agent is doing. mu does
+not read pane text to decide agent state, and it does not store agent state.
+
+Sources of runtime state, in order:
+
+1. herdr's `paneStatus()` on the herdr backend. This is herdr's own report,
+   not scraping.
+2. On tmux, murmur. The local read is the pane's `@murmur_pane_state` and
+   `@murmur_pane_since`. The remote read is `murmur status --json`, matched
+   on `agent_name` and `workstream`.
+3. Otherwise `unknown`, and mu says why.
+
+This follows ZEN rules 2 (report state, don't scrape it), 3 (absence means
+absence) and 5 (standalone tools that compose). mu's core needs none of this
+to work: the DAG, `claim`/`close`, `task wait`, workspaces, spawn, send and
+read.
+
+## Scope
+
+In:
+
+- A state resolver module that replaces every state read from
+  `detectPiStatus`:
+  - reconcile, including `mu agent list` and `mu state`
+  - `mu agent show`
+  - `mu agent wait`
+  - stall detection in `mu task wait`
+  - spawn readiness
+  - `computeAgentIdle`
+  - the TUI cards and popups
+- Stop writing `agents.status` after the initial insert, and stop reading it
+  everywhere.
+- A new `--json` shape for agents: `state` and `source`, with no `status`.
+- `mu doctor` checks for murmur and its pi extension.
+- Updates to the README, the skill, `REMOTE_WORKERS.md`, ARCHITECTURE,
+  DECISIONS and ROADMAP.
+- murmur 1.0.0: a contract section in its ARCHITECTURE, and the release.
+
+Out:
+
+- The two input-timing checks in `send`. `awaitPaneQuiescence` waits out
+  pi's re-init modal, which eats the Enter. `isTextStranded` detects a
+  prompt that was typed but never submitted. Both are about typing into a
+  terminal, not about agent state, and murmur cannot see either. They keep a
+  private helper for spinner and work-marker text. It is used only by
+  `send`, returns no status, and is not exported.
+- `detectSpawnStartupError` in `src/agents/spawn.ts`. It scans a new pane
+  for provider and auth errors (a dud spawn), which is a spawn failure, not
+  agent state. It stays for the same reason as the `send` checks.
+- Dropping the `agents.status` column. mu has no migration path: v10 is both
+  the minimum and the current schema. The drop waits for the first change
+  that needs a v11 anyway, and ROADMAP records it.
+- Reading murmur's SQLite files. Reading them would couple mu to murmur's
+  private schema.
+- Any feature added to murmur for mu. murmur only documents what it already
+  publishes.
+
+## Design
+
+### Caller's view
+
+```ts
+const states = await readAgentStates(db, agents);        // one tmux read, ≤1 murmur call
+const s = states.get(agent);  // { state: "busy", source: "murmur", since: 1790581553851 }
+if (s.state === "unknown") hint(s.reason);               // "murmur not installed" | ...
+```
+
+`mu agent list --json`:
+
+```json
+{ "name": "worker-1", "pane": "%4", "state": "busy", "source": "murmur",
+  "since": "2026-09-28T07:45:53Z" }
+{ "name": "worker-9", "pane": "%9", "state": "unknown", "source": "none",
+  "reason": "murmur not installed" }
+```
+
+### State resolver (`src/agent-state.ts`, new)
+
+```ts
+type RuntimeState = "busy" | "needs_input" | "needs_permission" | "unknown";
+type StateSource = "murmur" | "herdr" | "none";
+interface StateReading {
+  state: RuntimeState;
+  source: StateSource;
+  since: number | null;  // ms; when the state last changed, from the source
+  reason?: string;       // set when state is unknown
+}
+function readAgentStates(db: Db, agents: AgentRow[]): Promise<Map<AgentRow, StateReading>>;
+```
+
+- It takes a batch of agents, so a whole display costs one read.
+- **herdr backend:** calls `paneStatus()` per pane, as today.
+- **tmux, local:**
+  - One `list-panes -a -F '#{pane_id}\t#{@murmur_pane_state}\t#{@murmur_pane_since}'`
+    call.
+  - A pane with a value is read from murmur. A pane with no value is a
+    candidate for the remote read.
+  - murmur publishes `@murmur_pane_state` only for a pane its extension has
+    claimed (fixed in murmur `3c8c1a7`).
+- **tmux, remote:** the agents with no local value.
+  - One `murmur status --json` call, cached per mu process for
+    `MURMUR_CACHE_MS` (10 s), so the 1 s poll in `mu agent wait` does not
+    start Node every tick. murmur limits its own ssh collect to one per
+    30 s ± 10 s.
+  - A row matches when `agent_name` and `workstream` are equal and `local`
+    is false.
+  - Zero matches gives `unknown`, with reason "murmur has no row". More
+    than one match gives `unknown`, with reason "ambiguous: N hosts". A
+    peer that murmur reports as stale gives `unknown`, with reason "remote
+    snapshot stale".
+- **`since`:**
+  - For a local pane, it is `@murmur_pane_since`: the time the pane entered
+    its current state (see murmur 1.0.0 below).
+  - For a remote row, it is the row's `updated_at`. That is an
+    approximation, because it also moves on runtime updates. It is used
+    only for remote idle and stall timing, where scraping had no answer at
+    all.
+  - Only the remote path starts `murmur`. A machine with no remote workers
+    never runs it.
+- **When murmur is missing:** no `murmur` on PATH, or the pi extension not
+  linked (`~/.pi/agent/extensions/murmur.ts` missing).
+  - Every tmux agent gets `unknown`, with reason "murmur not installed" or
+    "murmur pi extension not linked".
+  - The resolver checks this once per process.
+
+### Mapping
+
+| murmur | mu |
+| --- | --- |
+| `working` | `busy` |
+| `idle` | `needs_input` |
+| `done` | `needs_input` |
+| `blocked` | `needs_permission` |
+| `crashed` | `needs_input` |
+
+- `done` and `idle` both mean "waiting for a prompt".
+- `blocked` means waiting on a human answer, which is what a permission
+  dialog means.
+- For `crashed`, pi is gone but the pane may still be alive. The mapping
+  makes waits and stall detection fire. Pane death stays with the reaper.
+
+herdr's mapping does not change: `working` gives `busy`; `blocked` gives
+`needs_permission`; `idle`, `done` and `unknown` give `needs_input`.
+
+### Consumers
+
+- **reconcile.** It keeps pruning dead panes and refreshing titles. It
+  stops detecting and writing status. `report-only` mode stays read-only.
+- **`mu agent list`, `mu state`, `mu agent show`, TUI.** These show
+  `state` from the resolver. An `unknown` state shows `?` and a one-line
+  hint, printed once per invocation: "agent state needs murmur (see mu
+  doctor)".
+- **`mu agent wait`.** It fires on busy → not busy, as today. `unknown`
+  never fires. If every watched agent is `unknown` at the first tick, it
+  prints the reason once and keeps waiting until `--timeout`.
+- **`mu task wait` stall detection.** The stall timer measures time in
+  `needs_input` using `since`. `unknown` never counts as a stall. The rest
+  of `task wait` is unchanged: it polls the DB, which is exact.
+- **Spawn readiness.**
+  - With murmur present, spawn waits until the pane's `@murmur_pane_state`
+    is set, within the existing budget. murmur publishes it right after the
+    extension claims the pane.
+  - Without murmur, spawn skips the wait and keeps the "pane died on spawn"
+    check. The first `send` waits for pi through its input-timing checks.
+- **`computeAgentIdle`.** An agent is idle when it is `needs_input` and
+  `since` is older than the threshold, taken from the resolver. It was
+  `agents.updated_at`.
+- **`mu doctor`.** It reports murmur on PATH, the version (≥ 1.0.0), the pi
+  extension linked, and whether the identity exists. A failure is a
+  warning, not an error.
+
+### `agents.status` in 2.0
+
+- It is deprecated in place.
+- Inserts write the fixed value `'spawning'` to satisfy `NOT NULL` and the
+  CHECK. Nothing updates it and nothing reads it.
+- Mid-spawn is already marked by the `pending:` pane-id placeholder.
+- `free` (from `adopt`) and the "sticky until activity" overwrite rule
+  disappear, because nothing overwrites anything.
+- `db.ts` marks the column deprecated.
+- The SDK drops `AgentStatus`, `shouldOverwriteAgentStatus`,
+  `updateAgentStatus` and the `detectPiStatus` export. It exports
+  `RuntimeState`, `StateReading` and `readAgentStates`.
+
+### murmur 1.0.0
+
+1.0.0 means the interfaces mu reads are stable. A breaking change to them
+needs a major version.
+
+- **New: `@murmur_pane_since`.** This is the time (ms since the epoch)
+  the pane entered its current `@murmur_pane_state`.
+  - It is set in the same tmux command as the state, and only when the
+    state changes: `if -F '#{!=:#{@murmur_pane_state},<new>}' 'set -p
+    @murmur_pane_since <now>' ; set -p @murmur_pane_state <new>`.
+  - The compare-and-set runs inside tmux, so every writer (the extension,
+    the collector, `clear`) agrees, and a repeated write of the same state
+    leaves the value alone. This was checked on a scratch server:
+    `working → working → idle` kept the first time and then moved.
+  - It is unset together with the state. It needs no store schema change.
+- **The contract**, listed in the "Contract" section of its ARCHITECTURE:
+  - `@murmur_pane_state` and its five values, and `@murmur_pane_since`
+  - the `status --json` fields `panes[].{pane, local, agent_name,
+    workstream, driver, activity, attention, freshness, updated_at}`
+  - the `MU_*` variables murmur reads
+- **Release:** it ships main (the idle-label fix) plus
+  `@murmur_pane_since`, with a CHANGELOG entry that says what 1.0 means.
+  There is no 0.6.2.
+- **Order:** murmur 1.0.0 first, then mu 2.0.0.
+
+## Cost
+
+Measured on the dev machine with 5 local agents:
+
+| Read | Before (scrape) | After |
+| --- | --- | --- |
+| local state, 5 agents | 5 × `capture-pane`, 13 ms | 1 × `list-panes`, 2 ms |
+| `agent wait`, per 1 s tick | 5 captures, plus detection in JS | 1 × `list-panes` |
+| local idle and stall timing | a DB timestamp that only moved on reconcile | `@murmur_pane_since`, read in the same call |
+| remote agents | captures that gave wrong answers | `murmur status --json`, 90 ms, cached for 10 s |
+
+`mu agent list` and `mu state` take about 0.8 s, and most of that is mu's
+startup (`mu --version` takes 0.30 s). This change removes work from both
+commands. No local path starts a second Node process.
+
+## Testing
+
+- **Unit tests** for the resolver, using a fake tmux and a fake `murmur`
+  runner:
+  - the local value
+  - a remote match
+  - no match, an ambiguous match and a stale peer
+  - murmur missing and the extension not linked
+  - the herdr path
+  - cache reuse within `MURMUR_CACHE_MS`
+  - no `murmur` process started when every agent has a local option
+- **Consumer tests:**
+  - `agent wait` never fires on `unknown`
+  - stall detection uses `since` and ignores `unknown`
+  - spawn readiness with murmur and without it
+  - `computeAgentIdle`
+- **Removal checks:**
+  - No state path imports the send helper. A grep test in the style of
+    murmur's cheap-tick check enforces this.
+  - `src/detect.ts` exports no status.
+- **Integration:**
+  - With real tmux and a fake `@murmur_pane_state` set with `tmux set -p`:
+    `mu agent list --json` shows `source: murmur`.
+  - Without the option, it shows `unknown` with its reason.
+- **Live check** on this machine: spawn a worker, send it work, and check
+  `mu agent list` for busy and then needs_input, plus `mu agent wait` and
+  `mu task wait --on-stall exit`.
+- **Gates:**
+  - mu: `npm run typecheck && npm run lint && npm run test`
+  - murmur: `npm run check`
+
+## Implementation checklist
+
+1. murmur: publish `@murmur_pane_since` with a compare-and-set in
+   `setPaneState`, with tests (set on change, kept on a repeat, unset with
+   the state). Add the Contract section to ARCHITECTURE and the 1.0.0
+   CHANGELOG entry. Live check, then release 1.0.0 through CI.
+2. mu: add `src/agent-state.ts` (the resolver, mapping and cache) and its
+   unit tests.
+3. mu: switch reconcile, `agent list/show`, `mu state` and the TUI to the
+   resolver. Stop writing status.
+4. mu: switch `agent wait`, `task wait` stall detection and
+   `computeAgentIdle` to the resolver.
+5. mu: switch spawn readiness to the murmur option, or skip it when murmur
+   is missing.
+6. mu: move the send input-timing checks to a private helper, remove the
+   state exports from `src/detect.ts`, and add the grep test.
+7. mu: add the `--json` shape (`state`, `source`, `since`, `reason`), and
+   make the SDK export changes.
+8. mu: add the `mu doctor` murmur check.
+9. mu docs:
+   - README: "agent state needs murmur"
+   - the skill and `REMOTE_WORKERS.md`: drop the "ask murmur by hand" step
+   - ARCHITECTURE: rewrite § "Status detection"
+   - DECISIONS: this decision and what it rejects
+   - ROADMAP: the column drop, and update § murmur
+   - VOCABULARY
+10. mu: CHANGELOG 2.0.0 (breaking: `status` is gone, murmur is needed for
+    state); do the live check, then release through CI.
+
+## Rejected
+
+- **Scraping as a fallback.** It keeps two answers, one for each source. It
+  also keeps the wrapper-patch cycle, and the misreads return whenever
+  murmur is absent. `unknown` is honest.
+- **Scraping only for remote workers.** Remote is exactly where scraping is
+  wrong.
+- **Storing runtime state in `mu.db`.** The copy goes stale. The data
+  belongs in murmur.
+- **Dropping the column now.** It would make this release mu's first
+  migration, and the only gain would be deleting an unused column.
+- **Reading murmur's `state.db`.** It couples mu to a private schema.
+- **Making murmur a hard dependency.** It pulls murmur's native
+  `better-sqlite3` build into installs that want only the task graph.
+- **Removing the send checks.** They fixed measured failures, such as a
+  prompt lost to pi's session-naming modal, and murmur cannot replace them.
+
+## Open questions
+
+None.