@mu-crew/mu 3.2.0 → 3.3.0

package/docs/reference/env.md

@@ -0,0 +1,87 @@
+# Environment variables
+
+Every env var mu reads or sets. mu has no config file. Durations are
+milliseconds; `0` disables a wait unless noted.
+
+## State and workstream
+
+| Name | Effect | Default |
+| --- | --- | --- |
+| `MU_DB_PATH` | SQLite file path. Wins over the state dir. | `<state-dir>/mu.db` |
+| `MU_STATE_DIR` | State directory. | `$XDG_STATE_HOME/mu` |
+| `XDG_STATE_HOME` | XDG state base; mu appends `mu/`. | `~/.local/state` |
+| `MU_SESSION` | Active workstream when `-w` is absent. | current `mu-<name>` mux session |
+| `MU_SYNC_DIR` | Folder holding one segment per machine. This is the whole sync setup; there is no peer list. | unset: sync off |
+
+## Multiplexer
+
+| Name | Effect | Default |
+| --- | --- | --- |
+| `MU_MUX` | Force `tmux` or `herdr`, skipping mux detection. An unknown value fails the invocation. | detected |
+| `HERDR_ENV` | Read only. `1` (set by herdr in its panes) selects herdr; outranks `$TMUX`. | |
+| `MU_TMUX_SOCKET` | tmux socket name (`-L <name>`). tmux only. | `$TMUX` |
+| `MU_HERDR_SESSION` | Named herdr server (`--session <name>`). herdr only. Tests must set it to a non-default name. | herdr default session |
+| `MU_BANNER_QUIET` | `1` disables mu's pane border and banner decorations. tmux only. | unset |
+
+## Spawn
+
+| Name | Effect | Default |
+| --- | --- | --- |
+| `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_LOCK_TIMEOUT_MS` | How long a spawn waits for the per-workstream spawn lock. | `15000` |
+
+## Send and state (tmux path)
+
+These apply to the tmux paste path only. For when that path runs, see
+[No silent fallback](../architecture/control-socket.md#no-silent-fallback).
+
+| Name | Effect | Default |
+| --- | --- | --- |
+| `MU_SEND_READINESS_MS` | Before pasting, wait out a pane's modal or re-init; after Enter, confirm it landed. `0` sends fire-and-forget. A busy pane is not waited on. | `15000` |
+| `MU_SEND_DELAY_MS` | Delay between the bracketed paste and Enter. | `500` |
+
+## Agents and timing
+
+| Name | Effect | Default |
+| --- | --- | --- |
+| `MU_IDLE_THRESHOLD_MS` | Time without progress before an owning agent, or a scratch agent, counts as idle. | `300000` |
+| `MU_LOG_TAIL_INTERVAL_MS` | `mu log --tail` poll interval; clamped to ≥ 50. | `1000` |
+
+## Set by mu in agent panes
+
+| Name | Value |
+| --- | --- |
+| `MU_AGENT_NAME` | The agent's name; first rung of actor identity. |
+| `MU_WORKSTREAM` | The agent's workstream. |
+| `MU_CTL_SOCK` | The agent's control socket path, derived from state dir, workstream, and agent. The mu pi extension serves it. |
+| `MU_MANAGED_AGENT` | `1`. Hides `mu_delegate` inside agents, so a helper cannot spawn helpers. |
+
+`mu agent remote-env <agent> --shell` prints `MU_SSH_ARGS` (the ssh
+socket forward) and `MU_REMOTE_ENV` (the four vars above) for a remote
+pi agent's `--command`. mu never reads them back.
+
+## pi extension and `mu link pi`
+
+| 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` |
+
+## Output and TUI
+
+| Name | Effect | Default |
+| --- | --- | --- |
+| `NO_COLOR` | Any value turns colour off; wins over everything. | unset |
+| `MU_FORCE_COLOR` | Truthy forces colour on. `""`, `0`, and `false` opt out. Checked before `FORCE_COLOR`. | unset |
+| `MU_NO_TUI` | `1` makes bare `mu` print help instead of opening the TUI. | unset |
+| `MU_TUI_DEBUG_MOUSE` | `1` logs mouse hit-tests to stderr. | unset |
+
+## Tests
+
+`VITEST` or `NODE_ENV=test` makes `openDb()` refuse the real default DB.
+`test/_setup.ts` clears inherited `MU_*` vars except `MU_TMUX_SOCKET`.

package/docs/reference/naming.md

@@ -0,0 +1,82 @@
+# Naming conventions
+
+Terms are defined in [VOCABULARY.md](../VOCABULARY.md).
+
+## Flags and positionals
+
+The primary entity a verb acts on is positional. Scope, modifiers, and
+payload are flags: `mu task close <id>`, `mu agent send <name> <text>`.
+
+- The workstream is a scope (`-w`) everywhere except under
+  `mu workstream`, where it is the entity. `init` and `teardown` take
+  it positionally; if the positional and `-w` disagree, mu exits 2.
+- When one verb takes a payload positionally and a sibling takes it as
+  a flag, both shapes are accepted (`mu task note <id> --text "..."`).
+  Adding an alias is not a breaking change; removing a shape is.
+- One concept, one parser: `--blocked-by` and `--by` are both blocker
+  lists and accept repeated, comma-separated, or mixed forms.
+
+## Empty and blank list fragments
+
+`parseCsvFlag` (`src/cli.ts`) applies one rule to every list flag
+(`--status`, `--by`, `--blocked-by`, `-w`):
+
+| Input | Kind | Result |
+| --- | --- | --- |
+| `--status "OPEN,"` | empty fragment | dropped: `[OPEN]` |
+| `--blocked-by ""` | empty fragment | dropped: `[]` |
+| `--status " "` | blank fragment | `UsageError`, exit 2 |
+| `--status "OPEN, "` | blank fragment | `UsageError`, exit 2 |
+
+A blank `-w ' '` is also rejected. Whether zero fragments is legal is
+per verb: `--by ''` exits 2, while `mu task reparent --blocked-by ''`
+clears all blockers.
+
+## Ids
+
+| Id | Shape | Unique within |
+| --- | --- | --- |
+| Agent name | `[a-z][a-z0-9_-]*`, ≤ 32 chars | workstream |
+| Task `local_id` | same | DB |
+| Workstream name | same; mux session is `mu-<name>` | DB |
+| Window (`--tab`) | `[A-Za-z][A-Za-z0-9 _-]*`, ≤ 32 chars | workstream |
+
+`scratch` is reserved: it is created only by the first
+`mu agent spawn <name> -w scratch`, and `mu workstream init scratch`
+is rejected. The `mu-` prefix is reserved too.
+
+## Agent names
+
+Name agents by role with a numeric suffix: `worker-1`, `reviewer-1`,
+`scout-1`. Human names (`alice`, `bob`) read as people in commands and
+make `mu agent list` harder to scan. mu does not enforce this; test
+fixtures may use human names.
+
+| Role | Use |
+| --- | --- |
+| `worker` | Long-lived implementer (the default) |
+| `reviewer` | Reads diffs; usually `--role read-only` |
+| `scout` | One-shot recon |
+| `oracle` | Second opinion before acting |
+| `auditor` | Long-lived watcher; `--role read-only` |
+| `planner` | Writes implementation plans |
+
+## File paths
+
+The state dir is `MU_STATE_DIR`, else `$XDG_STATE_HOME/mu`, else
+`~/.local/state/mu`.
+
+| Path | Contents |
+| --- | --- |
+| `<state-dir>/mu.db` | The SQLite DB for every workstream |
+| `<state-dir>/workstreams/<workstream>/` | Per-workstream artifacts, created lazily |
+| `<state-dir>/workspaces/<workstream>/<agent>/` | Per-agent VCS workspace, created by `mu agent spawn --workspace` |
+| `<sync-dir>/<machine_id>.jsonl` | This machine's segment; `<sync-dir>` is `MU_SYNC_DIR` |
+| `<sync-dir>/<machine_id>.manifest` | `{count, last_hlc, sha256}` for segment verification |
+
+Never put `MU_DB_PATH` inside `MU_SYNC_DIR`: syncing a live SQLite
+file and its `-wal` and `-shm` sidecars corrupts it. `mu doctor` checks
+for this.
+
+mu reads no agent-template directory (`~/.pi/agent/agents/`,
+`.pi/agents/`). A role is a name and a brief.

package/docs/specs/2026-09-28-agent-state-from-murmur.md

@@ -1,6 +1,6 @@
 # Agent state from murmur (mu 2.0.0, murmur 1.0.0)
 
-Status: approved design, 2026-09-28. Task `crew/mu_status_from_murmur`.
+Status: shipped in 2.0.0; partly superseded in 3.2.0 by the control socket ([architecture/control-socket.md](../architecture/control-socket.md)). Approved 2026-09-28. Task `crew/mu_status_from_murmur`.
 
 ## Problem
 

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

@@ -1,6 +1,6 @@
 # Task substates: classification without stranded dependents
 
-Status: 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. 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.0",
+  "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: $@