@mu-crew/mu 3.6.2 → 3.8.0

package/docs/ARCHITECTURE.md

@@ -120,7 +120,7 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | `src/agents/spawn.ts` | spawn: CLI resolution, pane create or reuse, liveness, readiness, ctl handshake, rollback |
 | `src/agents/spawn-lock.ts` | per-session lock around topology and row insert |
 | `src/agents/transport.ts` | send routing: ctl for pi agents, mux paste otherwise, no fallback; `expectsCtl` |
-| `src/agents/abort.ts` | stop a pi turn through the control socket |
+| `src/agents/abort.ts` | stop a pi turn through the control socket; abort + send (`--interrupt`) |
 | `src/agents/delegate.ts` | `delegateOutcome`: one wait result to `done` / `empty` / `died` / `timeout` / `pending` |
 | `src/agents/wait.ts` | block until task-less agents leave `busy` |
 | `src/agents/adopt.ts` | register an existing pane as an agent |
@@ -139,7 +139,7 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | `src/ctl/client.ts` | `ctlRequest`, `ctlProbe`, version and unknown-op errors |
 | `extension/mu-pi.ts` | pi extension, child side: serves `$MU_CTL_SOCK`; built to `dist/extension/mu-pi.js` |
 | `extension/delegate.ts` | pi extension, parent side: `mu_delegate` / `mu_delegate_cancel`, which shell out to `mu` |
-| `extension/nudge.ts` | pi extension: the keep-driving nudge. Arms on a `mu` dispatch, checks `mu state --json` at `agent_before_settle`, injects the SKILL.md rule once per prompt, logs `--kind nudge` |
+| `extension/nudge.ts` | pi extension: the keep-driving nudge. Arms on a `mu` dispatch, checks `mu state --json` at `agent_before_settle`, injects the SKILL.md rule once per prompt, logs `--kind nudge`. Also the close nudge (worker settles owning a task) and the refute nudge (`task claim --for` on a task with no refute decision in `mu task notes --json`; one notice, no continuation) |
 | `src/link.ts` | `mu link pi`: extension shim, skill symlink, `inspectLinks` for doctor |
 
 ### Tasks, workspaces and workstreams
@@ -168,7 +168,8 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | `src/cli.ts` | Commander wiring (`buildProgram`) |
 | `src/cli/*.ts` | one file per verb namespace, thin wrappers over the SDK; `format.ts` renders tables, `handle.ts` maps errors to exit codes and runs ambient sync |
 | `src/cli/tasks/*.ts` | the `mu task` namespace, including `mu me tasks` / `mu me next` |
-| `src/cli/dispatch-hints.ts` | dispatch-time `Next:` hints for pi agents (`--fresh`, `--steer`, abort) |
+| `src/cli/dispatch-hints.ts` | dispatch-time `Next:` hints for pi agents (`--fresh`, `--interrupt`, abort) |
+| `src/cli/stdin.ts` | `-` as a text argument: reads note / send text from stdin (heredoc prose) |
 | `src/cli/agents-remote.ts` | `mu agent remote-env`: prints the ssh forward and env, runs nothing |
 | `src/cli/tui-launch-focus.ts` | initial-tab focus ladder for bare `mu` and `mu state --tui` |
 | `src/cli/tui/` | the ink TUI; the only place ink and react are imported |

package/docs/architecture/control-socket.md

@@ -28,10 +28,11 @@ reply carries `v: 1`; the client (`src/ctl/client.ts`) throws
 | op | does |
 | --- | --- |
 | `hello` | identity plus `ops` (served ops) and `extVersion` (the mu version the extension was built from) |
