@mu-crew/mu 3.13.3 → 4.0.0

package/AGENTS.md

@@ -5,16 +5,16 @@ panes, coordinated through a task DAG.
 
 ## Read these first
 
-1. [docs/guide/README.md](docs/guide/README.md) — what mu does for a user.
-2. [CHANGELOG.md](CHANGELOG.md) — the upcoming version's entry is the
+1. [docs/guide/README.md](docs/guide/README.md): what mu does for a user.
+2. [CHANGELOG.md](CHANGELOG.md): the upcoming version's entry is the
    source of truth for verbs, schema, and env vars.
-3. [docs/VISION.md](docs/VISION.md) — design pillars you must not violate.
-4. [docs/ROADMAP.md](docs/ROADMAP.md) — what's next and the promotion
+3. [docs/VISION.md](docs/VISION.md): design pillars you must not violate.
+4. [docs/ROADMAP.md](docs/ROADMAP.md): what's next and the promotion
    criteria. Read [Anti-feature pledges](docs/ROADMAP.md#anti-feature-pledges)
    before you add a dependency, an abstraction, or a surface.
-5. [docs/VOCABULARY.md](docs/VOCABULARY.md) — canonical terms for code,
+5. [docs/VOCABULARY.md](docs/VOCABULARY.md): canonical terms for code,
    docs, and error messages. [docs/reference/](docs/reference/) holds env vars and naming.
-6. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — the module map (what
+6. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): the module map (what
    lives where in `src/`), plus deep dives under [docs/architecture/](docs/architecture/).
 
 ## Build, test, lint
@@ -33,6 +33,29 @@ npm run test:stress      # pre-release stability gate
 aliased to 6.x on purpose: `tsup --dts` needs the programmatic API that
 TS 7.0 lacks. Revisit at TS 7.1.
 
+## Gates
+
+Measured 2026-10-23 on linuxpc (16 cores, warm cache, shared host);
+see [the record](docs/test-health/2026-10-23-surface.md). Both gates are
+over budget today.
+
+| Gate | Command | Budget | Today |
+|---|---|---|---|
+| fast | `npm run typecheck && npm run lint && npm run test:fast` | 30 s | ~50 s |
+| slow | `npm run build && npm run test` | 5 min | 4.5 to 8.5 min |
+| targeted slow | `npm run build && npx vitest run <files>` | — | — |
+
+The "Today" column is stale: on a shared box the RC measured fast 22–39 s
+(4850 tests) and slow 307–486 s (5835 tests), over budget. Re-measure on an
+idle host before the release and rewrite the column.
+
+Workers run fast while iterating, then targeted slow for the changed area,
+and fast on the final commit. The orchestrator runs fast + slow once per
+merged batch (`npm run test` excludes lint and typecheck). Record gates per
+[test-health](skills/mu/recipes/test-health.md#gate-contract).
+`test/spawn-parallel-race.integration.test.ts` needs `dist/`, hence build
+first.
+
 ## Code style
 
 - Strict TypeScript with `noUncheckedIndexedAccess`, ESM only. Use
@@ -58,8 +81,8 @@ TS 7.0 lacks. Revisit at TS 7.1.
 - The fast tier (`*.test.ts`) stays in-process: mocked tmux and VCS,
   per-test temp DBs, no real tmux/git/jj/sl, no sleeps over 50ms.
 - Name full-only tests `*.integration.test.ts`. They may use real
-  tmux, herdr, VCS fixtures, or subprocesses. Real-tmux tests skip
-  without `$TMUX`. Set `process.env.MU_SPAWN_LIVENESS_MS = "0"` in
+  tmux, herdr, VCS fixtures, or subprocesses. Real-tmux tests run on the
+  private socket and need no `$TMUX`. Set `process.env.MU_SPAWN_LIVENESS_MS = "0"` in
   `beforeEach` when the spawned process is meant to live long.
 - Integration tests use unique session names
   (`mu-test-<pid>-<ts>-<rand>`), poll (50ms × 10) instead of sleeping,
@@ -71,12 +94,19 @@ TS 7.0 lacks. Revisit at TS 7.1.
   close only what you created.
 - `openDb()` refuses the real DB under vitest. Use `MU_DB_PATH` or
   `{ path }`.
+- In tests, `openDb` on a new path copies a template DB built once per
+  run (`test/_db-template.ts`). A test that pins fresh-file behaviour
+  (the DDL, a refusal leaving the file empty) calls
+  `vi.unmock("../src/db.js")`.
 - `test/_setup.ts` clears inherited `MU_*` vars except
   `MU_TMUX_SOCKET`. Opt in per test with `withEnv()` from `test/_env.ts`.
-- `test/_global-teardown.ts` kills every `mu-*` tmux session on the
-  default socket that has no workstream in your real DB. It skips the
+- Tests use temp DBs. `test/_global-teardown.ts` only reads the real DB
+  to decide which sessions to sweep: it kills every `mu-*` tmux session
+  on the default socket that has no workstream there, and skips the
   sweep when that DB is missing or unreadable.
-- Workers run `npm run test` concurrently. A test that fails
+- Workers run fast while iterating and slow for their changed area (see
+  [Gates](#gates)); the orchestrator runs fast + slow once per
+  merged batch. Tests may run concurrently across workers. A test that fails
   under load but passes alone is a test-infra concurrency bug (shared
   `/tmp`, sockets, leaked subprocesses). One that also fails alone is a
   real bug.
@@ -122,14 +152,20 @@ TS 7.0 lacks. Revisit at TS 7.1.
 
 ### Update the schema
 
-The schema is v11 (`CURRENT_SCHEMA_VERSION` in `src/db.ts`), applied by
-`applySchema(db)` as idempotent CREATE-IF-NOT-EXISTS. `openDb` refuses
-older DBs (`SchemaTooOldError`) and newer ones (`SchemaTooNewError`),
-both exit 4. There is no migration ladder.
+The schema is v13 (`CURRENT_SCHEMA_VERSION` in `src/db.ts`). `openDb`
+runs `upgradeSchema(db)`: the idempotent CREATE-IF-NOT-EXISTS DDL, any
+missing `ADDED_COLUMNS`, the schema stamp, and the capture triggers with
+their stamp, in ONE transaction. It accepts only v13 (no ladder; a v13
+file missing a later addition is completed) and refuses older DBs
+(`SchemaTooOldError`) and newer ones (`SchemaTooNewError`), both exit 4.
 
 1. Bump `CURRENT_SCHEMA_VERSION` and mirror the shape in
-   `CURRENT_SCHEMA`. Prefer additive or idempotent-drop changes. Write
-   a one-shot migration script only when neither works.
+   `CURRENT_SCHEMA`. A column an existing DB lacks also goes in
+   `ADDED_COLUMNS` (plain nullable or defaulted: SQLite adds nothing else
+   in place). Changing `CAPTURED_COLUMNS` or a trigger generator means
+   bumping `CAPTURE_VERSION` and the pinned checksum in
+   `test/capture-persistent.test.ts`. Test the upgrade on a populated
+   file (`test/fixtures/v13-populated.db.gz`, `test/loop-storage.test.ts`).
 2. Classify every new table in `PORTABLE_TABLES` or
    `MACHINE_LOCAL_TABLES`. `test/entities.test.ts` fails otherwise.
 3. Update `test/db.test.ts` and CHANGELOG `### Changed`.
@@ -150,9 +186,9 @@ Call sites use `await activeMux()` and never name a backend.
 
 Run tmux only through `tmux(args)` and herdr only through
 `herdr(args)`. pi agents are driven through the control socket, not
-the multiplexer. For non-pi agents and `--via mux`, tmux needs the
-bracketed-paste sequence in `sendToPane`, while herdr's `agent prompt`
-is one atomic call. Keep the tmux workaround out of herdr.
+the multiplexer. tmux refuses a send to a non-pi agent
+(`AgentSendUnsupportedError`; it has no `sendToPane`), while herdr's
+`agent prompt` is one atomic call.
 
 ## Known traps
 
@@ -160,29 +196,24 @@ is one atomic call. Keep the tmux workaround out of herdr.
   top-level await" is an import cycle: a file in `src/cli/tui/`
   imported `../../../cli.js`. Import from the real source module
   instead (`rg 'from "\.\./\.\./\.\./cli\.js"' src/cli/tui/`).
-- **ANSI in ink `<Text>`** breaks wrap math. Pre-wrap by visual width
-  with `src/cli/tui/wrap-ansi.ts` and pad lines to the box width.
-- **A key or click lands in the wrong popup**: a stale mouse event was
-  replayed. Consume it once, as `src/cli/tui/use-popup-action-queue.ts`
-  does.
-- **A hint for one popup** goes in its `hint` prop, not the global
-  `POPUP_DRILL_HINTS`.
+- **ANSI in ink `<Text>`** breaks wrap math. Size and cut styled lines
+  by visual width with `fitLine` in `src/cli/tui/text.ts`, and keep
+  frame lines exactly the box width (`frame.tsx`).
 
 ## Orchestrating on this repo
 
 Follow [skills/mu/recipes/orchestrator-loop.md](skills/mu/recipes/orchestrator-loop.md). Repo specifics:
 
-- Each workspace runs `npm install` into its own `node_modules`. Never
+- Each worktree runs `npm install` into its own `node_modules`. Never
   symlink main's.
-- `mu task wait` may list commits already on main when a worker forked
-  from an old HEAD. Check `git log` in the workspace and cherry-pick
-  only the new shas.
+- A worker may fork from an old HEAD. Check `git log` in its worktree
+  and cherry-pick only the new shas.
 - CHANGELOG.md conflicts are routine: keep both halves in order.
   Resolve source conflicts by hand, never with `--ours` or `--theirs`.
 - Fix a worker's bug in a separate commit after the cherry-pick. Do
   not amend it.
-- Gate the merged tree with the full gate below plus
-  `node dist/cli.js --help`.
+- Gate the merged tree with the fast gate and the slow gate (see
+  [Gates](#gates)) plus `node dist/cli.js --help`.
 - The installed `mu` may be older than the branch build. Confirm a
   worker received its brief (`mu agent read <w> -n 3`).
 
@@ -221,14 +252,21 @@ documenting" is not a reason.
 - No render layer beyond `cli-table3` + `picocolors`, except `ink`
   inside `src/cli/tui/`. Never a second TUI stack.
 - Don't bundle pi. It is an optional peer dependency.
-- Write files only under `~/.local/state/mu/`, `~/.cache/mu/`, or the
+- Write files only under `~/.local/state/mu-next/`, `~/.cache/mu/`, or the
   repo. The cache dir holds only files mu can lose at any time.
 
 ## When you're done
 
+Run the fast gate, then the slow gate for your changed area (see
+[Gates](#gates)):
+
 ```bash
-npm run typecheck && npm run lint && npm run test:fast && npm run test && npm run build
+npm run typecheck && npm run lint && npm run test:fast
+npm run build && npx vitest run <files>
 ```
 
+The orchestrator runs the fast gate and `npm run build && npm run test` on
+each merged batch.
+
 Then check that VOCABULARY, ARCHITECTURE, and CHANGELOG reflect the
 change.

package/README.md

@@ -2,76 +2,91 @@
 
 **A small control plane for a crew of AI coding agents working in
 parallel.** Agents run in multiplexer panes you can attach to. Work is a
-task DAG in SQLite. Each agent gets its own VCS workspace.
+task DAG in SQLite. Each agent gets its own git worktree.
 
-![mu dashboard](docs/img/tui-dashboard.png)
-
-*Bare `mu` opens a read-only dashboard: agents, tracks, ready,
-in-progress, and blocked tasks, the log tail, workspaces, and doctor.*
-
-- **Parallel work that does not collide.** Per-agent workspaces (jj
-  workspaces, sl shares, or git worktrees) and a task DAG with
+- **Parallel work that does not collide.** Per-agent git worktrees and a task DAG with
   `blocks` edges keep agents out of each other's way.
 - **State that outlives a pane.** One SQLite DB holds agents, tasks,
-  owners, notes, and workspaces. An append-only ops log records every
-  change, so `mu undo <group>` reverses one action and `mu rebuild`
+  owners, notes, and worktrees. An append-only ops log records every
+  change, so `mu log --group <group>` shows one action and `mu rebuild`
   replays the whole history.
 - **Exact control of pi agents.** mu's pi extension serves a control
   socket inside each agent, so send, state, wait, and abort are exact,
   locally and over ssh. The pane stays pi's normal TUI.
-
-mu persists state and coordinates handoffs. Every read path has
-`--json`, and every change goes through a typed CLI verb. See
-[What mu is not](#what-mu-is-not).
+- **One wait.** `mu wait` blocks until the first event you own (closed,
+  settled, needs you, dead, stalled) and prints one JSON result with a
+  `resume` command. In pi, the extension runs it for you, so an
+  orchestrator keeps driving until nothing is owed.
+- **Delegates without a pane.** A `mu_delegate` call is a fresh-context
+  helper recorded as a task with a durable id. With no tmux or herdr it
+  runs as a child pi.
+- **A capped skill.** One `mu` skill (under 600 words) and twelve short recipes,
+  checked by an eval matrix (`tools/eval`). `mu --help` holds the rest.
+
+Every read path has `--json`, and every change goes through a typed CLI
+verb. See [What mu is not](#what-mu-is-not).
+
+**Status:** 4.0, a breaking rewrite for agent callers with its own DB. It
+never imports a 3.x DB; open work moves one workstream at a time. Coming
+from 3.x? Read [Upgrade from 3.x to 4.0](docs/guide/upgrade.md#upgrade-from-3x-to-40)
+before you install.
 
 ## Install
 
 ```bash
 npm i -g @mu-crew/mu
-mu link pi       # pi extension (control socket, mu_delegate) + the mu skill
+pi install npm:@mu-crew/mu   # extension (control socket, mu_delegate), the mu skill, recipe prompts
 mu doctor
 ```
 
-To drive mu from another agent CLI (claude-code, codex), install the
-skill with `npx skills add mu-crew/mu` instead of `mu link pi`.
+To drive mu from another agent CLI (claude-code, codex, cursor-agent),
+install the skill with `npx skills add mu-crew/mu` instead of the pi
+package. Read [Run mu with other agent CLIs](docs/guide/other-agent-clis.md)
+first: pin which `mu` the harness runs, and see what works without pi.
 
 You need:
 
 - Node 22.12–26 (see `.nvmrc`).
-- tmux ≥ 3.0 or [herdr](https://github.com/herdrdev/herdr). `mu doctor`
-  reports which one is active.
+- tmux ≥ 3.0 or [herdr](https://github.com/herdrdev/herdr) for agents.
+  `mu doctor` reports which one is active. Without either, task verbs
+  and pi's `mu_delegate` still work (a delegate runs as a child pi).
 - pi, or another agent CLI.
-- jj, sl, or git on `PATH` for `--workspace`.
+- git on `PATH` for `--worktree`.
 
 [murmur](https://github.com/mu-crew/murmur) is optional for pi agents.
 Non-pi agents on tmux need it for state: without it their state is
-`unknown`, so `mu agent wait` and stall detection never fire for them.
+`unknown`, so a wait never sees them finish and stall detection never fires.
 On herdr, herdr reports state.
 
-To update or run from a checkout, see
+Updating, keeping 3.x runnable beside 4.0, and running from a checkout:
 [How to upgrade mu](docs/guide/upgrade.md).
 
 ## Quick start
 
-Run this inside tmux or herdr:
+Run this inside tmux or herdr, in a git repository:
 
 ```bash
-mu workstream init auth
-export MU_SESSION=auth   # init does not attach you; or pass -w auth to each verb
-mu task add design_auth --title "Design auth" --impact 80 --effort-days 2
-mu task add build_auth  --title "Build auth"  --impact 80 --effort-days 5 --blocked-by design_auth
-mu agent spawn worker-1 --workspace
-mu task claim design_auth --for worker-1
-mu agent send worker-1 --fresh 'Do task design_auth. Close it with evidence.'
-mu task wait design_auth --first --on-stall exit   # exit 7 = worker needs you
-mu                                                  # dashboard
-mu workstream teardown --yes                        # without --yes: dry run
+mu workstream init auth                             # every verb below names it with -w
+mu task add design_auth -w auth --title "Design auth" --impact 80 --effort-days 2
+mu task add build_auth  -w auth --title "Build auth"  --impact 80 --effort-days 5 --blocked-by design_auth
+mu agent spawn worker-1 -w auth --worktree
+mu task claim design_auth -w auth --for worker-1
+mu agent send worker-1 -w auth --fresh 'Do task design_auth. Close it with evidence.'
+mu wait task:design_auth -w auth   # one JSON result; exit 7 = worker needs you
+mu workstream teardown auth                         # preview (rev=<n>); apply with --if <n>
 ```
 
-For one helper, ask pi to delegate (`mu_delegate` ships with `mu link
-pi`), or spawn into the reserved `scratch` workstream:
+For one helper, ask pi to delegate (`mu_delegate` ships in the pi
+package), or spawn into the reserved `scratch` workstream:
 `mu agent spawn scout-1 -w scratch`.
 
+Run `mu` with no arguments for the read-only dashboard. It has five tabs
+(Overview, Tasks, DAG, Agents, Log), with what needs a human on top: a
+dead or stalled worker, one waiting on a permission or on input, a
+`human-needed` task.
+
+![The mu dashboard: a payments workstream with a dead worker, one waiting on a permission, one stalled on a tool, and a human-needed task.](docs/img/tui-dashboard.png)
+
 ## Ultrathink, the mu way
 
 Long agent runs fail in two ways: the agent stops at 35 of 50 items and
@@ -93,36 +108,34 @@ it in the open:
   ideally on another model, whose verdicts land on the task they
   judged. A 50-unit run adds about 50 units, 50 review gates and the
   findings that survive, not a task per check.
-- **Every agent is a pane.** Attach to any worker, reviewer, or judge
-  mid-run and steer it.
+- **Every agent is attachable.** Attach to any worker, reviewer, or judge
+  in its pane mid-run and steer it.
 - **Nothing lives only in a context window.** Verdicts, evidence, and
   stop rules are task notes. The run survives compaction, crashes, and
   a new orchestrator.
 
 Not every review needs a record. Reviewing someone's PR or a doc runs
 as delegates only: findings come back in their answers, and nothing
-lands in the ops log.
+enters your workstream's task graph. Each call is still a task in
+`scratch` (its prompt and answer), which syncs like any task.
 
-Ask your orchestrator to *ultrathink* a job, and it follows
-[skills/mu/recipes/ultrathink.md](skills/mu/recipes/ultrathink.md).
-That recipe composes smaller ones you can also use on their own:
+Ask your orchestrator to *ultrathink* a job, and it follows the
+[orchestrator loop](skills/mu/recipes/orchestrator-loop.md): every unit,
+review and round is a task, and checks are calls. The recipes it composes
+you can also use on their own:
 
 | Recipe | Shape |
 | ------ | ----- |
-| [fan-out](skills/mu/recipes/fan-out.md) | one task per unit, merged as each closes |
+| [orchestrator-loop](skills/mu/recipes/orchestrator-loop.md) | dispatch, wait, merge; also sweeps and loops until a stop rule holds |
 | [adversarial-review](skills/mu/recipes/adversarial-review.md) | a review gate per unit: a fresh agent tries to reject it before it ships |
-| [refute](skills/mu/recipes/refute.md) | finders record findings, one refuter call per finding, report from the graph |
-| [hypothesis-panel](skills/mu/recipes/hypothesis-panel.md) | independent theories from separate evidence, each attacked |
-| [tournament](skills/mu/recipes/tournament.md) | competing attempts, judged in pairs |
-| [loop-until-done](skills/mu/recipes/loop-until-done.md) | rounds until a stop rule written up front holds |
-| [backlog-triage](skills/mu/recipes/backlog-triage.md) | quarantined readers classify, a trusted actor acts |
-| [deep-research](skills/mu/recipes/deep-research.md) | searchers by angle, one checker per claim, a cited report |
-| [review-panel](skills/mu/recipes/review-panel.md) | one reviewer per angle on a diff; delegates by default, tasks when fixes follow |
-| [rules-audit](skills/mu/recipes/rules-audit.md) | one checker per AGENTS.md rule plus a skeptic; or mine repeated corrections into new rules |
-
-In pi, `mu link pi` adds them as commands: `/ultrathink <job>`,
+| [findings](skills/mu/recipes/findings.md) | reviewers record findings, one refuter call per finding, report from the graph |
+| [tasks-or-calls](skills/mu/recipes/tasks-or-calls.md) | refuters, judges and checkers as delegate calls |
+| [course-correct](skills/mu/recipes/course-correct.md) | a periodic look at whether a long job is on course |
+| [move](skills/mu/recipes/move.md) | move a 3.x workstream into 4.0 |
+
+In pi, the package adds them as commands: `/ultrathink <job>`,
 `/mu-research <question>`, `/mu-review [target]`, `/mu-refute <scope>`,
-`/mu-tournament <task>`, `/mu-rules-audit [check <target> | mine]`,
+`/mu-tournament <task>`, `/mu-rules-audit [target]`,
 `/mu-debug <symptom>`, `/mu-sweep <change>`, and `/mu-until <stop rule>`.
 
 All recipes, including the orchestrator loop and remote workers, are
@@ -131,9 +144,10 @@ in [skills/mu/recipes/](skills/mu/recipes/).
 ## What mu is not
 
 - **Not a hidden subagent.** Every agent, including a one-off
-  `mu_delegate` helper, is an ordinary agent in a pane: attach, steer,
-  abort, or keep talking to it. That costs a pane and a pi process per
-  agent; for many tiny calls a hidden subagent is lighter. See
+  `mu_delegate` helper, is an ordinary agent you can steer, abort, or keep
+  talking to, in a pane you can attach to (with no tmux or herdr, a child
+  pi and a task record). That costs a pi process per agent; for many tiny
+  calls a hidden subagent is lighter. See
   [the comparison](docs/guide/delegate.md#delegates-vs-hidden-subagents).
 - **Not a workflow engine.** No DSL, no hidden plan, no script runner.
   The plan is the task DAG; recipes are instructions an agent follows,
@@ -155,7 +169,7 @@ and [ROADMAP § Anti-feature pledges](docs/ROADMAP.md#anti-feature-pledges).
 - [Getting started](docs/guide/getting-started.md): the first
   workstream, end to end. Start here.
 - [User guide](docs/guide/README.md): how-tos for dispatch, remote
-  workers, sync, recovery, and the dashboard.
+  workers, sync, and recovery.
 - [skills/mu/SKILL.md](skills/mu/SKILL.md): what an orchestrating
   agent reads. [skills/mu/recipes/](skills/mu/recipes/) holds the
   recipes it points to, such as