@mu-crew/mu 3.8.1 → 3.10.0

package/docs/guide/tui.md

@@ -67,9 +67,9 @@ pane. The dashboard comes back when the tool exits.
 `/` filters the popup's rows by substring as you type. `Enter` keeps
 the filter. `Esc` clears it.
 
-In task popups, `o`, `i`, and `c` toggle `OPEN`, `IN_PROGRESS`, and
-`CLOSED`. In the DAG and All-tasks popups, `p` toggles parked tasks and
-`w` toggles tasks closed as anything but `done`. In All tasks, `b`
+In the DAG and All-tasks popups, `o`, `i`, and `c` toggle `OPEN`,
+`IN_PROGRESS`, and `CLOSED`, `p` toggles parked tasks, and `w` toggles
+tasks closed as anything but `done`. In All tasks, `b`
 cycles the blocked filter and `s` cycles the sort: ROI, recency, age,
 id.
 

package/docs/guide/upgrade.md

@@ -16,8 +16,9 @@ that both paths start from.
 
 - `--copy` copies the extension instead of the shim. You then have to
   relink after every upgrade.
-- `--force` replaces a skill symlink that points elsewhere, such as a
-  dev checkout. mu never replaces a real directory there (exit 4).
+- `--force` replaces an extension or skill symlink that points
+  elsewhere, such as a dev checkout. mu replaces the link, never its
+  target, and never replaces a real skill directory (exit 4).
 - `--extension-only` and `--skill-only` install one part.
 
 For agents other than pi, see [README § Install](../../README.md#install).
@@ -50,7 +51,12 @@ newer one with `SchemaTooNewError`. Both exit 4 and leave the file
 alone. `scripts/migrate.ts` converts a v7, v8, v9, or v10 DB into a new
 v11 file. It never writes in place.
 
+The npm package does not ship `scripts/` or `src/`, so run the recipe
+from a git checkout of mu at the version you upgraded to (`npm install`
+there first; `npx tsx` fetches tsx on first use).
+
 ```bash
+git clone --branch "v$(mu --version)" https://github.com/mu-crew/mu && cd mu && npm install
 DB=${MU_DB_PATH:-$HOME/.local/state/mu/mu.db}
 BACKUP="$HOME/mu-old-backup-$(date +%Y%m%d-%H%M%S).db"
 sqlite3 "$DB" ".backup '$BACKUP'"

package/docs/reference/env.md

@@ -1,6 +1,8 @@
 # Environment variables
 
-Every env var mu reads or sets. mu has no config file. Durations are
+Every env var mu reads or sets, except standard ones it reads as any
+tool does (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `DISPLAY`,
+`WAYLAND_DISPLAY`). mu has no config file. Durations are
 milliseconds; `0` disables a wait unless noted.
 
 ## State and workstream
@@ -8,8 +10,8 @@ milliseconds; `0` disables a wait unless noted.
 | 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_STATE_DIR` | State directory. Also holds `compile-cache/` (V8 code cache for the CLI; `NODE_DISABLE_COMPILE_CACHE=1` turns it off). | `$XDG_STATE_HOME/mu` |
+| `XDG_STATE_HOME` | XDG state base; mu appends `mu/`. An empty or relative value is ignored. | `~/.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 |
 
@@ -19,7 +21,10 @@ milliseconds; `0` disables a wait unless noted.
 | --- | --- | --- |
 | `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` |
+| `TMUX`, `TMUX_PANE` | Read only. Either one (set by tmux in its panes) selects tmux. `$TMUX` gates reading the current session name, which resolves the workstream when `-w` and `MU_SESSION` are absent. `$TMUX_PANE` identifies the calling agent (`mu me`, `mu log`, task claim errors). | |
+| `HERDR_WORKSPACE_ID` | Read only. Set by herdr in its panes; pane listing with no target reads this workspace first. | |
+| `HERDR_PANE_ID` | Read only. Set by herdr in its panes; fallback rung of actor identity after `MU_AGENT_NAME`. | |
+| `MU_TMUX_SOCKET` | Test isolation. Runs every tmux call on a private server (`-L <name>`) with `-f /dev/null`, so `~/.tmux.conf` is not loaded. tmux only. | unset: tmux's default server |
 | `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 |
 
@@ -27,7 +32,7 @@ milliseconds; `0` disables a wait unless noted.
 
 | 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_<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. On herdr, spawn refuses both with exit 2. | 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`. A pi agent skips the wait: the pane is checked on each ctl handshake tick and scanned when it ends. | `1500` |
 | `MU_SPAWN_LOCK_TIMEOUT_MS` | How long a spawn waits for the per-workstream spawn lock. | `15000` |
@@ -81,6 +86,7 @@ pi agent's `--command`. mu never reads them back.
 | `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 |
+| `NODE_ENV` | Unset: the TUI loads React's production build. Set it (e.g. `development`) to get React's dev build and warnings. | unset |
 
 ## Tests
 

package/docs/reference/naming.md

@@ -37,9 +37,9 @@ clears all blockers.
 | 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 |
+| Task `local_id` | `[a-z][a-z0-9_-]*`, ≤ 64 chars | workstream |
+| Workstream name | `[a-z][a-z0-9_-]*`, ≤ 32 chars; mux session is `mu-<name>` | DB |
+| Window (`--tab`) | not validated; passed to the mux as given. Avoid `:` and `.`, which tmux reads as target separators | workstream |
 
 `scratch` is reserved: it is created only by the first
 `mu agent spawn <name> -w scratch`, and `mu workstream init scratch`
@@ -87,7 +87,6 @@ The state dir is `MU_STATE_DIR`, else `$XDG_STATE_HOME/mu`, else
 | 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/mu",
-  "version": "3.8.1",
+  "version": "3.10.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"

package/skills/mu/SKILL.md

@@ -264,8 +264,8 @@ Close the task as your last action, or the orchestrator's wait hangs.
 ## Guardrails
 
 Task ownership outranks agent state. Coordinate through task notes and
-the activity log. Keep edges within one workstream and reserve the `mu_`
-task-id prefix. Give workers bounded paths and commands.
+the activity log. Keep edges within one workstream. Give workers
+bounded paths and commands.
 
 ## Recipes
 

package/skills/mu/recipes/drift-audit.md

@@ -34,12 +34,14 @@ or close you compare against is often older than it.
 2. Stale pins: for each build/binary sha or oracle commit named in an
    IN_PROGRESS note, and each merged fix its task's findings depend on:
    git merge-base --is-ancestor <fix> <pinned>. Exit 1 = pin is stale.
-3. Closed-task notes: notes added after the task's last task.close op.
-   Report each of the top 5 by count as its own finding with its count,
+3. Closed-task notes: notes added after the task's last task.close op,
+   minus the `CLOSE:` or `<SUBSTATE>:` note the close verb itself writes
+   as the very next op (seq + 1); any other note counts, whatever its
+   prefix. Report each of the top 5 by count as its own finding with its count,
    even when the notes look routine. A late note that reports the
    closed bug again usually ran on a build without the closing fix:
    check its sha with git merge-base --is-ancestor <fix> <sha>.
-   mu sql "select t.local_id name, count(*) late from tasks t join workstreams w on w.id=t.workstream_id join task_notes n on n.task_id=t.id where w.name='<ws>' and t.status='CLOSED' and n.created_at > (select max(o.created_at) from ops o where o.intent='task.close' and o.key='<ws>/'||t.local_id) group by t.local_id order by late desc"
+   mu sql "select t.local_id name, count(*) late from tasks t join workstreams w on w.id=t.workstream_id join task_notes n on n.task_id=t.id join (select key, max(seq) seq, max(created_at) at from ops where intent='task.close' and entity='task' group by key) c on c.key='<ws>/'||t.local_id where w.name='<ws>' and t.status='CLOSED' and n.created_at > c.at and not exists (select 1 from ops x where x.seq=c.seq+1 and x.entity='note' and x.key=c.key||'#'||n.id and (n.content like 'CLOSE: %' or n.content like upper(t.substate)||': %')) group by t.local_id order by late desc"
 4. Thin decisions: an ACCEPT/REJECTED/CLOSE/SUPERSEDED note under 40
    chars; a refuter tally with no REFUTER or VERDICT note; a review the
    orchestrator closed with no FILES/COMMANDS note and no commit.