@mu-crew/mu 3.1.0 → 3.2.1

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_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)
+
+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_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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "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"
@@ -55,9 +55,9 @@
     "test:fast": "vitest run --config vitest.fast.config.ts",
     "test:watch": "vitest",
     "test:watch:fast": "vitest --config vitest.fast.config.ts",
-    "lint": "biome check src test scripts",
-    "lint:fix": "biome check --write src test scripts",
-    "format": "biome format --write src test scripts",
+    "lint": "biome check src test scripts extension",
+    "lint:fix": "biome check --write src test scripts extension",
+    "format": "biome format --write src test scripts extension",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
     "prepare": "npm run build",
     "test:stress": "tools/test-stress.sh"