@martintrojer/mu 0.3.2 → 0.4.1

package/docs/ARCHITECTURE.md

@@ -53,7 +53,8 @@ just a fancier agent runner.
   `ROI = impact / effort` drives prioritization.
 - **One edge type**: `blocks`. `A → B` means A must close before B can
   start. Multiple edge types create ambiguity that defeats the purpose.
-- **Status lifecycle**: `OPEN → IN_PROGRESS → CLOSED/RESOLVED`.
+- **Status lifecycle**: `OPEN → IN_PROGRESS → CLOSED`, with
+  `REJECTED` and `DEFERRED` as terminal still-blocking outcomes.
 - **Notes** are append-only per task; survive across LLM sessions and
   agent restarts. The fix for context loss at the *task* level rather
   than the agent level.
@@ -71,8 +72,9 @@ separate query layer.
 
 ### Parallel-track detection (the killer feature)
 
-`mu task tracks` runs union-find on the graph to identify independent
-subtrees that can be assigned to different agents in parallel.
+The Tracks section in `mu state` / bare `mu` runs union-find on the
+graph to identify independent subtrees that can be assigned to
+different agents in parallel.
 
 **Diamond patterns get merged automatically.** If two roots share a
 prerequisite, they collapse into one track — preventing two agents
@@ -110,9 +112,10 @@ config identity: the agent doesn't have to know its own name.
 
 ### Scoped subtree views
 
-`mu task <id>` shows mission-control output filtered to that task's
-subtree. Enables recursive delegation: a sub-orchestrator agent runs
-`mu --scope feature_a` and sees only its slice of the graph.
+`mu task tree <id>` and task queries show the portion of the graph
+reachable from a task. This enables recursive delegation: a
+sub-orchestrator agent can inspect only its slice of the graph without
+asking an LLM to infer the scope.
 
 ### Why this is in the core
 
@@ -160,12 +163,15 @@ independent tmux sessions, fully isolated.
   `MU_SESSION=<name>`.
 - **Subsequent operations** in the same shell (or any child shell with
   `MU_SESSION_ID` set) target the same session.
-- **`mu agent attach`** → attach to the whole workstream's tmux session
-- **`mu agent attach <agent>`** → attach and focus that agent's window/pane
+- **`tmux attach -t mu-<workstream>`** → attach to the whole
+  workstream's tmux session
+- **`mu agent attach <agent>`** → print the agent's scrollback plus
+  the one-paste tmux attach command for that pane
 - **`mu agent list`** shows only the current workstream's agents by default
-- **`mu agent list --all`** shows agents across all workstreams on the box
-- **`session_id`** is the partition key on the `agents` table; queries
-  filter to the active session unless `--all` is set
+- **`mu agent list`** is scoped to one workstream; list workstreams first,
+  then run `mu agent list -w <workstream>` for the scope you want
+- **`session_id`** is the partition key on the `agents` table; agent-list
+  queries filter to the active workstream
 - **`mu doctor`** warns about cross-session pollution (orphan panes,
   ghost rows, agents whose tmux session no longer exists)
 
@@ -200,34 +206,244 @@ tmux protocol.)
 
 ---
 
-## Operations registry
+## Dual-audience CLI contract
+
+The top-level `mu` binary serves two audiences without creating a
+second namespace.
+
+- **Human entrypoint:** bare `mu` launches the read-only TUI when
+  `process.stdout.isTTY === true`. It loads every workstream on the
+  machine and chooses the initial active tab with the shared focus
+  ladder (`$MU_SESSION` → tmux session name → cwd inside a workspace
+  → cwd equal to a workspace's VCS-derived project root, with latest
+  activity breaking project-root ties → tab 0). If no
+  workstreams exist, it prints `mu --help` plus the one-paste
+  `Get started: mu workstream init <name>` hint and exits 0.
+- **Agent / script entrypoint:** typed verbs remain the API, with
+  `--json` on reads and structured errors. Bare `mu` on non-TTY
+  stdout (pipes, redirects, CI, most harnessed agent calls) prints
+  help instead of entering Ink. `MU_NO_TUI=1` forces that same path
+  for scripted use inside an otherwise-interactive terminal.
+- **Back-compat:** `mu state` remains the static state card, and
+  `mu state --tui` remains an explicit TUI selector. The split is
+  stdout-is-TTY plus the opt-out env var, not a separate
+  human-vs-agent command namespace.
+
+The TUI import stays dynamic (`await import("./cli/tui/index.js")` or
+the sibling state-module equivalent). No module outside
+`src/cli/tui/` may statically import ink/react; this prevents the
+static CLI bundle from pulling the TUI graph into help/version/json
+paths and preserves the ROADMAP render-layer pledge.
 