-| `status` | `state` (`busy` / `idle` / `needs_input`), `since`, `runs`, `pending` |
-| `send` | `pi.sendUserMessage`; when busy, `mode` is `steer` or `followUp` (default) |
+| `status` | `state` (`busy` / `idle`), `since`, `runs`, `pending` |
+| `send` | `pi.sendUserMessage`; when busy, `mode` is `steer` or `followUp` (default). Replies with the `status` fields measured before the dispatch, so `runs` is the baseline for a later `wait` |
 | `wait` | resolves on pi's `agent_settled` after `afterRuns`, with the run's `lastText` |
 | `abort` | `ctx.abort()` (pi's Esc) |
+| `interrupt` | busy: `ctx.abort()`, wait for `agent_settled` (up to `timeoutMs`), then `pi.sendUserMessage(text)` as a new run; idle: just the send. Replies `wasBusy`, `pending` (measured before the abort) and the `status` fields measured after the settle and before the send, so `runs` is the `wait` baseline for the new run. `timeout`: nothing sent |
 | `fresh` | new session plus prompt as one operation, through the internal `/mu-fresh` command; replies once the new run starts; refused with `busy` unless `force` |
 | `command` | `name` `new`, `reload` or `compact` (with optional `instructions`), through the internal `/mu-new`, `/mu-reload`, `/mu-compact` commands, which call `ctx.newSession()`, `ctx.reload()`, `ctx.compact()`. `new` replies once the session is replaced, `reload` after the `session_start` it causes, `compact` when compaction starts or with pi's error (`Nothing to compact ...`). Refused with `busy` unless `force` |
 
@@ -41,13 +42,14 @@ extension command, triggered with `expandPromptTemplates: true`, and
 its handler gets the command context that can replace or reload the
 session.
 
-These back `mu agent send` (`--fresh`, `--steer`, session commands), `mu agent wait`,
+These back `mu agent send` (`--fresh`, `--steer`, `--interrupt`, session commands), `mu agent wait`,
 `mu agent abort`, the agent state reading, and `mu_delegate`.
 
 ## Version skew
 
 An op the extension does not serve returns `unknown op: <op>` with its
-`ops` list. mu raises `AgentExtensionOutdatedError` (exit 4), whose
+`ops` list. `mu agent send --interrupt` then composes `abort`, `wait`
+and `send` itself. Any other op raises `AgentExtensionOutdatedError` (exit 4), whose
 next steps are `/reload` through the mux (an extension that lacks the
 `command` op cannot run it over ctl) or a respawn. `mu doctor`
 probes every pi agent's socket (the `ctl` row) and flags an
@@ -68,7 +70,10 @@ row reports whether `mu link pi` installed the extension.
 
 1. If the path already answers, another pi serves it (a nested `pi -p`
    inherited `MU_CTL_SOCK`). The extension leaves it alone and says so
-   on stderr.
+   on stderr. Identity follows the bind: that pi, and one that loses
+   the `link()` race, is nested and gets no keep-driving, close or
+   refute nudge, though it inherited the agent's `MU_AGENT_NAME`.
+   The decision lives in the process-global map, so `/reload` keeps it.
 2. Otherwise it listens on a private name in the same directory, sets
    mode 0600, and hard-links that name onto the public path. libuv
    unlinks the listened-on name at close, so the public path must never

package/docs/architecture/mux.md

@@ -104,7 +104,10 @@ as a capability, not a name check:
 - **tmux.** After `MU_SPAWN_LIVENESS_MS` (default 1500, `0` skips) mu
   verifies the pane survived and scans its tail for provider or auth
   startup errors. mu does not wait for murmur to claim the pane: state
-  reads before the first claim report `unknown`.
+  reads before the first claim report `unknown`. A pi agent skips the
+  fixed wait: mu checks the pane on every handshake tick (a dead pane
+  rolls back at once) and scans for startup errors when the handshake
+  ends.
 - **herdr.** mu creates a bare pane and calls `startAgentInPane`, which
   subsumes both checks.
 - **pi, either backend.** After the agent starts, mu polls its control

package/docs/guide/delegate.md

@@ -23,6 +23,7 @@ Delegates called in one turn run in parallel.
 | `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`), e.g. a cheaper model. |
 | `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). |
 
 - Watch or steer: run the attach command.
 - Stop: `mu_delegate_cancel`, or `mu agent abort <name> -w scratch`.
@@ -45,21 +46,42 @@ Delegates called in one turn run in parallel.
 
 `MU_DELEGATE=0` hides the tool ([env vars](../reference/env.md)).
 
+### Record a verdict
+
+For a refuter or check, pass `record` so the verdict lands on the task
+it judged. The task must exist (`mu task show`), else the call fails
+and nothing spawns. When the answer arrives, the tool runs
+`mu task note <task> -w <ws> --author <delegate>` once:
+
+- Done: `REFUTER <label> (<delegate>, <elapsed>):`, then the last
+  `VERDICT:` line and every `EVIDENCE:` line after it. Without a
+  VERDICT line, the answer's last 1500 chars after `NO VERDICT LINE:`.
+  Capped at 4000 chars.
+- Timeout, died, empty, error, or cancelled:
+  `REFUTER <label>: no verdict (<outcome>)`.
+
+The follow-up still carries the full answer and ends with
+`Recorded on <ws>/<task> as a note.`, or the reason recording failed.
+
 ## Delegate without pi
 
 From a script or other shell, run what the tool runs:
 
 ```bash
 mu agent spawn helper-1 -w scratch
