@mu-crew/mu 3.13.3 → 4.1.0

package/skills/mu/recipes/remote-workers.md

@@ -1,326 +1,25 @@
 # Remote workers
 
-Use when an agent's process runs on another machine (a devserver, a
-bigger box) while its pane stays local. mu has no remote backend, ssh
-code, or host registry. This is a recipe plus the traps that cost time.
+Use when an agent runs on another machine. A **host profile** holds your command templates; mu never connects.
 
-**If you read one thing:** on a session-capped host, an open attach pane
-holds the only ssh channel and silently breaks `git fetch`,
-`murmur collect`, and every other ssh. Attach to look, then
-`mu agent close`.
-
-## The model
-
-- **The pane is local, the process is remote.** The pane's foreground
-  process is ssh. `send`, `read`, and the reaper work unchanged. The pi
-  control socket rides the same ssh as a `-L` forward, so pi state,
-  `wait`, and `abort` are exact.
-- **One orchestrator DB.** Never run a second mu on the host.
-  `tasks.owner_id` is an FK into the machine-local `agents` table, so a
-  remote mu cannot claim tasks in your DAG.
-- **mu does not know the remote workspace**: no `mu workspace` verbs,
-  staleness warning, or auto-free. You own it.
-- **Everything is orchestrator-pull.** The host usually has no route
-  back to your laptop. Push setup out, fetch commits back.
-
-## The recipe
-
-```bash
-# 1. WORKSPACE: you create it; --workspace is local-only
-ssh dev 'git -C ~/repo worktree add ~/ws/worker-1'
-
-# 2. RECORD: location and per-worker baseline, in one note
-mu task note t1 -w big "REMOTE: dev:~/ws/worker-1
-REMOTE_BASE: worker-1:$(ssh dev 'cd ~/ws/worker-1 && git rev-parse HEAD')"
-
-# 3. SPAWN: env goes INSIDE the command (tmux -e stops at the hop).
-#    remote-env prints the socket forward and the identity env; it runs nothing.
-#    $SHELL -ilc: ssh's non-interactive shell skips ~/.zshrc (PATH, provider env).
-eval "$(mu agent remote-env worker-1 -w big --shell)"  # MU_SSH_ARGS, MU_REMOTE_ENV
-mu agent spawn worker-1 -w big --command \
-  "ssh $MU_SSH_ARGS dev -t 'cd ~/ws/worker-1 && $MU_REMOTE_ENV \$SHELL -ilc \"pi --approve\"'"
-
-# 4. CLAIM + SEND: as for a local agent
-mu task claim t1 -w big --for worker-1 --evidence 'remote on dev'
-mu agent send worker-1 -w big --fresh '...'
-
-# 5. WAIT: pi: mu agent wait worker-1 -w big --after-runs <send's runs> --json,
-#    then the claim's Next: once, after the worker reports done.
-#    non-pi: the same, once per reported-done turn
-
-# 6. COLLECT: fetch straight from the remote worktree
-git fetch "ssh://dev/~/ws/worker-1" HEAD && git cherry-pick FETCH_HEAD
-```
-
-Done when the worker's commits are cherry-picked locally, the merged
-tree passes the merged-tree gates (host and local checks below), and the pane is
-closed.
-
-### Step 2: the note is load-bearing
-
-Keep the exact forms `REMOTE: <host>:<path>` and
-`REMOTE_BASE: <agent>:<sha>`. `mu task claim --for` builds the
-poll-and-close command from them, and `mu state` lists `REMOTE:` lines.
-For a crew, poll every path in one bounded mule job:
-
-```bash
-mule run --max-secs 30 'for d in ~/ws/*/; do printf "%s %s\\n" \
-  "$(basename $d)" "$(cd $d && git rev-parse HEAD 2>/dev/null || echo unreadable)"; done'
-mule wait <job>; mule tail <job>
-```
-
-Accept only 40 hex characters. `unreadable` or an empty field means
-retry next turn, not progress.
-
-### Step 3: the control-socket forward
-
-Spawn reports `ctl: ok` when all of these hold (`mu doctor` has a ctl
-row per agent):
-
-- The host has the mu extension: run `mu link pi` there.
-- The ssh is direct. `$MU_SSH_ARGS` sets `ControlMaster=no
-  ControlPath=none`; a multiplexed ssh never binds the forward and spawn
-  reports `ctl: missing`.
-- sshd allows the forward. A refused forward kills the pane at spawn
-  (`ExitOnForwardFailure=yes`). Check `AllowStreamLocalForwarding`.
-
-A dead ssh leaves the socket file, which probes `refused`, never a
-stale `ok`. Non-pi agents get state from murmur, lagging 30 s ± 10 s
-plus a 10 s cache.
-
-### Step 5: poll once per turn
-
-The claim's `Next:` mule poll closes the task as done on any change of
-the remote HEAD. Run it once, only after the worker reports done (its
-close or final answer). For a pi worker, first block on
-`mu agent wait <name> --after-runs <runs> --json`, with `runs` from
-`mu agent send --json`. It settles exactly over the forwarded socket,
-and it returns at once for a run that settled before the wait started.
-Pass `<runs>` unchanged. On exit 5 (timeout), or on a wait that returns
-while the worker asks a question, do not poll: read the pane
-(`mu agent read <name> -n 20`) and answer.
-
-- Never `sleep` in a tool call. Aborting the loop can leave remote work
-  and a capped channel running.
-- Set a deadline before dispatch. At expiry, read the pane, then release
-  or re-dispatch.
-- On a capped host, run `Next:` through mule. A refused bare ssh returns
-  an empty sha that looks like progress.
-
-### Step 6: fetch from the worktree
-
-- No shared remote or bare repo is needed. It exits 128 on failure, so
-  `&&` chaining is safe.
-- Quote the URL. Unquoted, your local shell expands `~` to your laptop's
-  home.
-- Bucket work by file cluster, not by machine.
-
-### Run the merged gate on the host
-
-Reuse only equivalent [gate records](test-health.md#gate-contract).
-Cherry-pick a merge batch locally, push its pinned head to the host, and run
-full slow there with warm dependencies, plus fast if slow excludes it:
-
-```bash
-git cherry-pick <sha>
-git push -q "ssh://dev/~/hacking/<repo>.git" HEAD:refs/heads/gate-tmp
-mule run --cwd ~/hacking/<gate-checkout> --wait \
-  'git fetch -q origin gate-tmp && git checkout -q --detach FETCH_HEAD && npm run check'
-```
-
-`<gate-checkout>` is a scratch checkout or worktree used only for
-gates, never one holding work. Push to a temporary ref, never `main`;
-delete it afterwards (`git push origin :gate-tmp`). Push to `main` only
-after required gates pass. Replace `npm run check` with the repo's canonical
-merged-tree command(s), preserving full scope and recording host conditions.
-Keep the gate checkout pinned while other remote workers continue in theirs;
-use private artifacts ([build cache](orchestrator-loop.md#build-cache)).
-
-`--wait` exits with the suite's code. A bare ssh would hold the capped
-channel for minutes. Retain local platform-sensitive checks (macOS `ps`
-returns argv, Linux `ps -e` appends the environment, and a real bug lived
-there), and the repo-required final local gate before the push that matters.
-A remote pass does not substitute for non-equivalent local conditions.
-
-## Traps
-
-### A non-pi spawn on an auth prompt looks healthy
-
-With the channel busy, the attach ssh stopped at `Enter a passcode:`.
-Spawn succeeded, the agent showed `needs_input`, and the prompt went
-into the passcode field. This applies to non-pi CLIs and to
-`--via mux`, which paste into the pane. Confirm such an agent got the
-work (`mu agent read <name> -n 20`) before trusting it. Send nothing
-sensitive to an unconfirmed pane.
-
-A pi agent does not paste. Spawn reports `ctl: ok` only when pi
-answers on the socket; otherwise it warns `ctl: missing` or
-`ctl: refused`, and `mu agent send` fails instead of typing into the
-pane.
-
-### Use the host's real CLI command
-
-If your local `$MU_PI_COMMAND` is a wrapper such as `pi-meta
---pi-meta-no-solo --approve`, plain `pi` on the host gives a live pane
-with **no models configured**. Check with `ssh dev 'command -v pi-meta'`.
-
-### Tell the worker that mu is absent
-
-mu is usually not on the host, so the in-pane loop cannot run. Say so
-in the prompt and have the worker print its sha. You claim, note, and
-close. Otherwise `mu task wait` hangs.
-
-### A dropped connection reaps the task, not the commit
-
-The reaper reverts the task to OPEN, but the commit is still on the
-host. Fetch from the `REMOTE:` path before re-dispatching.
-
-### A dead non-pi remote agent vanishes
-
-murmur records `crashed` only when a pane outlives its process. Remotely
-tmux reaps the session with the agent, so SIGKILL gives zero rows, not
-`crashed`. (A dead pi agent probes `refused`.) Trust the `[reaper]`
-note and `ssh <host> 'tmux ls'`.
-
-### Stopping and cleaning up
-
-- `mu agent abort <name>` stops a pi turn through the forwarded socket.
-- `mu agent kick` signals the local ssh client, not the remote agent.
-  For an unresponsive agent, `mu agent close` and respawn.
-- mu does not remove remote worktrees:
-  `ssh dev 'git -C ~/repo worktree remove ~/ws/worker-1'`.
-
-## murmur
-
-pi agents need no murmur. [murmur](https://github.com/mu-crew/murmur)
-reports state for non-pi agents on tmux, and adds status pills,
-attachment hints, and `murmur peer list`. Without it, non-pi agents
-report `unknown`; everything else works.
-
-| Question | Ask |
-| --- | --- |
-| What happens next, who owns it, is it done | mu: the DAG, `claim`, `task wait` |
-| What is a pi agent doing | mu: the control socket |
-| What is a non-pi agent doing; is anything blocked on me | murmur |
-| Which host can I reach | murmur: `peer list` |
-
-**`$MU_REMOTE_ENV` goes inside the ssh command.** Without it the agent
-reports `driver=human` and shows in your own status bar.
-
-**murmur sees the remote pane** and links it to your local pane by the
-agent name in the local argv (`attached here %N`; focus instead of a
-second connection). The detached shape carries the name only in the
-session name, so name it `mu-<agent>`. An env prefix does not help:
-macOS `ps` reports argv, not env.
-
-### Picking a host
-
-```bash
-murmur peer list --json | jq -r '.[] | select(.error) | .name'
-```
-
-- `ssh` is last-known reachability. `error` is the current attempt.
-- It exits 0 either way. Branch on `.error`, not on presence.
-- `murmur collect` prints one line per unreachable host, now.
-
-Attach with the peer's jump command instead of hardcoding ssh. It may
-use a transport that takes no ssh session:
-
-```bash
-murmur peer set <name> --jump-command '<command with {pane}>'
-JUMP=$(murmur peer list --json | jq -r '.[]|select(.name=="dev").jump_command')
-mu agent spawn worker-1 -w big --command "${JUMP//\{pane\}/mu-worker-1}"
-```
-
-## When the host limits concurrent sessions
-
-Most sshd allow 10 sessions per connection (`MaxSessions`). A hardened
-host may set `MaxSessions 1`. Then the ssh holding your agent takes the
-only channel, and every other ssh, including `git fetch`, fails with a
-misleading `Permission denied (keyboard-interactive)`.
-
-Diagnose in this order. The first check is local and instant:
-
-```bash
-ssh-add -l      # "Error connecting to agent" => dead ssh agent, NOT the cap
-ssh <host> true # fails while `mu agent read` works => the cap
-```
-
-A dead `SSH_AUTH_SOCK` gives the same error via an invisible 2FA prompt;
-one session lost an hour treating it as the cap. To find what holds the
-channel:
-`ps -o pid=,command= -ax | grep "[s]sh <host>"`.
-
-`ControlMaster no` does not help (it governs master creation only).
-There is no client fix.
-
-### Run commands through mule
-
-[mule](https://github.com/mu-crew/mule) dispatches detached jobs on its
-own ssh ControlPath. On a `MaxSessions 1` host, eight bare `rev-parse`
-polls returned one sha and seven empty results; mule ran all eight.
-
-- Use mule for long work and for any command whose refusal could look
-  like success. Keep worktree setup and `murmur collect` bare: they fail
-  loudly.
-- A mule job is entirely remote. It cannot fetch from, push to, or rsync
-  with your laptop.
-- For an interactive agent under mule's lifecycle, use `mule run --tui`
-  (plain `mule run` has no live TUI). It prints the attach command.
-  Closing that pane does not stop the job.
-
-| mule exit | Meaning | Do |
-| --- | --- | --- |
-| 3 | No ssh master; opening one may need a hardware-key touch | Hand back: ask the operator to run the printed command. Never retry, run `ssh -MNf`, or fall back to `ssh <host> <cmd>` |
-| 4, 6 | Not yet | Poll again |
-| 5 | No result will ever arrive | Stop polling |
-
-None of these means the work failed. Full table: `mule --help`.
-
-### Run the agent in detached remote tmux
-
-Decouple the agent from the connection to release the channel:
-
-```bash
-eval "$(mu agent remote-env worker-1 -w big --shell)"
-# Agent runs detached on the host; this ssh returns at once
-ssh dev "tmux new-session -d -s mu-worker-1 -c ~/ws/worker-1 \
-  '$MU_REMOTE_ENV \$SHELL -ilc \"pi --approve\"'"
-
-# Attach a local pane (with the socket forward); claim and send as usual
-mu agent spawn worker-1 -w big --command "ssh $MU_SSH_ARGS dev -t 'tmux attach -t mu-worker-1'"
-
-# COLLECT: detach first to free the channel, then fetch
-mu agent close worker-1 -w big
-git fetch "ssh://dev/~/ws/worker-1" HEAD && git cherry-pick FETCH_HEAD
-
-# Reattach later with the same spawn command; LLM context is intact
-```
-
-- An attached pane blocks other ssh exactly like a direct one. Close it
-  before fetching, or use mule.
-- `mu agent close` detaches. It does not stop the agent. To stop it:
-  `ssh dev 'tmux kill-session -t mu-worker-1'`. `ssh dev 'tmux ls'` is
-  the only inventory of these sessions.
-- A dropped connection no longer reaps the agent. Each attach
-  re-creates the socket forward.
-- Keep the session name `mu-<agent>`: mu records neither, so it is the
-  only link. On an uncapped host this shape buys nothing.
-
-### Use ET for your own shell
-
-Eternal Terminal moves off ssh to `etserver`, so `MaxSessions` never
-counts it, even with a nested `tmux attach`. It makes a good jump
-command but cannot serve `git fetch`.
+The pane is the transport and forwards the remote pi's control socket: `send`, `wait`, `abort` work as locally; a dead pane is a dead agent. The host has no mu DB: you close the task, from the worker's `CLOSE:` block.
 
 ```bash
-et dev        # or your site's wrapper, such as `x2ssh -et dev`
+mu host init dev --ssh   # a starter to edit into `mu host add`
+mu host check dev
+mu agent spawn worker-1 -w <ws> --host dev --worktree --root <remote repo> --task <id> --send - <<'EOF'
+<brief>
+EOF
+mu agent wait worker-1 -w <ws> --after-runs <n> --json   # n = the spawn's printed "runs" (0 fresh); lastText: its CLOSE block
+mu agent collect worker-1 -w <ws>   # run in the local repo
+mu task close <id> -w <ws> --evidence "<the block's evidence>"
+mu agent close worker-1 -w <ws> --if <rev>
 ```
 
-An aborted `et` or `x2ssh` leaves local processes behind. Find them
-with `ps -o pid=,command= -ax | grep "[x]2ssh"` and kill only those of
-the aborted invocation (match its host or tty), not every x2ssh, before
-retrying.
+End the brief with: commit, then `CLOSE: task=<id> evidence="<command + result>"`. Cherry-pick the collected commits and re-run the evidence before you close.
 
-On a capped host: ET for you, mule for tooling, detached tmux for mu
-agents. None of them competes for the slot.
+- **One profile per machine** (the cap is per profile); `--root` picks the repo.
+- **`--max-sessions 1`**: the live pane holds the only channel; `collect` and `ssh dev` refuse. Raise the cap to collect mid-run.
+- **Long remote gates are panes** (`--command 'npm test'`), not a held ssh.
+- `close` refuses a dirty or uncollected tree: collect again.
+- A host command's exit 3 is a hand-back (hardware key): never retry or ssh yourself.

package/skills/mu/recipes/tasks-or-calls.md

@@ -1,89 +1,26 @@
 # Tasks or calls
 
-Use when a recipe step spawns an agent: decide whether that agent's job
-is a **task** in the DAG or a **call** to a delegate. Getting it wrong
-one way loses track of work; the other way, one PR review creates
-hundreds of tasks and a workstream nobody wanted.
+Use when a step spawns an agent: is its job a **task** in the DAG or a **delegate call**?
 
-## Delegate call
+**A task is work the graph tracks. Checking a thing is a call.**
 
-A **delegate call** is one `mu_delegate` tool call in pi, or outside pi
-a `scratch` spawn + `send --fresh` + `wait --after-runs` (below).
-
-- **It starts empty.** The brief carries everything: the finding or
-  claim, file paths, the criteria, and the answer to end with. See
-  [brief](brief.md). A tournament judge ends with `WINNER: ...`
-  ([tournament](tournament.md)). A refuter or claim checker passes
-  `record: { task: "<ws>/<id>" }` and ends with:
-
-  ```text
-  VERDICT: <id> CONFIRMED|REFUTED|UNVERIFIED <one line>
-  EVIDENCE: <file:line or command + result>   (3-6 lines)
-  ```
-
-- **Fan out in one turn.** Issue every call for a step together; in pi
-  the answers arrive later as follow-up messages. Calling one, waiting,
-  then the next runs them in series.
-- **Its `scratch` pane** stays attachable while it runs; `mu_delegate`
-  closes it after a clean finish and keeps it on a crash, timeout, or
-  API error (or always, with `keep: true`).
-- **An API error is yours to decide.** Re-issue the call, or record the
-  check as `UNVERIFIED` on its task, then close the kept pane
-  (`mu_delegate_cancel`, or `mu agent close`).
-
-Without the tool, write the note `record` would, before deciding:
-
-```bash
-mu agent spawn refuter-1 -w scratch
-runs=$(mu agent send refuter-1 -w scratch --fresh - --json <<'EOF' | jq .runs
-<brief, ending with the VERDICT block>
-EOF
-)
-mu agent wait refuter-1 -w scratch --after-runs "$runs" --json   # answer in lastText
-mu task note <id> -w <ws> - <<'EOF'
-REFUTER 1 (refuter-1, 4m 05s):
-<the VERDICT line and EVIDENCE lines, verbatim>
-EOF
-mu agent close refuter-1 -w scratch
-```
-
-A wait that times out or dies leaves `REFUTER 1: no verdict (<outcome>)`.
-`--after-runs` counts a run that finished before the wait started; the
-quoted heredocs keep the evidence verbatim ([brief § Quoting](brief.md#quoting)).
-
-## The rule
-
-**A task is a thing the graph tracks. Checking a thing is a call.**
-
-| Make it a task | Make it a delegate call |
+| Task | Delegate call |
 | --- | --- |
-| a unit of work that produces commits | refuting a finding |
-| a gate that decides whether work counts (`review_x`) | checking a claim against its source |
-| a finding, claim, or hypothesis that survives into the workstream | judging a pair in a tournament |
-| the umbrella, and each round of a loop | a skeptic or dedupe pass |
-| anything that needs its own workspace | a reader or scout whose output feeds one step |
-
-A call adds no node: its note and your decision land on the task it
-judged ([findings § Triage](findings.md#triage)).
+| a unit that produces commits | refuting a finding, checking a claim |
+| a gate deciding whether work counts (`review_x`) | judging a pair, a skeptic or dedupe pass |
+| a finding, or the umbrella | a scout or reader feeding one step |
+| anything needing its own worktree | |
 
-## Examples
+## The call
 
-- 30 findings to refute: 30 delegate calls, 0 new tasks; each finding
-  gets a `REFUTER` note, then your decision.
-- A tournament over 16 names: 15 judge calls; each round's `WINNER:`
-  lines go on the umbrella.
-- A hypothesis test that reverts commits or forces a race needs a
-  workspace: that one is a task.
+In pi: `mu_delegate`, with `record: {task: "<ws>/<id>"}` when it judges a task, `wave` for a fan-out. It starts empty: the brief carries the claim, paths, criteria and an answer ending:
 
-## Counting
+```text
+VERDICT: <id> CONFIRMED|REFUTED|UNVERIFIED <one line>
+EVIDENCE: <file:line or command + result>   (3-6 lines)
+```
 
-Before a wave, count what it will add: units + gates + expected
-findings. If the count is more than a few hundred for one change, the
-steps that only check things are probably tasks by mistake.
+- **Issue every call of a step in one turn**; one at a time runs in series. Past `MU_DELEGATE_MAX` (16) they queue, then are refused and reissuable.
 
-Cap and queue: [orchestrator-loop § Concurrency](orchestrator-loop.md#concurrency).
+Outside pi, use `scratch`: `mu agent spawn r1 -w scratch`; `mu agent send r1 -w scratch --fresh --json -` (keep `runs`, `incarnation`); `mu wait 'agent:r1@<runs>#<incarnation>' -w scratch`, whose snapshot `lastText` is the answer. Write it on the task as `REFUTER <n> (<agent>): <verdict lines>`, or `REFUTER <n>: no verdict (<outcome>)`. Then `mu agent close r1 -w scratch --if <rev>`.
 
-Done when every agent a recipe step spawns is either a task in the DAG
-or a delegate call whose answer landed where its step says: a
-`REFUTER` note on the task it judged, a `WINNER` line in the umbrella's
-note, or a unit list in the umbrella's note.

package/skills/mu/recipes/test-health.md

@@ -1,92 +1,34 @@
 # Test health
 
-Read when defining gates, choosing worker/reviewer verification, adding tests,
-or doing upkeep at a milestone, a budget crossing, or the user's request.
-Testing stays encouraged; upkeep protects coverage and the iteration loop.
+Use when you define gates, verify a merge, add tests, or a merged slow gate exceeds its budget.
 
 ## Gate contract
 
-Use the repo's `## Gates` in AGENTS.md or README: fast and slow commands,
-slow-gate budget (default 5 min), and a targeted slow-test command. Plan notes
-point there. Until a split is approved, keep the existing repo gate intact;
-recipe guidance does not waive project checks. Fast means iteration checks,
-not a universal seconds promise: measure cold and warm costs.
+Read the repo's `## Gates` (AGENTS.md or README): fast, slow and targeted commands, the slow budget. Never waive a repo check.
 
-- **Worker:** run the fast gate while iterating; before closing, run slow
-  tests for the changed area once, then fast on the final commit. Record
-  both, or why a scope is inapplicable/unavailable. Changes invalidate records.
-- **Reviewer:** inspect the diff and reuse equivalent worker records. Run
-  uncovered tests for the diff and reproduce claimed failures, rather than
-  repeating the full suite or building the parent for every new test.
-- **Orchestrator:** verify one pinned merged tree per batch with the full
-  slow gate, plus fast if slow does not include it. All required integration,
-  auth, release and packaging checks still pass before push. Bisect a failed
-  batch; record the corrected tree's pass. See [merging](orchestrator-loop.md#merging).
+- **Worker:** fast while iterating; before close, slow tests for the changed area, then fast on the final commit. Record both, or why one is inapplicable.
+- **Reviewer:** reuse equivalent worker records; run only what they leave uncovered.
+- **Orchestrator:** one pinned merged tree per batch gets the full slow gate, plus fast if slow omits it, before push.
 
-Gate records are task-note text, not a mu command or stored result cache:
+Record a gate in a task note:
 
 ```text
-GATE: commit=<sha> tree=<hash>; command=<exact command + filters>; scope=<full/area>
-RESULT: exit=<code>; duration=<wall time>; counts=<tests/assertions>; skips=<none or reasons>
-CONDITIONS: <toolchain, host/platform, privileges, relevant env/features, cache state>
+GATE: commit=<sha>; command=<exact command + filters>; scope=<full|area>
+RESULT: exit=<code>; duration=<wall>; counts=<tests>; skips=<none|reasons>
+CONDITIONS: <toolchain, host, env, cache state>
 ```
 
-Reuse requires the same tree, command/scope and equivalent execution
-conditions. Record uncommitted inputs too; a dirty tree hash alone is not
-an identity. A targeted pass, zero selected cases, or a skipped privileged
-check is not a full pass. Clear/reject inherited selectors for full runs;
-report skips explicitly and resolve required missing checks before push.
+Reuse needs the same tree, command, scope and conditions. A targeted pass, zero selected cases or a skipped required check is not a full pass.
 
-## Adding or changing tests
+A new test sits at the lowest level that catches the failure.
 
-Use the lowest level that catches the failure, covering behaviour not
-already guarded. A new slow case states what only it can see in a comment
-or commit message. For a bug with a cheap, obvious local target, the worker
-shows red on the base and green on the fix; feature work and integration-heavy
-paths need no mandatory red-green ceremony. Use direct executable evidence
-when stronger, recording the reason.
+## Upkeep
 
-Poll readiness/completion with a bound and useful failure output. Retain
-necessary temporal sampling, negative-observation windows and deliberately
-sleeping process fixtures; explain their timing contract.
+At a milestone or budget crossing, without stopping independent work:
 
-Reviewer findings identify risky untested/broken behaviour, a wrong test
-level, duplication of a named test, avoidable readiness padding, or measured
-gate slowdown—not every conceivable edge case without a test.
-
-## Upkeep loop
-
-Queue ordinary upkeep work at each phase/milestone end or when a merged slow
-gate exceeds budget. Prioritise it before new features; continue independent
-work. A budget is a scheduling trigger, not an indefinite crew-wide stop.
-
-1. **Profile.** Time each gate step and test, including setup/teardown.
-   List up to 20 slowest tests per level; inspect waits and repeated builds,
-   cold caches and profiles. BEFORE records wall time, counts, skips and
-   conditions. Use inspected execution logs, not commands merely mentioning
-   a gate or compound-command durations attributed entirely to tests.
-2. **Classify.** Parallel [delegate calls](tasks-or-calls.md#delegate-call),
-   one per area, give slow/overlapping tests an evidenced verdict:
-   KEEP; SPEED-UP (poll or share setup with isolation); MOVE-DOWN;
-   MERGE into a named test; DELETE as covered by a named test.
-3. **Refute.** Send every MERGE/DELETE verdict to a refuter: which failure
-   would no longer be caught? A refuted or unresolved verdict becomes KEEP.
-4. **Do.** Dispatch surviving changes as normal test-only tasks. Review
-   coverage preservation, isolation and correctness of the harness changes.
-   Preserve auth lanes, privilege checks and release scans; measure safe
-   [build reuse](orchestrator-loop.md#build-cache) separately.
-5. **Measure.** Run the merged gates and record AFTER under comparable
-   conditions, including coverage/count changes. If neither faster nor
-   smaller, say so and why; smaller alone does not prove preserved coverage.
-
-6. **Report.** Before teardown, commit a dated report to the repo
-   (`docs/test-health/<YYYY-MM-DD>.md`): conditions, BEFORE/AFTER, each
-   finding with its evidence, every refuted or rejected verdict with the
-   reason, and the remaining bottleneck. Task notes die with the
-   workstream; the next pass reads the latest report first and still
-   re-measures. Add a file per pass; never edit an old one.
-
-Done when AFTER records the outcome, the report is committed, and the slow
-gate is within budget or the report names the remaining bottleneck and
-prioritised follow-up. Keep unmet required checks distinct from a
-time-budget overrun.
+1. Profile each gate step and the 20 slowest tests (BEFORE: time, counts, skips).
+2. One delegate call per area: KEEP, SPEED-UP, MOVE-DOWN, MERGE or DELETE.
+3. A refuter checks each MERGE/DELETE: which failure goes uncaught? Unresolved means KEEP.
+4. Dispatch survivors as test-only tasks with review.
+5. Re-measure (AFTER); smaller alone proves no coverage.
+6. Commit `docs/test-health/<date>.md`: BEFORE/AFTER, verdicts, the remaining bottleneck.

package/skills/mu/recipes/worker.md

@@ -1,31 +1,24 @@
-# Worker loop
+# Worker
 
-Use when you are the worker: a task was claimed for you, or you were
-told to claim one.
-
-`$MU_AGENT_NAME` (injected at spawn) resolves identity; adopted panes
-fall back to the pane title. In a worker pane, bare `mu task claim <id>`
-works. In the unregistered orchestrator pane it errors; use `--self`,
-`--for <worker>`, or `mu agent adopt <pane>`.
+Use when you are the worker: a task was claimed for you, or you were told to claim one. `$MU_AGENT_NAME` and `$MU_WORKSTREAM` identify you; your cwd is your worktree.
 
 ```bash
-mu me
-mu me next
-mu task show <id>; mu task notes <id>
-mu task claim <id> --evidence "starting; read notes"
-mu task note <id> "FILES: ...\nCOMMANDS: ... (exit codes)\nDECISION: ...\nVERIFIED: ..."
-mu task close <id> --evidence "tests pass: ..."  # LAST action
+mu task show <id>; mu task notes <id>      # the brief, report and verdicts come first
+mu task claim <id> --evidence "starting"    # skip when already yours
+# work; commit before you close: the orchestrator cherry-picks commits, not your tree
+mu task note <id> - <<'EOF'
+FILES: ...
+COMMANDS: ... (exit codes)
+VERIFIED: ...
+EOF
+mu task close <id> --evidence "tests pass: <command> exit 0"   # LAST action
 ```
 
-Follow [test-health](test-health.md) for fast iteration checks, targeted slow
-checks before close, gate records, and cheap bug red-green. Include the gate
-records in your final note; adding tests uses its test-level and timing rules.
+Skipping `close` hangs the orchestrator's wait.
 
-The note follows the task note contract in SKILL.md. Keep each tool
-call to minutes (short batches, waits with a timeout): steering reaches
-you only between tool calls. Commit before you close: the orchestrator cherry-picks your commits, not your tree. A
-review or audit task records each problem per
-[findings § Record](findings.md#record).
+- **Remote host (no mu DB):** `mu task close` cannot work there. Commit, then end your final message with `CLOSE: task=<id> evidence="<command + result>"`; the orchestrator closes from it.
 
-Done when your changes are committed in the workspace, the task note holds FILES, COMMANDS (with exit codes), VERIFIED and applicable gate records, and `mu task close` succeeded as your last action. Skipping close makes the orchestrator's
-wait hang. Won't do it: `close --as wontfix --why "..."`.
+- Follow the brief's VERIFY and [test-health](test-health.md): fast while iterating, slow for your area before close; put the gate records in your note.
+- Keep each tool call to minutes; a steer reaches you only between calls.
+- A review or audit records each problem as a finding ([findings](findings.md)).
+- Won't do it: `mu task close <id> --as wontfix --why "..."`.