-Every mu action is defined exactly once via `defineOperation(...)`.
-The registry is collected at module import time (no codegen step) and
-from one source produces six surfaces:
+---
+
+## TUI architecture
+
+The TUI is a 10-card live-updating dashboard built on `ink` (React
+for the terminal). It is mu's flagship human surface, but it is
+**read-only** and lives entirely under `src/cli/tui/` — the static
+CLI verbs remain the canonical mutation API. The TUI yanks `mu`
+commands; the operator runs them.
+
+### Cluster shape
+
+`src/cli/tui/` is the only place ink/react are imported. The cluster
+role-by-role:
 
 ```
-              ┌─────────────────────────────┐
-              │  defineOperation(...)  │
-              │   name, category,      │
-              │   caps[], params,      │
-              │   handler              │
-              └─────────────┬──────────────┘
-                            │
-          ┌────────────┬──────┼──────┬───────────┐
-          ▼            ▼            ▼            ▼           ▼
-   ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌───────┐  ┌────────┐
-   │ CLI verb│  │ Pi tool │  │ mu.d.ts │  │ skill │  │ doctor │
-   └─────────┘  └─────────┘  └─────────┘  └───────┘  └────────┘
+src/cli/tui/
+├── index.ts                    # runTui entrypoint; alt-screen + mouse-mode lifecycle
+├── escapes.ts                  # pure ANSI byte sequences (alt-screen, SGR mouse mode)
+├── app.tsx                     # <App> root: popup state machine, global keymap, tabs
+├── state.ts                    # useDashboardSnapshot poll-loop hook (fast/slow tier split)
+├── keys.ts                     # pure dispatchGlobalKey + dispatchPopupKey + shouldSwallowGlobalKey
+├── keymap-spec.ts              # canonical keymap source-of-truth (drives help overlay + dispatch)
+├── mouse.ts                    # vendored SGR mouse parser + double-click + useMouse hook
+├── yank.ts                    # clipboard probe + write (pbcopy/wl-copy/xclip/xsel/clip.exe + OSC-52)
+├── tuicr.ts                    # `t` shortcut: alt-screen handoff to tuicr -r <sha>
+├── 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
+├── glyphs.ts                   # superscript digit + status glyphs
+├── format-helpers.ts           # shared TUI formatters (relTime, sinceClaim, ROI)
+├── titled-box.tsx              # rounded border with section-header / bottomLabel inset
+├── popup-shell.tsx             # popup outer chrome (cyan TitledBox)
+├── list-row.tsx                # centralised non-selected row primitive
+├── padded-rows.tsx             # per-card body padder
+├── 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
+├── help.tsx                    # ?/F1 keymap overlay (scrollable on short panes)
+├── use-popup-filter.tsx        # shared '/' substring filter hook + applyFilter + FilterPrompt
+├── use-status-filter.tsx       # task-status toggles (o/i/c/r/d) for task-list popups
+├── 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
+├── cards/                      # 10 dashboard glance cards (one slot each)
+│   ├── _placeholder.tsx        # shared loading/empty body wrapper
+│   └── {agents,tracks,ready,log,workspaces,inprogress,blocked,recent,commits,doctor}.tsx
+└── popups/                     # fullscreen drill-down popups
+    ├── {agents,tracks,ready,log,workspaces,inprogress,blocked,recent,commits,doctor}.tsx
+    ├── dag.tsx                 # keybind-only on `g`: full task DAG forest
+    ├── all-tasks.tsx           # keybind-only on `t`: sortable / filterable list of every task
+    ├── drill.tsx               # DrillScrollView + useDrillKeymap (shared scrollable-text leaf)
+    ├── task-detail.tsx         # TaskDetailDrill (notes timeline; the recursion sink)
+    ├── cursor-row.tsx          # selected-row primitive (delegated to from list-row)
+    ├── scroll.ts               # pure applyCursor / applyScroll / clampScrollTop / isNavAction
+    ├── viewport.ts             # popupViewport + POPUP_CHROME_ROWS + POPUP_VIEWPORT_FLOOR
+    └── show-loader.ts          # subprocess-preserving show loader (avoids blank-flash mid-refetch)
 ```
 