-mu agent send helper-1 -w scratch --fresh 'Investigate why foo.spec.ts fails. Report the cause.'
-mu agent wait helper-1 -w scratch --json
+runs=$(mu agent send helper-1 -w scratch --fresh --json 'Investigate why foo.spec.ts fails. Report the cause.' | jq .runs)
+mu agent wait helper-1 -w scratch --after-runs "$runs" --json
 ```
 
+`--after-runs` waits for the first run past the count the send
+reported, so a run that settles before the wait starts still counts.
+
 Use `--fresh`: a plain send to a reused agent carries the previous
 task's context.
 
 `mu agent wait` fires when the agent leaves busy (including to
-`needs_input`), never on an already idle agent. For pi, the `--json`
+`needs_input`), never on an already idle agent unless it finished a run
+past `--after-runs`. For pi, the `--json`
 row carries:
 
 - `outcome`: `done`, `empty`, `error`, `died`, `timeout`, or `pending`.

package/docs/guide/dispatch.md

@@ -33,7 +33,8 @@ socket. Pick the mode by what the agent is doing:
 | Situation | Command |
 | --------- | ------- |
 | New task, any state | `mu agent send worker-1 --fresh '<brief>'` |
-| Busy, and you want to interrupt the current run | `mu agent send worker-1 --steer '<text>'` |
+| Busy, and the current work is wasted (wrong input, changed rule): act now | `mu agent send worker-1 --interrupt '<text>'` |
+| Busy, advice that can wait for the next tool boundary | `mu agent send worker-1 --steer '<text>'` |
 | Answering a question, or adding to the same task | `mu agent send worker-1 '<text>'` |
 
 - `--fresh` starts a new pi session and sends the prompt into it as
@@ -41,7 +42,14 @@ socket. Pick the mode by what the agent is doing:
   `mu agent abort` first, or pass `--force` to drop the running turn.
 - Never send `/new` and then the prompt as two sends to pi. The prompt
   can land during the reset and vanish.
-- A plain send to a busy agent queues as a follow-up.
+- A plain send to a busy agent queues as a follow-up: pi sees it after
+  the run ends. `--steer` lands between tool calls, after the running
+  tool returns; it does not stop a long tool such as a test batch, a
+  wait, or a `sleep`.
+- `--interrupt` aborts the run (kills the running tool), waits for pi
+  to settle, then sends the text as a new run. Queued messages go back
+  to the pane's editor unsent. Exit 5 when pi does not settle within
+  `--timeout` (default 30 s); the text is then not sent.
 - `/new`, `/reload` and `/compact [instructions]` run inside pi through
   the socket and report pi's answer (for example `Nothing to compact`).
   They refuse with exit 4 while pi is busy; `--force` overrides. Any
@@ -77,7 +85,9 @@ git commit -am '...' THEN
 mu task close build -w auth --evidence '...'
 ```
 
