@mu-crew/mu 1.6.0 → 2.0.0

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "A persistent, observable crew of pi agents running in one tmux or herdr session per workstream, coordinated through a built-in task DAG.",
   "publishConfig": {
     "access": "public"

package/skills/mu/REMOTE_WORKERS.md

@@ -10,7 +10,8 @@ the traps below it are the part that costs time.
 **If you read one thing:** on a session-capped host, never leave an
 attach pane open — it holds the only ssh channel and silently breaks
 `git fetch`, `murmur collect` and every other ssh. Attach to look, then
-`mu agent close`. See § Never leave an attach pane open.
+`mu agent close`. See § Never leave an attach pane open. This guidance
+concerns interactive attachment, not mu's automatic agent-state reads.
 
 ---
 
@@ -19,8 +20,8 @@ attach pane open — it holds the only ssh channel and silently breaks
 **The pane is local, the process is remote.** `mu agent spawn
 --command 'ssh <host> -t "..."'` starts an ordinary tmux pane whose
 foreground process happens to be ssh. Everything mu does is
-pane-shaped, so `mu agent send`, `mu agent read`, status detection and
-the reaper all work unchanged, across the network, with no mu changes.
+pane-shaped, so `mu agent send`, `mu agent read`, and the reaper work
+unchanged across the network. murmur reports the remote process's agent state.
 
 **One orchestrator DB; panes may be remote.** All state stays on your
 machine. Do not run a second mu on the host to "coordinate": ownership
@@ -65,8 +66,8 @@ the only ssh channel**. While it is open, `git fetch`, `git push`,
 `Permission denied (keyboard-interactive)` error.
 
 **Attach to look, then close immediately.** `mu agent close <name>`
-detaches without stopping a detached-tmux agent. Poll with `murmur
-collect` + `murmur status`; use mule for orchestrator commands because
+detaches without stopping a detached-tmux agent. mu reads agent state
+through murmur automatically; use mule for orchestrator commands because
 its separate ControlPath cannot contend with the attach pane. See
 § When the host limits concurrent sessions for diagnosis and the
 remote-agent setup.
@@ -140,39 +141,30 @@ Local and remote agents mix freely in one workstream. The DAG, tracks,
 — task status is a row in YOUR database, written by you, so a wait on
 it is exact.
 
-**Agent STATUS is different, and this is the one place "nothing
-changes" is false.** `busy` / `needs_input` / `idle` come from reading
-the local pane's scrollback, which for a remote worker is a nested tmux
-rendered over ssh. What you get is redraw lag and quiet periods that
-look like idleness, so anything derived from status is unreliable here:
+**Agent state comes from murmur.** Its extension runs inside pi on the
+host and reports state without reading the nested tmux screen. mu reads
+murmur's remote rows and caches them for 10 seconds. Remote rows can lag
+by murmur's collect floor (30 seconds ± 10 seconds) plus that cache;
+their `since` value is the row's `updated_at`, so idle and stall age is
+approximate.
 
 | waiting on | remote? |
 | --- | --- |
 | `mu task wait` (task status) | exact — a DB poll, once something closes the task |
 | the reaper | fires, but see below |
-| stall detection | unreliable |
-| `mu agent wait --first` | same, it is status-based |
+| stall detection | exact state from murmur; approximate age |
+| `mu agent wait --first` | exact state from murmur |
 
-Measured both directions in one session: a stall fired at 300s against
-a worker that was visibly mid-turn, and `mu agent list` showed
-`needs_input` for another that was working. Give remote waits a generous
-`--timeout`; see `mu task wait --help` for stall controls.
+Without murmur, remote agent state is `unknown`. `mu agent wait` does not
+fire on `unknown`, and `unknown` never counts as a task stall. Run
+`mu doctor` for the missing-source reason.
 
-The reaper is right for a DIRECT spawn — the connection dying really
+The reaper is right for a direct spawn — the connection dying really
 does kill that agent — and wrong for a detached-tmux one, where the
 agent outlives the ssh but mu reaps the task anyway. See § A dropped
 connection reaps the task but NOT the commit.
 
-**If you need trustworthy remote status, ask murmur, not mu.** Its
-extension runs inside pi ON THE HOST and pushes state, so nothing is
-scraped and no ssh hop distorts it:
-
-```bash
-murmur collect && murmur status --json   # activity is host-reported
-```
-
-That is the division worth remembering: mu owns the work, murmur owns
-what the agent is doing.
+The division is: mu owns the work; murmur reports what the agent is doing.
 
 ### On step 2 — the note is load-bearing
 
@@ -361,17 +353,18 @@ respawn.
 
 ## mu and murmur, and what you lose without it
 
-[murmur](https://github.com/mu-crew/murmur) is optional and
-**strictly additive**. Nothing in mu needs it: the DAG, claim/close/
-wait, workspaces, spawn/send/read, the reaper, `mu state`, this whole
-remote recipe and `git fetch` collection all work with murmur absent.
-What you lose is the *view* — cross-machine agent state, the tmux
-status pills, `prefix+a`, the attachment hint, and `murmur peer list`
-for host reachability. Guard on it (`if it is installed`) rather than
-assuming it.
-
-The division: **mu owns the work, murmur owns what an agent is doing.**
-murmur never places work.
+[murmur](https://github.com/mu-crew/murmur) provides agent state for
+mu's tmux backend. Without it, mu reports agent state as `unknown`.
+The DAG, claims, task completion waits, workspaces, spawn, send, read,
+the reaper, this remote recipe, and `git fetch` collection still work.
+Agent-state consumers such as `mu agent wait`, idle flags, and task-stall
+detection wait rather than treating `unknown` as completion or a stall.
+
+murmur also provides the tmux status pills, `prefix+a`, attachment hints,
+and `murmur peer list` for host reachability. The division is: **mu owns
+the work; murmur reports what an agent is doing.** murmur never places
+work. Its interfaces used by mu are in murmur's
+[stable contract](https://github.com/mu-crew/murmur/blob/main/ARCHITECTURE.md#contract).
 
 | question | ask |
 | --- | --- |

package/skills/mu/SKILL.md

@@ -32,8 +32,8 @@ both. `--json` exists on every verb:
 - **agent** — named worker in a pane (you may be one).
 - **mux** — the multiplexer mu drives: tmux, or herdr. One per
   invocation. `mu doctor` names the active one; `MU_MUX` forces it.
-  Spawn, send, read, and status detection work on both; `mu agent
-  kick` is herdr's remaining gap (Linux-only there).
+  Spawn, send, and read work on both. Agent state comes from murmur
+  on tmux and from herdr on herdr; `mu agent kick` is Linux-only on herdr.
 - **task** — DAG node with mandatory `impact` (1–100) and
   `effort_days`. Status: `OPEN`, `IN_PROGRESS`, `CLOSED`
   (satisfies `--blocked-by`). Record postponed/wont-do rationale as
@@ -98,8 +98,9 @@ that a refusal with `--strict-staleness`.
 ### Remote agents
 
 Agents can run on another machine: the PANE is local, the PROCESS is
-remote (`--command 'ssh <host> -t "..."'`), so `send`, `read`, status
-detection and the reaper all keep working unchanged. **One orchestrator
+remote (`--command 'ssh <host> -t "..."'`), so `send`, `read`, and the
+reaper keep working unchanged. murmur reports the remote agent's state.
+**One orchestrator
 DB; panes may be remote** — never run a second mu on the host, since
 `tasks.owner_id` is an FK into the machine-local `agents` table and a
 remote mu could not claim your tasks anyway. You create the remote
@@ -158,7 +159,7 @@ Every turn:
    `mu task claim <id> -w <ws> --for <agent> --evidence "..."`.
    If no task exists, `mu task add` first; include initial context with
    `--note 'REPRO: ...\nSCOPE: ...'` when the title alone is not
-   enough. Agent status is noisy; task ownership is durable and
+   enough. Agent state is runtime observation; task ownership is durable and
    waitable.
 4. Send terse instructions: task id, files/notes to read, workspace
    path, validation command, scope guards, task note contract.
@@ -210,8 +211,8 @@ Every turn:
   conflict. Refresh workspaces between waves.
 - Cross-workstream wait/claim uses qualified refs. The owner stays in its own
   workstream; only task ownership crosses.
-- For an idle worker, inspect scrollback, then send a retry or release its task.
-  `MU_IDLE_THRESHOLD_MS` defaults to 5m.
+- For an idle worker, read the pane to learn why it stopped, then answer,
+  retry, or release its task. `MU_IDLE_THRESHOLD_MS` defaults to 5m.
 - `mu agent kick` targets a wedged foreground subprocess. It refuses to signal
   the wrapping CLI; close the agent if that is what must stop.
 - Use `mu agent send`, not raw mux input: mu preserves literal text and confirms
@@ -291,24 +292,18 @@ Convention: `pi_mini` / `pi` / `pi_big`. Use mini for probing,
 modest for build/edit/refactor, big for design/review/incidents.
 Discover model strings with `pi --list-models [fuzzy-search]`.
 
-## Reaper and status limits
+## Reaper and agent state
 
 If an agent pane dies, or `mu agent close` kills it mid-task, owned
 IN_PROGRESS tasks revert to OPEN with a `[reaper]` note and `task
 reap` op. No manual release after crashes.
 
-Status detection is heuristic and can lag behind custom `--command`
-wrappers. It is weakest for a remote worker, where the scrollback is a
-nested tmux rendered over ssh.
-
-**[murmur](https://github.com/mu-crew/murmur), if installed, is
-authoritative there** — its extension pushes state from inside the agent
-on the host rather than scraping a pane, and it answers across machines.
-Optional and strictly additive: nothing here needs it, and the seam is
-the env vars `mu agent spawn` already injects (`MU_MANAGED_AGENT`,
-`MU_AGENT_NAME`, `MU_WORKSTREAM`), which murmur reads to mark a pane as
-crew. **mu owns the work; murmur owns what an agent is doing.** See
-[REMOTE_WORKERS.md](REMOTE_WORKERS.md) § mu and murmur.
+Agent state comes from [murmur](https://github.com/mu-crew/murmur) on
+tmux and from herdr on herdr. `unknown` means no state source; run
+`mu doctor` for the reason. mu needs murmur only for agent state:
+tasks, claims, workspaces, spawn, send, read, and task completion waits
+work without it. **mu owns the work; murmur reports what an agent is
+doing.** See [REMOTE_WORKERS.md](REMOTE_WORKERS.md) § mu and murmur.
 
 For high-stakes decisions:
 
@@ -359,7 +354,7 @@ Sending to a BUSY agent is not delayed — that input queues normally.
 
 ## Guardrails
 
-Task ownership outranks scraped status. Coordinate through task notes and the
+Task ownership outranks runtime agent state. Coordinate through task notes and the
 activity log. Keep edges within one workstream, role-name agents, and reserve
 the `mu_` task-id prefix. Give workers bounded paths and commands; use `mu
 agent kick` if a subprocess wedges.