-No operation may exist outside the registry. CLI verbs that are not
-operations (e.g., `mu workstream init`, `mu agent attach`, `mu doctor`) are exceptions
-listed explicitly in the CLI module and motivated.
+### State machine
+
+`<App>` is the root. It owns:
+
+- **Popup state** — `null` (dashboard) or one of the popup ids.
+  Single-popup invariant; `Esc` / `q` returns to dashboard.
+- **Card visibility** — `Record<CardId, boolean>` toggled by `0`-`9`.
+- **Tick rate** — fast tick interval (1s default; adjustable with
+  `+` / `-` / `=` / `0`).
+- **Active workstream tab** — index into the resolved workstream
+  set; `Tab` / `Shift-Tab` cycles when N≥2.
+- **Footer flash** — transient status-bar message (yank confirm,
+  tuicr exit, etc.).
+
+Popups own their own local state (cursor, filter query, drill mode,
+local modes like Workspaces' `list` / `commits` / `show`). Popups
+NEVER mutate App-level state — they receive a read-only props bag
+(`snapshot`, `db`, `workstream`, `fastTickNonce`, `slowTickNonce`,
+`yank`, `onClose`, `onModeChange`, `onFilterEditingChange`,
+`onFooter`).
+
+### Polling tiers (fast vs slow)
+
+The poll loop in `state.ts` (`useDashboardSnapshot`) splits work
+into two intervals:
+
+- **Fast tick** (default 1s, adjustable): SQL-only. `loadWorkstreamSnapshotFast`
+  reads tasks, tracks, workspace registry rows, recent events,
+  workspace orphans. Cheap (~p50 <1ms).
+- **Slow tick** (10s, hardcoded `SLOW_TICK_MS`): subprocess-backed.
+  `loadWorkstreamSnapshotSlow` runs tmux liveness, per-workspace
+  dirty status, recent project commits, and the Doctor summary.
+  Expensive (~p50 hundreds of ms).
+
+The last slow result is merged into every fast render via
+`mergeSnapshotFastSlow` so cards never flicker through a loading
+state. `r` / `F5` triggers both intervals immediately. Workstream
+tab switch clears the slow cache and eager-fetches the new
+workstream so cards are fresh within 1s of switching.
+
+A pure `snapshotKey` / `snapshotKeyString` re-render guard returns
+the SAME `data` reference across no-op ticks so React's diffing
+short-circuits cleanly.
+
+### Render geometry
+
+Responsive layout lives in `layout.ts`:
+
+- **Breakpoint-driven columns**: stacked below 120 cols; 2 columns
+  at 120; 3 at 180; 4 at 240. Stream cards (Commits, Activity log)
+  trail; slot 0 (Commits) trails last.
+- **Per-card row budgets**: each visible card gets a `min` /
+  `max` / `chrome` budget; the allocator distributes available
+  rows so a noisy list can't crowd siblings. Overflow surfaces as
+  `+N more · Shift+N` inset into the card's bottom border.
+- **Cull-on-tight-pane**: when even minimum budgets don't fit,
+  cull cards by priority (Doctor → Recent → Workspaces → …) and
+  show `+N cards hidden · resize taller` at the bottom. Outer
+  height clip is the safety net.
+
+Text rendering is ANSI-aware: `wrap-ansi.ts` wraps by visual width
+(via `string-width`) and closes any open SGR state on the early-
+return + end-of-loop paths so coloured fragments without trailing
+`\x1b[0m` can't bleed into adjacent ink chrome cells. Drill bodies
+are also space-padded to exact box width so ink's `wrap="truncate"`
+ANSI miscount can't eat the trailing right-border glyph.
+
+### Read-only invariant + the `tuicr` escape
+
+Every popup row exposes one canonical `mu` command via `y`. `yank.ts`
+probes for a clipboard backend (pbcopy / wl-copy / xclip / xsel /
+clip.exe) and falls back to OSC-52 over stderr if none is found.
+The command goes to the clipboard; the operator runs it.
+
+The one user-driven escape is `t` inside any `git show` drill:
+`tuicr.ts` writes `ALT_SCREEN_EXIT` + the SGR mouse-mode disable
+bytes, exec's `tuicr -r <sha>` in the project root / workspace cwd
+as a foreground subprocess, then on exit writes `ALT_SCREEN_ENTER`
++ mouse-mode-enable and the dashboard re-renders. This is a
+deliberate handoff, not an in-process mutation.
+
+The read-only pledge is in `docs/ROADMAP.md`'s anti-feature list;
+any future TUI gesture that wants to mutate state must file a
+roadmap entry first.
+
+### Mouse + keyboard
+
+Mouse support is opt-in via SGR mouse mode (`escapes.ts` provides
+the enable/disable bytes). `mouse.ts` parses `ESC[<button;x;y;M/m`
+from stdin, detects double-clicks, and exposes a `useMouse()` hook.
+
+Keyboard dispatch flows through pure helpers in `keys.ts`:
+`dispatchGlobalKey` (dashboard mode), `dispatchPopupKey` (popup
+mode), and `shouldSwallowGlobalKey` (which keys popups consume
+and do not bubble to the global dispatcher). The keymap source-of-
+truth lives in `keymap-spec.ts` so the help overlay and the
+dispatcher can never drift apart.
+
+Double-click on a card emits `{kind: "setCursor", index}` followed
+by `{kind: "drill"}` through `use-popup-action-queue.ts`, which
+consumes one action per render (so the cursor update lands before
+the drill resolves the focused row).
+
+### Drill recursion
+
+List popups drill via `Enter` into entity-specific leaves. The
+central primitive is `popups/drill.tsx`'s `DrillScrollView` (a
+scrollable text leaf shared by Workspaces' git-show, Agents'
+scrollback, the Activity log payload drill, and the Doctor
+remediation drill). Task popups drill into
+`popups/task-detail.tsx`'s `TaskDetailDrill` (the notes timeline);
+the Tracks popup chains track → task list → TaskDetailDrill via
+the same leaf.
+
+`useDrillKeymap` owns the scroll state, accepts an optional
+`resetKey` (so identity-change resets scroll while tick-driven body
+refreshes preserve it), an optional `onScrollChange` callback (so
+the DAG popup's focused-root tracking stays in lockstep), and
+shares ANSI-aware wrapped body metadata so the scroll-clamp math
+and the painter can't desync.
+
+Subprocess-backed drills (Workspaces git-show, Agents scrollback,
+Commits show) use `popups/show-loader.ts` which preserves the
+prior body during a refetch — no blank-flash flicker on the slow
+tick.
+
+### Test seam
+
+TUI behaviour testing is documented in `test/README.md`. The
+seam is `test/_ink-render.ts`'s `createInkInputStream` +
+`createInkCaptureStream` + `simulateInput` + `latestRenderedFrame`.
+Mount a popup or `<App>` into a CaptureStream, drive keystrokes,
+assert against the visible frame and spy callbacks. Source-greps
+are reserved for narrow structural guards (App ↔ keys ↔ layout
+wiring; slot ↔ keymap glue) — not for behaviour.
+
+---
+
+## CLI / SDK surface
+
+Every user-visible operation is a typed SDK function plus a thin
+Commander wrapper. The CLI wiring in `src/cli.ts` and the verb
+namespace files under `src/cli/` are the canonical verb surface;
+there is no generated registry layer, DSL, or separate operation
+schema. Programmatic callers import the same SDK functions from
+`src/index.ts`, while agents/scripts compose CLI verbs with `--json`.
 
-(A capability-tag system on operations was considered and dropped
-as an abstraction with no current consumer; see
-[ROADMAP.md § Open questions](ROADMAP.md#open-questions).)
+The boundary rule is: external surfaces accept operator-facing names
+(`workstream`, task id, agent name); internal helpers resolve those to
+surrogate INTEGER ids once and then stay on ids. See
+[§ Surrogate-PK + SDK-boundary discipline](#surrogate-pk--sdk-boundary-discipline-load-bearing).
 
 ---
 
@@ -268,35 +484,48 @@ Key properties:
 
 ## Modules (actual src/ layout)
 
-Mostly-flat `src/`: 18 root `.ts` files plus two cohesive
-subclusters (`src/agents/`, `src/tasks/`) and the `src/cli/` verb
-wrappers (with their own `src/cli/tasks/` sub-cluster). No
-`core/` subdirectory; no anticipatory layering. Subclusters obey
-the AGENTS.md rule: imports flow cluster → root, never upward.
+Mostly-flat `src/`: root `.ts` modules plus cohesive subclusters
+(`src/agents/`, `src/tasks/`, and `src/cli/` wrappers with their own
+`src/cli/tasks/` and `src/cli/tui/` sub-clusters). No `core/`
+subdirectory; no anticipatory layering. Subclusters obey the
+AGENTS.md rule: cluster files import from neighbours and root
+substrate modules, never from the hub they're re-exported through.
 Each module is concrete and consumed today.
 
 | Module                | Responsibility                                                                            |
 | --------------------- | ----------------------------------------------------------------------------------------- |
-| `src/db.ts`           | SQLite (better-sqlite3) connection, WAL mode, schema (14 tables + 3 views, **schema v7** — v5 surrogate-INTEGER-PK substrate, plus v6's 5 additive `archive_*` tables, minus v7's drop of `approvals`), default paths, `resolveWorkstreamId` (the SDK boundary's first leg). Pre-current DBs are upgraded in place on `openDb`: v5 → v6 was additive (CREATE-TABLE-IF-NOT-EXISTS), v6 → v7 is destructive-but-idempotent (`DROP TABLE IF EXISTS approvals` runs before `applySchema`); both happen with no migration script. |
+| `src/db.ts`           | SQLite (better-sqlite3) connection, WAL mode, schema (16 tables + 3 views, **schema v8** — v5 surrogate-INTEGER-PK substrate, v6's 5 additive `archive_*` tables, v7's drop of `approvals`, v8's additive `machine_identity` + `workstream_sync` sync substrate), default paths, `resolveWorkstreamId` (the SDK boundary's first leg). `openDb` refuses pre-v5 DBs loudly; v5+ DBs are brought to the current idempotent schema shape by `applySchema` (including v7's `DROP TABLE IF EXISTS approvals`) and `openDb` seeds `machine_identity` on open. |
 | `src/tmux.ts`         | Single tmux executor wrapper, send protocol (bracketed-paste), pane validation            |
 | `src/detect.ts`       | Pi-only status detector (`busy` / `needs_input` / `idle` / `done`)                        |
 | `src/reconcile.ts`    | Ghost prune + status detect + orphan surface; "reality wins"                              |
 | `src/agents.ts`       | Hub: CRUD + send / read / list / close / free + liveness + reaper. Re-exports `src/agents/*` (spawn, adopt, errors); pane-title composition (`composeAgentTitle`) lives here. |
 | `src/agents/*.ts`     | Cohesive cluster of agent-lifecycle internals: `spawn.ts` (spawnAgent + resolveCliCommand / awaitSpawnLiveness / pane create-or-reuse / prestage / rollback), `adopt.ts` (register an existing tmux pane as a managed agent), `kick.ts` (signal the foreground pgid of an agent pane's TTY — escape hatch for wedged tool subprocesses), `errors.ts` (typed agent error classes — `AgentNotFoundError`, `AgentDiedOnSpawnError`, …). |
-| `src/tasks.ts`        | Hub: every read/write verb on the DAG (edit / edges / queries) + cycle check + auto-event emission. Re-exports `src/tasks/*` (status, claim, lifecycle, wait, errors). |
-| `src/tasks/*.ts`      | Cohesive cluster of task-graph internals: `status.ts` (TaskStatus enum + helpers — single source of truth), `claim.ts` (claim/release + `resolveActorIdentity`, atomic CAS), `lifecycle.ts` (setTaskStatus / closeTask / openTask / rejectTask / deferTask + cascade), `wait.ts` (waitForTasks: block until tasks reach a target status), `errors.ts` (typed task error classes — `TaskAlreadyOwnedError`, `CycleError`, …). |
+| `src/dag.ts`          | Shared DAG read/render helpers: `loadFullDag(db, workstream)` for whole-workstream root+edge forests and pure `renderForest` / `renderTaskTree` ASCII rendering reused by `mu task tree` and the TUI DAG popup. |
+| `src/tasks.ts`        | Task SDK hub: re-exports the concrete task-graph cluster so external imports keep using `./tasks.js`; no implementation logic. |
+| `src/tasks/*.ts`      | Cohesive cluster of task-graph internals: `core.ts` (row-shape mapping, surrogate-id resolution, `touchTask`), `id.ts` (task-id validation + title slug helpers), `queries.ts` (get/list/ready/blocked/goals/notes/owned/search reads), `edit.ts` (add task/note, update, delete), `edges.ts` (edge reads, cycle check, block/unblock/reparent), `status.ts` (TaskStatus enum + helpers — single source of truth), `sort.ts` (shared task sort keys/comparators for CLI + TUI), `claim.ts` (claim/release + `resolveActorIdentity`, atomic CAS), `lifecycle.ts` (setTaskStatus / closeTask / openTask / rejectTask / deferTask + cascade), `wait.ts` (waitForTasks: block until tasks reach a target status), `errors.ts` (typed task error classes — `TaskAlreadyOwnedError`, `CycleError`, …). Cluster files import neighbours/root substrate modules directly, never the `src/tasks.ts` hub. |
 | `src/tracks.ts`       | Parallel-tracks union-find with diamond merge                                             |
+| `src/staleness.ts`    | Shared workspace staleness threshold (`WORKSPACE_STALE_THRESHOLD = 10`) and pure `isWorkspaceStale` predicate consumed by static state, the TUI Workspaces card, and dispatch-time warn/refuse checks. |
 | `src/workstream.ts`   | ensureWorkstream / list / summarize / destroy / export (thin wrapper around the bucket renderer) |
-| `src/exporting.ts`    | Unified bucket renderer for `mu workstream export` and `mu archive export`: per-task markdown + manifest.json (`bucketVersion: 2`); idempotent via per-file sha256; deleted-task preservation banner; refuses pre-0.3 single-source layouts |
-| `src/importing.ts`    | Inverse of `src/exporting.ts`: parses a v0.3 bucket directory and rebuilds every source-ws as live tasks + edges + notes. Markdown-only (never reads .db); per-source-ws transactional; refuses silent merges into existing workstreams |
-| `src/archives.ts`     | Cross-workstream **archives** — feature complete (SDK + 6 CLI verbs: `mu archive create / list / show / add / remove / delete`, plus `search` and `export` via the unified bucket renderer): `createArchive` / `listArchives` / `getArchive` / `deleteArchive` / `addToArchive` (idempotent at `(archive, source_workstream)`) / `removeFromArchive` / `listArchivedTasks`. Backed by the v6 `archives` + `archived_tasks` + `archived_edges` + `archived_notes` + `archived_events` tables; archives outlive workstreams (TEXT `source_workstream` columns, no FK). |
+| `src/exporting.ts`    | Unified bucket renderer for `mu workstream export` and `mu archive export`: per-task markdown + manifest.json (`bucketVersion: 2`); idempotent via per-file sha256; deleted-task preservation banner; refuses pre-0.3 single-source layouts. Buckets are read-only artifacts for humans / git / docs, not a DB round-trip substrate. |
+| `src/db-sync.ts`      | Whole-machine DB sync SDK: `exportDb` (`VACUUM INTO` + manifest), `importDb` (per-workstream drift plan over `machine_identity` + `workstream_sync`; dry-run by default; `--force-source` parks divergence sidecars), manifest/schema validation, workstream copy/replace helpers, typed db-sync errors. |
+| `src/db-sync-replay.ts` | Manual replay planner/applier for divergence sidecars parked by `mu db import --force-source`: selects missing tasks/notes/eligible edges, refuses `local_id` collisions with diverged content, dry-run by default. Re-exported by `src/db-sync.ts` for SDK callers. |
+| `src/archives.ts`     | Archive SDK hub: re-exports the concrete `src/archives/` cluster, including restore, so external imports keep using `./archives.js`; no implementation logic. |
+| `src/archives/*.ts`   | Cohesive cluster for cross-workstream **archives** — feature complete (SDK + CLI verbs: `mu archive create / list / show / add / restore / remove / delete`, plus `search` and read-only `export` via the unified bucket renderer): `core.ts` (label validation, row types, typed archive errors, id resolution/summarise helpers), `query.ts` (`createArchive`, `listArchives`, `getArchive`, `listArchivedTasks`, `searchArchives`), `addremove.ts` (`addToArchive` idempotent at `(archive, source_workstream)`, `removeFromArchive`), `restore.ts` (`restoreArchive` lossless un-archive into a fresh workstream), `delete.ts` (`deleteArchive`). Backed by the v6 `archives` + `archived_tasks` + `archived_edges` + `archived_notes` + `archived_events` tables; archives outlive workstreams (TEXT `source_workstream` columns, no FK). Cluster files import neighbours/root substrate modules directly, never the `src/archives.ts` hub. |
+| `src/archives/restore.ts` | Lossless un-archive implementation: validates `--source` when an archive has multiple source workstreams, refuses `--as` collisions through workstream creation, snapshots before writing, copies archived tasks/edges/notes directly from `archived_*` rows, and emits an archive-restore event. Does not restore agents, workspace paths, or the live `agent_logs` stream. |
 | `src/logs.ts`         | `agent_logs` SDK: appendLog / listLogs / latestSeq / emitEvent                            |
-| `src/vcs.ts`          | `VcsBackend` interface + jj / sl / git / none impls; detection precedence; `commitsBehind(workspacePath, ref)` for staleness signal (no auto-fetch; pure observation); `isClean(workspacePath)` cheap working-copy probe used by `closeAgent`'s clean-workspace auto-free path |
-| `src/workspace.ts`    | Per-agent VCS workspaces (registry layer on top of vcs.ts); CRUD + cascade; orphan-dir detection (`listWorkspaceOrphans`); staleness decoration (`decorateWithStaleness` populates `commitsBehindMain` per row) |
-| `src/snapshots.ts`    | Whole-DB snapshots (`VACUUM INTO`); auto-captured before destructive verbs; SDK for `mu undo`. The `snapshots` table is schema v4 (carried forward unchanged through v5/v6/v7). |
+| `src/vcs.ts`          | VCS SDK hub: re-exports the concrete `src/vcs/` cluster so external imports keep using `./vcs.js`; no implementation logic. |
+| `src/vcs/*.ts`        | Cohesive cluster of VCS backends: `types.ts` (`VcsBackend` interface, result shapes, typed workspace errors, show-output cap), `helpers.ts` (exec/probe/run/show/commit-summary parsing helpers), `git.ts`, `jj.ts`, `sl.ts`, and `none.ts` (one concrete backend per file), `index.ts` (detection precedence dispatcher: `jj root` → `sl root` → `git rev-parse --show-toplevel` → none; `backendByName`). Backend methods cover `commitsBehind(workspacePath, ref)` for staleness (no auto-fetch; pure observation), `recentCommits(projectRoot, limit)` + `showCommit(projectRoot, sha)` for the TUI Commits card/popup, and `isClean(workspacePath)` for `closeAgent`'s clean-workspace auto-free path. Cluster files import neighbours/root substrate modules directly, never the `src/vcs.ts` hub. |
+| `src/workspace.ts`    | Workspace SDK hub: re-exports the concrete `src/workspace/` cluster so external imports keep using `./workspace.js`; no implementation logic. |
+| `src/workspace/*.ts`  | Cohesive cluster for per-agent VCS workspaces (registry layer on top of `vcs.ts`): `core.ts` (row shapes, path helpers, typed workspace errors), `crud.ts` (create/get/list/free/refresh/commits/clean checks), `decorate.ts` (staleness + dirty decoration), `orphans.ts` (per-workstream and all-workstream orphan-dir detection), `recreate.ts` (free+create between-wave verb). Cluster files import neighbours/root substrate modules directly, never the `src/workspace.ts` hub. |
+| `src/snapshots.ts`    | Snapshot SDK hub: re-exports the concrete `src/snapshots/` cluster so external imports keep using `./snapshots.js`; no implementation logic. |
+| `src/snapshots/*.ts`  | Cohesive cluster for whole-DB snapshots (`VACUUM INTO`): `core.ts` (row shapes, typed snapshot/prune errors, GC env readers, paths, size/version helpers), `capture.ts` (capture/list/auto-GC), `restore.ts` (`mu undo` restore file-swap), `prune.ts` (manual prune/delete cleanup verbs). The `snapshots` table is schema v4 (carried forward unchanged through v5/v6/v7/v8). Cluster files import neighbours/root substrate modules directly, never the `src/snapshots.ts` hub. |
 | `src/output.ts`       | NextStep type + `printNextSteps` + `errorNextSteps` plumbing for self-documenting output |
+| `src/state.ts`        | SDK seam for the `mu state` verb. `loadWorkstreamSnapshotFast(db, ws, opts?)` is the pure-SQL tier used by the TUI's 1s fast tick (tracks, task slices, workspace registry rows, workspace orphans, recent events; subprocess fields empty). `loadWorkstreamSnapshotSlow(db, ws, opts?)` is the subprocess tier (tmux-derived `view`, workspace dirty flags, recent project commits/backend, Doctor summary). `mergeSnapshotFastSlow` overlays the last slow result onto each fast result, and `loadWorkstreamSnapshot(db, ws, opts?)` stays as a back-compat wrapper that composes both tiers for static/non-TUI callers. Opt-in flags: `withDirty` (slow-tier dirty flag), `withDoctor` (Doctor summary), `withRecentCommits` (Commits card/popup), `withAllTasks` (legacy/full-snapshot all-task list; the TUI all-tasks popup can read SQLite directly while open). Plus pure derivation helpers: `agentStatusHistogram(agents)`, `summarizeOwnedTasks(owned)`, `roiBucket(impact, effortDays)`. |
+| `src/doctor-summary.ts` | TUI-friendly slice of `mu doctor`'s checks. `loadDoctorSummary(db, snapshot)` returns a `DoctorSummary` (`{ checks: DoctorCheck[], problemCount }`) using only synchronous DB pragmas + COUNT-shape SELECTs and snapshot-derived counts (ghosts / orphan panes / orphan workspace dirs) — cheap enough for the per-tick poll-loop the TUI's slot-9 Doctor card runs on. `loadDoctorChecks(db, snapshot)` is a thin wrapper that returns the full check array (OK + warn + fail) for the slot-9 Doctor popup, which renders every row rather than just the non-OK subset. Also home to the per-check remediation helpers `yankCommandForCheck(check)` (informational SELECT-shape verb to yank for the focused row, with a `# ...` comment fallback for schema-shape checks) and `remediationParagraph(check)` (multi-line prose explaining the failure shape) — both pure, both re-exported from `src/index.ts`, both consumed by the slot-9 popup's drill view but living next to `DoctorCheck` so adding a new check is a single touchpoint. The textual `mu doctor` verb (`src/cli/doctor.ts`) keeps its own renderer; this is the data seam consumed by the dashboard. |
 | `src/cli.ts`          | commander entry; `buildProgram()` (re-exports `format`/`handle` symbols for back-compat with existing import sites). |
-| `src/cli/*.ts`        | one file per verb-namespace; thin wrappers over the SDK; `--json` rendering for every read verb. Currently: `workstream.ts`, `agents.ts`, `tasks.ts`, `workspace.ts`, `log.ts`, `archive.ts`, `state.ts` (canonical state card + bare `mu` mission-control / hud render mode), `snapshot.ts`, `sql.ts`, `doctor.ts`. Two non-verb cluster-mates carry the rendering + error-handling primitives that every verb wrapper imports: `format.ts` (table renderers, status colourers, `truncate`/`relTime`) and `handle.ts` (typed-error → exit-code map + the `handle()` wrapper). Imports flow cluster → root (never the other way). |
+| `src/cli/db.ts`       | Thin commander/renderer for `mu db export / import / replay`: summary tables, dry-run vs apply Next steps, `--only-ws` repeated-or-comma parsing, and JSON envelopes over the `src/db-sync.ts` SDK. |
+| `src/cli/*.ts`        | one file per verb-namespace; thin wrappers over the SDK; `--json` rendering for every read verb. Currently: `workstream.ts`, `agents.ts`, `tasks.ts`, `workspace.ts`, `log.ts`, `archive.ts`, `db.ts` (whole-machine sync), `state.ts` (canonical static state card + explicit `--tui` back-compat dispatch; bare `mu` TTY routing lives in `src/cli.ts` so it can inspect the root argv/TTY seam), `tui-launch-focus.ts` (pure shared initial-tab focus ladder for bare `mu` and `mu state --tui`: `$MU_SESSION`, tmux session, cwd inside workspace, cwd at VCS-derived project root with latest-activity tie-break, tab 0), `snapshot.ts`, `sql.ts`, `doctor.ts`. Two non-verb cluster-mates carry the rendering + error-handling primitives that every verb wrapper imports: `format.ts` (table renderers, status colourers, `truncate`/`relTime`) and `handle.ts` (typed-error → exit-code map + the `handle()` wrapper). Imports flow cluster → root (never the other way). |
+| `src/cli/tui/*.tsx`   | Cohesive cluster of the interactive ink-based TUI (`mu state --tui`). Lazy-imported by `src/cli/state.ts` so non-TUI verbs avoid the ink/react cost. Per-file: `index.ts` (runTui entrypoint; writes the alt-screen enter/exit sequences from `escapes.ts` around the ink render and enables/disables mouse mode in the same finally-guarded lifecycle), `escapes.ts` (pure ANSI escape constants `ALT_SCREEN_ENTER`/`ALT_SCREEN_EXIT` plus SGR mouse-mode enter/exit bytes — no ink/react imports so unit tests can assert exact bytes without booting a renderer), `mouse.ts` (tiny vendored SGR mouse layer: enable/disable helpers, stdin parser for `ESC[<button;x;y;M/m`, double-click detector, and `useMouse()` hook), `app.tsx` (root `<App>` with popup state machine + global keymap dispatch + footer + tick state + active-workstream-tab state per feat_tui_multi_workstream), `state.ts` (poll-loop hook `useDashboardSnapshot` split into a fast SQL-only interval controlled by `tickMs` and a hardcoded `SLOW_TICK_MS = 10_000` subprocess interval; cached slow fields are merged into every fast render, `r`/F5 triggers both intervals immediately, and workstream switches clear the slow cache then eager-fetch the new workstream; plus pure `snapshotKey`/`snapshotKeyString` re-render guard so the hook returns the SAME `data` reference across no-op ticks; `lastTickMs` lives in its own useState so its tick-rate display can update without dragging the cards along; plus `clampTick`/`fasterTick`/`slowerTick` constants), `keys.ts` (pure `dispatchGlobalKey` + `dispatchPopupKey` keymap dispatchers), `yank.ts` (clipboard probe + write: pbcopy/wl-copy/xclip/xsel/clip.exe + OSC-52 fallback), `list-row.tsx` (`<ListRow>` — the centralised non-selected row primitive every popup/card consumes per feat_centralize_list_row_render; owns four invariants in one place: outer `<Box width={contentWidth}>` pin, canonical `COL_GUTTER`-spaced cells, `wrap="truncate"` on the outer `<Text>`, and selected→`<CursorRow>` delegation. Per-cell colours pass in declaratively as a `colors` array sibling of `COLUMN_SPECS`. Replaces 18 near-identical hand-rolled row JSX blocks across `popups/*.tsx`+`cards/*.tsx`; the test/tui-card-render-width.test.ts invariant is now "every renderRow consumer routes through ListRow OR CursorRow" — enforced by static-source assertions so a future popup author can't drift the gutter, forget the width pin, or skip wrap=truncate), `titled-box.tsx` (rounded-border primitive with section header inset into the top border; optional `bottomLabel` prop insets a `+M more · Shift+N` truncation hint into the BOTTOM border line per feat_card_footer_inset, suppressing the inner Box's bottom edge — the geometry is shared with the top-border path via the pure `computeBorderRowDashes` helper), `layout.ts` (pure responsive-dashboard helpers: breakpoint-driven pair-aware card columns plus per-card row-budget allocation with min/max/chrome config; columns use slot-stable ordering, slot 0 trails, and the 2-column layout splits stream cards as bottom trailers to keep the all-cards view balanced), `columns.ts` (column-aligned row layout with protect/clip clipping policy; exposes `contentWidthFromCols(cols)` + `termColsForLayout()` helpers — every card/popup feeds the result as `layoutColumns(rows, specs, contentWidth)` so clip cells actually clip instead of overflowing the row to a second line per bug_tui_long_lines_overflow), `help.tsx` (? keymap overlay), `cards/{agents,tracks,ready,log,workspaces,inprogress,blocked,recent,commits,doctor}.tsx` + `cards/_placeholder.tsx` (`<CardPlaceholder>` — shared loading/empty body wrapper invoked as a function so the test walker still sees the underlying TitledBox/PaddedRows; collapses 20 near-identical 10-line `<TitledBox><PaddedRows><Text dimColor>...</Text></PaddedRows></TitledBox>` blocks across the 10 cards per review_tui_card_loading_empty_boilerplate) (10 dashboard glance cards; slot 0 is Commits, slot 5 promoted by feat_card_5_workspaces, slot 6 by feat_card_6_inprogress, slot 7 by feat_card_7_blocked, slot 8 is Recent, slot 9 by feat_card_9_doctor; DAG and all-tasks are keybind-only popup conventions, not cards), `popups/{dag,all-tasks,agents,tracks,ready,log,workspaces,inprogress,blocked,recent,commits,doctor}.tsx` (12 fullscreen drill-down popups; `dag.tsx` is keybind-only on `g` and renders the active workstream's full task-DAG forest; `all-tasks.tsx` is keybind-only on `t`, renders every task as a sortable/filterable list via the shared `use-status-filter.tsx`, and drills into `TaskDetailDrill`; `commits.tsx` is slot-0 via Shift+0 and drills into backend show output; slot-5 popup promoted by feat_popup_5_workspaces, slot-6 by feat_popup_6_inprogress, slot-7 by feat_popup_7_blocked, slot-8 by feat_popup_8_recent (yanks `mu task open <id>`); slot-9 by feat_popup_9_doctor (the Doctor drill is a small ad-hoc detail view via `DrillScrollView`, NOT TaskDetailDrill — rows are doctor checks rather than tasks). All reserved numeric popup slots are now filled), `popups/drill.tsx` (`DrillScrollView` — the scroll-list primitive every popup-drill body shares; re-exports `clampScrollTop` from `popups/scroll.ts` for back-compat), `popups/scroll.ts` (pure `applyCursor` + `applyScroll` + `clampScrollTop` + `isNavAction` — the centralised navigation primitive every popup + drill consumes per feat_centralize_scroll_navigation; replaces ~60 near-duplicate `case "moveDown"/"moveUp"/"jumpTop"/"jumpBottom"/"pageUp"/"pageDown"` switch arms across 9 popups so j/k/g/G/Ctrl-D/U/PgUp/PgDn behave identically in every list-mode AND every drill-mode; pure TS with no ink/react imports, covered by test/tui-scroll.test.ts), `popups/viewport.ts` (pure `popupViewport(rows, chromeOverride?)` + `POPUP_CHROME_ROWS` + `POPUP_VIEWPORT_FLOOR` — each popup reads `useStdout().rows` at render time and calls `popupViewport` to size the body slice; replaces the prior hardcoded `const VIEWPORT = 20` per bug_tui_popup_data_doesnt_fill so the row data inside a `flexGrow={1}` popup Shell actually fills the pane), `popups/task-detail.tsx` (`TaskDetailDrill` — the read-only task-notes leaf consumed by the Tasks popup drill AND by the Tracks-popup `drill → task-detail` chain; future task-list popups under feat_more_cards_umbrella plug in unchanged), `use-popup-filter.tsx` (shared `/` filter state-machine: pure `popupFilterReducer` + `usePopupFilter` hook + `applyFilter<T>(items, query, blobOf)` + `<FilterPrompt>`. Every list popup wires the hook in ~5 LOC and gets the full UX — incremental edit, Enter commit, Esc cancel, status-bar mode flip, no-matches fallback — for free; new card popups under feat_more_cards_umbrella MUST consume it rather than re-implement), `use-status-filter.tsx` (shared task-status toggle hook + `<StatusFilterStrip>` for task-list popups; default all-on, popup-local, mnemonic o/i/c/r/d toggles OPEN / IN_PROGRESS / CLOSED / REJECTED / DEFERRED, no persistence), `use-notes-drill.ts` (shared notes-drill memo — returns the `renderNotes(...)` body string for the focused task only when the popup is in drill mode; per task review_tui_task_popups_duplicated_template the byte-identical useMemo block deduped from all five task-list popups (Tasks/ready, In-progress, Blocked, Recent, All-tasks) so the next task-list popup is a one-line drop-in and the SQL+tick semantics stay in lockstep), `tab-strip.tsx` (`<TabStrip>` — multi-workstream tab switcher rendered above the cards when `<App>` is launched with N≥2 workstreams; bold/cyan + `▸ ` marker for the active tab, dim names + ` · ` separators for the rest, plus a `(Tab / Shift-Tab)` affordance hint; renders nothing for N=1 so the single-ws frame is byte-identical to the pre-multi-ws build; pure presentational — the active index lives in `<App>`, `Tab`/`Shift-Tab` keys come through `dispatchGlobalKey`'s `nextTab`/`prevTab` actions). **The ONLY place ink/react are imported** — enforced by ROADMAP pledge. |
 | `src/cli/tasks/*.ts`  | sub-cluster of the `mu task` namespace; `tasks.ts` at the root re-exports only what callers outside the cluster import (`wireTaskCommands`, `cmdMyNext`/`cmdMyTasks`, `unescapeNoteText`). One file per concern: `queries.ts` (list/next/owned-by + the `cmdMyTasks` / `cmdMyNext` helpers that back `mu me tasks` / `mu me next`), `lifecycle.ts` (close/open/reject/defer + 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). Each file < 600 LOC; the hub is < 35. |
 | `src/index.ts`        | SDK entrypoint (re-exports)                                                               |
 | `skills/mu/SKILL.md`  | Bundled skill teaching the LLM the model + verb list + jq pipelines                       |
@@ -312,7 +541,7 @@ Each module is concrete and consumed today.
 4. **Executes the operation** — agent ops shell out to tmux (and to
    jj/sl/git for workspaces); task ops are pure SQL.
 5. **Reconciles with reality** — for read-paths that need accuracy
-   (`mu agent list`, mission control), queries tmux for live pane
+   (`mu agent list`, state views), queries tmux for live pane
    state and updates the DB (ghost prune + status detect).
 6. **Auto-emits a `kind='event'` row** to `agent_logs` for any
    state-changing verb, conditional on actual change. `mu log
@@ -328,11 +557,12 @@ each are deliberately small.
 
 | Seam                | Add a new impl by...                                                                                                          |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `VcsBackend`        | Implementing `detect / createWorkspace / freeWorkspace / isClean / commitsBehind / rebaseTo / commitsSinceBase` (~80–150 LOC; jj/sl/git/none are working examples)        |
+| `VcsBackend`        | Implementing `detect / createWorkspace / freeWorkspace / isClean / commitsBehind / rebaseTo / commitsSinceBase / recentCommits / showCommit` (~80–150 LOC; jj/sl/git/none are working examples)        |
 | Per-CLI `Detector`  | Adding patterns to `detectPiStatus` (vanilla pi `to interrupt)`; pi-meta + every TUI wrapper covered by Braille spinner glyph fallback `[\u2800-\u28FF]`)                  |
 | New typed verb      | Add an SDK function in the relevant `src/*.ts`; add a `cmd<Verb>` to the matching `src/cli/<namespace>.ts` (or create a new namespace if the verb doesn't fit existing ones); wire one commander block in `src/cli.ts`'s `buildProgram()` (use `handle()` for the exit-code map; route through `printNextSteps` for self-documenting output) |
-| New schema migration| Bump `CURRENT_SCHEMA_VERSION` in `src/db.ts`; mirror the new shape in `CURRENT_SCHEMA`. Two of the three post-v5 bumps were script-free: v5 → v6 was purely additive (the existing CREATE-TABLE-IF-NOT-EXISTS pass picked up the new `archive_*` tables), and v6 → v7 was a destructive-but-idempotent in-place migration (a `DROP TABLE IF EXISTS approvals` block in `applySchema`). Reach for a one-shot migration script only when the change can't be expressed that way (the v4 → v5 surrogate-PK substrate switch was the canonical example; restore from git history if you need to see the shape). The loud-fail hook in `openDb` rejects pre-current DBs with `SchemaTooOldError` (exit code 4) and a migration instruction. |
+| New schema migration| Bump `CURRENT_SCHEMA_VERSION` in `src/db.ts`; mirror the new shape in `CURRENT_SCHEMA`. Three of the four post-v5 bumps were script-free: v5 → v6 was purely additive (the existing CREATE-TABLE-IF-NOT-EXISTS pass picked up the new `archive_*` tables), v6 → v7 was a destructive-but-idempotent in-place migration (a `DROP TABLE IF EXISTS approvals` block in `applySchema`), and v7 → v8 is additive (`machine_identity`, `workstream_sync`, plus the `openDb` seed for `machine_identity`). Reach for a one-shot migration script only when the change can't be expressed that way (the v4 → v5 surrogate-PK substrate switch was the canonical example; restore from git history if you need to see the shape). The loud-fail hook in `openDb` rejects pre-current DBs with `SchemaTooOldError` (exit code 4) and a migration instruction. |
 | Snapshot hook       | Add `await captureSnapshot(db, 'verb-name', workstream)` at the top of any new destructive verb (one-liner; GC + restore behaviour automatic) |
+| Cross-machine sync  | `machine_identity` gives each state directory a durable uuid; `workstream_sync.last_known_peer_seqs` records per-workstream peer progress. `mu db import` compares source `latestSeq`, local `latestSeq`, and the last-seen peer seq to classify the five cases: `IDENTICAL` / `FAST_FORWARD` / `LOCAL_AHEAD` / `CONFLICT` / `IMPORT`. Conflicts are sharp: refuse by default, or `--force-source` after parking the whole local workstream into a divergence sidecar for later `mu db replay`. |
 
 ## Surrogate-PK + SDK-boundary discipline (load-bearing)
 
@@ -380,7 +610,8 @@ export function claimTask(
   opts?: ClaimOptions,
 ): ClaimResult {
   const wsId = resolveWorkstreamId(db, workstream);
-  const taskId = resolveTaskId(db, wsId, localId);
+  const taskId = tryResolveTaskId(db, wsId, localId);
+  if (taskId === null) throw new TaskNotFoundError(localId);
   const agentId = resolveCurrentAgentId(db, wsId);
   return claimTaskById(db, taskId, agentId, opts);
 }
@@ -392,10 +623,12 @@ function claimTaskById(db, taskId, agentId, opts): ClaimResult { ... }
 Why exactly once at the boundary: no double-resolution; no
 mid-function ambiguity (once surrogate ids exist, internal helpers
 don't need to thread workstream context — the FKs make scope
-implicit); one place to do error mapping
-(`WorkstreamNotFoundError` / `TaskNotFoundError` /
-`AgentNotFoundError` all originate at resolve-time, with the
-operator's input string in the error payload).
+implicit); one place to do error mapping (`WorkstreamNotFoundError`
+originates at resolve-time inside `src/db.ts`; `TaskNotFoundError` /
+`AgentNotFoundError` are raised by SDK callers wrapping the
+`tryResolve*` null-return so the typed class — and the CLI's
+exit-code 3 mapping — stays consistent regardless of which leg of
+the resolve missed).
 
 **`--json` output preserves operator-facing names.** Surrogate ids
 stay strictly internal — they never leak into `--json`, error
@@ -456,9 +689,19 @@ action) so `mu doctor` can surface them readably.
 | `src/tracks.ts`                    | Pure functions; union-find + diamond-merge properties                           |
 | `src/agents.ts`                    | Mocked tmux executor via `setTmuxExecutor()`; reaper integration tests          |
 | `src/logs.ts`                      | Real SQLite; cursor semantics, AUTOINCREMENT durability, FK CASCADE             |
-| `src/vcs.ts` + `src/workspace.ts`  | Real git in `os.tmpdir()`; jj/sl tests feature-detect (skip if binary missing)  |
+| `src/vcs.ts` + `src/workspace.ts`  | `*.integration.test.ts` files use real git in `os.tmpdir()`; jj/sl tests feature-detect (skip if binary missing) |
 | `src/cli.ts` / verb integration    | `*.integration.test.ts` files; real tmux server, unique session per test        |
-| End-to-end                         | `test/acceptance.test.ts` — the canonical 10-task / 3-agent demo                |
+| Fast unit/dev-loop tier            | `npm run test:fast`; excludes `*.integration.test.ts` / `*.smoke.test.ts`, uses mocked tmux/VCS and per-test temp DBs |
+| Stress / flake audit               | `npm run test:stress`; repeats the full suite with per-run logs/timeouts and can run parallel full-suite waves (`MU_TEST_STRESS_MODE=parallel`) to simulate multiple mu agents testing concurrently |
+| End-to-end                         | `test/acceptance.integration.test.ts` — the canonical 10-task / 3-agent demo   |
+
+Historical flake audit summary: the closed
+`bug_test_suite_flakes_audit_and_remediate` task found no separate
+product seam. The durable lessons are: treat pass-alone/fail-under-load
+cases as concurrency bugs first; use retrying temp-dir cleanup for VCS
+fixtures whose subprocesses keep files alive briefly; drive wait/reaper
+integration tests from poll-loop seams instead of fixed timers; and wait
+for stable Ink output instead of sleeping a fixed number of ms.
 
 ## Distribution
 
@@ -478,4 +721,4 @@ not in the mu package.
 
 The dependency list lives in `package.json`; the rule for adding
 new ones is the anti-feature pledge in
-[ROADMAP.md § Anti-feature pledges](ROADMAP.md#anti-feature-pledges-still-in-force-reinforced-by-an-internal-critique).
+[ROADMAP.md § Anti-feature pledges](ROADMAP.md#anti-feature-pledges).