-Single-quote prompts that contain `$` or backticks. To see only what the worker wrote after the claim, run
+Single-quote short prompts. Pass prose (apostrophes, `$`, backticks) as `-` with a
+quoted heredoc: `mu agent send worker-1 - <<'EOF'`; see
+[brief](../../skills/mu/recipes/brief.md#quoting). To see only what the worker wrote after the claim, run
 `mu task notes build -w auth --since-claim`.
 
 ## Give each worker a workspace
@@ -118,8 +128,11 @@ mu task wait auth/build auth/docs --first --on-stall exit --json
   polling instead.
 
 Exit 7 has several causes: the worker finished but did not close, it
-asked a question, or it hit a prompt. In each case, run
-`mu agent read <owner>` first.
+asked a question, or it hit a prompt. In each case, run the exit's
+`Next:` first. For a pi owner, it starts with
+`mu agent wait <owner> --after-runs <runs-1> --json`, which prints the
+last answer at once. Then it shows `mu agent read <owner>`, for the
+dialogs and crashes that only the pane shows.
 
 Pipeline the work: merge one task, run your tests on the merged tree,
 then dispatch the next task. Waiting for a whole wave hides partial
@@ -136,6 +149,10 @@ mu task release build -w auth
 
 - Closed substates other than `done` need `--why`. Every `CLOSED`
   substate satisfies a blocker.
+- Deciding a finding (`accept`, or `close --as rejected|wontfix|duplicate`)
+  with a reason under 40 characters and no `VERDICT:` or `REFUTER` note
+  prints a warning. The exit code stays the same. A `REJECTED` or `SUPERSEDED`
+  note appends the title of each task id it names.
 - `--if-ready` closes only when every blocker is closed. Otherwise it
   lists the open blockers and exits 0.
 - A parked task leaves the ready set, and its dependents keep waiting.

package/docs/guide/getting-started.md

@@ -126,7 +126,7 @@ The exit code tells you what happened:
 | `0` | the task closed | merge the work |
 | `5` | `--timeout` expired (default 600 s) | wait again |
 | `6` | the worker's pane died and the task went back to `OPEN` | spawn and claim again |
-| `7` | the worker sat in `needs_input` for 2 minutes | `mu agent read worker-1 -w auth`, then answer it |
+| `7` | the worker sat in `needs_input` for `--stuck-after` seconds (120, or 5 for a pi worker read over its control socket) | run its `Next:` (for a pi worker, `mu agent wait worker-1 --after-runs <runs-1> --json -w auth` returns the last answer; otherwise `mu agent read worker-1 -w auth`), then answer it |
 
 `--on-stall exit` is the default; it is spelled out above so older mu
 versions behave the same. With `--on-stall warn`, a stalled worker only
@@ -179,7 +179,7 @@ mu has not freed. That protects work you have not merged.
 ## Next steps
 
 - [Dispatch work to a worker](dispatch.md) covers more than one
-  worker and the `--fresh`, `--steer`, and plain send choices.
+  worker and the `--fresh`, `--interrupt`, `--steer`, and plain send choices.
 - [Use the TUI dashboard](tui.md): run bare `mu` to see every
   workstream at once.
 - [Clean up](cleanup.md) when the workstream is finished.

package/docs/guide/recovery.md

@@ -41,22 +41,27 @@ back to pasting.
 
 | State | Means | Fix |
 | ----- | ----- | --- |
-| `ctl missing` | no socket: the extension is not loaded | run `mu link pi`, then respawn the agent |
+| `ctl missing` | no socket: the extension is not loaded, or a new pi waits at its trust prompt | answer the [trust prompt](#a-new-pi-agent-shows-ctl-missing), or run `mu link pi`, then respawn the agent |
 | `ctl refused` | the socket exists but does not answer | respawn the agent; for a remote agent, check the ssh forward |
-| `extension X older than installed Y` | pi loaded an older mu build | type `/reload` in the pane, or respawn |
+| `extension X older than installed Y` or `extension lacks ops` | pi loaded an older mu build | send `/reload`, or respawn |
 
 To send `/reload` without attaching:
 
 ```bash
-mu agent send worker-1 -w auth '/reload' --via mux
+mu agent send worker-1 -w auth '/reload'             # extension serves op command
+mu agent send worker-1 -w auth '/reload' --via mux   # older: type it into the pane
 ```
 
-`/reload` keeps the pi session. A `send --fresh` or `abort` against an
+The error names the right form. `/reload` keeps the pi session. A `send --fresh` or `abort` against an
 outdated extension fails with exit 4 and prints the same two fixes.
 
-## A new pi agent is stuck at `needs_input`
+## A new pi agent shows `ctl missing`
 
-pi asks whether to trust a project folder on first start. Run
+pi asks whether to trust a project folder on first start. It asks
+before it loads extensions, so the agent has no control socket yet:
+mu shows `unknown (ctl missing)` and spawn warns after 30 s. A pi
+launched through a wrapper whose name is not `pi` or `pi-meta` shows
+`needs_input` instead. Run
 `/trust` in the pane once, or spawn with
 `--command 'pi --approve'`. `--approve` trusts every directory,
 including workspace forks, so use it only on your own code.

package/docs/guide/upgrade.md

@@ -25,15 +25,15 @@ For agents other than pi, see [README § Install](../../README.md#install).
 ## Reload running pi agents
 
 A running pi keeps the extension it loaded at start. After an upgrade,
-type `/reload` in each agent's pane, or respawn the agent. From a
-shell:
+send `/reload` to each agent, or respawn the agent. From a shell:
 
 ```bash
-mu agent send worker-1 -w auth '/reload' --via mux
+mu agent send worker-1 -w auth '/reload'             # extension serves op command
+mu agent send worker-1 -w auth '/reload' --via mux   # older extension
 ```
 
 Until then, the `ctl` row of `mu doctor` warns
-`extension X older than installed Y`. Ops the old extension lacks,
+`extension X older than installed Y` or `extension lacks ops`. Ops the old extension lacks,
 such as `send --fresh`, fail with exit 4.
 
 ## Upgrade from 3.1 or earlier

package/docs/reference/env.md

@@ -29,7 +29,7 @@ milliseconds; `0` disables a wait unless noted.
 | --- | --- | --- |
 | `MU_<CLI>_COMMAND` | Executable for `--cli <cli>`; hyphens become underscores (`--cli pi-meta` reads `MU_PI_META_COMMAND`). May hold arguments. `--command` wins; the spawn line names the env var when it supplied the command. | the cli value |
 | `MU_SPAWN_CTL_MS` | Budget for the control-socket handshake with a new pi agent, polled every 250ms. On timeout spawn still exits 0, reports `ctl: missing` or `ctl: refused`, and warns. `--no-ctl` skips it per spawn. | `30000` |
-| `MU_SPAWN_LIVENESS_MS` | tmux only. Wait this long, then check the pane is alive and its scrollback has no startup error (auth failure, `command not found`). Failure rolls back the row and throws `AgentDiedOnSpawnError` or `AgentSpawnStartupError`. | `1500` |
+| `MU_SPAWN_LIVENESS_MS` | tmux only. Wait this long, then check the pane is alive and its scrollback has no startup error (auth failure, `command not found`). Failure rolls back the row and throws `AgentDiedOnSpawnError` or `AgentSpawnStartupError`. A pi agent skips the wait: the pane is checked on each ctl handshake tick and scanned when it ends. | `1500` |
 | `MU_SPAWN_LOCK_TIMEOUT_MS` | How long a spawn waits for the per-workstream spawn lock. | `15000` |
 
 ## Send and state (tmux path)
@@ -68,7 +68,7 @@ pi agent's `--command`. mu never reads them back.
 | --- | --- | --- |
 | `MU_DELEGATE` | `0` hides the `mu_delegate` tool. `mu doctor` reports it. | unset: shown |
 | `MU_DELEGATE_MAX` | Most delegates one pi session runs at once. Further calls queue, up to four times this; past that `mu_delegate` refuses. A positive integer. | `16` |
-| `MU_NUDGE` | `0` turns off both nudges: the keep-driving nudge (one reminder when an orchestrator ends a turn with dispatched work still IN_PROGRESS) and the close nudge (one reminder when a mu-spawned pi worker ends a turn still owning an IN_PROGRESS task). `mu doctor` reports it. | unset: on |
+| `MU_NUDGE` | `0` turns off the three nudges: the keep-driving nudge (one reminder when an orchestrator ends a turn with dispatched work still IN_PROGRESS), the close nudge (one reminder when a mu-spawned pi worker ends a turn still owning an IN_PROGRESS task), and the refute nudge (one notice when an orchestrator dispatched a task whose notes hold no `REFUTER`, `VERDICT:` or `REFUTE-EXEMPT:` line). A pi nested in an agent's pane (it found `MU_CTL_SOCK` served by another pi) gets none of them; a pi without UI (`pi -p`, json mode) gets no close or refute nudge. `mu doctor` reports it. | unset: on |
 | `MU_PI_HOME` | Root under which `mu link pi` writes `.pi/` and `.agents/`. | `$HOME` |
 | `PI_CODING_AGENT_DIR` | Read only. pi's agent dir, checked for a linked murmur extension. | `~/.pi/agent` |
 | `MU_EXTENSION_ENTRY` | Test only. Built extension the `mu link pi` shim imports. | `dist/extension/mu-pi.js` |

package/docs/specs/2026-10-03-keep-driving-nudge.md

@@ -140,3 +140,24 @@ claimed a task for a worker, ended its turn, received one
 `[mu-keep-driving]` message with `mu task wait nudgeprobe/slow ...`, and
 `mu log --kind nudge` held one entry. With nothing IN_PROGRESS, no
 nudge fired.
+
+## Refute nudge (2026-10-05)
+
+A sibling hook in the same file (`registerRefuteNudge`), registered on
+its own: it does not need the keep-driving markers and has its own
+once-per-prompt flag.
+
+- **Arm** on `mu task claim <id> --for` (`dispatchedTasks`: the id is
+  the first positional that is not an option value; `<ws>/<id>`
+  splits). `review_*` tasks never arm: their brief is the fixed
+  reviewer template, judging work against an already-refuted brief.
+- **Check** at a completed `agent_before_settle`: `mu task notes <id>
+  -w <ws> --json` per armed task. This is a second read beside
+  `mu state --json`. A task counts as refuted when a note has a line
+  starting `REFUTER `, `VERDICT:` or `REFUTE-EXEMPT:`; prose that only
+  mentions the words mid-line does not count.
+- **Notify** once per prompt: one `custom_message`
+  (`customType: "mu-refute-brief"`, `display: true`) listing every
+  unrefuted `<ws>/<id>`, and `mu log --kind nudge 'refute: ...'`. No
+  `continue`: it informs, and the orchestrator decides. `MU_NUDGE=0`
+  turns it off.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.6.2",
+  "version": "3.8.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,6 +1,6 @@
 ---
 name: mu
-description: Manage AI agents in terminal-multiplexer panes (tmux or herdr) — from a single off-the-cuff helper to a persistent crew coordinated through a built-in task graph. Use when the user asks to "create/spin up a subagent to X", "run X in the background", "do this in parallel", "use one subagent per X to do Y", "kick off a helper to watch/investigate/draft X", or to spawn, send work to, observe, or coordinate one or many agents — especially work you'll keep talking to, long-lived or background agents, or anything needing a dependency graph. For zero-ceremony helpers use the reserved `scratch` workstream; for one-shot "fire and get a result back" use the `mu_delegate` tool — its pane is attachable while it runs.
+description: Fresh-context 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 over files; background helpers (watchers, soak runs, agents you keep talking to); persistent crews with a task graph, review gates and merges. Outside pi, delegate through the reserved `scratch` workstream.
 ---
 
 # mu — Multi-agent orchestration
@@ -53,9 +53,9 @@ Recipe words, the same in every recipe:
 - **wave** — the units dispatched from one main revision; refresh
   workspaces before the next.
 - **finding** — one reported problem, recorded as an `OPEN/triage` task.
-- **verdict** — the last line of a check's answer:
-  `VERDICT: CONFIRMED | REFUTED | UNVERIFIED <evidence>` (or ACCEPT |
-  REJECT for a review gate).
+- **verdict** — a check's answer: `VERDICT: <id> CONFIRMED | REFUTED |
+  UNVERIFIED <one line>` plus `EVIDENCE:` lines (or ACCEPT | REJECT for
+  a review gate).
 - **stop rule** — the command and condition that end a loop, written on
   the umbrella first ([loop-until-done](recipes/loop-until-done.md)).
 
@@ -65,12 +65,18 @@ Use mu for persistent helpers, parallel work, dependencies, gated review, or
 work that must survive context compaction. Stay in one context for tiny edits
 or inspection.
 
-### Off-the-cuff helpers (`scratch`)
+### Quick checks and off-the-cuff helpers (`scratch`)
 
-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`, then `mu agent wait --json` (`lastText`).
-Recipes call either form a **delegate call**.
+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)).
+
+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
+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.
 
 - `mu agent wait <names...> --first` waits for busy → idle instead of a
   `sleep` loop; exit 0 met, 5 timeout, 6 pane died.
@@ -78,8 +84,10 @@ Recipes call either form a **delegate call**.
 - One agent per independent unit; `--workspace` for any helper that may edit,
   build, or test the shared repo.
 
-A helper stuck at `needs_input` right after spawn likely hit pi's
-project trust prompt: add `--approve` to `MU_<CLI>_COMMAND`. Move off
+A pi helper showing `unknown (ctl missing)` right after spawn (spawn
+warns after 30 s) likely sits at pi's project trust prompt (through a
+wrapper whose argv0 is not `pi`/`pi-meta` it shows `needs_input`): add
+`--approve` to `MU_<CLI>_COMMAND`. Move off
 `scratch` when work gains dependencies or review gates.
 
 ## Mental model
