# Changelog before 3.0 Releases 2.0.0 and older, moved verbatim from [CHANGELOG.md](../../CHANGELOG.md). Newer releases live there. ## [2.0.0] — 2026-09-28 ### Changed - **Agent state comes from murmur.** mu no longer reads pane text to decide what an agent is doing, and no longer stores it. On tmux it reads [murmur](https://github.com/mu-crew/murmur) 1.0.0 or later: one `tmux list-panes` call for local agents, and `murmur status --json` (cached for 10 s) only for agents running on other hosts. On herdr it reads herdr. Without murmur, agent state shows `unknown` and `mu doctor` says why. Remote workers now report real state instead of an ssh-rendered pane. - `mu task wait --stuck-after` times the stall from murmur's `@murmur_pane_since`, the moment the agent went idle, instead of the last time mu happened to reconcile. - `mu agent spawn` waits for murmur to claim the pane. Without murmur it returns after the liveness check; the first `mu agent send` still waits for pi to accept input. - `mu doctor` has an `agent state` row (`environment.agentState` in `--json`). ### Breaking - Agent JSON (`mu agent list/show --json`, `mu state --json`, `mu me --json`) drops `status` and adds `state` (`busy`, `needs_input`, `needs_permission` or `unknown`), `source` (`murmur`, `herdr` or `none`), `since` (ISO time or null) and `reason` (when `unknown`). - `mu agent wait` and `mu task wait --stuck-after` never fire on `unknown`. Without murmur they wait until `--timeout`. - The `free` and `spawning` agent statuses are gone. `mu agent adopt` no longer marks an agent free. - SDK: removed `AgentStatus`, `detectPiStatus`, `extractTail`, `updateAgentStatus`, `agentStatusGlyph`, `AGENT_STATUS_GLYPH` and `STATUS_EMOJI`. Added `readAgentStates`, `RuntimeState`, `StateSource`, `StateReading`, `LiveAgent`, `agentStateGlyph` and `MuxPaneStatus`. - The `agents.status` column is unused and always `spawning`. It is dropped at the next schema migration. ### Unchanged Tasks, claims, `mu task wait` on task status, workspaces, spawn, send and read work the same with or without murmur. ### Upgrade ```sh npm i -g @mu-crew/mu@2 @mu-crew/murmur@^1 murmur init # once per machine murmur link pi # then restart pi sessions mu doctor # agent state : ok agent state from murmur 1.x ``` ## [1.6.0] — 2026-09-27 ### Moved - **mu is now `@mu-crew/mu`, in the [mu-crew](https://github.com/mu-crew) org.** Install with `npm i -g @mu-crew/mu` and the skill with `npx skills add mu-crew/mu`. `@martintrojer/mu` stops at 1.5.0. The skill's remote-worker guidance now names mule (formerly coop). ### Changed - **Pane titles now carry durable mu context, not sampled runtime status.** They retain the agent name and owned task summary, while live activity stays on reconciled state surfaces. Mu also leaves `pane-border-format` untouched so the user's tmux configuration can render a continuously updated observer's status; it still enables and styles borders for mu-managed windows. - **Every operator-facing `mu task wait` hint now includes `--on-stall exit`.** Generated `Next:` output, CLI help examples, the usage guide, and the bundled skill no longer leave unattended orchestrators polling after a worker needs attention. The wait default remains `warn` for direct invocations. ### Fixed - **A send immediately after `/new` no longer races pi's delayed screen transition.** The `/new` send now waits for the pane to visibly change and then stabilize before returning, without matching configuration-dependent pi output. A following `mu agent send` therefore cannot paste into a transition that the old screen had not started rendering yet. - **The running TUI now marks workstreams torn down by another process.** Its launch-time tab set stays stable, while a missing workstream is dimmed and struck through on the next fast tick. A single-workstream TUI surfaces its normally hidden tab when torn down. Recreating the same name restores the tab without restarting the dashboard. - **A re-delivered block of ops no longer wedges a peer's ingest forever.** When a peer's segment contains a byte-identical repeat of ops it already wrote, the monotonic-hlc check (layer 3) saw a backwards clock and halted, as it must for genuine reordering. But those ops are already in the local `ops` table, identified by the same `UNIQUE (machine_id, hlc)` that makes ingest idempotent, so re-applying them is a no-op and skipping them cannot produce a state neither machine had. Halting was also unrecoverable: `mu sync --repair` re-read from zero straight back into the same lines, and the advertised repair was the only one the CLI offers. Such a line is now reported as a new `duplicate-op` defect and skipped, exactly as `entity-not-synced` already was; a non-monotonic line that is NOT already recorded is still real damage and still halts. Observed in the field: three duplicated lines at position 21,347 of a 23,192-line segment held back 1,846 later ops and left two machines in permanent, undiagnosable drift. - **Full-DAG and single-task tree reads no longer take a query per task or make SQLite compare every task pair.** A redundant same-workstream join predicate made the planner choose a quadratic join for `loadFullDag`, while `renderTaskTree` separately walked the graph with an edge query plus task lookup per node. Both now load the indexed workstream DAG once. On the 698-task / 1,418-edge dogfood graph, the full DAG fell from ~77ms to ~2.6ms and a 584-line task tree from 838 SQL prepares / ~36ms to 3 prepares / ~5ms. - **Opening a large track in the TUI no longer fetches its tasks one by one.** The track drill performed two SQL reads per task; the largest live track made 351 lookups and took ~33ms. It now loads the workstream's tasks once and filters them in memory (~2ms on the same data). ## [1.5.0] — 2026-09-19 ### Changed - **Node 26 is supported and the npm dependency set is current.** The declared engine range is now Node 22.12 through 26. `better-sqlite3` 13.0.3 loads its N-API binary and executes queries on Node 26; React, React DevTools, Vitest, tsup, Biome, fast-check, and the Node/React type packages move to their latest releases. The remaining direct packages were already current. ### Fixed - **Switching TUI workstream tabs no longer blocks for seconds on the shallow drift check.** The note invariant used a correlated dynamic-prefix `LIKE`, so SQLite scanned every note op for every live note. The TUI runs Doctor on its eager slow-tier load after a tab switch; 4,384 notes therefore held the Node event loop for ~3 seconds. The equivalent half-open key range now uses the existing `(entity, key)` index and takes ~4ms on that DB. No background jobs, cancellation plumbing, or additional state were needed. - **Parallel-track detection no longer runs one recursive SQL query per active goal.** The TUI recomputes tracks on every fast tick, so a large workstream paid an N+1 query cost once per second. It now traverses every goal's prerequisite subgraph in one recursive CTE and merges goals as shared tasks are observed. On a 1,500-goal fixture this reduced a warm track read from ~170ms to ~8ms; the dogfood workstream with 698 tasks and 1,418 edges retains the same 24 tracks. ## [1.4.0] — 2026-09-16 ### Added - **`mu doctor` has a `housekeeping` section answering "which workstreams can I tear down?"** `mu workstream list` prints row counts and no dates, so the workstream finished in June looked exactly like the one worked on an hour ago. On the dogfood box that meant 11 workstreams, two of them untouched for three months, and nothing ever torn down — teardown is reversible, so the cost of the missing surface was not risk, it was that the list only grew. Two buckets, never one number, because merging them gives actively bad advice: - **finished** — every task `CLOSED` and idle ≥ 14 days. Nothing is at stake; the remediation is the `mu workstream teardown` command. - **abandoned** — idle ≥ 60 days but still holding unclosed tasks. Those tasks are the record of what was left to do, so the remediation lists them instead of offering a teardown. Teardown removes the plan, not the code: no checkout is touched (this list excludes workstreams that have one) and `mu undo` restores the rows — the cost is losing sight of the outstanding work, not losing it. The thresholds differ on purpose: a fortnight away from a project is a holiday, not abandonment. A single "dormant" list would have invited `--empty`-style sweeping of 27 open tasks on the box this was written against. Severity is always `ok` — a tidy-up opportunity is not a fault, and `warn` would make doctor claim something needs attention forever on a healthy box. Excludes the current workstream, `scratch` (ephemeral by design), anything with a live agent or registered workspace, and task-less workstreams (already `mu workstream teardown --empty`'s job). Report-only, like the rest of the `disk` section: every finding names its command and mu runs none of them. Idle time is derived from `MAX(tasks.updated_at)`, not a new `workstreams.last_activity` column — no schema change, and no second source of truth that can disagree with the rows it summarises. `mu doctor --json` gains a `housekeeping.dormantWorkstreams` key with the rows structured (`kind`, `idleDays`, `unclosed`) so an agent can act without parsing prose. ### Fixed - **A peer's unrecognised op entity no longer freezes its watermark forever.** `applyOp` rejected every entity outside `SYNCED_ENTITIES`, and `ingestSegment` treated that rejection as segment damage: defect recorded, watermark left at the offending line, loop broken. On a real fleet a peer wrote 27 `entity:"marker"` ops (legal on the build that wrote them, whose vocabulary included it), the first at line 2533 of a 20,305-line segment, and 87% of that peer's history never applied. The segment was intact — sha256 matched its manifest — so nothing surfaced the cause, and the suggested `mu sync --repair ` only resets the watermark, so it re-read straight back into line 2533. A permanent wall advertised as a stale watermark. Ingest now separates three cases that were one: - **Damage** (torn write, crc mismatch, non-monotonic HLC, manifest mismatch) still halts at the first bad record. A gap in an ordered log is indistinguishable from reordering. - **A KNOWN machine-local entity** (the new `MACHINE_LOCAL_ENTITIES` in `src/db.ts`: `agent`, `workspace`, `event`, `broadcast`) is still a reported `entity-not-synced` defect — a peer shipping a pane id or an absolute path is a real bug — but the line is now SKIPPED rather than halting. It projects nothing, so it leaves no hole, and the rest of the segment arrives. - **An UNRECOGNISED entity** applies as a forward-compatible no-op, recorded in `ops` and projected nowhere, exactly like `message`. No defect. A reader's vocabulary may legitimately lag a writer's in a mixed fleet; the op survives for a later build and for `mu rebuild`. `mu sync` also stops suggesting `--repair` for a defect a re-read cannot clear. ## [1.3.3] — 2026-09-14 ### Changed - **Semantic state markers now consistently use `src/glyphs.ts`.** The all-tasks popup uses `GLYPH.blocked`, and multi-task summaries use `GLYPH.multi`, removing the last production literals outside the shared vocabulary. Source comments now name meanings instead of preserving an old visual alphabet. - **Pane-title state now comes last.** Titles read agent, task context, then state. Long titles truncate the task portion while preserving the agent name used by identity fallback and the final state glyph used for quick scanning. ## [1.3.2] — 2026-09-13 ### Changed - **The `needs_input` stall warning states the observation instead of guessing a cause** (`agent_attention_required`, renamed from `agent_close_discipline_gap`). The warning asserted "Worker likely committed but skipped `mu task close `", but the predicate behind it only knows "owner has been in `needs_input` for >= N". That covers at least three situations needing opposite responses: a worker that finished without closing, one waiting on an answer, and one sitting at an approval prompt. Naming the first misdirected an operator into hunting for a commit to merge while the worker was waiting on a design decision. The text now reports what was measured and points at `mu agent read `, which is the next move in all three cases — the evidence is in the pane, not the task row. The pattern rename follows: a worker stopping to ask a question is desirable behaviour, and the old name presumed negligence. - **The warning reports the worker's real age, not the threshold.** It interpolated `--stuck-after`, so `--stuck-after 1` said "(>= 1000ms since last status change)" about a worker that had been waiting five minutes. `StallDetectedDuringWaitError.ageSecs` was wrong the same way. Both now carry the measured age, formatted as `45s` / `5m` / `2h`. - **A stuck ref's `nextSteps` reads the owner's pane.** On timeout every unmet ref got `mu task show `, which for this case shows a healthy-looking IN_PROGRESS row and none of the reason it stopped. `stuck` refs with a known owner now get `mu agent read --lines 60` instead; ownerless refs keep `mu task show`. `StallDetectedDuringWaitError`'s steps were reordered to lead with `agent read` for the same reason — they led with "poke the worker", which is right for one of the three causes and actively wrong for a worker waiting on an answer, since a poke with no answer in it just restates the question. ### Fixed - **`mu task wait --stuck-after --help` no longer hides `--on-stall`.** Its description ended "Wait keeps polling — the warning is observation-only", which was written when `--stuck-after` was the only flag and has been false since 0.3.0 added `--on-stall exit`. Read in order it was a dead end, and a reporter filed a request for a flag that had existed for ten releases after stopping at that sentence. The text now names itself as the TRIGGER and ends by pointing at the ACTION. - **`mu agent wait --help` explains when NOT to use it.** It fires on `busy → needs_input`, so it looks like the answer for catching a worker that asked a question — but it keys on agents, so a task-DAG orchestrator would have to track the task→agent mapping itself and run two waits concurrently. The description now says so and points at `mu task wait --stuck-after`. --- ## [1.3.1] — 2026-09-13 ### Changed - **All state glyphs now come from one file, `src/glyphs.ts`, and one font family.** Symbols were inlined at each render site — three separate `"✓"` literals (Recent card, Workspaces card, doctor card), `"⚠"` in two CLI formatters, `"⛓"` / `"⋈"` / `"★"` / `"ⓘ"` / `"●"` each at their call site — which is one place per literal for the next drift to start. `AGENT_STATUS_GLYPH` (was `STATUS_EMOJI`, kept as an alias) and the new `GLYPH` record are keyed by MEANING (`GLYPH.stale`, not a clock), so re-pointing a symbol is a one-line edit. The TUI's `superscriptDigit` folded in from `src/cli/tui/glyphs.ts`; two files called `glyphs.ts` was its own trap. Every glyph is now a classic Nerd Font `nf-fa-*` codepoint. Mixed families were the original bug: a Unicode emoji like ⚙️ is two codepoints that `cli-table3` sizes as width 2 but the terminal draws one cell wide, so rows mixing families misalign. `nf-md-*` slots move between font releases and render as the wrong icon. - **`busy` agent glyph is `nf-fa-play` instead of `nf-fa-cog`.** murmur's dash paints a running pane with the play glyph, and mu drives the same panes. A gear reads as "settings" in every other TUI the operator uses; play reads as "this is running" with no lookup. - **`scripts/migrate.ts` accepts v7 and restores pre-1.0 archives.** The sidecar already covered v8/v9 → v10. Real upgrade DBs are often still on v7 with empty live tables and the useful history only in `archived_*` — which the importer used to refuse unless `--drop-archives` threw that history away. It now auto-detects v7, synthesizes ops from `archived_tasks` / edges / notes / events into live workstreams named after each row's `source_workstream`, and keeps `--drop-archives` as the explicit skip. A live/archive task-key collision still refuses rather than merging two histories onto one key. See `scripts/README.md`. --- ## [1.3.0] — 2026-09-11 ### Added - **Remote dispatches now print a bounded, one-shot wait command.** `mu task wait` cannot fire for a remote worker, because nothing on the host can close the task — so every orchestrator invented its own poll loop, and the observed ones were unbounded `while true` with a hardcoded baseline. Record the workspace and per-worker baseline in a task note (`REMOTE: :` plus `REMOTE_BASE: :`); `mu task claim --for ` then adds a `Next:` step with the real host, path, task id, agent name and baseline substituted. It dispatches a 30-second-bounded coop probe, validates the returned sha, and closes the task with it as evidence — which is what makes `mu task wait` usable again. **mu stays transport-free:** it prints the operator-owned network command and never opens the connection itself. ### Changed - **The skill files are 25% smaller, with nothing non-recoverable lost.** `SKILL.md` 3537 → 2461 words and `REMOTE_WORKERS.md` 5343 → 4334, because both had grown into caches of `mu --help` and `coop --help` — verb lists, flag tables and an exit table that one command answers and that go stale silently. SKILL.md loads on every invocation, so this is context returned to the user's actual work. The coop reference material moved back to coop, whose `--help` now carries it and which warns at dispatch about the traps the skill used to teach. `AGENTS.md` gained a section explaining why these files are context rather than documentation, and the "adding a verb" checklist no longer instructs contributors to grow `SKILL.md` by default. - **Remote-worker guidance corrected on two measured points.** Polling a capped host with bare ssh is not merely slow, it is wrong: eight concurrent `rev-parse` polls returned one sha and seven *empty* results, and an empty result compares unequal to the baseline, so a naive wait fires on a refusal. Route by whether a refusal could look like success, not by duration. Also `git -C rev-parse` fails over ssh where `cd && git rev-parse` works — the previous fragment used the broken form. --- ## [1.2.0] — 2026-09-09 ### Breaking - **`mu workstream destroy` is now `mu workstream teardown`, with no alias.** "Destroy" claimed irreversibility that was never true: the verb writes **tombstone** ops, so `mu undo ` restores every row it removed. The wrong word had a measurable cost — it drove defensive pre-flight `mu db backup` runs, 12 of them (270M) in one operator's home directory, named `mu-pre-destroy-*` and friends. The `--yes` two-phase dry-run is unchanged; only the noun was wrong. The old verb is GONE, not aliased: a half-renamed verb is worse than either end state. `mu workstream destroy` now exits with commander's unknown-command error. History is unaffected. New ops carry `intent='workstream.teardown'`, and the ~5k existing ops spelled `workstream.destroy` stay readable: `mu log` renders both as "workstream teardown" (it already did), and `mu log --intent workstream.teardown` matches both spellings via a new `LEGACY_INTENT_SYNONYMS` map in `src/legacy-ops.ts`. Without that, a rename would silently truncate history at the release boundary and `mu undo` would stop finding pre-rename groups — verified it still reverses a 1057-op teardown from 2026-08-26. `--json` field renamed with it: `destroyed` → `tornDown` on `mu workstream teardown --empty`. SDK: `destroyWorkstream` → `teardownWorkstream`, `DestroyResult` → `TeardownResult`. ### Added - **`mu state` now inventories remote workers from task notes.** An exact `REMOTE: :` line appears in a `Remote workers` section and in the JSON snapshot's `remoteWorkers` array, preserving the only durable record of a remote workspace after its agent row disappears. Prose that merely mentions `REMOTE:` and malformed lines are ignored; no empty text section is rendered. - **`mu workstream list --torn-down`** — past teardowns, read from the ops log, with the **group** id to pass to `mu undo`. A teardown is reversible, which is useless if the group cannot be found: bare `mu undo` lists only recent groups, so a teardown from last month needed hand-written SQL over `ops` to recover. Columns are name, group (short, the form `mu undo` accepts), relative time, and the task / edge / note counts the teardown removed, so a row says what is at stake without a second query. The `Next:` block prints the ready-to-run `mu undo ` / `--yes` pair. Read straight from the log rather than a projection — the log already holds it, and a side table would be one more thing that can disagree with it. Consequences that fall out of that: one entry per teardown rather than per name (a name torn down twice lists twice; the group is the identity), teardowns predating the 1.2.0 intent rename are included, and an entry a later op put back is marked `← recreated since` instead of being hidden, since "I tore this down, then undid it" is history worth seeing. The suggested undo always names the newest entry that is still restorable, so the printed command is never a no-op. ### Fixed - **The remote-worker guide is 806 words smaller.** The coop section now keeps mu-specific routing guidance and measured failure evidence while delegating coop's flags, warnings, and exit table to `coop --help`. The attach-pane rule is consolidated with the session-cap diagnosis and detached-tmux fix instead of explaining the same contention twice. - **The bundled mu skill is 1,042 words smaller.** Removed CLI-reference caches that `mu --help` already answers, consolidated dispatch and scratch guidance, and moved remote-only stall handling to `REMOTE_WORKERS.md`. Measured failure history, recovery traps, exit semantics absent from help, and the remote-worker pointer remain. - **The `mu task wait --json` docs promised a `firing` field that `--any` never sets.** `docs/USAGE_GUIDE.md`, the `--first` help text and the comment in `src/cli/tasks/claim.ts` all said `firing` is populated "on `--first` / `--any` success". Only `--first` sets it. `--any` exits **0** with `firing: null` on a perfectly successful wait, so a documented consumer reading `.firing.qualifiedId` after `--any` dereferences null exactly when the wait worked. Corrected in all four places, including `skills/mu/SKILL.md`, and pinned by tests. Reported as "`--first` can exit 0 with `firing: null`", which it cannot: `--first` implies `any: true`, and both non-timeout returns in `waitForTasks` are guarded by `isDone()`, which for `any: true` means at least one ref reached the target — so the `?? null` fallback is unreachable, and a clean `--first` exit always names a ref. No exit code changed; the false documentation was the whole defect. - **A prose log line poisoned the sync segment, and mu blamed a torn write for it on every invocation.** `encodeSegmentLine` interpolated `ops.payload` into the JSON line raw, on the assumption that the column always holds JSON. It does not: `mu log "text"` writes an entity-`message` op whose payload is bare prose, and prose containing a comma or a quote produced `"payload":Added 5 tasks, ...` — a line that is not JSON at all. Payloads are now passed through verbatim when they parse as JSON and encoded as a JSON string when they do not, with the wrapping undone on ingest so a peer's `ops` table holds the origin's bytes. The damage was noise, not loss — the `ops` table stayed canonical and `mu doctor` was clean throughout — but it was **permanent** noise. The segment self-repair regenerates from `ops`, and regeneration re-emitted the same unencodable payload, so the warning fired on every single mu command, forever. That is the real cost: it trains you to ignore sync warnings, and a genuine torn write then reads as background noise. - **A complete-but-unparsable segment line is no longer reported as a torn write.** Layer 1 called every `JSON.parse` failure `torn-write`, which sent the reader hunting for a crash-during-write that never happened; the line above was 765 complete bytes ending in a valid `crc`. A line carrying its trailing `,"crc":"…"}` framing cannot have been cut off in flight, so it is now reported as `malformed-shape`. Different cause, different remediation: refetch the tail versus go read the writer. - **An incompatible herdr server looked available on herdr 0.9.0.** 0.9.0 split `herdr status`'s single `compatible: yes|no` line into `endpoint_compatible:` (the stable public API generation) and `private_protocol_compatible:` (the internal protocol). mu's availability gate matched `^\s*compatible:\s*no$`, which the new prefixed keys can never satisfy — so a server predating endpoint generation 1 passed the check, `activeMux()` picked herdr, and the failure surfaced on the first real verb instead of degrading to tmux. The two lines are now read for what they mean: `endpoint_compatible: no` is fatal, private-protocol skew is not (since 0.9.0 it disables individual actions and leaves running agents alone, so a client one release ahead of its server still drives panes). herdr ≤0.8.x's bare `compatible:` line is still honoured. The predicate is now one exported `isHerdrStatusUsable()` that `test/_mux.ts`'s integration-tier gate also calls — it had its own hand-rolled copy, which is precisely why the rename went unnoticed on both sides. - **`mu workstream teardown` now refuses a herdr workspace group instead of failing with a bare mux error.** herdr 0.9.0 rejects `workspace close` with `workspace_group_close_required` when worktree workspaces are linked to the target. mu does **not** retry with `--group`: those siblings were created by `herdr worktree`, host panes mu never spawned, and closing them to satisfy a teardown would destroy unsaved work with no undo. The new `HerdrWorkspaceGroupCloseError` exits 2 (the operator-decision lane, beside the other herdr refusals) and prints the `herdr worktree remove` / `herdr workspace close --group` commands. Teardown kills the mux session before touching the DB, so the workstream is left intact and the command is safe to re-run. - **`mu undo` of a pre-v10 `workstream destroy` could not run at all.** Three independent walls, each fatal on its own, all of which real history presents together: 1. Legacy `workstream.export` ops are `entity='workstream'` carrying a PROSE payload. SQLite raises `malformed JSON` while STEPPING a `json_type()`, so the query failed before any row reached JS and `mu undo ` died with `Unexpected token 'w', "workstream"... is not valid JSON`. `src/legacy-ops.ts` existed for exactly this shape and `rebuild` / `segments` / `sync` already skipped it — the undo and apply paths never got the check. Now a shared SQL predicate (`LEGACY_LOG_ONLY_SQL_EXCLUSION`) excludes them in the WHERE clause, which a JS-side filter cannot do. 2. Restores replayed `DEFERRED` / `REJECTED`, retired in 1.1.0, and the schema CHECK clause aborted the whole transaction on the first one. The apply path already normalized these to `OPEN`; that logic now lives in `normalizeTaskStatus` and both paths share it. 3. Note tombstones written before 1.1.1 carry `'{}'`, and a note's key embeds a rowid that reprojection reassigns, so neither the per-key fold nor the (new) self-describing tombstone could resolve them and notes were silently not restored — 255 tasks and 266 edges came back with 0 of 535 notes. A third tier now recovers content from the puts for the same TASK. Ordinal pairing is deliberately NOT used: notes are a grow-only set keyed on (task, content), so identical prose collapses, and one task had 5 puts against 3 tombstones. Restoring the distinct contents reaches the same end state the dedupe produced. Verified against a real 27k-op log: undoing a 1057-op destroy from 2026-08-26 now restores 255 tasks, 535 notes and 266 edges, and the notes are byte-identical to an independent pre-destroy backup. `mu doctor --deep` clean afterwards. Consequence worth stating: a destroy has always been fully recoverable from the ops log — this bug meant the recovery PATH was broken, not that data was gone. ## [1.1.1] — 2026-09-03 ### Added - **`mu doctor` reconciles the state dir against the DB, in both directions** (new `disk` section; `src/disk-recon.ts`). Every other doctor check reads the database; nothing looked at `` and compared the two, so both kinds of disagreement were invisible: - `ws-rows` — a `vcs_workspaces` row whose path is gone. This had **no surface at all** before: `mu workspace list` printed such a row as healthy, and the next send or refresh against it failed deep inside the VCS backend rather than at the row that lied. Usually a hand-run `rm -rf` where `mu workspace free` was wanted. - `ws-dirs` — a workspace dir with no row, counting `stranded` ones separately. `listAllOrphanWorkspaces` already existed but was reachable only from `mu workspace orphans` and the TUI card, so running `mu doctor` to answer "is anything wrong" said nothing about dirs that will fail their next spawn. - `db-copies` — stray `mu.db*` files that are not the live WAL triple (49M on the box this was written against). Hand-made copies and pre-upgrade saves: nothing reads them and nothing prunes them. - `exports` — leftovers from `mu workstream export`, which 1.0 removed without removing its output directory. The one finding here that is a defect rather than housekeeping: mu deleted the producer and left the output unreferenced. - `ws-empty` / `locks` — empty per-workstream dirs (`ok` severity; `workspace free` leaves the parent behind) and advisory-lock dirs older than an hour, which are not a deadlock but are evidence of a spawn or flush that died mid-critical-section. **Report-only by construction.** Each finding carries its own cleanup command in the remediation block and mu runs none of them — an orphan or stranded dir may hold the only copy of uncommitted work, and a diagnostic that deleted checkouts because a `readdir` raced a spawn would be a worse bug than the residue it removed. Findings are `FleetHazard`-shaped, so doctor's row renderer, `--json` (new `disk` key, with remediation lines included) and the TUI Doctor card need no new shape. The default tier is `readdir` + `stat` at depth 2 (~1ms). - **`mu doctor --disk`** adds recursive per-checkout byte accounting with the orphan share called out as reclaimable (758M across 4 checkouts, ~2s, on the box above). Separate flag because its cost scales with the size of your checkouts rather than with mu's state, and `mu doctor` has to stay cheap enough to run reflexively. ### Documentation - **[skills/mu/REMOTE_WORKERS.md](../../skills/mu/recipes/remote-workers.md) (now `recipes/remote-workers.md`)** — running agents on another machine. This already worked with no mu changes (the pane is local, the process is remote, so send/read/status/reaper are unaffected), but nothing said so and the failure modes are not guessable. Written from a mixed local+remote crew run against a real devserver: cherry-pick handoff needs no shared remote, since `git fetch ssh://host/path HEAD` reads a remote worktree directly; the local `$MU_PI_COMMAND` wrapper is not what a bare `pi` gives you on the host, which yields a healthy-looking pane with no models; a dropped connection reaps the task but strands the commit, so the remote path belongs in a task note; and a host with `MaxSessions 1` lets the agent's own ssh block the orchestrator's `git fetch` behind a misleading `Permission denied (keyboard-interactive)`. A separate file rather than more `SKILL.md`, which is loaded every session — the skill keeps a short stub and links out. ### Fixed - **A throwaway `MU_DB_PATH` leaked phantom peers into the user's real sync dir.** Overriding the DB does not contain a test or a smoke run: sync is ambient, so the first flush stamps the fresh DB's new `machine_id` onto a segment in whatever `MU_SYNC_DIR` names. Nothing prunes segments — absence of one is the only way a peer disappears — so `mu sync` then lists a machine that never existed, forever. Eight had accumulated in one `~/mu`, each holding a single op from a disposable `workstream init` (`smoke`, `smoketest`, `doccheck`, ...), all traceable to the documented `MU_DB_PATH=/tmp/mu-smoke.db mu ` recipe. `syncDir()` now refuses a sync dir outside `tmpdir()` when running under a test runner — the exact sibling of the `openDb` guard that refuses the user's real DB (`refuseUserDbDuringTests`), and for the same reason: the failure was silent, permanent, and invisible until someone read the folder. Tests that exercise sync legitimately already use a per-test `mkdtemp` dir and are unaffected. Production never sets `VITEST`, so the shipped CLI is untouched. AGENTS.md's smoke-test recipe now blanks `MU_SYNC_DIR` too, since a hand-run `node dist/cli.js` is not under vitest and the guard cannot help it. - **`mu undo` of a workstream destroy silently failed to restore notes whose rowid had shifted** (drift-641). A note's op key embeds its rowid (`/#`), which is not portable: a rebuild, a v8/v9 reprojection, or any path that reinserts a note assigns a fresh one. The historical `put` then sat under the OLD key while the `del` emitted at destroy time used the CURRENT one, so nothing joined them. `planUndo` reconstructs a tombstoned row by folding the puts for that exact key, so such a note folded to `{}` and `restoreRow` skipped the insert and reported no change. Undoing a destroy therefore brought back every task and edge but only the notes whose rowid happened to be unchanged — on the box this was found, 73 of 714 — and the 641 orphaned rows then showed up as `mu doctor --deep` drift ("present in live tables but the log cannot explain it"), which breaks undo, sync and rebuild together since all three derive from the log. Note tombstones are now **self-describing**: the `task_notes` BEFORE DELETE trigger records `OLD.author/content/created_at` instead of `'{}'` (new `fullOldPayload` in `src/capture.ts`), and `planUndo` falls back to the tombstone's own payload when the fold comes back empty (new `payloadFields` in `src/undo.ts`, sharing `NEVER_RESTORE` and the scalar guard so a fallback can never reintroduce a surrogate id or FK). The inverse no longer depends on finding a matching put. Other tombstones stay empty — the key plus the preceding puts already describe them, and notes are the only entity whose key is not stable. Costs ~2 bytes per existing note tombstone in the log and needs no schema change; old empty-payload tombstones keep working through the fold path. ## [1.1.0] — 2026-08-28 ### Breaking - **`mu workstream` fields renamed to backend-neutral mux naming** (`find_workstream_json_tmux_named_fields_on_herdr`). The `mu workstream list` / `init` / `destroy` JSON shapes and CLI prose used `tmuxSession` / `tmuxAlive` / `killedTmux` and "tmux session" wording even when the active backend was herdr, contradicting the backend-agnostic `activeMux()` seam both verbs already went through. `WorkstreamSummary.tmuxSession` → `muxSession`, `WorkstreamSummary.tmuxAlive` → `muxAlive`, `DestroyResult.killedTmux` → `killedMux`; `WorkstreamOptions.tmuxSession` (the session-name override on `summarizeWorkstream` / `destroyWorkstream`) → `muxSession`. The `mu workstream list` table header and the `destroy` dry-run / result lines now say "mux" / "mux session" instead of "tmux". No deprecated aliases are kept — scripts consuming the old JSON field names must update. `mu agent spawn` / `mu agent adopt` / `mu state`'s unrelated `tmuxSession` session-override option (a different interface, orthogonal to this rename) is unchanged. `mu workstream init --json`'s own `sessionName` field is likewise renamed to `muxSession` for the same consistency. - **Three-state task lifecycle (schema v10).** `REJECTED` and `DEFERRED` task statuses are removed. Only `OPEN`, `IN_PROGRESS`, and `CLOSED` remain. `mu task reject` and `mu task defer` are deleted. Use task notes (`mu task note "won't do: ..."`) to record rationale; close the task to satisfy blocked-by edges. Pre-v10 databases are refused at startup with `SchemaTooOldError` (exit 4); no in-process migration ladder is provided. The retained `scripts/migrate.ts` sidecar auto-detects v8/v9 and writes a fresh v10 DB. For v9 sources, current `REJECTED` / `DEFERRED` tasks project as `OPEN` with a durable migration note, while original op payloads remain unchanged. The SDK no longer exports `rejectTask`, `deferTask`, `RejectDeferOptions`, `RejectDeferResult`, or `TaskHasOpenDependentsError`. ### Changed - **`mu workspace create` and `mu workspace recreate` removed (surface-audit).** Both standalone verbs are gone with no compatibility aliases. Workspace creation is not an operator verb: it happens inside `mu agent spawn --workspace` (with `--workspace-backend` / `--workspace-from` / `--workspace-project-root`), and cleanup on `mu agent close` is unchanged. The remaining namespace is `list`, `refresh`, `commits`, `free`, `path`, `orphans`. Between waves use `mu workspace refresh` (preserves the worker's commits by rebasing onto fresh main); for destructive cleanup use `mu workspace free`. The SDK no longer exports `recreateWorkspace`, `RecreateWorkspaceOptions`, or `RecreateWorkspaceResult`, and `src/workspace/recreate.ts` is deleted; the lower-level `createWorkspace` remains, since spawn needs it. `workspace.recreate` is removed from `LocalIntent` and the log-render verb table, and the private `_suppressEvent` flag on `createWorkspace` / `freeWorkspace` (which only existed to give recreate one atomic event line) is gone. Operator-facing hints that recommended free + create — the `mu state` stale-workspace tip and the `mu task wait` next-step recipe — now recommend `mu workspace refresh`. - **`mu agent ensure`, `poll`, `reap-idle`, `free`, and `attach` removed (surface-audit).** These five secondary convenience verbs are gone with no compatibility aliases. The remaining lifecycle is: `spawn`, `send`, `read`, `show`, `list`, `wait`, `kick`, `adopt`, `close`. SDK helpers `ensureAgent`, `freeAgent`, `pollAgents`, `reapIdleAgents` and their types are removed from `src/agents.ts` and `src/index.ts`. `agent.free` removed from `LocalIntent` and the log-render verb table. - **TypeScript 7 (the Go-native compiler) for typechecking.** `npm run typecheck` drops from ~9s to ~0.6s. The upgrade is not a plain version bump, because TS 7.0 ships **no programmatic compiler API** — `ts.createProgram` and friends are gone, the package exports two keys, and the API is deferred to 7.1. `tsup --dts` goes through `rollup-plugin-dts`, which needs that API, so `typescript@7` alone builds JS and then dies on declaration emit. Resolved with the aliasing the TS team documents for exactly this case: `@typescript/native` is TS 7 and provides the `tsc` binary, while `typescript` resolves to `@typescript/typescript6` so library consumers still get the JS API. The two bins do not collide (`tsc` vs `tsc6`). Revertible to a single dependency once 7.1 ships its API and `rollup-plugin-dts` adopts it. ### Changed (docs / help) - **Docs and `--help` text realigned to the reduced surface (`align-small-cli-contract`).** AGENTS.md's schema-version note and module-layout comments now say v10 (was v9) and drop the removed `archives.ts` / `exporting.ts` / `cli/archive.ts` rows and the `workspace create`/`recreate` and `agent free`/`attach` verbs from the file-tree annotations. `src/cli.ts`'s header comments no longer hardcode a verb/namespace count that drifts every time a namespace is added or removed. `src/cli/agents.ts`'s `spawn` / `send` / `list` / `adopt` help text is backend-neutral ("mux pane" / "the active mux") instead of naming tmux specifically, matching the `activeMux()` seam those verbs already go through; `send`'s description now names herdr's atomic `agent prompt` alongside tmux's bracketed-paste. `docs/USAGE_GUIDE.md`'s three-state task lifecycle: the "placeholder task" cancellation example no longer references the deleted `mu task reject --cascade`, the TUI keymap table and per-status-toggle prose drop `r` / `d` (REJECTED / DEFERRED), the status colour line drops the two dead colours, and `--if-ready` / `--reopen` / `release` prose drop the two dead terminal statuses. The keymap reference table also gains the four real keys it was missing (`a` attach, `l` lazygit, `b` blocked-filter cycle, `c` clear footer) so `?`/`docs` and the actual dashboard agree. `src/tasks/lifecycle.ts`'s capture-trigger comment no longer lists `task.reject` / `task.defer` as live intents this file can still produce (they only appear in historical pre-v10 ops, rendered by `src/log-render.ts`, which is unchanged and correct). Finally, `mu workstream init --json`'s `sessionName` field is renamed to `muxSession`, matching `mu workstream list` / `destroy`'s naming from the mux-neutral-fields rename above — the one JSON field that rename missed. - **Final documentation sweep against the built CLI (`final-doc-sweep`, surface-audit).** Docs still described behavior removed by the second cleanup round or never matched the shipped binary. `docs/USAGE_GUIDE.md`'s worked examples now read "mux session" / `Attach the session : tmux attach -t mu-` instead of the pre-mux-rename "tmux session" / `tmux a -t mu-` wording (verified against a live `mu workstream init`); the `mu doctor` sample output now shows `schema_version : 10`; `mu workstream destroy`'s sample output drops the `Pre-destroy export:` line left over from the removed auto-export. `docs/ARCHITECTURE.md` and `AGENTS.md`'s TUI module-tree comments drop the removed `r`/`d` (REJECTED/DEFERRED) toggle keys from the `use-status-filter.tsx` annotation (now `o/i/c`) and `AGENTS.md`'s `src/agents/` and `src/mux/` listings gain the `spawn-lock.ts`, `wait.ts`, and `index.ts` rows that existed in source but not in the tree; the TUI cluster listing gains `use-terminal-size.ts`, `agent-display.ts`, `lazygit.ts`, and `tmux-attach.ts`. `AGENTS.md`'s `tasks/lifecycle.ts` and `cli/tasks/lifecycle.ts` comments drop `rejectTask`/`deferTask` and `reject`/`defer`, which the three-state-lifecycle removal already deleted from those files. `skills/mu/SKILL.md` no longer claims herdr `agent spawn`/`send`/`read` are unimplemented (they shipped) and drops `free` from its agent-verb list (`mu agent free` was removed with the other secondary agent verbs); its vocabulary entry now points at `mu agent kick`'s Linux-only gap instead. `docs/VISION.md`'s "no dry-run on most mutations" gap now names `task delete` and `undo`, which gained two-phase dry-run/`--yes` after that line was written, and its iteration- speed LOC/test counts are corrected from a stale ~30k LOC / ~2800 tests to the current ~95k LOC / ~2900 tests (`wc -l` over `src/` + `test/`; `npm run test`). `docs/ROADMAP.md`'s rejected- substrates table drops "and archives" from a capture-bug consequence list — the archive namespace no longer exists to corrupt. Historical CHANGELOG entries, the v8/v9 migration recipe in `scripts/README.md`, and legacy task-status compatibility text are left untouched — they describe what shipped, not current behavior. Verification: `mu --help` / relevant `mu --help` cross-checked against every corrected claim, `npm run typecheck && npm run lint && npm run test:fast && npm run test && npm run build` all green. ### Fixed - **Removed the dead `suppressSnapshot` field from `DestroyWorkstreamOptions`** (`reviewfind_dead_suppresssnapshot_field`). It was already a documented no-op since v9 dropped the `snapshots` table, and no caller in the codebase ever set it — a pure speculative-flexibility leftover the code-reviewer's Speculative Generality smell flags. No behaviour change. - **`mu sync --from ` crashed on the same legacy `workstream.export` op the two sibling readers already skip.** `ingestFromDb()` filtered rows by `SYNCED_ENTITIES` only, so a peer DB carrying a pre-1.0 `workstream.export` op (prose payload, synced `workstream` entity) reached `applyIncomingOp` and threw `SyntaxError` from `JSON.parse`, aborting the whole `--from` read in one transaction. `flushSegment` and `rebuild.ts`'s `isProjectable` already call `isLegacyLogOnlyIntent`; `ingestFromDb` now does too, folding the skip into the existing `skippedLocal` counter like the segment path does. - **`flushSegment` no longer regrows a corrupted own segment forever.** `readSegmentTail` could not distinguish clean EOF from a defect, so `flushLocked` repeatedly re-derived and appended the same tail after damage. It now truncates to the last verified-good line before regenerating from the canonical ops log, and reports the repair so `mu sync` and ambient sync warn instead of failing silently. - **Removed commands no longer erase their historical op compatibility.** `workstream.export` ops used a synced `workstream` entity but carried a prose payload. The export command is still removed, but its intent now remains in a narrow permanent compatibility classifier used by rebuild and segment flush. Old databases therefore retain the row as history without sending it to `applyOp` or writing malformed segment JSON. - **Log-only ops are no longer replayed, flushed, or projected (`workstream.export`).** `emitEvent` derives an op's entity from its intent prefix, so `workstream.export` lands on `entity='workstream'` — a synced, projectable entity — while carrying a PROSE payload rather than JSON. `rebuild.ts` already excluded it by intent; two other consumers did not, and each broke differently: - `mu archive restore` crashed with `Unexpected token 'w'` whenever the marker sat above a `workstream.export` op. Reachable on any archive, because `workstream destroy` auto-exports and re-pinning puts that op BELOW the new marker. Observed on a real DB: 8 of 10 archived workstreams refused to restore. - `flushSegment` wrote a MALFORMED segment line for it, because `encodeSegmentLine` embeds the payload as raw JSON. Worse, it compounded: `readSegmentTail` stops at the first bad record to recover its watermark, so the watermark rewound and every later flush re-appended the whole tail. Observed in the wild: a 2.7 MB segment grown to 102 MB, 221,627 lines holding 12,978 distinct ops, some repeated 96 times. A corrupt segment is repaired by deleting it and re-running `mu sync` — the ops log is canonical, so the segment is rebuilt from it with no data at risk. `LOG_ONLY_INTENTS` moved from private to exported so all three consumers shared one list rather than three copies drifting apart. The list is now gone along with its only member — see the `mu workstream export` removal below. - **`mu archive list` no longer blows past the terminal width.** One label accumulates markers from many workstreams (cross-workstream pinning is the point), so a dozen names joined into a ~150-char cell and pushed the table to ~206 columns. The `workstreams` column now takes a budget from the actual terminal width and overflows into `+N more`, so the hidden count — the thing that tells you whether to run `mu archive list