@mu-crew/mu 3.13.3 → 4.1.0

package/skills/mu/recipes/findings.md

@@ -1,123 +1,29 @@
 # Findings
 
-Use whenever an agent reviews, audits, checks, or researches something
-and reports problems: every recipe that produces findings follows this
-one. It decides where findings live, and how they become work.
+Use when an agent reviews, audits or checks something and reports problems.
 
-## Pick the mode first
+**Mode.** Will agents fix these through the DAG? No (someone's PR, a doc): delegates answer with one `FINDING:` line each and you act; nothing enters your DAG (calls are synced `scratch` tasks). Yes: workstream mode, below.
 
-Ask: **will anyone act on these findings through the DAG?**
+## Record
 
-| Situation | Mode | Findings live in |
-| --- | --- | --- |
-| The result is read once and acted on directly: PR comments, doc edits, a go/no-go, a draft fact-check | **Delegate** | the delegate's answer |
-| Findings become work agents fix, or must be tracked to closure | **Workstream** | one `OPEN/triage` task per finding |
-
-Delegate mode keeps reviews of other people's PRs and docs out of the
-ops log, which is permanent and syncs to every machine. Workstream mode
-is the mu way for your own work: the graph shows every finding, who
-decided it, and the fix.
-
-## Delegate mode
-
-1. Run reviewers as [delegate calls](tasks-or-calls.md#delegate-call):
-   one per angle or slice, all in one turn so they run in parallel,
-   under the cap ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)).
-2. Each delegate ends its answer with one line per finding:
-
-   ```text
-   FINDING: high src/api/user.ts:88 PUT handler skips the auth check EVIDENCE: curl -X PUT ... returned 200
-   ```
-
-3. You read the answers, merge duplicates, and act: post the comments,
-   edit the doc, give the verdict.
-4. **Promote** when the findings turn out to be work: create one
-   `OPEN/triage` task per line (below) and continue in workstream mode.
-
-Done when every delegate answered and every finding line was acted on
-or dropped with a reason.
-
-## Workstream mode
-
-### Record
-
-The reviewer records each finding as a task in triage, blocking the
-review's umbrella so the umbrella cannot close while findings are
-undecided:
+One `OPEN/triage` task per finding, blocking the review's umbrella.
 
 ```bash
-mu task add -w <ws> --triage \
-  -t "high: PUT /user skips the auth check" -i 70 -e 0.5 \
-  --note 'FINDING: high src/api/user.ts:88 PUT skips the auth check EVIDENCE: curl -X PUT ... returned 200 without a token'
-mu task block <umbrella> -w <ws> --by <finding-id>
+mu task add -w <ws> --triage --blocks <umbrella> -t "high: PUT /user skips auth" -i 70 -e 0.5 \
+  --note 'FINDING: high src/api/user.ts:88 PUT skips the auth check EVIDENCE: curl -X PUT returned 200'
 ```
 