@@ -170,11 +178,18 @@ rules hold even when you skip it:
 - **`mu task wait --first --on-stall exit`**; exit 7 means read the
   owner's pane and answer it.
 - **Stop a worker gently**: `mu agent abort`, then `kick`, then `close`.
+  To redirect a busy pi now: `send --interrupt` (`--steer` waits for
+  the running tool).
+- **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.
 - **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
-  turn; their verdict lands on the task they judged. `mu_delegate` runs
-  `MU_DELEGATE_MAX` (default 16) at once and queues the rest.
+  turn. Refuters and claim checkers pass `record` (or hand-write the
+  `REFUTER` note) to land the verdict on the task; judges report
+  `WINNER:`. `MU_DELEGATE_MAX` (16) run at once; the rest queue.
 - **Findings are tasks.** A reviewer's or auditor's findings become
   `mu task add --triage` tasks blocking the review, decided with
   `mu task accept` or `close --as rejected|duplicate`. A review nobody
@@ -193,6 +208,8 @@ rules hold even when you skip it:
 - **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.
+- **Prose in notes, prompts, `--why` or `--evidence`**: an apostrophe
+  ends `'...'`; use a quoted heredoc ([brief](recipes/brief.md#quoting)).
 - **`mu sql`** does not pull synced ops; run any other mu command first.
 - **Never put `MU_DB_PATH` inside `MU_SYNC_DIR`**: it corrupts the DB.
 - Before undo, rebuild, teardown (dry-run without `--yes`), sync setup,
@@ -209,9 +226,15 @@ export MU_PI_COMMAND="pi --model sonnet:medium"
 mu agent spawn a --cli pi_big   # uses $MU_PI_BIG_COMMAND
 ```
 
-Convention: `pi_mini` for probing, `pi` for build and refactor,
-`pi_big` for design, review, and incidents. List models with
-`pi --list-models [search]`.
+`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.
 
 ## Reaper and agent state
 
@@ -254,6 +277,7 @@ risky job that needs several of them, start with
 | [remote-workers](recipes/remote-workers.md) | an agent runs on another machine |
 | [waves](recipes/waves.md) | more than one worker edits the same repo at once |
 | [long-run](recipes/long-run.md) | a task or proof runs for hours, or must survive flakes |
+| [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 |
 | [tasks-or-calls](recipes/tasks-or-calls.md) | a recipe step spawns an agent: DAG task or delegate call |

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

@@ -28,9 +28,8 @@ PR or diff from several angles, use [review-panel](review-panel.md).
 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. Use a different model from
-   the worker where you can (`--cli pi_big` reviewing `pi`): a second
-   model has different blind spots. Give it the worker's workspace path
+   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
    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:**
@@ -71,11 +70,20 @@ where it fails the acceptance criteria in `mu task notes <x>`.
   UNVERIFIED for it. Unverified is not a pass and not a fail.
 - Do not edit files.
 
-End with a note in the task note contract, then close with the verdict:
-  ACCEPT: mu task close review_<x> --evidence '<key check>'
-  REJECT: mu task close review_<x> --as rejected --why '<gap ids>'
+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>), ..."
 ```
 
+mu adds each named gap'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
+<finding>`, and name the check in `--evidence`. Not `one finding fixed
+by orchestrator`.
+
 ## Traps
 
 - **A reviewer that sees the author's reasoning agrees with it.** Send

package/skills/mu/recipes/brief.md

@@ -32,6 +32,7 @@ not in the brief, or one pointer away, does not exist for it.
 6. **Ask for evidence, not reassurance.** The final note names the
    commands run and their exit codes (the task note contract). "Done,
    all good" is not a result.
+7. **A brief that makes claims is refuted before dispatch** ([SKILL.md](../SKILL.md#orchestrator-rules)).
 
 ## Shape
 
@@ -46,8 +47,35 @@ VERIFY: <exact command>
 
 ⚠️ FINAL ACTION
 git commit -am '<msg>' THEN
-mu task close <id> -w <ws> --evidence '<command + result>'
+mu task close <id> -w <ws> --evidence "$v"   # command + result; see Quoting
 ```
 
+## Quoting
+
+Single quotes suit short text with no `'`. Prose (an apostrophe ends
+`'...'`; `"..."` expands `$` and backticks) goes through stdin with a
+quoted heredoc, stored verbatim:
+
+```bash
+mu task note <id> -w <ws> - <<'EOF'
+it's fine: $HOME and `pwd` stay literal
+EOF
+```
+
+`mu task add --note -`, `--text -` and `mu agent send <a> -` read stdin
+the same way. `--why` and `--evidence` have no `-` form: capture the
+heredoc in a variable and double-quote it:
+
+```bash
+v=$(cat <<'EOF'
+it's fine: $HOME stays literal
+EOF
+)
+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.

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

@@ -62,16 +62,24 @@ 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 sh = async (c) => (await tools.bash({ command: c })).output;
+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) => {
-  const a = `refuter-${i + 1}`;
+  const a = `refuter-${i + 1}`, t0 = Date.now();
   await sh(`mu agent spawn ${a} -w scratch`);
-  await sh(`mu agent send ${a} -w scratch --fresh '<brief for ${id}: ... end with VERDICT: ...>'`);
-  const w = JSON.parse(await sh(`mu agent wait ${a} -w scratch --json --timeout 1200`));
-  const text = w.agents?.[0]?.lastText ?? "";
-  await sh(`mu agent close ${a} -w scratch`);
-  return `${id}\t${(text.match(/VERDICT:.*$/m) ?? ["VERDICT: UNVERIFIED no verdict line"])[0]}`;
+  const { runs } = json(await sh(`mu agent send ${a} -w scratch --fresh --json - <<'MU_EOF'\n<brief for ${id}, ending with the VERDICT block>\nMU_EOF`));
+  const w = json(await sh(`mu agent wait ${a} -w scratch --after-runs ${runs} --json --timeout 1200`)).agents?.[0] ?? {};
+  const lines = (w.lastText ?? "").trimEnd().split("\n");
+  const at = lines.findLastIndex((l) => /^[\s>*_`-]*VERDICT:/.test(l));
+  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`);
+  if (w.outcome === "done") await sh(`mu agent close ${a} -w scratch`);
+  return `${id}\t${note.split("\n")[1] ?? note}`;
 }));
 return rows.join("\n");
 ```
@@ -82,9 +90,11 @@ What the tool did for you, the script now owns:
   each script's list at or under it.
 - **Cleanup.** Close each scratch pane; a timed-out one stays, readable
   with `mu agent read <a> -w scratch`.
-- **Recording.** The table is not the record. Record each verdict on its
-  finding (`mu task accept`, `close --as rejected --why`), from the
-  script or after it returns.
+- **Recording.** The script writes each `REFUTER` note in `record`'s
+  shape, and `no verdict (<outcome>)` for a failed wait; it does not
+  cap long answers or special-case empty ones as `record` does. Decide
+  each finding after it returns ([findings § Triage](findings.md#triage)
+  step 3).
 
 ## Traps
 

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

@@ -41,12 +41,13 @@ answer rests on is an `OPEN/triage` task, decided like a finding
    gets the claim and its sources, not the searcher's reasoning, fetches
    the source itself, and tries to break the claim: is the quote there,
    does it say that, is it current, does another source disagree? It
-   ends with `VERDICT: c4 CONFIRMED | REFUTED | UNVERIFIED <evidence>`.
+   ends with the VERDICT block
+   ([tasks-or-calls § Delegate call](tasks-or-calls.md#delegate-call)).
    For contradicted claims, one checker per side. Batch under the cap
-   ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)). In workstream mode the
-   verdict is the claim task's state: `accept` for confirmed,
-   `close --as rejected` for refuted, an `UNVERIFIED:` note in triage
-   otherwise.
+   ([orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency)).
+   In workstream mode the checker passes `record` on the claim task, and
+   the verdict is decided as in [findings § Triage](findings.md#triage)
+   step 3.
 5. **Synthesize** once every checker has answered (in workstream mode,
    when no claim task is left undecided): answer the question
    from confirmed claims only, each with its source URL. List