@mu-crew/mu 1.6.0

package/AGENTS.md

@@ -0,0 +1,611 @@
+# Repo guide for AI coding agents
+
+You're an AI coding agent working on the `mu` repo, which builds
+**mu** — a CLI that manages a persistent crew of AI agents in
+multiplexer panes (tmux or herdr) coordinated through a built-in
+task DAG.
+
+Read the linked docs before you write code. Follow the conventions
+below.
+
+---
+
+## Read these first (in this order)
+
+1. **[docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md)** — what mu does
+   from a user's perspective. ~10 minutes.
+2. **[CHANGELOG.md](CHANGELOG.md)** — the upcoming version's entry.
+   Single source of truth for the verb list, schema, env vars.
+3. **[docs/VISION.md](docs/VISION.md)** — the design principles you
+   must not violate.
+4. **[docs/ROADMAP.md](docs/ROADMAP.md)** — what's next, with
+   promotion criteria. **Read the "Anti-feature pledges" section
+   before adding any new dep, abstraction, or surface.**
+5. **[docs/VOCABULARY.md](docs/VOCABULARY.md)** — canonical terms.
+   **Source of truth for every word** in code, docs, and error
+   messages. If you use a term not defined there, fix the docs first.
+6. **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — module layout,
+   reconciliation algorithm, TUI architecture, key seams.
+
+Design rationale for rejected and unbuilt features lives in
+[docs/ROADMAP.md](docs/ROADMAP.md) per item, alongside its promotion
+criteria.
+
+> **If you are an orchestrator** — a coding agent driving a crew of
+> pi worker agents on this repo via `mu` — read
+> **[docs/HANDOVER.md](docs/HANDOVER.md)** instead of the order
+> above: onboarding steps, the 8-phase dispatch loop,
+> conflict-resolution playbook, known gotchas, end-of-session
+> checklist. AGENTS.md is for workers and humans editing the repo
+> directly.
+
+---
+
+## Repo layout
+
+```
+mu/
+├── README.md              # human-user entry point
+├── AGENTS.md              # this file
+├── CHANGELOG.md           # release notes
+├── docs/                  # everything else
+│   ├── USAGE_GUIDE.md     # user-facing tour (§ 5b is the TUI reference)
+│   ├── HANDOVER.md        # orchestrator goto reset doc (8-phase loop + gotchas)
+│   ├── ROADMAP.md         # what's next; promotion criteria; anti-feature pledges
+│   ├── VISION.md          # design pillars
+│   ├── VOCABULARY.md      # canonical terms (single source of truth)
+│   └── ARCHITECTURE.md    # module layout, TUI architecture, key seams
+├── src/                   # all source (root files: SDK + shared infra; one
+│                          # level of subdirs OK for cohesive clusters — see
+│                          # `src/cli/`, `src/agents/`, `src/tasks/`, `src/mux/`)
+│   ├── db.ts              # SQLite schema + openDb (single CREATE-IF-NOT-EXISTS block; v10)
+│   │                      # also owns SYNCED_ENTITIES / PORTABLE_TABLES / MACHINE_LOCAL_TABLES
+│   ├── mux.ts             # multiplexer backend hub (re-exports src/mux/*)
+│   ├── mux/               # cohesive cluster: one file per multiplexer
+│   │   ├── index.ts       # re-export hub consumed by src/mux.ts
+│   │   ├── types.ts       # MuxBackend interface + MuxError / PaneNotFoundError / NoMultiplexerError
+│   │   ├── detect.ts      # MU_MUX → HERDR_ENV → $TMUX → availability ladder; activeMux()
+│   │   ├── tmux.ts        # tmux impl: wrapper, 6-step send protocol, pane validation
+│   │   └── herdr.ts       # herdr impl: JSON socket API, atomic send, native pane status
+│   ├── tmux.ts            # back-compat re-export of the tmux backend (new code imports mux.js)
+│   ├── detect.ts          # pi status detector + Braille-spinner fallback; used only when
+│   │                      # the backend has no paneStatus() of its own (i.e. tmux)
+│   ├── reconcile.ts       # ghost prune + status detect + orphan surface
+│   ├── agents.ts          # CRUD + send/read/list/close + liveness + reaper hub (re-exports src/agents/*)
+│   ├── agents/            # cohesive cluster of agent-lifecycle internals
+│   │   ├── spawn.ts       # spawnAgent + resolveCliCommand / awaitSpawnLiveness / pane create-or-reuse / prestage / rollback
+│   │   ├── spawn-lock.ts  # cross-process advisory lock around a spawn's topology critical section
+│   │   ├── kick.ts        # reaper events + cleanup of dead agent rows
+│   │   ├── adopt.ts       # adoptAgent: register an existing pane as a managed agent
+│   │   ├── wait.ts        # waitForAgents: block on task-less agents finishing (busy → any other state)
+│   │   └── errors.ts      # typed agent error classes (AgentNotFoundError, AgentDiedOnSpawnError, …)
+│   ├── tasks.ts           # task SDK hub (re-exports src/tasks/*)
+│   ├── tasks/             # cohesive cluster of task-graph internals
+│   │   ├── status.ts      # TaskStatus enum + helpers
+│   │   ├── core.ts        # core SDK funcs reused across cluster files
+│   │   ├── id.ts          # tryResolveTaskId / qualified-id helpers
+│   │   ├── queries.ts     # listTasks / nextTasks / owned-by
+│   │   ├── edit.ts        # addTask / setTaskTitle / etc (no edges)
+│   │   ├── edges.ts       # block / unblock / reparent / delete + dedupe
+│   │   ├── claim.ts       # claim / release + resolveActorIdentity (atomic CAS)
+│   │   ├── lifecycle.ts   # setTaskStatus / closeTask / openTask + cascade
+│   │   ├── wait.ts        # waitForTasks: block until tasks reach a target status
+│   │   ├── sort.ts        # sortTasks (roi / recency / age / id)
+│   │   └── errors.ts      # typed task error classes (TaskAlreadyOwnedError, CycleError, …)
+│   ├── tracks.ts          # parallel-tracks union-find with diamond merge
+│   ├── workstream.ts      # ensureWorkstream / list / summarize / destroy
+│   ├── hlc.ts             # hybrid logical clock: the monotonic ordering key on every op
+│   ├── capture.ts         # SQLite triggers recording every portable mutation as an op, in-transaction
+│   ├── op-context.ts      # withOpContext (intent/actor/group) + withCaptureSuppressed echo guard
+│   ├── apply.ts           # the apply path: per-field LWW merge + tombstones + deferred reprojection
+│   ├── undo.ts            # inverse ops for one group (granular undo; supersede refusal)
+│   ├── rebuild.ts         # replay the whole ops log into a NEW DB file (disaster recovery)
+│   ├── drift.ts           # ops-log-vs-live-tables drift check (cheap default tier + --deep rebuild-diff)
+│   ├── segments.ts        # JSONL segment transport: flush own ops / ingest peers from a watermark
+│   ├── sync.ts            # peer status + the ambient flush/ingest hook + --from reader + --repair
+│   ├── fleet-hazards.ts   # mixed-fleet doctor checks (DB inside MU_SYNC_DIR, network mount, case collisions)
+│   ├── file-lock.ts       # generic cross-process advisory lock via atomic fs.mkdir
+│   ├── logs.ts            # typed READER over `ops` + appendLog / emitEvent (the one write path triggers can't cover)
+│   ├── log-render.ts      # the ONE op → prose formatter (renderOp); shared by CLI + TUI
+│   ├── vcs.ts             # VcsBackend hub (re-exports src/vcs/*: jj/sl/git/none impls)
+│   ├── workspace.ts       # per-agent VCS workspaces hub (re-exports src/workspace/*)
+│   ├── glyphs.ts          # THE glyph vocabulary: agent status + state glyphs + card digits
+│   ├── shell-quote.ts     # POSIX single-quote helper for copy-pasteable Next: hints
+│   ├── dag.ts             # full-DAG forest builder (loadFullDag for `mu task tree` + DAG popup)
+│   ├── state.ts           # SDK seam for `mu state` (fast SQL tier + slow subprocess tier + merge)
+│   ├── staleness.ts       # WORKSPACE_STALE_THRESHOLD + isStaleWorkspace
+│   ├── project-root.ts    # detectProjectRoot for the TUI launch cwd ladder
+│   ├── doctor-summary.ts  # TUI-friendly slice of `mu doctor` checks + remediation helpers
+│   ├── output.ts          # NextStep type + printNextSteps / errorNextSteps
+│   ├── cli.ts             # commander wiring (buildProgram); re-exports format/handle for back-compat
+│   ├── cli/               # one file per verb-namespace; thin wrappers over the SDK
+│   │   ├── workstream.ts  # workstream init / list / destroy
+│   │   ├── agents.ts      # agent spawn / send / read / list / show / close / kick / wait / adopt
+│   │   ├── tasks.ts       # `mu task` hub (re-exports wireTaskCommands / cmdMyNext / cmdMyTasks / unescapeNoteText)
+│   │   ├── tasks/         # sub-cluster of the `mu task` namespace
+│   │   │   ├── queries.ts    # list / next / owned-by + cmdMyTasks / cmdMyNext (back `mu me tasks` / `mu me next`)
+│   │   │   ├── lifecycle.ts  # close / open + cascade preview
+│   │   │   ├── edit.ts       # add / show / notes / note / update + helpers
+│   │   │   ├── edges.ts      # block / unblock / reparent / delete
+│   │   │   ├── claim.ts      # claim / release / wait
+│   │   │   ├── tree.ts       # tree rendering
+│   │   │   └── wire.ts       # Commander glue
+│   │   ├── workspace.ts   # workspace list / free / path / orphans / refresh / commits
+│   │   ├── log.ts         # log read / write / tail
+│   │   ├── undo.ts        # mu undo [group] (list / preview / --yes apply)
+│   │   ├── sync.ts        # mu sync (peer status; --from / --repair)
+│   │   ├── rebuild.ts     # mu rebuild <file>
+│   │   ├── state.ts       # `mu state` (canonical state card); --tui dispatches to src/cli/tui/
+│   │   ├── staleness.ts   # shared workspace-staleness CLI helpers + warn formatter
+│   │   ├── tui-launch-focus.ts # initial-tab focus ladder for bare `mu` and `mu state --tui`
+│   │   ├── tui/           # interactive ink-based TUI cluster; ONLY place ink/react are imported
+│   │   │   ├── index.ts            # runTui entrypoint; alt-screen + mouse-mode lifecycle
+│   │   │   ├── escapes.ts          # pure ANSI escape constants (ALT_SCREEN_*, mouse-mode bytes) — no ink imports
+│   │   │   ├── app.tsx             # <App> root (popup state machine + global keymap + footer + tick + tabs)
+│   │   │   ├── state.ts            # poll-loop hook (useDashboardSnapshot; fast/slow tick split)
+│   │   │   ├── keys.ts             # pure dispatchGlobalKey + dispatchPopupKey + shouldSwallowGlobalKey
+│   │   │   ├── keymap-spec.ts      # canonical keymap source-of-truth (drives help overlay + dispatch)
+│   │   │   ├── yank.ts             # clipboard probe + write (pbcopy/wl-copy/xclip/xsel/clip.exe + OSC-52)
+│   │   │   ├── mouse.ts            # vendored SGR mouse layer (parser + double-click + useMouse hook)
+│   │   │   ├── layout.ts           # responsive multi-column dashboard + per-card row budgets
+│   │   │   ├── columns.ts          # column-aligned row layout with protect/clip clipping
+│   │   │   ├── wrap-ansi.ts        # ANSI-aware visual-width line wrapper + SGR close-on-end
+│   │   │   ├── format-helpers.ts   # shared TUI formatters (relTime, sinceClaim, ROI, etc.)
+│   │   │   ├── titled-box.tsx      # rounded border with section header inset into top border + bottomLabel
+│   │   │   ├── popup-shell.tsx     # popup outer chrome (cyan TitledBox)
+│   │   │   ├── list-row.tsx        # centralised non-selected row primitive (width pin + gutter + truncate)
+│   │   │   ├── padded-rows.tsx     # per-card body padder
+│   │   │   ├── help.tsx            # ?/F1 keymap overlay (scrollable on short panes)
+│   │   │   ├── status-bar.tsx      # bottom status bar (mode + active ws + tick + footer flash)
+│   │   │   ├── tab-strip.tsx       # multi-workstream tab switcher (N≥2)
+│   │   │   ├── tab-strip-layout.ts # pure window-around-active layout helper for the tab strip
+│   │   │   ├── tuicr.ts            # `t` shortcut: alt-screen handoff to tuicr -r <sha>
+│   │   │   ├── use-popup-filter.tsx       # shared '/' substring filter hook + applyFilter + FilterPrompt
+│   │   │   ├── use-status-filter.tsx      # task-status toggles for task-list popups (o/i/c)
+│   │   │   ├── use-notes-drill.ts         # shared notes-drill memo (5 task popups consume it)
+│   │   │   ├── use-popup-action-queue.ts  # consume mouse PopupAction queue once per render
+│   │   │   ├── use-terminal-size.ts       # shared reactive terminal-size hook (ink doesn't re-render on resize)
+│   │   │   ├── agent-display.ts           # shared agent-row display helpers for cards/popups
+│   │   │   ├── lazygit.ts                 # `l` in the Commits popup: alt-screen handoff to lazygit
+│   │   │   ├── tmux-attach.ts             # `a` in the Agents popup: alt-screen handoff to the agent's mux pane
+│   │   │   ├── cards/{agents,tracks,ready,log,workspaces,inprogress,blocked,recent,commits,doctor}.tsx + _placeholder.tsx
+│   │   │   └── popups/{agents,tracks,ready,log,workspaces,inprogress,blocked,recent,commits,doctor,dag,all-tasks}.tsx
+│   │   │                          # plus drill.tsx (DrillScrollView), task-detail.tsx (TaskDetailDrill),
+│   │   │                          # cursor-row.tsx, scroll.ts (applyCursor/applyScroll), viewport.ts,
+│   │   │                          # show-loader.ts (shared subprocess-preserving loader)
+│   │   ├── db.ts          # db backup (VACUUM INTO)
+│   │   ├── sql.ts         # sql escape hatch
+│   │   ├── doctor.ts      # doctor diagnostic
+│   │   ├── format.ts      # pure rendering helpers (table renderers, status colourers, truncate/relTime)
+│   │   └── handle.ts      # typed-error → exit-code map + handle() wrapper
+│   └── index.ts           # SDK entrypoint (re-exports)
+├── test/                  # ~200 *.test.ts files / ~2900 tests (`npm run test`); many use real tmux/git/jj/sl
+├── skills/mu/SKILL.md     # what the LLM running inside an agent pane sees
+├── package.json           # bin: { mu: ./dist/cli.js }, type: module
+├── tsconfig.json          # strict + noUncheckedIndexedAccess + verbatimModuleSyntax
+├── tsup.config.ts         # bundles src/ → dist/ (cli + index entries)
+├── biome.json             # lint + format
+└── vitest.config.ts       # tests
+```
+
+---
+
+## Working conventions
+
+### Build / test / lint
+
+```bash
+npm install
+npm run build            # tsup → dist/
+npm run typecheck        # source + test TypeScript checks
+npm run lint             # biome check src test
+npm run test:fast        # fast unit/dev-loop tier (excludes *.integration.test.ts / *.smoke.test.ts)
+npm run test             # full vitest suite, including integration tests
+npm run test:watch       # vitest in watch mode
+npm run test:watch:fast  # fast-tier watch mode
+```
+
+#### Two TypeScript compilers, on purpose
+
+`tsc` is **TypeScript 7** (the Go-native compiler) and `tsc6` is the
+TypeScript 6 JS compiler. `package.json` aliases them:
+
+```json
+"@typescript/native": "npm:typescript@^7.0.2",
+"typescript": "npm:@typescript/typescript6@^6.0.2"
+```
+
+This looks backwards and is not. TS 7.0 ships **no programmatic
+compiler API** (`ts.createProgram` and friends return undefined; the
+package exports exactly two keys). It is deferred to 7.1. `tsup --dts`
+goes through `rollup-plugin-dts`, which needs that API, so a plain
+`typescript@7` install builds JS fine and then dies with
+`Cannot read properties of undefined (reading 'useCaseSensitiveFileNames')`.
+
+The alias resolves both needs at once: anything that `require`s
+`typescript` as a LIBRARY gets the 6.x JS API, while the `tsc` BINARY
+is the fast Go compiler (typecheck went ~9s → ~0.6s). The two bins do
+not collide, so no shim is needed.
+
+Revisit when 7.1 lands its new API and `rollup-plugin-dts` adopts it;
+at that point `typescript` can point at 7.x directly and
+`@typescript/native` disappears.
+
+Use `npm run test:fast` for the inner dev loop and concurrent worker
+checks; it is the concurrency-safe tier that avoids real tmux/VCS
+subprocess fixtures. The green gates still include `npm run test`
+before any commit. Real-tmux integration tests need `$TMUX` set and
+skip themselves otherwise; CI runs inside tmux.
+
+### Commits
+
+- Conventional but not strict: prefix with the scope when helpful
+  (e.g. `R4 + R9: ...`, `schema: ...`). One logical change per
+  commit.
+- Body explains **what changed and why**, not just what. Reference
+  the [VISION.md](docs/VISION.md) pillar / [ROADMAP.md](docs/ROADMAP.md)
+  item / promotion criterion that motivated the change.
+- Verify typecheck + lint + tests + build clean before committing.
+  Say so in the commit message.
+
+### Code style
+
+- TypeScript, strict mode. `noUncheckedIndexedAccess` is on — don't
+  trust array indices to be defined; use early returns.
+- ESM only (`"type": "module"`). NodeNext module resolution.
+- No `any`. Use `unknown` and narrow.
+- No non-null assertions (`!`). Use early returns or `if (!x) throw`.
+- Errors are typed classes (e.g. `AgentNotFoundError`,
+  `TaskAlreadyOwnedError`, `CycleError`, `MuxError` and its per-backend
+  subclasses `TmuxError` / `HerdrError`,
+  `AgentDiedOnSpawnError`) so the CLI's `handle()` wrapper can map
+  them to specific exit codes.
+- Imports stay sorted (Biome's `organizeImports` enforces this).
+- Run `npx biome check --write src test` to auto-fix sort + format.
+  **Do not** run `--write --unsafe`: it rewrites `delete
+  process.env.X` to `process.env.X = undefined`, which silently
+  produces the literal string `"undefined"`. The env-deletion pattern
+  here is `const key = "FOO"; delete process.env[key];`.
+- Hard cap: 1500 LOC per file. Refactor signal at 800.
+- **Layout: flat at the root; one level of subdirs is allowed when a
+  cluster of files is naturally cohesive** (e.g. `src/cli/` for the
+  thin commander wrappers, one file per verb-namespace). Each subdir
+  cluster needs:
+  (1) a clear theme (every file does the same kind of thing),
+  (2) imports go from cluster-files → root-files (no upward imports),
+  (3) ARCHITECTURE.md's module table has a row covering it.
+
+### Tests
+
+- Unit tests: real SQLite (in-temp-dir), mocked tmux executor via
+  `setTmuxExecutor()`. Fast, deterministic. For anything touching the
+  multiplexer, use `installMux()` from `test/_mux.ts` rather than the
+  raw setters — it installs the backend AND its executor together and
+  hands back one `restore()`, which removes the ordering hazard of
+  stubbing one backend while asserting against another.
+- TUI popup/card behaviour tests should follow `test/README.md`:
+  prefer the `test/_ink-render.ts` CaptureStream seam over
+  `readFileSync` source-greps except for narrow structural guards.
+- Fast tier: `npm run test:fast` runs `test/**/*.test.ts` while
+  excluding `*.integration.test.ts` and `*.smoke.test.ts`. Keep this
+  tier pure/in-process: mocked tmux/VCS, real SQLite only in per-test
+  temp DBs, no real tmux/git/jj/sl subprocess fixtures, no
+  filesystem-heavy export/import/snapshot paths, and no fixed sleeps
+  above 50ms.
+- Integration tests: full-only tests use the `.integration.test.ts`
+  suffix (e.g. `tmux.integration.test.ts`). They may touch real tmux
+  or herdr servers, git/jj/sl fixture repos, subprocess-backed smoke
+  paths, filesystem-heavy export/import/snapshot flows, or
+  intentionally slower in-process CLI flows. Real-tmux tests are
+  skipped when `$TMUX` is unset; real-herdr tests skip unless a
+  running, protocol-compatible server is present. These tests typically opt out of the spawn
+  liveness check via `process.env.MU_SPAWN_LIVENESS_MS = "0"` in
+  `beforeEach`, since the sh subprocesses they spawn are intentionally
+  long-lived.
+- Each test gets its own temp DB and (for integration) a unique
+  tmux session like `mu-test-<pid>-<ts>-<rand>` to avoid colliding
+  with the user's panes or with parallel test runs.
+- **herdr isolation is a guard, not a socket.** tmux gets a private
+  server via `MU_TMUX_SOCKET`, so a stray test is contained
+  structurally. herdr has no equivalent: its only isolation is a named
+  session (`MU_HERDR_SESSION`), so `test/_mux.ts` enforces it at
+  runtime — `assertHerdrIsolated()` refuses to run when the var is
+  unset or names `default`, and the fatal verbs (`server stop`,
+  `server restart`, `server kill`) are refused even inside a correct
+  session, because a stopped server is shared-fate. **Never stop the
+  herdr server or kill its main process from a test.** That destroys
+  the user's real panes and their unsaved work, with no undo. Clean up
+  per-entity (close what you created), never by nuking the server.
+- Dogfood reality: multiple pi worker agents often run `npm run test`
+  concurrently on the same machine from different workspaces. Treat
+  flakes that pass in isolation but fail under load as concurrency
+  bugs first (shared `/tmp` cleanup, tmux socket/session collisions,
+  leaked subprocesses, VCS background file activity). Use
+  `npm run test:stress` for the pre-release/stability gate; it runs
+  the suite repeatedly with a per-run timeout and can simulate
+  parallel full-suite runs via
+  `MU_TEST_STRESS_MODE=parallel MU_TEST_STRESS_PARALLEL=2`.
+- The acceptance test in `test/acceptance.integration.test.ts` is the
+  "everything works" gate. Keep it passing.
+- **DB baseline**: `openDb()` refuses to open the user's REAL
+  default DB (`<HOME or XDG_STATE_HOME>/mu/mu.db`) when
+  `process.env.VITEST` is set or `NODE_ENV === "test"`. Tests
+  MUST use a per-test temp DB — either via MU_DB_PATH (which
+  `test/_runCli.ts` sets automatically) or an explicit `{ path }`
+  argument to `openDb`. A regression that forgets either one
+  fails loudly at the offending openDb() call site instead of
+  silently writing to the dev box's live state. Production never
+  sets VITEST, so the guard is a no-op outside the test runner.
+- **Env baseline**: `test/_setup.ts` (vitest `setupFiles`) clears
+  every `MU_*` env var inherited from the parent shell at the start
+  of each fork, so SDK-level overrides (`MU_PI_COMMAND`,
+  `MU_IDLE_THRESHOLD_MS`, `MU_SEND_DELAY_MS`, …) can't silently
+  change behaviour underneath tests. Allowlist: `MU_TMUX_SOCKET`
+  (set by `_global-teardown.ts` at MODULE LOAD time — BEFORE vitest
+  spawns the worker pool — for Layer-3 isolation; see round-3
+  Part A in the file's header comment for why module-load not
+  setup()). Tests that need a specific value opt IN per-test via
+  `process.env.X = "..."` or `withEnv()` from `test/_env.ts`.
+- **Default-socket sweep philosophy**: `_global-teardown.ts` runs
+  an ALLOWLIST sweep of `mu-*` sessions on the user's default tmux
+  socket at suite setup AND teardown. The allowlist is DB-rooted:
+  (1) `mu-<name>` for every workstream in the user's REAL DB
+  (read-only via better-sqlite3, bypassing the `openDb()` test
+  guard) and (2) `mu-$MU_SESSION` if the orchestrator runs the suite
+  inside a tmux pane. Anything else is, by elimination, test residue
+  and is killed. No session is grandfathered by being present at
+  module load — that defeats the self-healing intent. Cost: an ad-hoc
+  `tmux new-session -t mu-foo` with no DB row gets killed; run
+  `mu workstream init foo` first. Tests can hardcode any workstream
+  name — if they accidentally bypass the private socket, the sweep
+  catches them.
+
+### When you change behaviour, update VOCABULARY first
+
+Vocabulary is canonical. If you introduce a new concept, name, or
+verb, **add it to docs/VOCABULARY.md before the code lands**. If you
+rename something, update VOCABULARY.md in the same commit.
+
+### Deferred features — don't smuggle them in
+
+[docs/ROADMAP.md](docs/ROADMAP.md) lists what's next, by version,
+with **promotion criteria**:
+
+> 1. A real user hits the missing feature in real workflows ≥2
+>    times.
+> 2. The current substrate makes the addition straightforward (no
+>    major pillar refactor).
+> 3. The addition fits in <300 LOC or has a clear smaller subset.
+
+If you find yourself adding something not on the roadmap and not
+meeting these criteria, **stop**. Add an entry to
+[docs/ROADMAP.md](docs/ROADMAP.md) (or open an issue) and move on.
+
+The "anti-feature pledges" in ROADMAP.md are firm:
+
+- No config file
+- No daemon / background process beyond what the multiplexer +
+  SQLite give us
+- No anticipatory abstractions (no traits with zero implementors)
+- No wrappers around wrappers
+- No codegen / embedded JS engine / workflow DSL
+- No template/discovery system for agent roles (spawn flags + first
+  message ARE the definition)
+- No render layer beyond `cli-table3` + `picocolors`, EXCEPT `ink`
+  confined to `src/cli/tui/`. NO second TUI stack alongside `ink`
+  (no `blessed` / `terminal-kit` etc.); if `ink` ever stops paying
+  off, REPLACE it, don't stack stacks.
+- No plugin runtime, web UI, RPC, chat/docs integrations, memory
+  system, workflow engine
+- Don't bundle pi (it's a peer dep)
+
+### When in doubt: be small
+
+Ship the smallest thing that works, then layer on as real friction
+proves itself.
+
+---
+
+## Common tasks
+
+### "Add a new CLI verb"
+
+1. Find or write the programmatic function in `src/agents.ts`,
+   `src/tasks.ts`, `src/workstream.ts`, etc. Test it with mocked
+   tmux. Return a typed result object (`{ changed: boolean,
+   previousStatus, ... }`) so callers can log lifecycle
+   transitions.
+2. Wire the verb in `src/cli.ts` using `commander`. Use
+   `handle(...)` so typed errors map to exit codes. If the verb
+   takes `--workstream`, use `command.optsWithGlobals()` (via
+   `this`) so the top-level option doesn't swallow it (commander
+   gotcha).
+3. Update [docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md) with the new
+   verb in the right section.
+4. Update [docs/VOCABULARY.md](docs/VOCABULARY.md) operations
+   table.
+5. Update [skills/mu/SKILL.md](skills/mu/SKILL.md) **only if the verb has a
+   gotcha `--help` cannot state.** The skill is not a verb list — see
+   § Skill files are context, not documentation, below.
+6. Update [CHANGELOG.md](CHANGELOG.md) under the upcoming version.
+7. If this verb promotes a `mu sql` workaround, remove the
+   workaround entry from the `docs/USAGE_GUIDE.md` gaps table.
+8. Smoke-test: `MU_SYNC_DIR= MU_DB_PATH=/tmp/mu-smoke.db node
+   dist/cli.js <verb> ...` to verify it works against real tmux. If
+   the verb touches the agent layer, smoke it on herdr too —
+   `MU_MUX=herdr` plus a private `MU_HERDR_SESSION` (never the default
+   session).
+
+   **Blank `MU_SYNC_DIR` as well as `MU_DB_PATH`.** Overriding the DB
+   alone does not contain a smoke test: sync is ambient, so the first
+   flush stamps the throwaway DB's fresh `machine_id` onto a segment
+   in your REAL sync folder. Nothing prunes it, and absence of a
+   segment is the only way a peer disappears, so `mu sync` then lists
+   a phantom machine forever. Eight of them accumulated in `~/mu`
+   before anyone noticed. `src/segments.ts` now refuses a non-temp
+   sync dir under vitest, but a hand-run `node dist/cli.js` is not
+   under vitest — blank the var yourself.
+
+### "Update the schema"
+
+1. Current schema version is **v10** (`CURRENT_SCHEMA_VERSION` in
+   `src/db.ts`): 10 tables + 3 views. The schema is the
+   `applySchema(db)` block — idempotent CREATE-IF-NOT-EXISTS plus
+   targeted `DROP TABLE IF EXISTS`. `openDb` REFUSES any pre-v10 DB
+   with `SchemaTooOldError` (exit 4); there is no in-process
+   migration ladder.
+2. Bump `CURRENT_SCHEMA_VERSION` in `src/db.ts` and mirror the new
+   shape in `CURRENT_SCHEMA`. Prefer script-free bumps: additive
+   CREATE-TABLE-IF-NOT-EXISTS, or an idempotent `DROP TABLE` block.
+   Reach for a one-shot migration script only when the change can't
+   be expressed that way. **If you add a table, classify it** in
+   `PORTABLE_TABLES` or `MACHINE_LOCAL_TABLES` —
+   `test/entities.test.ts` fails loudly otherwise.
+3. Update tests that exercise the schema (`test/db.test.ts`).
+4. Update [CHANGELOG.md](CHANGELOG.md) under the upcoming version's
+   `### Changed` section.
+
+### "Add a new multiplexer operation"
+
+mu drives **two** multiplexers, tmux and herdr, behind the
+`MuxBackend` interface in `src/mux/types.ts`. Call sites resolve one
+with `await activeMux()` and never name a backend.
+
+1. **Add the method to `MuxBackend`** with a doc comment saying what
+   it means, not how tmux does it.
+2. **Implement it in BOTH** `src/mux/tmux.ts` and `src/mux/herdr.ts`.
+   A backend with no equivalent no-ops (see
+   `enableMuPaneBorders*`, `selectLayout`) — it does not throw.
+3. **If only one backend can do it**, make it an OPTIONAL method
+   (`paneStatus?()`, `startAgentInPane?()`) and have the caller
+   branch on the CAPABILITY being present, never on `mux.name`.
+4. **Decide load-bearing vs best-effort.** Load-bearing calls (spawn,
+   send, kill) let `NoMultiplexerError` propagate to exit 5.
+   Best-effort calls (identity, decoration, orphan surfacing) wrap in
+   try/catch so a missing mux degrades instead of failing the verb —
+   `resolveWorkerIdentity` in `src/tasks/claim.ts` is the shape.
+
+All tmux invocations go through `src/mux/tmux.ts` `tmux(args)`; all
+herdr invocations through `src/mux/herdr.ts` `herdr(args)`. **No raw
+`execa("tmux", …)` / `execa("herdr", …)` anywhere else.** Each wrapper
+produces a typed error (`TmuxError` / `HerdrError`, both extending
+`MuxError`) and each has an executor seam the tests mock — use
+`installMux()` from `test/_mux.ts` rather than the raw setters.
+
+For send-style operations the two backends differ sharply, and that
+difference is the point: tmux needs the canonical bracketed-paste
+sequence in `sendToPane` (naive `tmux send-keys "<text>"` is broken —
+`/`, `?`, `f` get eaten by the agent's TUI), while herdr's
+`agent prompt` is one atomic call. Do not port the tmux workaround
+to herdr.
+
+### "Fix a flaky integration test"
+
+Integration tests against real tmux can be slow because tmux/sh
+processes need time to settle. Use:
+
+- Unique session names (`mu-test-<pid>-<ts>-<random>`) so parallel
+  runs never collide.
+- Polling loops (50ms × 10 attempts) when waiting for state to
+  propagate, not fixed sleeps.
+- `try { ... } catch {}` cleanup in `afterEach` for tmux session
+  kills and DB closes — a failure mid-test should never block the
+  next.
+- `setSleepForTests(async () => {})` in unit tests so the real
+  `MU_SEND_DELAY_MS` doesn't slow them.
+- `process.env.MU_SPAWN_LIVENESS_MS = "0"` in integration-test
+  `beforeEach` to skip the 1500ms post-spawn check (the unit-test
+  suite covers it).
+
+---
+
+## Skill files are context, not documentation
+
+`skills/mu/SKILL.md` and `skills/mu/REMOTE_WORKERS.md` are loaded into an
+orchestrator's context window, SKILL.md on every invocation, where every word
+competes with the user's actual work for attention. **Keep them ruthlessly
+terse.**
+
+Read the `writing-for-agents` skill before editing either one. Work its levers
+in this order:
+
+- **Cache test.** `mu <verb> --help` is a one-command lookup that cannot go
+  stale. A skill that restates it is a cache that rots. Verb lists, flag
+  enumerations and option tables belong in `--help`; the skill carries only
+  what `--help` cannot say — the gotcha, the reason, the trap.
+- **Single source of truth.** One meaning, one place. Scattered advice does not
+  get assembled by the reader: it gets missed. Prefer a consolidating edit that
+  deletes as much as it adds.
+- **Progressive disclosure.** SKILL.md gets the trigger and the rule.
+  REMOTE_WORKERS.md gets the detail. Anything only some branches need goes
+  behind the pointer, never in the always-loaded file.
+- **No-op hunt.** Delete any sentence the model already obeys by default. The
+  test is behavioural: does it change what an agent does?
+- **Positive instruction.** State the target behaviour. A prohibition drags the
+  banned shape into context and makes it more available, so name an
+  anti-pattern only where a reader needs to recognise their own instinct.
+
+Measure before and after. An edit that grows SKILL.md needs a reason in the
+commit message, and "the new verb needed documenting" is not one.
+
+Two failures already paid for this rule. A 910-word section titled "CLI
+overview (only gotchas; use `--help` for full syntax)" was half verb list, and
+a DO/DON'T section was the orchestrator loop written twice — 675 words removed
+with nothing lost. And a warning about wedging a host existed in the file while
+the agent that wedged the host never saw it, because it sat 350 lines from the
+section it applied to. **A skill that sprawls stops being read**, which makes
+sprawl a correctness problem, not a tidiness one.
+
+---
+
+## What NOT to do
+
+- **Don't pad the skill files.** They are context, not docs, and
+  `--help` is the verb list. See § Skill files are context, not
+  documentation.
+- **Don't add a config file.** mu is CLI flags + env vars.
+- **Don't add a daemon, watcher, or background process.** Every
+  invocation is short-lived.
+- **Don't add abstractions for hypothetical future flexibility.**
+  Two real impls today, or use a concrete type. (Cautionary tale: a
+  prior internal runtime's `RunContext` trait with zero implementors.)
+- **Don't grow stream wrappers around stream wrappers.**
+  (`TextStream` / `TextState` / `StreamResult`.)
+- **Don't generate JS strings as a "typed protocol."**
+- **Don't put state-snapshot/handle layering on top of SQLite.**
+  SQLite is the canonical state. Read it directly; don't introduce
+  a `MuStateHandle` facade.
+- **Don't add a template/discovery system for agent roles** until
+  pattern promotion criteria are met.
+- **Don't bundle pi.** It's a peer dep, optional.
+- **Don't write to files outside `~/.local/state/mu/` or the
+  project repo** without documenting why.
+- **Don't promote a roadmap item to "shipped"** unless its
+  promotion criteria in [docs/ROADMAP.md](docs/ROADMAP.md) are met.
+
+---
+
+## When you're done
+
+Before opening a PR or marking a task complete:
+
+```bash
+npm run typecheck && npm run lint && npm run test:fast && npm run test && npm run build
+```
+
+The acceptance test (`test/acceptance.integration.test.ts`) must
+pass — it's the "end-to-end works" gate.
+
+Checklist for any non-trivial change:
+
+- [ ] If you added a typed verb, the corresponding `mu sql`
+      workaround row was removed from `docs/USAGE_GUIDE.md`.
+- [ ] If you added vocabulary, `docs/VOCABULARY.md` has the new
+      entry.
+- [ ] If you changed an architectural seam,
+      `docs/ARCHITECTURE.md` is updated.
+- [ ] [CHANGELOG.md](CHANGELOG.md) has an entry under the upcoming
+      version.
+
+That's it. Be small, be typed, follow the conventions, ship clean
+green builds.