-The title starts with the severity. The note is one `FINDING:` line,
-the same shape everywhere: `FINDING: <severity> <file:line> <what>
-EVIDENCE: <command + output>`. `OPEN/triage` keeps the finding out of `mu task next`, and
-`claim` refuses it, so no worker starts on an undecided finding.
-
-**Severity** drives the three-refuter rule, so grade it strictly:
-`critical` needs a concrete scenario to data loss, a security breach or
-an outage; `high` a plausible bug; style is `low` unless it hides a bug.
-When unsure, pick the lower. A vague finding from one reviewer (no line,
-no scenario) drops a level at consolidation. Reviewers who differ by 2+
-levels go to the human.
-
-**More than 5 findings from one reviewer:** the reviewer writes them as
-`FINDING:` lines in its own task note instead. Before that reviewer
-task closes, the orchestrator adds `triage_<umbrella>` blocking the
-umbrella; the triage agent ([Triage](#triage) step 1) merges duplicates
-across reviewers and creates one task per real problem.
-
-### Triage
-
-1. **Who:** a handful of findings, the orchestrator triages itself. Many,
-   or several reviewers on one change: a `triage_<umbrella>` task, run
-   by a fresh agent, so the orchestrator reads only its result.
-2. **Refute** each finding before accepting it with a
-   [delegate call](tasks-or-calls.md#delegate-call) that passes
-   `record: { task: "<ws>/<id>" }`: a fresh agent tries to prove it
-   false, and its VERDICT block lands on the finding as a
-   `REFUTER <label> (<delegate>, <elapsed>):` note (VERDICT line, 3-6
-   EVIDENCE lines), or `REFUTER <label>: no verdict (<outcome>)` when
-   it times out or dies. Without `mu_delegate`, write that note yourself
-   before deciding
-   ([tasks-or-calls § Delegate call](tasks-or-calls.md#delegate-call)).
-   Skip this for low-severity style findings. High severity: three
-   refuters, accept only if at least two say CONFIRMED.
-3. **Decide** each one; the decision is the task's state. The reason
-   names the deciding evidence, not a tally or a judgement. mu warns
-   when a reason is under 40 chars and no note holds a `VERDICT:` line
-   or `REFUTER` note. Prose reasons go through a heredoc variable
-   ([brief § Quoting](brief.md#quoting)).
-
-   | Decision | Command | Bad reason |
-   | --- | --- | --- |
-   | real work | `mu task accept <id> --evidence "2/3 CONFIRMED: refuters 1 and 3 show the checklist:3 vs :33 cycle"` | `valid`, `orchestrator: valid`, `2/3 CONFIRMED` |
-   | false | `mu task close <id> --as rejected --why "<the guard or command that disproves it>"` | `refuter REFUTED` |
-   | same as another | `mu task close <id> --as duplicate --why "same as <id>"` | |
-   | valid, not worth it | `mu task close <id> --as wontfix --why "<cost vs impact>"` | `not worth it` |
-   | could not check | stays in triage, with an `UNVERIFIED: <why>` note | |
-
-4. **Group** accepted findings that touch the same files into one fix
-   task when separate workers would collide. Block the umbrella on the
-   fix task (`mu task block <umbrella> --by <fix-task>`), then close the
-   grouped findings `--as superseded --why "fixed in <fix-task>"`:
-   superseding unblocks the umbrella.
-
-Done when `mu task list --substate triage -w <ws>` lists only findings
-with an `UNVERIFIED` note, and each of those is reported to the human.
+Grade strictly: `critical` needs a concrete path to data loss, breach or outage; `high` a plausible bug; style is `low`. When unsure, lower.
 
-### Fix and close
+## Triage
 
-Accepted findings are ordinary tasks: dispatch them, review the fix
-([adversarial-review](adversarial-review.md)), merge. The umbrella
-closes with `mu task close <umbrella> --if-ready` once every finding is
-`CLOSED/*`. A plain `close` would succeed with findings still open; an
-`UNVERIFIED` finding blocks `--if-ready`, so the umbrella stays open
-until the human decides it.
+1. **Refute each** with a [delegate call](tasks-or-calls.md) passing `record`. Skip low style findings. High: three refuters, accept at 2 CONFIRMED.
+2. **Decide**; the state is the decision, and `--why` names the deciding evidence:
+   - real: `mu task accept <id> --evidence "2/3 CONFIRMED: <why>"`
+   - false: `mu task close <id> --as rejected --why "<the guard that disproves it>"`
+   - same as another: `--as duplicate --why "same as <id>"`
+   - true, not worth it: `--as wontfix --why "<cost vs impact>"`
+   - unchecked: stays in triage with `UNVERIFIED: <why>`; report it to the human. It is not REFUTED.
+3. **Group** accepted findings sharing files into one fix task, block the umbrella on it, close the grouped ones `--as superseded`.
 
-The report is a query, not a document: `mu task list -w <ws>
---substate rejected`, `--substate duplicate`, `--status OPEN`, and the
-notes on each task.
+`mu task close <umbrella> --if-ready` does nothing until every finding is closed.

package/skills/mu/recipes/models.md

@@ -1,102 +1,27 @@
-# Model tiers
+# Models
 
-Read when you pick a model for a spawn or a delegate call. mu passes the
-model through and never picks one; the choice is yours. Recipes name a
-tier (cheap, mid, strong, frontier) and say which one their roles need;
-this file says how to tell a model's tier.
+Use when you pick a model. mu passes it through.
 
-## Tiers
+Rank a model within its own family; the id prefix in `pi --list-models` names the family, the provider column often does not. 
 
-Rank a model within its own family. The model-id prefix in
-`pi --list-models` (`anthropic/`, `openai/`, `google/`) names the family
-when it names a lab; the provider column is often one shared gateway, so
-it does not tell families apart.
-
-| Tier | Where it sits in its family | Names as of 2026-10 |
+| Tier | Position | Examples (2026-10) |
 | --- | --- | --- |
-| **frontier** | an exceptional tier above the lab's normal flagship, priced well above it, often gated | fable, astra |
-| **strong** | the lab's normal flagship | opus, sol |
-| **mid** | the everyday default | sonnet, terra |
-| **cheap** | the lab's small, fast hosted model | haiku, luna, flash, mini, nano, lite |
-| **local** | runs on this machine (ollama, lmstudio, llama.cpp) | qwen, gemma, gpt-oss |
-
-Names go stale within months; the position in the family does not. Rank
-a model you cannot place by the lab's own description of its lineup
-(flagship, balanced, fast). `pi --list-models` shows context and max
-output, not price or quality, and siblings often share both. Still
-unsure: run it on a small slice of the real work and compare it with a
-model you can place. Until then, pick conservatively: a model you know
-is strong enough for the work, and for a checker never one that might
-sit below the author.
-
-Thinking effort strengthens a model within its tier. It does not change
-the tier, and it does not stand in for another family.
-
-## Local models are a last resort
-
-A hosted cheap model beats a small local one at agent work: tool calls,
-long briefs, multi-step edits. Small local models lose the thread of a
-brief and fake tool results; in `pi --list-models` they tend to show
-thinking `no` and small context and output limits. Use one only when no
-hosted model is available, or the work must stay on the machine, and
-then only for cheap-tier work whose output something stronger checks. A
-local model never reviews, refutes or judges.
-
-## Roles
+| frontier | above the flagship | fable |
+| strong | the flagship | opus |
+| mid | everyday default | sonnet |
+| cheap | small, fast, hosted | haiku, flash |
+| local | on this machine | qwen |
 
 | Work | Tier |
 | --- | --- |
-| fan-out scouting (listing units), searchers collecting quoted claims, watchers, first-pass finders | cheap |
-| building, refactoring, tests, routine fixes | mid |
-| review, refute, judge, audit, synthesize | the tier of whoever wrote the thing being checked, or higher; another family when one exists |
-| design, plans, incidents, root cause, final synthesis of a large run | strong |
-| a strong attempt failed, or the final judge of a close call | frontier; none available: the strongest model, from a family not yet used on the job |
-
-Cheap work suits bounded tasks whose output can be checked: a searcher's
-claim carries a quote a checker verifies. A cheap finder's misses stay
-missed, since refuters only test what was reported. When an omission is
-costly (a security audit, a coverage sweep), run the finders mid or
-strong, or add a second finder from another family.
-
-## Checkers
-
-A checker (reviewer, refuter, judge, auditor) must not share the
-author's blind spots. The author is whoever wrote the thing being
-checked: the worker for a diff, the planner for a brief, the finder for
-a finding.
-
-- **Level or up.** At least the author's tier; never down.
-- **Another family when one exists**, at that tier. One model's blind
-  spot repeated is still one blind spot.
-- **No peer in another family**: the same model, fresh context, higher
-  thinking unless at max.
-
-A delegate with no `model` runs the cli's configured default, which is
-your own model only if you are on that default. When the tier or family
-matters, pass `model`.
-
-## How to pass a model and effort level
-
-pi takes both in one `--model` value: `<provider/id>:<level>`, where the
-thinking (effort) level is one of `off`, `minimal`, `low`, `medium`,
-`high`, `xhigh`, `max`. Leave `:<level>` off to keep the model's default. With `:<level>`, pi
-reads the first segment as the provider, so copy `<provider>/<model>`
-exactly from `pi --list-models`. Through a gateway that is
-`modelbridge/anthropic/claude-sonnet-5-5:high`; `anthropic/…:high` fails
-with "No API key".
+| scouts, watchers, first-pass finders | cheap |
+| building, routine fixes | mid |
+| design, plans, root cause, synthesis | strong |
+| review, refute, judge, audit | the author's or higher |
+| a strong attempt failed; a close final call | frontier, else the strongest unused family |
 
-- `mu_delegate`: `model: "<provider>/<model>:high"`.
-- Spawn: `mu agent spawn r -w <ws> --command "pi --model <provider>/<model>:high"`.
-- A `cli` key (`--cli pi_big`) works only if `$MU_<KEY>_COMMAND` is set
-  in the environment; check before you rely on one.
-- herdr refuses a command override, so neither model nor level can be
-  set per agent there: every helper runs the cli's default. The only
-  independence left is fresh context; say so in the verdict.
+A cheap finder's misses stay missed: use mid or strong where omission is costly. Effort is no other family. A local model never checks.
 
-Probe a model you have not used this session
-(`pi --model <id> -p "say ok"`); `ctl: ok` after spawn does not test the
-model.
+**Checkers** must not share the author's blind spots: the author's tier or higher, another family when one exists; else the same model, fresh context, higher effort.
 
-Done when the chosen `model` is placed in a tier, a checker is at the
-author's tier or higher and from another family (or the verdict says why
-not), and a model new this session answered `pi --model <id> -p "say ok"`.
+**Passing it.** `mu_delegate`: `model: "<provider>/<id>:<effort>"`. Spawn: `--command "pi --model <provider>/<id>:<effort>"`. Effort: `off|minimal|low|medium|high|xhigh|max`. Copy `<provider>/<id>` from `pi --list-models`. No `model`: the cli default. herdr refuses a command override.

package/skills/mu/recipes/move.md

@@ -0,0 +1,14 @@
+# Move a 3.x workstream
+
+Use when the human asks to move ONE 3.x workstream into 4.0, from the machine holding it. Open tasks move; the rest stays in the 3.x DB. `mu` is 4.0; `<mu3>` is 3.x, e.g. `npx -y @mu-crew/mu@3.13.3`.
+
+1. **Read the old DB**: `sqlite3 -readonly -json <old.db> "<query>"`, never `MU_DB_PATH`. 4.0 runs on its own state dir and `MU_SYNC_DIR` (or blank).
+2. **IN_PROGRESS first**: finish, or `<mu3> task release <id> -w <ws>` (park refuses it).
+3. **Select** the open tasks (local_id, title, impact, effort_days, substate), each one's first and last note (brief; park reason or status), and the `task_edges` with both ends open (`from_task_id` blocks `to_task_id`). A last note that is the brief or `CLAIM: dispatch` is no status: write one.
+4. **Write a script** (python argv lists: briefs hold quotes) that runs, per task, dependents first (`--blocks` needs the umbrella):
+
+   `mu task add <id> -t <title> -i <impact> -e <effort> --blocks <its dependents> --note - -w <ws>`
+
+   with the brief on stdin, then `mu task note <id> -w <ws> -` with `moved from 3.x <ws>/<id>; last note: <it, capped 2 KB>`; for a parked task, pass that text to `mu task park <id> -w <ws> --why` instead. Keep the ids.
+5. **Verify**: open-task and edge counts (`mu db query ... --all`) match; `mu task tree <a root> -w <ws>` matches. Mismatch: fix, never mark.
+6. **Mark the old one**: `MU_DB_PATH=<old.db> <mu3> task park <id> -w <ws> --why "moved to 4.0"` per moved task.

package/skills/mu/recipes/orchestrator-loop.md

@@ -1,135 +1,36 @@
 # Orchestrator loop
 
-Use when you run a workstream: you dispatch DAG tasks to workers and
-merge their commits. The hard rules in SKILL.md still apply; this is
-the loop and the reasons behind them.
+For dispatch and merge.
 
-## Every turn
+## Each turn
 
-1. `mu state -w <ws>` — read agents, IN_PROGRESS, ready tasks.
-2. Spawn one agent per ready task, up to the ceiling below. Tasks that
-   edit the same files are chained with `block`, so only one is ready
-   ([waves](waves.md)).
-3. **Claim before sending — even one-shot reviewers/scouts.**
-   `mu task claim <id> -w <ws> --for <agent> --evidence "..."`.
-   If no task exists, `mu task add` first (`--note 'REPRO: ...'` when
-   the title is not enough). Ownership is durable and waitable; agent
-   state is not. Review tasks: [adversarial-review](adversarial-review.md).
-4. Run `mu workspace refresh <w>`, then send a [brief](brief.md) with
-   `mu agent send <w> --fresh '...'` (new session + prompt in one step;
-   refuses while busy). The brief ends with its final-action block.
-5. `mu task wait ... --first --on-stall exit --json`.
-6. Cherry-pick the accepted worker's **new** commit(s) into a merge batch
-   (below), then continue the loop in the same turn. Do not barrier or
-   loop in shell.
-   Only `CLOSED/done` ships; other closes: read the reason note.
-7. Repeat from `mu state`.
+1. `mu state -w <ws> --json`.
+2. Note the ceiling on the umbrella (`CONCURRENCY: workers 4`); one worker per ready task.
+3. Dispatch with a [brief](brief.md) on stdin. New worker:
 
-## Concurrency
+   ```bash
+   mu agent spawn worker-1 -w <ws> --worktree --task <id> --send - <<'EOF'
+   <brief>
+   EOF
+   ```
 
-Write the ceiling on the umbrella before the first wave
-(`CONCURRENCY: delegates 12, workers 4`) so a resumed orchestrator
-keeps it.
-
-- **[Delegate calls](tasks-or-calls.md#delegate-call)** (read-only): 10 to 20 at once is reasonable.
-  Token spend and provider rate limits bind first; start near 8 and
-  raise after a clean wave. `mu_delegate` runs at most
-  `MU_DELEGATE_MAX` (default 16) and queues up to four times that
-  (`queued-N`, started as slots free); past that it refuses.
-- **Answers arrive when you stop**, as pi follow-up messages, never
-  mid-turn. pi's `followUpMode: "all"` delivers every waiting answer in
-  one turn instead of one turn each; each answer names its delegate and
-  ends with its `VERDICT: <id>` block, so a batch still maps back. Read
-  every verdict in the batch before deciding any.
-- **Workers with workspaces** build and test: about one per CPU core,
-  fewer when targeted slow checks contend for resources. A remote host has
-  its own session cap ([remote-workers](remote-workers.md)).
-- **Stream dispatch.** Keep the pool full: dispatch the next unit
-  when one closes, rather than waiting for a whole wave. With the
-  `codemode` tool, a [driver](codemode-driver.md) can dispatch a batch
-  of workers in one script.
-
-## Waiting
-
-Use `--first --on-stall exit`: `--first` populates `.firing`, and
-`--on-stall exit` stops an unattended wait when a worker needs attention.
-Exit 6: the owner's pane died and the reaper reopened the task; exit 7:
-the owner sat in `needs_input`. Run the exit's `Next:` and answer: the
-worker may be waiting on you. For a pi owner it leads with
-`mu agent wait <owner> --after-runs <runs-1> --json`, which returns the
-last answer at once. The pane read follows because dialogs and crashes
-show only in the pane.
-
-Never release or reassign a task because its owner reads `unknown`:
-that is degraded reading, not absence. Read the pane or run `mu doctor`
-first. The reaper acts only on a dead pane.
-
-For an idle worker, read its last answer (the same `--after-runs`
-wait for pi, else the pane), then answer, retry, or release its task.
-`MU_IDLE_THRESHOLD_MS` defaults to 5m. A remote owner: for pi,
-`mu agent wait --after-runs` first, then poll once; otherwise poll once
-per turn ([remote-workers](remote-workers.md#step-5-poll-once-per-turn)).
+   Idle worker: `mu task claim <id> -w <ws> --for <w> --evidence "..."`; `git -C <cwd> fetch && git -C <cwd> rebase <base>` (conflict: `rebase --abort`, tell the human); `mu agent send <w> -w <ws> --fresh -`.
+4. `mu wait -w <ws>` waits on what you started (workers, tasks, calls). `data.exit` 0: an event in `data.firing`, or `timedOut` (run `data.resume`); 6: worker died before closing, re-dispatch it; 7: `mu agent read <w>`, answer.
+5. Merge. Close a finished worker: `mu agent close <w> -w <ws>` only previews; run its printed `--if <rev>`. Then step 1. If `mu state` says a course check is due, finish merging, then follow [course-correct](course-correct.md) first.
 
 ## Merging
 
-- **Pipeline; don't barrier.** Cherry-pick accepted new commits as tasks
-  close and dispatch the next unit. Choose a bounded merge batch; an umbrella
-  wait hides progress and stale branches can restore reverted code.
-- **Pin the batch tree.** Run full slow once, plus fast if slow excludes it,
-  under [the gate contract](test-health.md#gate-contract). Keep the tested
-  checkout unchanged during the run; independent workers continue in their
-  workspaces. Later merges form the next batch, not an extension of this pass.
-  Remote hosts: [run the merged gate there](remote-workers.md#run-the-merged-gate-on-the-host).
-- **Bisect a failed batch.** Isolate the offending commit/interaction, fix it,
-  and gate the corrected merged tree before shipping.
-- **Push only the verified tree.** Make `git push` the last line under
-  `set -e`; required integration and safety checks must actually run.
-  Record the gate result and slow duration with the merged tree in the merge
-  note/`mu log`. Queue [upkeep](test-health.md#upkeep-loop) on a budget crossing
-  or milestone, rather than stopping all independent work.
-- **Accept evidence, not close notes.** Re-run the key measurement from
-  a clean checkout; close notes have claimed unpushed commits. A
-  worker's "done" counts only once the diff shows the change. Your own
-  accept and close notes name the check run and the commit.
-- **Ask whether the check could have failed.** A gate that cannot say
-  no is not evidence: a test filtered to zero cases, a script you wrote
-  agreeing with itself, a fixture you tuned on. A nonzero diff is a
-  failure even when the command exited 0.
-
-## Build cache
-
-Keep build targets private per workspace and auth/profile lane. Share dependency
-downloads and use an existing compiler cache when available; measure cold/warm
-cost and contention. Keep normal-auth, test-auth and release artifacts distinct,
-with explicit executable paths for consumers. A shared writable Cargo target
-can replace a binary after its build lock is released, while tests still use it.
-Warm-up may copy a quiescent snapshot into private storage, never hardlinks or
-a live target. This is build guidance, not a new mu cache or dependency.
+- Cherry-pick new commits as workers close; gate one pinned batch ([test-health](test-health.md)); push the verified tree.
+- Accept evidence, not close notes: rerun the check.
 
 ## Sending
 
-A running worker sees what you send, never a new task note: deliver
-an instruction for it with a send (or the next `--fresh` brief), and
-keep the note as the durable copy. pi:
-
-| `mu agent send` | busy pi acts | Use for |
-| --- | --- | --- |
-| plain | after the run ends | answers, same-task additions |
-| `--steer` | after the current tool call | advice that can wait for the tool boundary |
-| `--interrupt` | now: kills the running tool | a correction that wastes the current work (stale input, wrong target, changed stop rule) |
-| `--fresh` | refused (`--force` drops the run) | unrelated work: new session + prompt |
+`--steer`: after the tool. `--interrupt`: now, kills the tool. `--fresh`: unrelated work.
 
-- claude-code/codex: send `/new` (codex: `/clear`), then the prompt; a
-  send it cannot confirm prints a `warning:` on stderr.
-- Use `mu agent send`, not raw mux input. Quote prompts per
-  [brief](brief.md#quoting).
-- Cross-workstream wait and claim use qualified refs; only task
-  ownership crosses.
-- A long run drifts unseen: audit it per [drift-audit](drift-audit.md).
+## Delegate waves
 
-## Stopping a worker
+One `wave` label per fan-out ([tasks-or-calls](tasks-or-calls.md)); `mu wait -w <ws> --wave <label>` returns its tally. An answer read via `task notes` still arrives once from `mu wait`; act once.
 
-`mu agent abort <w>` first for pi, then `mu agent kick` (pi
-unresponsive, or non-pi), then `mu agent close`.
+## Stopping
 
-Done when every task is closed, or a decision only a human can make blocks all progress (SKILL.md § Orchestrator rules).
+`mu agent abort <w>`; close as step 5.

package/skills/mu/recipes/recovery.md

@@ -1,32 +1,11 @@
-# Recovery: undo, rebuild, sync
+# Recovery
 
-Use before you undo a change, rebuild the DB, tear down a workstream,
-set up sync, or act on `mu doctor` output. Each of these can lose work
-when done in the wrong order.
+Use before you tear down a workstream, rebuild the DB, set up sync, or act on `mu doctor` output. Each can lose work in the wrong order.
 
-- **`workstream teardown`** is reversible: `workstream list --torn-down`
-  lists the group ids to `mu undo`; the log is the backup.
-- **`mu undo`** restores rows only: killed panes and freed workspace
-  dirs do not come back. Redo = undo the undo.
-- **`mu rebuild <file>`** writes a new DB from the ops log, without
-  agents or workspaces; re-spawn after the swap. Recovery is
-  `mu rebuild`, not `mu db backup`.
-- **Sync:** set `MU_SYNC_DIR` on each machine to a shared folder
-  (Syncthing). Every command flushes and ingests ops, merged per field.
-  mu never runs ssh or rsync; `mu sync` prints the line.
-  `--repair <peer>` is always safe. Agents, workspaces, and task
-  ownership never travel.
-- **`mu db forget <ws...>`** deletes torn-down workstreams' ops for
-  good (no undo); `mu db compact` only blanks redundant tombstones. Both
-  back up beside the DB first. Forget only what the human named.
-- **`mu doctor --deep` DRIFT** (exit 5) is a capture bug: back up and
-  report it. Do not rebuild; the live rows may hold work the log missed.
-- The `doctor` `disk` section is report-only: an orphan dir may hold the
-  only copy of uncommitted work, so mu prints cleanup commands and runs
-  none. Read before you run them.
+- **Teardown** is soft: `mu workstream teardown <ws>` previews with `rev=<n>`; apply with `--if <n>`. Rows stay hidden, worktrees stay (`mu agent close` removes them). Reusing a name later permanently deletes the old rows, after its own preview.
+- **`mu rebuild <file>`** writes a new DB from the ops log, without agents or worktrees; swap it in with the printed command, then re-spawn. Recovery is `rebuild`, not `mu db backup`.
+- **Sync:** set `MU_SYNC_DIR` on each machine to a shared folder; every verb ingests and flushes. mu runs no ssh or rsync. `mu sync --repair <peer>` is safe. Agents, worktrees and ownership never travel.
+- **`mu db forget <ws...>`** deletes torn-down workstreams' ops for good. Forget only what the human named; it backs up first.
+- **`mu doctor --deep` DRIFT** is a capture bug: back up and report it. Do not rebuild; live rows may hold work the log missed.
+- **Doctor's `disk` section** prints cleanup commands and runs none. An orphan dir may hold the only copy of uncommitted work; read each command before you run it.
 
-Done when, per operation: undo or teardown was previewed, then applied
-with `--yes`; rebuild was swapped in and agents re-spawned; `mu sync`
-lists the peer; forget touched only the named workstreams. Any
-`doctor --deep` DRIFT is backed up and reported to the human, and you
-read every cleanup command before you ran it.