@mu-crew/mu 3.10.1 → 3.11.0

package/dist/tui-sync-worker.js

@@ -1,7 +1,7 @@
 import {
   ambientSyncPass,
   openDb
-} from "./chunk-YIF3X32A.js";
+} from "./chunk-WYBOR4FX.js";
 import "./chunk-4PACTXAB.js";
 import "./chunk-PZ5AY32C.js";
 

package/docs/VISION.md

@@ -201,6 +201,9 @@ mu agent spawn worker-1   --cli pi_mini
 mu agent spawn reviewer-1 --cli pi_big
 ```
 
+The skill's [model tiers](../skills/mu/recipes/models.md) are advice to
+the agent choosing; mu reads none of it.
+
 ## What it enables
 
 - **Visible crews.** Spawn agents once and send them work all day. Each

package/docs/guide/delegate.md

@@ -22,7 +22,7 @@ Delegates called in one turn run in parallel.
 | `timeout` | Seconds to wait for the answer (default 3600). After it, the answer does not come back; the follow-up gives the `mu agent wait` command. |
 | `workspace` | Own VCS checkout, for delegates that edit files. The follow-up names its path. It isolates repository edits only. |
 | `cli` | Key for `$MU_<CLI>_COMMAND` (default `pi`). Only keys set in pi's environment exist. |
-| `model` | pi `--model` value, appended to the cli's command (`sonnet`, `openai/gpt-5:high`). Varies models across a panel. tmux only: herdr refuses a command override. |
+| `model` | pi `--model` value, appended to the cli's command (`sonnet`, `<provider>/<model>:high`, copied from `pi --list-models`). Varies models across a panel. tmux only: herdr refuses a command override. |
 | `keep` | Keep the pane after it finishes, to talk to it again. |
 | `record` | `{ task, workstream? }` (or `task: "<ws>/<task>"`): write the answer's verdict onto that task as a note. See [Record a verdict](#record-a-verdict). |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.10.1",
+  "version": "3.11.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/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: mu
 description: >-
-  Fresh-context subagents and crews in tmux/herdr panes. Check before you
+  Fresh-context delegates (mu's counterpart to hidden subagents) and crews
+  in tmux/herdr panes. Check before you
   commit: before acting on a claim, root cause, plan, fix or brief, have a
   `mu_delegate` call refute it. Also for a fresh delegate's second look at
   your own work or diff; parallel read-only research, investigation or fan-out
@@ -24,14 +25,14 @@ not in `--help` do not exist.
 Default output is a card on stdout plus a `Next:` block. Read both.
 Every verb takes `--json`: one stdout object; collections are
 `{items, count}`, except `mu agent list` (`{agents, orphans}`); `mu sql --json` is bare rows; `mu log --tail` is
-NDJSON. Errors are `{error,message,nextSteps,exitCode}` on stderr
+NDJSON; `mu log` writes print text even with `--json`. Errors are `{error,message,nextSteps,exitCode}` on stderr
 (validation errors add `usage`). **`nextSteps` survives in JSON.**
 
 ## Vocabulary
 
 - **workstream** — one **mux session** `mu-<name>` (tmux session or
   herdr workspace) and one DB partition.
-- **agent** — named worker in a pane (you may be one).
+- **agent** — named process in a pane (you may be one); a **worker** is an agent claiming tasks.
 - **mux** — tmux or herdr, one per invocation. `mu doctor` names it;
   `MU_MUX` forces it. `mu agent kick` is Linux-only on herdr.
 - **control socket (ctl)** — how mu drives a pi agent: the mu pi
@@ -44,7 +45,8 @@ NDJSON. Errors are `{error,message,nextSteps,exitCode}` on stderr
 - **claim / release** — atomic take/clear of `tasks.owner`.
 - **note** — append-only task context; survives sessions.
 - **track** — tasks connected by `block` edges (`mu task block B --by A`
-  puts B on A's track); spawn at most one agent per ready track.
+  puts B on A's track). Spawn one agent per ready task, not per track:
+  an umbrella puts all its units on one track.
 - **workspace** — per-agent VCS copy under
   `<state-dir>/workspaces/<workstream>/<agent>/`.
 
@@ -62,7 +64,7 @@ Recipe words, the same in every recipe:
 - **finding** — one reported problem, recorded as an `OPEN/triage` task.
 - **verdict** — a check's answer: `VERDICT: <id> CONFIRMED | REFUTED |
   UNVERIFIED <one line>` plus `EVIDENCE:` lines (or ACCEPT | REJECT for
-  a review gate).
+  a review gate). REFUTED on a brief means it holds a false claim: rewrite it.
 - **stop rule** — the command and condition that end a loop, written on
   the umbrella first ([loop-until-done](recipes/loop-until-done.md)).
 
@@ -76,12 +78,12 @@ or inspection.
 
 Before you act on a claim, root cause, plan, fix or brief, or to get a second
 look at your own work or diff, make a [delegate call](recipes/tasks-or-calls.md#delegate-call)
-that tries to refute it (briefs: see Orchestrator rules; many claims: [refute](recipes/refute.md)).
+that tries to refute it, on another model family ([models](recipes/models.md#checkers); briefs: see
+Orchestrator rules; many claims: [refute](recipes/refute.md)).
 
 For one-shot work inside pi, call `mu_delegate` (installed by `mu link pi`). Outside pi: spawn
-into the reserved `scratch` workstream (no task DAG, auto-created), `send --fresh --json`, then
-`mu agent wait --after-runs <its runs> --json` (`lastText`); without `--after-runs` a run that
-ends first hangs the wait. Recipes call either form a **delegate call**. A check judging a mu
+into the reserved `scratch` workstream (no task DAG, auto-created), as in
+[delegate call](recipes/tasks-or-calls.md#delegate-call). Recipes call either form a **delegate call**. A check judging a mu
 task lands its verdict there: `record: { task: "<ws>/<id>" }` on `mu_delegate`, a hand-written
 `REFUTER` note on the spawn path; with no task, skip both.
 
@@ -102,8 +104,10 @@ wrapper whose argv0 is not `pi`/`pi-meta` it shows `needs_input`): add
 ### Workstreams, DAGs, tracks
 
 The DAG has one edge: `mu task block A --by B` means **B blocks A**.
-Tracks sharing a prerequisite collapse into one, so two agents never
-take the same dependency.
+Tracks sharing a prerequisite collapse into one, so an umbrella every
+unit blocks makes the whole job one track. Parallelism is the ready
+set: tasks that edit the same files get a `block` edge between them,
+so only one is ready at a time.
 
 ### Workspaces prevent trampling
 
@@ -112,9 +116,9 @@ repo, spawn with `--workspace`. Two builds in one checkout corrupt each
 other; keep the main checkout for orchestration.
 
 Workspaces auto-detect jj, sl, or git (else `cp -a`). `mu agent close`
-frees one **only if clean** (no uncommitted changes, no commits since
-fork); otherwise it fails with `WorkspacePreservedError`. Then use
-`mu workspace free <agent>` or `--discard-workspace` (lossy).
+frees one **only if clean**; otherwise it fails with
+`WorkspacePreservedError`. A `cp -a` copy is never clean. Cherry-pick what
+to keep, and pass `--discard-workspace` only to throw the rest away.
 Before each `--fresh` send, `mu workspace refresh <agent>` rebases onto
 main and keeps LLM context ([waves](recipes/waves.md) when workers share
 files). Claim and send warn at ≥10 commits behind
@@ -190,7 +194,7 @@ rules hold even when you skip it:
 - **Send, don't note, a running worker**: it never sees new notes. The note is the durable copy
   ([how to send](recipes/orchestrator-loop.md#sending)).
 - **Refute a brief claiming a cause, fix, threshold or code fact** before dispatch:
-  one `record`ed refuter call; rewrite on AMEND. Others get a `REFUTE-EXEMPT: <why>` note.
+  one `record`ed refuter call; rewrite on REFUTED. Others get a `REFUTE-EXEMPT: <why>` note.
 - **Checks are calls, not tasks.** Refuters, claim checkers, judges and
   skeptics are [delegate calls](recipes/tasks-or-calls.md#delegate-call)
   (`mu_delegate`, or a `scratch` spawn without it), all issued in one
@@ -205,13 +209,9 @@ rules hold even when you skip it:
 
 ## CLI gotchas
 
-- **`task close --if-ready`** no-ops until every blocker is CLOSED; bare
-  `task release` reopens IN_PROGRESS.
 - **`task close --as rejected|wontfix --why ...`** unblocks dependents
   (listed in the output). `rejected` = the claim is false; `wontfix` =
-  true, not worth doing. To keep dependents waiting, `task park --why` instead: parked
-  leaves `next`, and `claim` refuses it without `--force`. Park refuses
-  IN_PROGRESS — `task release` first.
+  true, not worth doing. To keep dependents waiting, `task park --why` instead.
 - **For waits use `task wait`, not `log --tail`.** `mu log --kind <k>`
   entries are your own durable state (a ledger); `--intent` filters what
   mu recorded.
@@ -225,23 +225,14 @@ rules hold even when you skip it:
 
 ## Models and thinking effort
 
-mu doesn't reason about models; pi does. Controls:
+mu passes the model through; you pick it. Before you choose one for a
+spawn or a delegate call, read [recipes/models.md](recipes/models.md):
+tiers, which roles need which, and local models as a last resort.
 
-```bash
-mu agent spawn r --command "pi --model opus:high"
-export MU_PI_COMMAND="pi --model sonnet:medium"
-mu agent spawn a --cli pi_big   # uses $MU_PI_BIG_COMMAND
-```
-
-`pi_mini` scouts and finds, `pi` builds and refactors, `pi_big` designs and
-handles incidents. A reviewer, refuter,
-judge or auditor checks level or up, never down: at least the worker's
-capability, from another family if one exists (provider or model-id prefix in
-`pi --list-models`). Small-model signs: a local runtime (ollama, lmstudio,
-llama.cpp), a size (`4b`, `27b`), mini/haiku/flash/nano/lite, thinking `no`,
-context or max-out far below the worker's. No such peer: same model, fresh
-context, higher thinking unless at max. Probe an unused model first
-(`pi --model <provider/model> -p "say ok"`); `ctl: ok` does not test it.
+- `mu_delegate` takes `model`; a spawn takes `--command "pi --model <id>"`.
+- A checker (reviewer, refuter, judge, auditor) runs at the author's tier
+  or higher, from another family when one exists. A delegate with no
+  `model` runs the cli's default model; pass `model` when it matters.
 
 ## Reaper and agent state
 
@@ -264,7 +255,7 @@ Close the task as your last action, or the orchestrator's wait hangs.
 ## Guardrails
 
 Task ownership outranks agent state. Coordinate through task notes and
-the activity log. Keep edges within one workstream. Give workers
+the ops log (`mu log`). Keep edges within one workstream. Give workers
 bounded paths and commands.
 
 ## Recipes
@@ -287,6 +278,7 @@ risky job that needs several of them, start with
 | [drift-audit](recipes/drift-audit.md) | hours into a long run, after a batch, compaction or resume, before a stop rule |
 | [watcher](recipes/watcher.md) | a helper polls a PR, CI, or log for change |
 | [findings](recipes/findings.md) | any review, audit, or check reports problems: where they live, how they are triaged |
+| [models](recipes/models.md) | you pick a model for a spawn or delegate call |
 | [tasks-or-calls](recipes/tasks-or-calls.md) | a recipe step spawns an agent: DAG task or delegate call |
 | [adversarial-review](recipes/adversarial-review.md) | gate each unit you dispatch before it merges (a review task per unit) |
 | [fan-out](recipes/fan-out.md) | a sweep or migration: the same change over many files or call sites |

package/skills/mu/recipes/adversarial-review.md

@@ -1,13 +1,15 @@
 # Adversarial review
 
 Use when a unit of work must be checked by someone other than its
-author before it counts: a fix, a finding, a claim, a plan. The author
+author before it counts: a unit that produces commits (a fix, a feature).
+Checking a finding or claim is a delegate call
+([findings § Triage](findings.md#triage), [refute](refute.md)). The author
 grades its own work generously; a fresh agent told to refute it does
 not. Every other review-shaped recipe builds on this one.
 
 The review is a task in the DAG, not a step inside the worker's
-session. Its verdict, its evidence, and every gap it finds stay in the
-DB: each gap is a finding task ([findings](findings.md)). For a one-off
+session. Its verdict, its evidence, and every finding it makes stay in the
+DB: each is a finding task ([findings](findings.md)). For a one-off
 check outside any workstream, one
 [delegate call](tasks-or-calls.md#delegate-call) is enough; to review a
 PR or diff from several angles, use [review-panel](review-panel.md).
@@ -22,27 +24,29 @@ PR or diff from several angles, use [review-panel](review-panel.md).
 
    ```bash
    mu task add review_x -w <ws> -t "Review x" -i 50 -e 0.5 --blocked-by x \
