@mu-crew/mu 1.6.0 → 3.0.0

package/docs/specs/2026-09-29-task-substates.md

@@ -0,0 +1,247 @@
+# Task substates: classification without stranded dependents
+
+Status: implemented 2026-09-29 (approved 2026-09-29; see [Deviations during implementation](#deviations-during-implementation))
+Date: 2026-09-29
+Supersedes the notes-only convention from `9e3c47b` ("tasks: reduce lifecycle to three states").
+
+## Problem
+
+`9e3c47b` removed `REJECTED` and `DEFERRED`. That fixed a real problem and created a new one.
+
+The real problem: each old status mixed two independent facts into one value.
+
+| old status | lifecycle phase | why | effect on dependents |
+|---|---|---|---|
+| `REJECTED` | ended | won't do | still blocked |
+| `DEFERRED` | not active | parked | still blocked |
+
+Neither satisfied a `blocks` edge, so rejecting or deferring a task silently stranded its dependents. The guard against that refused the transition unless `--cascade` was given. `--cascade` then stamped the whole subtree, which was too aggressive (`bug_cascade_reject_too_aggressive`).
+
+The new problem: with only `OPEN | IN_PROGRESS | CLOSED`, mu cannot tell "done" from "abandoned", and cannot keep a task out of the scheduler without closing it. The "why" lives only in free-text notes, which no view can filter on.
+
+## Approach
+
+Split the two facts into two columns.
+
+- **`status`** is the lifecycle phase. It alone decides edge satisfaction: `CLOSED` satisfies a `blocks` edge, anything else does not. Unchanged.
+- **`substate`** qualifies the status. It never touches edge semantics.
+- **Blocked / ready** stay derived from edges in views. They are never stored.
+
+Rule: **store intent, derive graph facts.** Only what a person or agent decides is stored.
+
+| status | substates | default |
+|---|---|---|
+| `OPEN` | `todo`, `parked` | `todo` |
+| `IN_PROGRESS` | `active` | `active` |
+| `CLOSED` | `done`, `wontfix`, `duplicate`, `superseded` | `done` |
+
+`substate` is never null. Every status has one named default, so an absent value never carries meaning.
+
+Consequences:
+
+- `CLOSED/wontfix` (and any other close) unblocks dependents. The close reports which dependents it unblocked. Nothing gets stranded, so no cascade is needed.
+- `OPEN/parked` leaves the scheduler: it is excluded from `ready` and `next`, and `claim` refuses it without `--force`. It stays in `goals`, because tracks are built from goals and a parked goal must not make its subtree vanish; a track whose non-closed tasks are all parked is marked parked instead. Its dependents stay ordinarily blocked, and surfaces say "blocked by parked X".
+- A closed blocker now means "stop waiting", not "the prerequisite work exists". `mu task wait` and `close --if-ready` fire on any `CLOSED/*` blocker. This is intended, and it is why every non-`done` close prints the dependents it unblocked.
+
+## Key decisions
+
+| # | Decision | Why |
+|---|---|---|
+| D1 | Two columns (`status` + `substate`), not more statuses. | Keeps a single rule for edge semantics; classification can grow without touching the DAG. |
+| D2 | Parked is an `OPEN` substate, not a status. | The dependency is still real: B still waits on A. Only scheduling changes. |
+| D3 | Non-`done` closes unblock dependents. | Blocking caused the stranding problem last time. The report keeps the effect visible. |
+| D4 | `substate` is never null; each status has a named default. | An absent value must not carry meaning. |
+| D5 | Valid pairs are enforced by a lookup table plus a composite foreign key `DEFERRABLE INITIALLY DEFERRED`. | Enforces the rule across both columns; tolerates sync's one-field-at-a-time writes, because the check runs at commit; adding a value is an `INSERT`, not a table rebuild. Verified in SQLite (see Appendix A). |
+| D6 | Drop the `status` CHECK. The lookup table is the single list. | Two lists would drift. |
+| D7 | Every lifecycle op writes `status` and `substate` together. | Both fields carry the same HLC, so per-field last-write-wins cannot split a pair from our own ops. |
+| D8 | Apply resolves the pair before writing: a status-only op, or an unknown substate from a newer peer, falls back to the status default. The original payload stays in `ops`. | The foreign key fails the whole commit. Version skew must not break sync; the foreign key is there to catch our own bugs. |
+| D9 | Non-`done` close and `park` require `--why`, stored as an ordinary note in the same transaction. | Keeps the rationale, the one good part of the notes-only convention. |
+| D10 | Start with `parked` as the only non-default `OPEN` substate. No `--until`. | YAGNI. mu has no daemon to run the automatic un-park. Adding `triage` later is one seeded row. |
+| D11 | One shared legacy mapping: `REJECTED → CLOSED/wontfix`, `DEFERRED → OPEN/parked`. | Replaces `normalizeTaskStatus` (currently folds both onto `OPEN`). Apply, rebuild, undo and migration all use it, so recovery happens on every path. |
+| D12 | Migrate v10 → v11 through `scripts/migrate.ts`, not in `openDb`. | Keeps the "production never migrates in place" rule. SQLite cannot add a foreign key to an existing table, so a new target is required anyway. |
+
+## Schema (v11)
+
+```sql
+CREATE TABLE IF NOT EXISTS task_substates (
+  status     TEXT NOT NULL,
+  substate   TEXT NOT NULL,
+  is_default INTEGER NOT NULL DEFAULT 0 CHECK (is_default IN (0, 1)),
+  PRIMARY KEY (status, substate)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_task_substates_one_default
+  ON task_substates (status) WHERE is_default = 1;
+
+-- tasks gains:
+  substate TEXT NOT NULL,
+  FOREIGN KEY (status, substate) REFERENCES task_substates (status, substate)
+    DEFERRABLE INITIALLY DEFERRED
+-- and loses: CHECK (status IN ('OPEN', 'IN_PROGRESS', 'CLOSED'))
+```
+
+- `applySchema` seeds the pairs with `INSERT OR IGNORE`, before any task write.
+- `CURRENT_SCHEMA_VERSION = MIN_ACCEPTED_SCHEMA_VERSION = 11`.
+- `EXPECTED_TABLES` gains `task_substates` (11 entries).
+- Views:
+  - `ready`: add `AND t.substate <> 'parked'`.
+  - `blocked`: unchanged.
+  - `goals`: unchanged (see Consequences: tracks mark parked instead).
+- `SchemaTooOldError.errorNextSteps` names `scripts/migrate.ts`.
+- New `SchemaTooNewError` (exit 4): `openDb` refuses a DB newer than `CURRENT_SCHEMA_VERSION`. v10 has no such guard, so a v10 binary opening a v11 DB fails only when it writes (NOT NULL / FK). The guard protects v12 and later; for v11 the operator must switch every binary before the swap (see Restoring destroyed workstreams).
+- `substate` has no column DEFAULT, so a writer that doesn't know about it fails loudly instead of guessing.
+
+`src/tasks/status.ts` mirrors the table:
+
+```ts
+export const TASK_SUBSTATES = {
+  OPEN: ["todo", "parked"],
+  IN_PROGRESS: ["active"],
+  CLOSED: ["done", "wontfix", "duplicate", "superseded"],
+} as const satisfies Record<TaskStatus, readonly string[]>;
+export const DEFAULT_SUBSTATE = { OPEN: "todo", IN_PROGRESS: "active", CLOSED: "done" } as const;
+export function resolvePair(status: string, substate: unknown): { status: TaskStatus; substate: TaskSubstate };
+export function mapLegacyStatus(value: string): { status: TaskStatus; substate: TaskSubstate } | null;
+```
+
+The seed rows are generated from `TASK_SUBSTATES`. A test asserts that the seeded table and the map are identical.
+
+## Sync and ops
+
+- `capture.ts` `CAPTURED_COLUMNS.tasks` and `apply.ts` `APPLIABLE_COLUMNS.tasks` gain `substate`.
+- Every lifecycle verb writes `{status, substate}` in one op payload.
+- `applyTaskPut` projects the payload in this order:
+  1. Map legacy status values through `mapLegacyStatus`. This can set both fields.
+  2. Apply per-field LWW as today.
+  3. Read the resulting row pair. If it is invalid, write the default substate for the status. The repair is deterministic, so every peer converges on the same row without an extra op.
+- `undo.ts` `restoreRow` uses the same mapping and repair.
+- v10 peers drop `substate` as an unknown field and keep working. Status-only ops from v10 peers are repaired by step 3.
+
+## CLI and SDK surface
+
+| Command | Effect |
+|---|---|
+| `mu task close <id> [--as done\|wontfix\|duplicate\|superseded] [--why "..."]` | `CLOSED/<as>`; default `done`. `--why` required unless `done`. Prints unblocked dependents when `--as` is not `done`. |
+| `mu task park <id> --why "..."` | `OPEN/todo → OPEN/parked`. Refuses `IN_PROGRESS` (next step: `release` first) and `CLOSED` (next step: `open` first). Idempotent on `OPEN/parked`. |
+| `mu task unpark <id>` | `OPEN/parked → OPEN/todo`. No-op on other pairs. |
+| `mu task open <id>` | `→ OPEN/todo` from any pair. |
+| `mu task claim <id>` | `→ IN_PROGRESS/active`. Refuses `OPEN/parked` without `--force`. |
+| `mu task release <id>` | `IN_PROGRESS/active → OPEN/todo`. `--reopen` from `CLOSED/*` also gives `OPEN/todo`. |
+| `mu task list --substate <name>` | Filter. Composes with `--status`. |
+| `mu task show`, `list`, `tree`, `next`, `mu state` | Render `STATUS/substate` when the substate is not the default, for example `OPEN/parked` or `CLOSED/wontfix`. Show the bare status for defaults. JSON always carries both fields. |
+
+- `mu task show` blocked output names the blocker's substate: "blocked by X (OPEN/parked)".
+- SDK exports: `TaskSubstate`, `TASK_SUBSTATES`, `DEFAULT_SUBSTATE`, `parkTask`, `unparkTask`, and `closeTask(…, { as, why })`. `TaskRow` gains `substate`.
+- Tracks: a track whose non-closed tasks are all parked is marked parked and is not counted as available parallel work.
+
+## TUI
+
+The TUI only reads data; it has no commands that change tasks. Only `recent.tsx` references `closeTask`, and only to describe it. So the TUI work is display, filtering and yank strings.
+
+| Surface | File | Change |
+|---|---|---|
+| Colours | `src/cli/format.ts` `colorStatus`, `inkColorForStatus` | Take the pair. `OPEN/parked` gray; `CLOSED/done` green; other `CLOSED/*` red/dim. `InkColor` gains `gray` and `red` again. |
+| Status label | `list-row.tsx`, `all-tasks.tsx:243`, `task-detail.tsx`, DAG `renderForest` | Render `STATUS/substate` for non-defaults, sharing one formatting helper with the CLI. |
+| Filter strip | `use-status-filter.tsx`, `keymap-spec.ts` | Keep `o/i/c`. Add `p`, which toggles parked tasks within `OPEN`, and `w`, which toggles non-`done` closes within `CLOSED`. Default: all visible. Update the `DAG_HINTS` / `ALL_TASKS_HINTS` clusters and the help pane; `tui-help-overlay.test.ts` enforces that they match. |
+| Ready card | `cards/ready.tsx:72` | Parked tasks drop out via the view. Empty-state text: mention parked when some exist, e.g. "(no ready tasks) 3 parked". |
+| Blocked card / popup | `cards/blocked.tsx`, `popups/blocked.tsx` | `stillGating` unchanged (not `CLOSED`). Annotate gating blockers that are parked: "← X (parked)". |
+| Tracks popup | `popups/tracks.tsx` `statusRank` | Order: `IN_PROGRESS`, `OPEN/todo`, `OPEN/parked`, `CLOSED/*`. Mark all-parked tracks. |
+| Recent card | `cards/recent.tsx` | Show the close substate: "closed (wontfix)". |
+| Yank | `popups/ready.tsx` `yankCommandForTask` | `OPEN/parked` → `mu task unpark …`. `CLOSED/*` → `mu task open …` (unchanged). |
+| Glyphs | `src/glyphs.ts` | Add a `parked` glyph for dense rows. The status text stays the source of truth. |
+
+## Migration (`scripts/migrate.ts`)
+
+Extend the existing sidecar to target v11. It already accepts v7–v9; add v10. The default output suffix becomes `.v11.db`.
+
+**v10 → v11.** Use `rebuildInto` as the v9 path does: copy the full ops log, then replay it through the v11 apply path. Recovery mostly comes for free, because the legacy payloads are still in the log:
+
+1. Ops carrying `REJECTED` / `DEFERRED` project through `mapLegacyStatus` to `CLOSED/wontfix` / `OPEN/parked`.
+2. Normal LWW decides the result. If a later op wrote the status, that later write wins and nothing is recovered, which is the "later change wins" rule.
+   When looking for the last status writer, ignore ops with intent `undo` or `migrate.substate`. An undo restore replays an older value; it is not a new decision.
+3. **Fallback from `MIGRATION:` notes.** If a task has a `MIGRATION: previous status was X` note, currently projects as `OPEN/todo`, and no status-writing op is newer than the note's `created_at`, append one `migrate.substate` op setting the mapped pair.
+4. Carry machine-local rows (agents, workspaces, owners) exactly as the v9 path does.
+
+**v7–v9 → v11.** Unchanged, except that the target is v11. The shared mapping now yields substates directly. Stop appending `MIGRATION:` notes: the substate carries the information.
+
+**Report.** In addition to the current output, list every recovered task with its old and new pair, and for each `CLOSED/wontfix` recovery, the dependents it unblocked.
+
+`scripts/README.md`: rename the section to "v7–v10 to v11", update the recipe paths, and document the recovery rules above.
+
+## Restoring destroyed workstreams
+
+Run this after the v11 swap, using ordinary `mu undo`, so the undo ops sync and appear in `mu log`. `restoreRow` uses the shared mapping, so restored tasks come back as `OPEN/parked` or `CLOSED/wontfix`, not as `OPEN`.
+
+A tombstone written after the v10 migration may hold the already-folded `OPEN`, not the legacy value, so mapping alone recovers nothing. The migration's recovery pass (steps 1–3 above) is therefore a shared function, `recoverLegacySubstates(db, workstream)`. After restoring, run it on each restored workstream with `npx tsx scripts/migrate.ts --recover <db> -w <ws>`. It uses the same last-status-writer rule and writes `migrate.substate` ops.
+
+Current live DB (read-only check, 2026-09-29):
+
+- 69 tasks with legacy statuses in history, all in 11 destroyed workstreams: `feedback`, `gchatui`, `gchatui-node` (2 destroy groups), `infer-rs`, `modelbridge` (teardown), `mufeedback`, `mufeedback-v03`, `multimachine`, `roadmap-v0-2`, `surface-audit`, `tui-impl`.
+- 42 workstreams in total are tombstoned; only 3 are live.
+- Dry runs of `mu undo 6f3d12e7` and `mu undo f34e2141` on v10 both plan full restores.
+
+Scope: all 42 tombstoned workstreams, not only the 11 with legacy tasks.
+
+Recipe:
+
+1. For each destroy/teardown group, oldest first, run `mu undo <group>` (dry run). Record conflicts. A workstream destroyed more than once (e.g. `gchatui-node`) needs its groups undone newest first.
+2. Apply with `--yes`. Do not use `--force`; resolve any superseded groups by hand.
+3. Run `mu doctor --deep`, then `mu task list --substate parked` and `--substate wontfix` per workstream, and compare against the migration report.
+
+## Testing
+
+- **Schema:** fresh DB seeds pairs; invalid pair, unknown value, and deleting a pair that is in use all fail; per-field writes inside one transaction commit; one default per status.
+- **Map parity:** `TASK_SUBSTATES` equals the seeded rows.
+- **Lifecycle:** each verb's resulting pair; `park` refuses `IN_PROGRESS` and `CLOSED` with next steps; `claim` on parked refuses without `--force`; `--why` is required; the unblocked-dependents report is correct.
+- **Views:** parked tasks are excluded from `ready` and stay in `goals`; a dependent of a parked task is in `blocked`; a dependent of `CLOSED/wontfix` is `ready`.
+- **Apply:** status-only op (v10 peer) repairs to the default; unknown substate falls back; legacy payloads map; the same op sequence converges on two DBs.
+- **Undo:** restoring a tombstoned legacy task yields the mapped pair; undoing a park restores the prior pair.
+- **Migration:** v10 fixtures with (a) a legacy op and no later status op → recovered; (b) a later `task.open` → not recovered; (c) a note but truncated ops → fallback fires; (d) v9 source → v11 directly. `mu doctor --deep` reports zero drift on the target.
+- **TUI:** filter-key parity test; `yankCommandForTask` for parked; colour and label helper cases; ready empty-state text.
+
+## Out of scope
+
+- Task kinds (bug / feature / chore) and free-form labels.
+- `--until` automatic un-parking.
+- `triage` / `needs-info` substates (one seeded row each, later).
+- Substates for `IN_PROGRESS` beyond `active`.
+- Blocking semantics for any closed substate.
+
+## Resolved questions
+
+1. **Restore scope:** restore all 42 tombstoned workstreams, then run legacy recovery on each.
+2. **Park on `IN_PROGRESS`:** refuse. The owner must `release` first. One verb, one transition.
+3. **TUI keys:** `p` and `w` accepted.
+
+## Implementation checklist
+
+1. `status.ts`: `TASK_SUBSTATES`, `DEFAULT_SUBSTATE`, `resolvePair`, `mapLegacyStatus`; delete `normalizeTaskStatus`.
+2. `db.ts`: v11 schema, seed, view changes, `EXPECTED_TABLES`, `SchemaTooOldError` next steps.
+3. `capture.ts` / `apply.ts` / `undo.ts`: carry `substate`, apply-time mapping and repair.
+4. Lifecycle verbs and SDK: `close --as/--why`, `park`, `unpark`, claim guard, unblocked-dependents report.
+5. CLI rendering, `--substate` filter, JSON fields, tracks marking.
+6. TUI changes per the table above.
+7. `scripts/migrate.ts`: v10 → v11 path, `recoverLegacySubstates`, `--recover` mode, report; `scripts/README.md`.
+8. Docs: `VOCABULARY.md` (substate, park, resolution values), `skills/mu/SKILL.md`, `CHANGELOG.md` (Breaking: v11; Added: substates).
+9. Operator step: migrate the live DB, then restore workstreams per the recipe.
+
+## Deviations during implementation
+
+Recorded after tasks 1–7 landed. Where this section and the text above disagree, this section describes the code.
+
+1. **Substate is resolved from the log, not by per-field LWW** (task 3). [Sync and ops](#sync-and-ops) step 2–3 described per-field LWW plus a row-only repair. That diverges by arrival order: a repair that reads only the row bakes the fallback into it, and a later status change keeps the fallback on one peer and the real substate on another. `repairTaskPair(db, rowId, pending?)` in `src/apply.ts` instead takes the substate from the newest op in the log that writes one (an explicit substate, a legacy status implying its mapped pair, or a status-only op implying the status default), then resolves it against the row's current status. The result is a pure function of the op set, so every peer converges and the repair records no op. `applyOp` wraps each task put in `db.transaction` so the deferred FK sees a complete pair. `normalizeTaskStatus` and `RETIRED_STATUSES` are deleted.
+2. **A second `updated_at`-only task op may share the group** (tasks 4, 5). `close --why` and `park` insert a note, and the note's parent touch writes a separate task op carrying only `updated_at` when the millisecond clock ticks between the two writes. It sits in the same group, so undo and log rendering are unaffected. Tests count ops that carry `status` or `substate`, not all task ops.
+3. **Ready empty-state text is shorter** (task 6): `(no ready tasks) N parked · the rest are blocked or closed`, truncated at the card edge. The longer text in [TUI](#tui) wrapped over the card's border. The Recent card shows the pair (`CLOSED/wontfix`) rather than "closed (wontfix)". `inkColorForStatus` is removed in favour of `inkColorForPair`; `loadFullDag` gained an `include` predicate so the root module does not import the TUI filter.
+4. **Migration and drift** (task 7). `src/drift.ts` compares `substate`, so `mu doctor --deep` sees substate drift. The v7/v8/v9 paths no longer write `MIGRATION:` notes. The migration report lists a third source, `replay`, for pairs the apply path derived during replay, alongside `ops` and `note` for captured `migrate.substate` recoveries. Recovery candidates are `OPEN/todo` tasks only, and a task that already has a `migrate.substate` op is skipped, which makes `--recover` idempotent. The v10 path turned out to need captured recovery only for the undo-hidden and note-only cases; replay already maps the rest.
+5. **`SchemaTooNewError`** (task 2). `openDb` refuses a DB whose `schema_version` is newer than `CURRENT_SCHEMA_VERSION` (exit 4), before `applySchema`. Without it, a v10 binary would open a v11 DB and fail at commit on its first write. `tasks.substate` has no `DEFAULT`, so an old INSERT fails loudly rather than silently choosing a substate.
+
+## Appendix A: foreign key verification
+
+Tested in SQLite with `PRAGMA foreign_keys=ON` and the deferred composite foreign key:
+
+| test | result |
+|---|---|
+| Change `status`, then `substate`, in two `UPDATE`s inside one transaction | committed |
+| `CLOSED` + `parked` | rejected |
+| unknown substate `bogus` | rejected |
+| delete an allowed pair that a task uses | rejected |
+| `ALTER TABLE … ADD CONSTRAINT FOREIGN KEY` on an existing table | syntax error (hence D12) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "1.6.0",
+  "version": "3.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,12 +32,12 @@ 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
-  task notes; close the task to satisfy blockers.
+  `effort_days`. Shown as status/substate: `OPEN/todo|parked`,
+  `IN_PROGRESS/active`, `CLOSED/done|wontfix|duplicate|superseded`.
+  Any `CLOSED/*` satisfies `--blocked-by`.
 - **claim / release** — atomic take/clear of `tasks.owner`.
 - **note** — append-only task context; survives sessions.
 - **track** — independent DAG subtree; don't spawn more agents than
@@ -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.
@@ -173,6 +174,7 @@ Every turn:
 6. `mu task wait ... --first --on-stall exit --json`.
 7. Cherry-pick the closed worker's **new** commit(s), verify the MERGE
    (see below), return control. Do not barrier or loop in shell.
+   Only `CLOSED/done` ships; other closes: read the reason note.
 8. Repeat from `mu state`.
 
 ## Dispatch rules that prevent real failures
@@ -210,8 +212,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
@@ -231,6 +233,10 @@ Every turn:
   5 timeout, 6 pane died.
 - **`task close --if-ready`** no-ops until every blocker is CLOSED; bare
   `task release` reopens IN_PROGRESS.
+- **`task close --as wontfix --why ...`** unblocks dependents (listed in
+  the output). To keep dependents waiting, `task park --why` instead: parked
+  leaves `next`, and `claim` refuses it without `--force`. Park refuses
+  IN_PROGRESS — `task release` first.
 - **For waits use `task wait`, not `log --tail`.** `--kind` is the operator's
   log-ledger channel; `--intent` is what mu recorded.
 - **`mu undo`** bare lists undoable actions with group ids; `<group>` previews;
@@ -291,24 +297,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:
 
@@ -337,7 +337,8 @@ mu task note <id> "FILES: ...\nDECISION: ...\nVERIFIED: ..."
 mu task close <id> --evidence "tests pass: ..."  # LAST action
 ```
 
-Skipping close makes the orchestrator's wait hang.
+Skipping close makes the orchestrator's wait hang. Won't do it:
+`close --as wontfix --why "..."`.
 
 ## Follow-on prompts
 
@@ -359,7 +360,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.