@mu-crew/mu 3.2.1 → 3.4.0

package/docs/ARCHITECTURE.md

@@ -139,6 +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` |
 | `src/link.ts` | `mu link pi`: extension shim, skill symlink, `inspectLinks` for doctor |
 
 ### Tasks, workspaces and workstreams

package/docs/VISION.md

@@ -224,7 +224,9 @@ mu agent spawn reviewer-1 --cli pi_big
   visible pane: attach, steer, abort, or keep talking to it. It costs one
   pane and one pi process. A hidden subagent is lighter for many tiny
   calls. mu bets that visibility and steering are worth the cost. There
-  are no agent types: the brief is plain text.
+  are no agent types: the brief is plain text. A delegate's answer is
+  not recorded in mu; only what the caller writes back (a note, a state
+  change) is.
 - **DB-undoable, not substrate-undoable.** `mu undo <group> --yes`
   restores rows. It does not revive killed panes or freed workspace
   directories. Reconciliation then reports ghosts and orphans.

package/docs/VOCABULARY.md

@@ -40,11 +40,14 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | **role** | The capability flag: `full-access` or `read-only`. | "permission", "tier" |
 | **persistent** | An agent that stays alive across tasks. | "long-lived" (prose only) |
 | **one-shot** | An agent that exists for one task. | "ephemeral", "transient" |
+| **nudge** | The pi extension's one-shot keep-driving reminder: after a dispatch, if the orchestrator ends its turn with work IN_PROGRESS, it injects the SKILL.md rule once and continues. Logged as `--kind nudge`. | "goal", "loop" |
 | **delegate** | A scratch agent started for one task; its answer returns when its control-socket `wait` resolves. The `mu_delegate` tool does it in one call; the pane stays attachable. | "subagent", "child agent" |
+| **delegate call** | Using a delegate for one check (a refuter, judge, claim checker): one `mu_delegate` call, or `mu agent spawn -w scratch` + `send --fresh` + `wait --json` without the tool. Its verdict is recorded on the task it judged; the call itself adds no task. | "subtask" |
 | **hidden subagent** | A child agent in other tools (pi-subagents, Claude Code and Codex task tools) with no pane to attach or steer. mu's counterpart is the **delegate**. | "subagent" (alone) |
 | **agent state** | `busy`, `needs_input`, `needs_permission`, or `unknown`, from the **state source**. Not persisted; see [Agent state values](#agent-state-values). | "agent status", "lifecycle state" |
 | **state source** | The **control socket** for pi agents; else herdr's `paneStatus()` or, on tmux, murmur. A silent pi socket gives `unknown` (`ctl missing`, `ctl refused`). | "scraper" |
 | **control socket** / **ctl** | The per-agent unix socket (`$MU_CTL_SOCK`) the mu pi extension serves inside pi. **ctl state** is `ok`, `missing`, or `refused`. | "rpc", "daemon" |
+| **session command** | `/new`, `/reload`, or `/compact [instructions]` sent to a pi agent. mu runs it inside pi through the ctl `command` op, never as a paste. Any other slash command to a pi agent is refused; `--via mux` types it into the pane. | "slash paste" |
 | **outdated extension** | A running pi whose loaded extension is older than mu (exit 4 on a missing op). pi's `/reload` fixes it. | |
 | **lastText** | A pi run's final assistant message, returned verbatim by `wait`. mu never interprets it. | "result", "output" (alone) |
 | **ghost** | An `agents` row whose `pane_id` no longer exists. Pruned by **reconcile**. | "dead agent", "stale row" |
@@ -61,8 +64,10 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | --- | --- | --- |
 | **task** | A node in the DAG with mandatory `impact` and `effort_days`, a **task status**, and a **substate**. | "issue", "ticket", "item" |
 | **task status** | `OPEN`, `IN_PROGRESS`, or `CLOSED`. Any `CLOSED/*` satisfies a blocker. | "state" |
-| **substate** | What the status means, shown as `STATUS/substate`; never null. `OPEN`: `todo`, `parked`. `IN_PROGRESS`: `active`. `CLOSED`: `done`, `rejected`, `wontfix`, `duplicate`, `superseded`. | "resolution", "reason" |
+| **substate** | What the status means, shown as `STATUS/substate`; never null. `OPEN`: `todo`, `parked`, `triage`. `IN_PROGRESS`: `active`. `CLOSED`: `done`, `rejected`, `wontfix`, `duplicate`, `superseded`. | "resolution", "reason" |
 | **park** / **unpark** | `OPEN/todo` ↔ `OPEN/parked` (park needs `--why`). Parked tasks leave **ready**. | "defer", "snooze" |
+| **triage** / **accept** | `OPEN/triage` is a proposed task, usually a review **finding**, not yet accepted as work: out of **ready**, refused by `claim`, but it blocks its dependents. `mu task add --triage` creates one; `mu task accept` moves it to `OPEN/todo`; declining is `close --as rejected` or `--as duplicate`. | "inbox", "pending" |
+| **finding** | One problem a reviewer, checker, or auditor reports. Recorded as an `OPEN/triage` task (the mu way), or as an answer line when a **delegate** reviews something nobody will track. | "issue", "comment" |
 | **task DAG** / **graph** | The directed acyclic graph of tasks. | "task list", "tree" |
 | **edge** | The single edge type: `A blocks B` means A must close before B starts. | "dependency" (prose only) |
 | **subtree** / **scope** | Tasks reachable from a root via blocks-edges. | "subgraph" |

package/docs/architecture/control-socket.md

@@ -33,15 +33,23 @@ reply carries `v: 1`; the client (`src/ctl/client.ts`) throws
 | `wait` | resolves on pi's `agent_settled` after `afterRuns`, with the run's `lastText` |
 | `abort` | `ctx.abort()` (pi's Esc) |
 | `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` |
 
-These back `mu agent send` (`--fresh`, `--steer`), `mu agent wait`,
+`pi.sendUserMessage` dispatches only extension commands, not pi's
+built-in `/new`, `/reload`, `/compact`. Each internal command is an
+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`,
 `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
-next steps are `/reload` through the mux or a respawn. `mu doctor`
+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
 `extVersion` older than the installed mu or a missing op. Its extension
 row reports whether `mu link pi` installed the extension.
@@ -90,9 +98,15 @@ The mux paste path (bracketed paste, `MU_SEND_DELAY_MS`,
 
 - non-pi CLIs;
 - adopted panes without ctl;
-- slash commands, because `sendUserMessage` does not run them;
 - an explicit `--via mux`.
 
+A pi agent's `/new`, `/reload` and `/compact [instructions]` go
+through the `command` op. Any other slash command to a pi agent raises
+`AgentSlashCommandUnsupportedError` (exit 2), whose next step is the
+same text with `--via mux`. Text such as `/tmp/x.log ...` is a plain
+prompt, not a slash command. A pi agent therefore never reaches
+`capturePane` or the paste timing in `src/mux/input-timing.ts`.
+
 ## Remote agents
 
 The user's `ssh` command carries `-L <local derived path>:<remote path>`

package/docs/architecture/dag.md

@@ -14,11 +14,11 @@ it mu is only an agent runner. Overview:
 - **Status lifecycle:** `OPEN → IN_PROGRESS → CLOSED`. Status alone
   decides edge satisfaction: any `CLOSED` task satisfies its blockers.
 - **Substate** qualifies status and never touches edges:
-  `OPEN/todo|parked`, `IN_PROGRESS/active`,
+  `OPEN/todo|parked|triage`, `IN_PROGRESS/active`,
   `CLOSED/done|rejected|wontfix|duplicate|superseded`. The rule is
   "store intent, derive graph facts": ready and blocked stay derived
-  from edges. `OPEN/parked` is excluded from `ready` but stays in
-  `goals`.
+  from edges. `OPEN/parked` and `OPEN/triage` are excluded from `ready`
+  but stay in `goals`; `claim` refuses both without `--force`.
 - **Notes** are append-only per task. They survive LLM context loss
   and agent restarts, which fixes context loss at the task level
   rather than the agent level.

package/docs/architecture/mux.md

@@ -97,15 +97,14 @@ as a capability, not a name check:
 | --- | --- | --- |
 | `NewWindowOptions.command` | carries the command | refused if non-empty |
 | `startAgentInPane()` | absent | implemented |
-| after start | mu checks pane life and startup errors, then murmur readiness for non-pi CLIs | the mux returns once the agent is ready |
+| after start | mu checks pane life and startup errors | the mux returns once the agent is ready |
 
 `spawnAgent` branches on `mux.startAgentInPane !== undefined`.
 
 - **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. If murmur is installed, it then polls until murmur
-  claims the pane (`MU_SPAWN_READINESS_MS`, default 10s). Without
-  murmur that poll is skipped.
+  startup errors. mu does not wait for murmur to claim the pane: state
+  reads before the first claim report `unknown`.
 - **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/README.md

@@ -21,5 +21,10 @@ How-to guides:
 - [Choose a multiplexer backend](backends.md)
 - [Clean up](cleanup.md)
 
+Agent-facing recipes (orchestrator loop, worker loop, recovery, waves,
+long runs, watchers, remote workers) live
+in [skills/mu/recipes/](../../skills/mu/recipes/). The skill's
+[recipe index](../../skills/mu/SKILL.md#recipes) says when to read each.
+
 For features mu does not have on purpose, see
 [ROADMAP.md § Explicitly rejected](../ROADMAP.md#explicitly-rejected).

package/docs/guide/delegate.md

@@ -29,7 +29,9 @@ Delegates called in one turn run in parallel.
 - The pane closes after a clean finish; died or timed-out panes stay
   as evidence.
 - pi's footer shows how many delegates this session is waiting on.
-- Each delegate costs a pane and a pi process.
+- Each delegate costs a pane and a pi process. A session runs at most
+  `MU_DELEGATE_MAX` at once (default 16); past that, the tool refuses
+  and the rest wait for answers.
 
 `MU_DELEGATE=0` hides the tool ([env vars](../reference/env.md)).
 
@@ -79,9 +81,34 @@ mu log -w scratch --kind pr-state -n 1 --json
 Act only on change. `--since <seq>` replays entries a dead watcher
 missed.
 
+## Delegates vs hidden subagents
+
+Claude Code, Codex, and pi-subagents delegate to a hidden child process
+and return only its result. A mu delegate is an ordinary agent in a
+pane.
+
+|                         | Hidden subagent          | mu delegate |
+| ----------------------- | ------------------------ | ----------- |
+| Visibility              | none while it runs       | a pane; attach and watch |
+| Steer mid-run           | no                       | `mu agent send`; stop with `mu agent abort` |
+| Keep talking after it answers | no                 | yes, with `keep: true` |
+| Transcript              | collapses into a result  | a normal pi session log |
+| If the work grows       | re-brief a new agent     | same task DAG and workspaces |
+| Cost                    | light                    | one pane and one pi process |
+
+For many tiny calls, a hidden subagent is lighter. mu bets that seeing
+and steering agent work is worth a pane.
+
 ## When to stop delegating
 
-Dependencies, several agents, or review need a real workstream: see
+Use delegates when you only need the answer: reviewing someone's PR or
+a doc, a fact-check, a go/no-go. Nothing they find lands in the ops
+log, which is permanent and syncs to every machine.
+
+Move to a workstream when the findings become work agents will fix, or
+the job has dependencies or several stages: see
 [Getting started](getting-started.md) and
 [How to dispatch work](dispatch.md). There, `mu task wait` keys on the
-task and has `--on-stall`.
+task and has `--on-stall`. The agent-facing rules for both are in
+[recipes/findings.md](../../skills/mu/recipes/findings.md) and
+[recipes/tasks-or-calls.md](../../skills/mu/recipes/tasks-or-calls.md).

package/docs/guide/dispatch.md

@@ -1,8 +1,10 @@
 # How to dispatch work to a worker
 
 This guide assumes you finished [Getting started](getting-started.md).
-The orchestrator loop and its traps are in
-[skills/mu/SKILL.md](../../skills/mu/SKILL.md).
+The agent-facing loop and its traps are in
+[recipes/orchestrator-loop.md](../../skills/mu/recipes/orchestrator-loop.md). For several workers in
+one repo, see [waves](../../skills/mu/recipes/waves.md); for runs that
+last hours, see [long runs](../../skills/mu/recipes/long-run.md).
 
 ## Claim before you send
 
@@ -40,6 +42,10 @@ socket. Pick the mode by what the agent is doing:
 - 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.
+- `/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
+  other slash command exits 2; add `--via mux` to type it into the pane.
 - If the socket does not answer, the send fails with exit 1 and
   pastes nothing. `--via mux` pastes into the pane on purpose.
 
@@ -86,8 +92,9 @@ context:
 mu workspace refresh worker-1 -w auth
 ```
 
-It refuses on a dirty tree. On a conflict it exits 5 with a `cd`
-hint. To throw the workspace away instead, run
+It rebases onto the remote's main (`origin/HEAD`); without a remote,
+pass `--from main`. It refuses on a dirty tree. On a conflict it exits 5
+with a `cd` hint. To throw the workspace away instead, run
 `mu workspace free worker-1 -w auth`.
 
 Claim and send warn when the worker's workspace is 10 or more commits

package/docs/guide/getting-started.md

@@ -147,6 +147,9 @@ The worker keeps its pi context:
 mu workspace refresh worker-1 -w auth
 ```
 
+The default target is the remote's main branch (`origin/HEAD`). In a
+repository without a remote, name the branch: `--from main`.
+
 ## Check the graph
 
 ```bash

package/docs/guide/recovery.md

@@ -2,7 +2,9 @@
 
 Start with `mu doctor`. Each row that is not `ok` prints the command
 that fixes it. mu reports and never cleans up for you, because an
-orphan directory can hold the only copy of uncommitted work.
+orphan directory can hold the only copy of uncommitted work. Agents
+read the same rules in
+[recipes/recovery.md](../../skills/mu/recipes/recovery.md).
 
 ```bash
 mu doctor           # exit 0 healthy, 5 on drift

package/docs/guide/remote.md

@@ -4,7 +4,7 @@ The pane is local and the pi process is remote. mu runs no ssh
 itself. `mu agent remote-env` prints the ssh pieces, and you put them
 in the spawn command. The full recipe, with recording, collecting,
 and the traps, is in
-[skills/mu/REMOTE_WORKERS.md](../../skills/mu/REMOTE_WORKERS.md).
+[skills/mu/recipes/remote-workers.md](../../skills/mu/recipes/remote-workers.md).
 Read it before your first remote spawn.
 
 ## Prepare the host

package/docs/history/CHANGELOG-pre-3.md

@@ -587,7 +587,7 @@ mu doctor          # agent state : ok agent state from murmur 1.x
 
 ### Documentation
 
-- **[skills/mu/REMOTE_WORKERS.md](../../skills/mu/REMOTE_WORKERS.md)** — running
+- **[skills/mu/REMOTE_WORKERS.md](../../skills/mu/recipes/remote-workers.md) (now `recipes/remote-workers.md`)** — running
   agents on another machine. This already worked with no mu changes (the
   pane is local, the process is remote, so send/read/status/reaper are
   unaffected), but nothing said so and the failure modes are not

package/docs/reference/env.md

@@ -30,7 +30,6 @@ 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_READINESS_MS` | tmux only, when murmur is installed. Budget to wait for murmur to claim the new pane. | `10000` |
 | `MU_SPAWN_LOCK_TIMEOUT_MS` | How long a spawn waits for the per-workstream spawn lock. | `15000` |
 
 ## Send and state (tmux path)
@@ -68,6 +67,8 @@ pi agent's `--command`. mu never reads them back.
 | Name | Effect | Default |
 | --- | --- | --- |
 | `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; `mu_delegate` refuses past it. A positive integer. | `16` |
+| `MU_NUDGE` | `0` turns off the keep-driving nudge: one reminder when an orchestrator ends a turn with dispatched work still IN_PROGRESS. `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/reference/naming.md

@@ -45,6 +45,24 @@ clears all blockers.
 `mu agent spawn <name> -w scratch`, and `mu workstream init scratch`
 is rejected. The `mu-` prefix is reserved too.
 
+## Workstream names
+
+Name a workstream `<project>-<purpose>`: `hail-auth`, `swayward-v2`,
+`dotfiles-zsh`. The project is the repo or folder; the purpose is the
+effort. Two repos then never share `auth`, and `mu workstream list`
+groups by project. `workstream init` prints a hint for a name with no
+`-`.
+
+- **One workstream per effort.** Tear it down when the effort ships;
+  the ops log keeps the history and `mu undo` restores it. A long-lived
+  catch-all becomes a log nobody reads: `mu state` hints once a
+  workstream passes 300 tasks with fewer than 10% open.
+- **Ultrathink runs** get their own: `<project>-ut-<topic>`.
+- **Delegate-only work** (reviewing someone's PR or a doc) goes in
+  `scratch`, never a new workstream.
+- `mu-` is reserved, so the mu repo's own workstreams use the purpose
+  alone or another prefix.
+
 ## Agent names
 
 Name agents by role with a numeric suffix: `worker-1`, `reviewer-1`,

package/docs/specs/2026-09-29-task-substates.md

@@ -1,6 +1,6 @@
 # Task substates: classification without stranded dependents
 
-Status: shipped in 3.0.0 (schema v11); `CLOSED/rejected` added in 3.1.0. Implemented 2026-09-29 (approved 2026-09-29; see [Deviations during implementation](#deviations-during-implementation))
+Status: shipped in 3.0.0 (schema v11); `CLOSED/rejected` added in 3.1.0; `OPEN/triage` added in 3.4.0 (per D10, one seeded row). Implemented 2026-09-29 (approved 2026-09-29; see [Deviations during implementation](#deviations-during-implementation))
 Date: 2026-09-29
 Supersedes the notes-only convention from `9e3c47b` ("tasks: reduce lifecycle to three states").
 

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

@@ -0,0 +1,142 @@
+# Keep-driving nudge: one prompt when an orchestrator stops early
+
+Status: shipped (unreleased). Implemented 2026-10-03; see [Deviations](#deviations-during-implementation)
+Date: 2026-10-03
+
+## Problem
+
+An orchestrator dispatches workers, then ends its turn to print a
+status summary while those workers are still running. Nothing happens
+until the human notices and types "carry on". The crew sits idle for
+as long as the human is away. This is the most common way a long run
+stalls, and a rule in the skill alone has not stopped it.
+
+`skills/mu/SKILL.md` § Orchestrator rules now states the rule ("While
+workers run, keep driving"). The pi extension can back it up at the one
+moment it matters: when the orchestrator is about to stop.
+
+## Approach
+
+When a pi session that dispatched mu work is about to settle, and that
+work is still running, the extension injects **one** message quoting
+the skill's rule, and asks pi to continue. The model then either goes
+back to `mu task wait`, or ends the turn again with a reason. The
+second stop is final: the nudge fires at most once per user prompt.
+
+This is not a goal loop. It does not re-check, re-inject, or count
+continuations. One reminder, then the model's judgement stands.
+
+## Behaviour
+
+1. **Arm.** During a run, the extension watches `tool_call` events for
+   bash commands that dispatch mu work: `mu agent send`, `mu agent
+   spawn`, or `mu task claim ... --for`. It records the workstreams
+   they name (`-w`, `--workstream`, or a qualified `<ws>/<task>` ref),
+   falling back to the default resolution (`$MU_SESSION`, tmux session).
+   A run with no dispatch never arms. `mu_delegate` does not arm: its
+   answers already arrive as follow-ups.
+2. **Check.** On `agent_before_settle`, if armed and not yet fired for
+   this prompt, run `mu state -w <ws...> --json` (about 1 s) and count
+   `inProgress` tasks across those workstreams. Zero means the work is
+   done or parked: let the turn end.
+3. **Nudge.** Otherwise return one `custom_message` entry
+   (`customType: "mu-keep-driving"`, `display: true`) and
+   `continue: true`. The text is the skill paragraph verbatim, followed
+   by the live count and the wait command:
+
+   ```text
+   [mu] <the skill paragraph>
+
+   3 tasks IN_PROGRESS in auth. Next: mu task wait -w auth --first --on-stall exit
+   ```
+
+4. **Record.** Write `mu log -w <ws> --kind nudge 'keep-driving: 3 in
+   progress'` so the push is visible in the activity log, next to the
+   orchestrator's own entries.
+5. **Reset.** The fired flag and the armed set clear on the next
+   `input` event, i.e. the next human (or mu-sent) prompt.
+
+`outcome: "aborted"` or `"error"` never nudges: the human pressed Esc,
+or the run failed, and both should stop.
+
+## Single source for the text
+
+The paragraph lives in `SKILL.md` between
+`<!-- mu:keep-driving -->` and `<!-- /mu:keep-driving -->`. The
+extension reads it from the package's skill at load time. A test
+asserts the markers exist and the extracted text is non-empty, so
+editing the skill edits the nudge, and deleting the markers fails the
+gate rather than silently sending nothing.
+
+## Opt-out
+
+`MU_NUDGE=0` disables it. `mu doctor` reports it next to `MU_DELEGATE`.
+
+## Fit with the pillars
+
+- **The CLI is the product.** The nudge adds no state and no logic the
+  CLI lacks: its only data is `mu state --json`, and its only write is
+  `mu log`. Without the extension, the same rule is in the skill. Like
+  `mu_delegate`'s follow-up callback, it is harness glue, not a feature.
+- **One DB is canonical.** The armed set and fired flag are per-prompt
+  scratch, never persisted. Losing them loses one reminder.
+- **Nothing hidden.** The message is displayed in the transcript and
+  logged in the DB.
+- **ROADMAP.** No daemon, watcher, or loop: one hook, one check, one
+  message. Estimated under 150 LOC plus tests.
+
+## Key decisions
+
+| # | Decision | Why |
+|---|---|---|
+| D1 | At most once per user prompt. | A loop overrides the model's judgement on real human decisions; one reminder corrects the common mistake and then defers. |
+| D2 | Arm only on observed dispatch. | A session that never dispatched is not orchestrating; nudging it would be noise. |
+| D3 | Gate on `inProgress > 0`, not ready tasks. | Ready-but-unclaimed work may be waiting on the human's go-ahead. Running workers are the clear case. |
+| D4 | Quote the skill paragraph, read at load. | One source of truth; the model sees the exact rule it was taught. |
+| D5 | `agent_before_settle` + `continue: true`, not `sendUserMessage`. | The boundary hook is pi's designed point for one continuation, and the entry is a visible custom message, not fake user input. |
+| D6 | Log every nudge with `--kind nudge`. | The push is part of the run's record; `mu log --kind nudge` shows how often orchestrators stop early. |
+
+## Out of scope
+
+- A worker that stops without closing its task. Same shape (check
+  `mu me` for an owned IN_PROGRESS task, nudge once), but a separate
+  decision.
+- Non-pi harnesses. They get the skill rule only.
+- Any repeat, backoff, or goal condition.
+
+## Test plan
+
+- Unit, with a fake pi API (as `delegate.ts` tests do):
+  - no dispatch in the run → no nudge;
+  - dispatch + `inProgress: 0` → no nudge;
+  - dispatch + `inProgress: 2` → one entry, `continue: true`, one
+    `mu log` call;
+  - a second settle in the same prompt → no nudge;
+  - a new `input` event → armed again;
+  - `outcome: "aborted"` → no nudge;
+  - `MU_NUDGE=0` → no nudge.
+- Marker test: `SKILL.md` contains the markers; extracted text matches
+  the paragraph.
+- Manual: real orchestrator session, dispatch two workers, ask for a
+  status summary; confirm one `[mu]` message, the model resumes
+  waiting, and `mu log --kind nudge` shows the entry.
+
+## Deviations during implementation
+
+- **Wait hint names tasks.** `mu task wait` takes task ids, so the
+  message lists up to eight `<ws>/<task>` refs and counts the rest,
+  instead of a `-w <ws>` form that does not exist.
+- **Both `mu state --json` shapes.** One `-w` prints a bare card; several
+  print `{ workstreams: [...] }`. The unit tests first mocked only the
+  second; the live run used the first and stayed silent. Both are read
+  and tested now.
+- **`scratch` never arms.** Dispatches into the reserved delegate
+  workstream are `mu_delegate`'s, whose answers return as follow-ups.
+- **The check runs once per prompt even when it fails.** A failing
+  `mu state` does not retry on the next settle.
+
+Live verification: a real pi orchestrator against a throwaway DB
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.2.1",
+  "version": "3.4.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"
@@ -44,6 +44,7 @@
   "files": [
     "dist",
     "skills",
+    "prompts",
     "docs",
     "README.md",
     "AGENTS.md"

package/prompts/mu-debug.md

@@ -0,0 +1,8 @@
+---
+description: "Debug with mu: independent hypotheses from separate evidence, each attacked, fix verified"
+argument-hint: "<symptom>"
+---
+Debug this with mu. Load the mu skill, then read its
+`recipes/hypothesis-panel.md` in full and follow it.
+
+Symptom: $@

package/prompts/mu-refute.md

@@ -0,0 +1,8 @@
+---
+description: "Find, refute, synthesize with mu: audit or fact-check with a refuter per finding"
+argument-hint: "<what to audit or check>"
+---
+Run a find-refute-synthesize pass with mu. Load the mu skill, then read
+its `recipes/refute.md` in full and follow it.
+
+Scope: $@

package/prompts/mu-research.md

@@ -0,0 +1,8 @@
+---
+description: "Deep research with mu: fan out searches, check every claim, cited report"
+argument-hint: "<question>"
+---
+Research this with mu. Load the mu skill, then read its
+`recipes/deep-research.md` in full and follow it.
+
+Question: $@

package/prompts/mu-review.md

@@ -0,0 +1,8 @@
+---
+description: "Review panel with mu: parallel focused reviewers, refuted findings, one report"
+argument-hint: "[diff, PR, branch, or path]"
+---
+Run a review panel with mu. Load the mu skill, then read its
+`recipes/review-panel.md` in full and follow it.
+
+Target: ${@:-the uncommitted changes in this repo}

package/prompts/mu-rules-audit.md

@@ -0,0 +1,8 @@
+---
+description: "Rules audit with mu: check a change against AGENTS.md rule by rule, or mine missing rules"
+argument-hint: "[check <target> | mine]"
+---
+Run a rules audit with mu. Load the mu skill, then read its
+`recipes/rules-audit.md` in full and follow it.
+
+Mode and target: ${@:-check the uncommitted changes in this repo}

package/prompts/mu-sweep.md

@@ -0,0 +1,8 @@
+---
+description: "Sweep with mu: the same change over many files or call sites, one task per unit"
+argument-hint: "<change, and where>"
+---
+Run a sweep with mu. Load the mu skill, then read its
+`recipes/fan-out.md` in full and follow it.
+
+Change: $@

package/prompts/mu-tournament.md

@@ -0,0 +1,9 @@
+---
+description: "Tournament with mu: competing attempts judged in pairs against a rubric"
+argument-hint: "<what to choose or build>"
+---
+Run a tournament with mu. Load the mu skill, then read its
+`recipes/tournament.md` in full and follow it. Ask me for the rubric
+first if the task does not imply one.
+
+Task: $@

package/prompts/mu-until.md

@@ -0,0 +1,8 @@
+---
+description: "Loop with mu until a check is clean (tsc, lint, tests), with a stop rule written first"
+argument-hint: "<stop rule, e.g. npx tsc --noEmit exits 0>"
+---
+Loop with mu until this holds. Load the mu skill, then read its
+`recipes/loop-until-done.md` in full and follow it.
+
+Stop rule: $@

package/prompts/ultrathink.md

@@ -0,0 +1,10 @@
+---
+description: "Run a large or risky job the mu way: DAG, fan-out, adversarial review"
+argument-hint: "<job>"
+---
+Ultrathink this job with mu. Load the mu skill, then read its
+`recipes/ultrathink.md` in full and follow it. Every unit, review, and
+round goes in the task DAG; checks (refuters, judges, skeptics) are
+delegate calls. Keep driving until the stop rule holds.
+
+Job: $@