-     --note 'ACCEPTANCE: see x notes. Refute; report gaps, not style.'
+     --note 'ACCEPTANCE: see x notes. Refute; report findings, not style.'
    ```
 
 3. **Dispatch the work** as usual. When `x` closes, `review_x` becomes
    ready.
 4. **Spawn a fresh reviewer.** A new agent, or `--fresh` on an idle one,
-   so it has none of the author's reasoning, on a model chosen per
-   [Models](../SKILL.md#models-and-thinking-effort). Give it the worker's workspace path
+   so it has none of the author's reasoning, at the worker's tier or
+   higher and from another family ([models](models.md#checkers)). Give it the worker's workspace path
    and commits read-only by instruction; it edits nothing.
 5. **Claim `review_x` for the reviewer**, send the brief (below), wait.
 6. **Act on the verdict:**
    The review's state is the verdict: `CLOSED/done` for ACCEPT,
    `CLOSED/rejected` for REJECT.
    - `ACCEPT`: cherry-pick `x`'s commits and verify the merge.
-   - `REJECT`: the reviewer recorded each gap as an `OPEN/triage` task.
-     Add `review_x_2` and block it on every gap
-     (`mu task block review_x_2 --by <gap>`); work downstream of `x`
-     waits on `review_x_2`, not on the rejected review. Decide each gap
-     as a finding ([findings § Triage](findings.md#triage)), then
-     dispatch the accepted gaps to the original worker, whose context
-     still holds the work. Repeat from step 4 when the gaps are closed.
+   - `REJECT`: the reviewer recorded each finding as an `OPEN/triage` task.
+     Add `review_x_2` and block it on every finding
+     (`mu task block review_x_2 --by <finding>`). Closing `review_x`
+     `--as rejected` unblocked its dependents, so re-block each task
+     downstream of `x` on `review_x_2`
+     (`mu task block <downstream> --by review_x_2`). Decide each
+     finding ([findings § Triage](findings.md#triage)), then
+     dispatch the accepted ones to the original worker, whose context
+     still holds the work. Repeat from step 4 when the findings are closed.
      The DAG grows; nothing is rewritten.
 7. **Cap the rounds.** After two rejections on the same unit, stop the
    loop and decide yourself: split the unit, change the criteria, or
@@ -60,24 +64,25 @@ You are reviewing task <x>. You did not write it. Your job is to find
 where it fails the acceptance criteria in `mu task notes <x>`.
 
 - Read the diff (<range>) and the criteria. Run the tests that cover it.
-- Report gaps against the criteria: a requirement not met, an edge case
+- Report findings against the criteria: a requirement not met, an edge case
   without a test, a change outside scope, a claim the evidence does not
   support. Not style, not preferences.
-- Record each gap as a finding, per findings.md § Record:
-  mu task add -w <ws> --triage -t "<severity>: <gap>" -i <n> -e <days> \
-    --note 'FINDING: <severity> <file:line> <gap> EVIDENCE: <command + output>'
+- Record each as a finding, per findings.md § Record:
+  mu task add -w <ws> --triage -t "<severity>: <title>" -i <n> -e <days> \
+    --note 'FINDING: <severity> <file:line> <what fails> EVIDENCE: <command + output>'
 - If you could not check something (tool failed, no access), say
   UNVERIFIED for it. Unverified is not a pass and not a fail.
-- Do not edit files.
+- Your only writes are `mu task add` (findings), the verdict note, and
+  the close; leave the workspace as you found it.
 
 Write the verdict note (FILES/COMMANDS/FINDINGS/VERIFIED), then close
 (long reasons: a heredoc variable, brief.md § Quoting):
   ACCEPT: mu task close review_<x> --evidence "<key command>: <result>"
   REJECT: mu task close review_<x> --as rejected \
-            --why "<n> gaps: <id> (<why it fails, one clause>), ..."
+            --why "<n> findings: <id> (<why it fails, one clause>), ..."
 ```
 
