@mu-crew/mu 3.2.1 → 3.3.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/VOCABULARY.md

@@ -40,11 +40,13 @@ 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" |
 | **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" |

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/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/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,7 @@ 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_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/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.3.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-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-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/ultrathink.md

@@ -0,0 +1,9 @@
+---
+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; keep driving until the stop rule holds.
+
+Job: $@