-mu adds each named gap's title to the REJECTED note.
+mu adds each named finding's title to the REJECTED note.
 
 **Closing a review yourself** (you fixed a finding, or accept without a
 fresh reviewer): write the reviewer's note plus `COMMIT: <sha> fixes
@@ -93,7 +98,7 @@ by orchestrator`.
   reviewer ran. A review with no evidence is a
   rejected review: re-send it.
 - **Reviewers drift into fixing.** A reviewer that edits the code is now
-  an author nobody reviews. The fix belongs to the gap tasks.
+  an author nobody reviews. The fix belongs to the finding tasks.
 - **Review is not merge verification.** An accepted unit can still
   break once merged with moved main. Verify the merge as in
   [orchestrator-loop](orchestrator-loop.md#merging).

package/skills/mu/recipes/brief.md

@@ -77,5 +77,6 @@ mu task close <id> -w <ws> --evidence "$v"
 Chain batched adds with `&&`, then `mu task list`, so one
 quoting failure cannot half-apply the batch unseen.
 
-Done when a worker with no other context could finish the task from
-the brief and the notes it points at, and could tell when it is done.
+Done when the brief has GOAL, FILES, DONE WHEN, VERIFY and the
+final-action block, every shared fact is a `Read:` pointer, and the task
+holds a refuter verdict or a `REFUTE-EXEMPT:` note.

package/skills/mu/recipes/codemode-driver.md

@@ -44,7 +44,7 @@ return wait.output;
 
 Size the worker list from the ceiling on the umbrella
 ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)),
-one per ready track. Merge and verify outside the script
+one per ready task. Merge and verify outside the script
 ([orchestrator-loop § Merging](orchestrator-loop.md#merging)). Check
 field names against `--json` output; the script is a shape, not an API.
 
@@ -54,8 +54,8 @@ field names against `--json` output; the script is a shape, not an API.
 answers arrive after the script, as follow-up messages: the script
 gains nothing over issuing the calls in one turn. Use it from a script
 only when `codemode.mode` is `only` and the tool is not offered
-directly. Check `Promise.allSettled` results for rejections: past the
-cap, `mu_delegate` refuses.
+directly. Check `Promise.allSettled` results for rejections; the cap is in
+[orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency).
 
 To get the verdicts back as one table instead of one message each, use
 the `scratch` form through `tools.bash`:
@@ -63,8 +63,9 @@ the `scratch` form through `tools.bash`:
 ```js
 // @options: {"timeout_ms": 1800000}
 const ws = "audit";
-const findings = ["f_auth_put", "f_sql_order"]; // finding task ids, at most the cap per script
+const findings = ["f_auth_put", "f_sql_order"]; // finding task ids, within the cap
 const sh = async (c) => (await tools.bash({ command: c })).output;
+const dir = `${(await sh("echo $HOME")).trim()}/.local/state/mu`;
 const json = (s) => { try { return JSON.parse(s); } catch { return {}; } };
 const el = (ms) => { const t = Math.round(ms / 1000); return t < 60 ? `${t}s` : `${Math.floor(t / 60)}m ${String(t % 60).padStart(2, "0")}s`; };
 const rows = await Promise.all(findings.map(async (id, i) => {
@@ -77,7 +78,8 @@ const rows = await Promise.all(findings.map(async (id, i) => {
   const note = w.outcome !== "done" ? `REFUTER ${i + 1}: no verdict (${w.outcome ?? "no result"})`
     : `REFUTER ${i + 1} (${a}, ${el(Date.now() - t0)}):\n` + (at < 0 ? `NO VERDICT LINE: ${(w.lastText ?? "").slice(-1500)}`
     : [lines[at], ...lines.slice(at + 1).filter((l) => /^[\s>*_`-]*EVIDENCE:/.test(l))].join("\n"));
-  await sh(`mu task note ${id} -w ${ws} - <<'MU_EOF'\n${note}\nMU_EOF`);
+  await tools.write({ path: `${dir}/note-${a}.txt`, content: note }); // answer text never touches a shell
+  await sh(`mu task note ${id} -w ${ws} - < ${dir}/note-${a}.txt && rm ${dir}/note-${a}.txt`);
   if (w.outcome === "done") await sh(`mu agent close ${a} -w scratch`);
   return `${id}\t${note.split("\n")[1] ?? note}`;
 }));
@@ -87,7 +89,8 @@ return rows.join("\n");
 What the tool did for you, the script now owns:
 
 - **The cap.** `MU_DELEGATE_MAX` does not apply to bash spawns: keep
-  each script's list at or under it.
+  each script's list within
+  [orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency).
 - **Cleanup.** Close each scratch pane; a timed-out one stays, readable
   with `mu agent read <a> -w scratch`.
 - **Recording.** The script writes each `REFUTER` note in `record`'s

package/skills/mu/recipes/deep-research.md

@@ -31,7 +31,8 @@ answer rests on is an `OPEN/triage` task, decided like a finding
    ```
 
    A claim without a source and a quote is not a claim. Searchers can
-   run on a cheap model.
+   run cheap (hosted, not local: [models](models.md#local-models-are-a-last-resort));
+   the checkers in step 4 run mid or higher.
 3. **Dedupe claims**: merge the same fact from several sources (keep
    every source), and flag claims that contradict each other. In
    workstream mode, each surviving claim becomes an `OPEN/triage` task

package/skills/mu/recipes/drift-audit.md

@@ -35,13 +35,14 @@ or close you compare against is often older than it.
    IN_PROGRESS note, and each merged fix its task's findings depend on:
    git merge-base --is-ancestor <fix> <pinned>. Exit 1 = pin is stale.
 3. Closed-task notes: notes added after the task's last task.close op,
-   minus the `CLOSE:` or `<SUBSTATE>:` note the close verb itself writes
-   as the very next op (seq + 1); any other note counts, whatever its
-   prefix. Report each of the top 5 by count as its own finding with its count,
+   minus those the close verb writes in its own transaction
+   (`--evidence`, `--why`: timestamp within 50ms of the close op); any
+   other note counts, whatever its prefix. Report each of the top 5 by
+   count as its own finding with its count,
    even when the notes look routine. A late note that reports the
    closed bug again usually ran on a build without the closing fix:
    check its sha with git merge-base --is-ancestor <fix> <sha>.
-   mu sql "select t.local_id name, count(*) late from tasks t join workstreams w on w.id=t.workstream_id join task_notes n on n.task_id=t.id join (select key, max(seq) seq, max(created_at) at from ops where intent='task.close' and entity='task' group by key) c on c.key='<ws>/'||t.local_id where w.name='<ws>' and t.status='CLOSED' and n.created_at > c.at and not exists (select 1 from ops x where x.seq=c.seq+1 and x.entity='note' and x.key=c.key||'#'||n.id and (n.content like 'CLOSE: %' or n.content like upper(t.substate)||': %')) group by t.local_id order by late desc"
+   mu sql "select t.local_id name, count(*) late from tasks t join workstreams w on w.id=t.workstream_id join task_notes n on n.task_id=t.id join (select key, max(created_at) at from ops where intent='task.close' and entity='task' group by key) c on c.key='<ws>/'||t.local_id where w.name='<ws>' and t.status='CLOSED' and (julianday(n.created_at)-julianday(c.at))*86400 > 0.05 group by t.local_id order by late desc"
 4. Thin decisions: an ACCEPT/REJECTED/CLOSE/SUPERSEDED note under 40
    chars; a refuter tally with no REFUTER or VERDICT note; a review the
    orchestrator closed with no FILES/COMMANDS note and no commit.

package/skills/mu/recipes/fan-out.md

@@ -9,7 +9,9 @@ some and calls the job done; one task per unit cannot.
 1. **Enumerate first.** A scout (a [delegate call](tasks-or-calls.md#delegate-call)) lists the units and
    writes them to the umbrella's note, one per line. The list is done
    when it matches a command the scout ran (`rg -l`, a test listing),
-   not when it looks complete. Record the command and the count.
+   not when it looks complete. Record the command and the count. The
+   scout runs cheap; the units run mid, or strong when each is a
+   judgement call ([models](models.md#roles)).
 2. **One task per unit**, blocked into an umbrella:
 
    ```bash
@@ -23,13 +25,13 @@ some and calls the job done; one task per unit cannot.
    only checks (no commits) makes each unit a delegate call instead
    ([tasks-or-calls](tasks-or-calls.md)).
 3. **Cap concurrency** ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)).
-   Spawn at most one agent per ready track. Tell workers to avoid
+   One agent per ready unit, up to the ceiling. Tell workers to avoid
    repo-wide commands so more can run.
 4. **Pipeline.** Dispatch, wait `--first`, merge
    ([orchestrator-loop § Merging](orchestrator-loop.md#merging)), dispatch
    the next unit to the freed worker with `--fresh`. With `codemode`, a
    [driver](codemode-driver.md) can dispatch each batch. Units that touch the same files
-   go on one track (see [waves](waves.md)).
+   are chained with `block` (see [waves](waves.md)).
 5. **Review per unit** when a wrong unit is costly: add a review task
    per unit ([adversarial-review](adversarial-review.md)).
 6. **Synthesize** when the output is a report, not commits: one

package/skills/mu/recipes/findings.md

@@ -94,8 +94,10 @@ across reviewers and creates one task per real problem.
    | 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; close the grouped findings
-   `--as superseded --why "fixed in <fix-task>"`.
+   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.
@@ -105,7 +107,9 @@ with an `UNVERIFIED` note, and each of those is reported to the human.
 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.
+`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.
 
 The report is a query, not a document: `mu task list -w <ws>
 --substate rejected`, `--substate duplicate`, `--status OPEN`, and the

package/skills/mu/recipes/hypothesis-panel.md

@@ -9,7 +9,8 @@ form independent theories; separate agents then try to kill them.
 
 1. **Write the symptom** on the umbrella: what happens, how often, the
    repro command, and what would count as fixed.
-2. **One reader per evidence source** (a [delegate call](tasks-or-calls.md#delegate-call)): logs, the
+2. **One reader per evidence source** (a [delegate call](tasks-or-calls.md#delegate-call), strong tier:
+   root cause is judgement, [models](models.md#roles)): logs, the
    code path, recent commits, data, environment. Each sees only its
    source, so the theories do not anchor on each other. Record each
    theory as an `OPEN/triage` task blocking the umbrella, decided like

package/skills/mu/recipes/models.md

@@ -0,0 +1,102 @@
+# Model tiers
+
+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.
+
+## Tiers
+
+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 |
+| --- | --- | --- |
+| **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
+
+| 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".
+
+- `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.
+
+Probe a model you have not used this session
+(`pi --model <id> -p "say ok"`); `ctl: ok` after spawn does not test the
+model.
+
+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"`.

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

@@ -6,10 +6,10 @@ the loop and the reasons behind them.
 
 ## Every turn
 
-1. `mu state -w <ws>` — read agents, IN_PROGRESS, ready tasks,
-   parallel tracks.
-2. Spawn at most one agent per independent ready track ([waves](waves.md)
-   when workers share files).
+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
@@ -109,9 +109,7 @@ keep the note as the durable copy. pi:
 
 ## Stopping a worker
 
-`mu agent abort <w>` first for pi (exact, local or remote, keeps
-context, waits for idle; exit 5 = still busy; queued follow-ups return
-to the editor unsent). Then `mu agent kick` (pi unresponsive, or
-non-pi; local panes only), then `mu agent close`.
+`mu agent abort <w>` first for pi, then `mu agent kick` (pi
+unresponsive, or non-pi), then `mu agent close`.
 
 Done when every task is closed, or a decision only a human can make blocks all progress (SKILL.md § Orchestrator rules).

package/skills/mu/recipes/plan.md

@@ -38,20 +38,20 @@ human asks for a file.
    of order.
 6. **Add edges for dependencies only.** `mu task block A --by B` when A
    consumes what B produces. Plan order is not a dependency: an extra
-   edge serialises tracks that could run in parallel. The exception:
-   tasks that edit the same files share a track ([waves](waves.md)).
+   edge serialises tasks that could run in parallel. The exception:
+   tasks that edit the same files are chained ([waves](waves.md)).
 7. **Self-review before dispatch.** Map each spec requirement to its
    task, grep the notes for placeholders, match INTERFACES names across
    tasks, and read the graph back (`mu task tree task_0 -w <ws> --down`).
    Then refute each brief that makes claims ([call](tasks-or-calls.md#delegate-call),
-   all in one turn): "What in this brief is false about the code,
+   all in one turn, at your tier from another family: [models](models.md#checkers)): "What in this brief is false about the code,
    ambiguous, or would make a correct worker fail review? Cite
-   file:line." Rewrite each AMEND. Five of six briefs refuted in one run had
+   file:line." Rewrite each REFUTED brief. Five of six briefs refuted in one run had
    such a defect, e.g. a fallback test old extensions made unpassable.
 
 Done when every spec requirement maps to a task, no note holds a
 placeholder, every claim-making brief has a verdict, and `mu state`
-shows the intended parallel tracks. Then dispatch per [orchestrator-loop](orchestrator-loop.md).
+lists the tasks you meant to run in parallel as Ready together. Then dispatch per [orchestrator-loop](orchestrator-loop.md).
 
 ## Notes