@martintrojer/mu 0.3.2 → 0.4.1

package/docs/USAGE_GUIDE.md

@@ -1,26 +1,27 @@
 # mu — Usage Guide
 
-A practical, copy-pasteable tour of mu (current main; v0.3-track).
+A practical, copy-pasteable tour of mu (current main; v0.4.1).
 Everything below works against the built CLI. Terms are canonical
 — see [VOCABULARY.md](VOCABULARY.md) for definitions; the complete
 current verb list is in `## CLI — complete verb list` of
 [skills/mu/SKILL.md](../skills/mu/SKILL.md).
 
-> **Status:** v0.3 wave (pre-1.0). ~60 typed verbs across 8
+> **Status:** v0.4.1 (pre-1.0). ~65 typed verbs across 9
 > namespaces (`workstream`, `agent`, `task`, `workspace`, `log`,
-> `snapshot`, `archive`, `me`) plus bare top-level verbs
-> (`state`, `doctor`, `sql`, `undo`, `adopt`). Every verb accepts
-> `--json` (one allow-listed exception, `mu agent attach`),
-> per-agent VCS workspaces (jj/sl/git/none), activity log with
-> `--tail` subscription, canonical state card (`mu state` —
-> default / `--hud` / `--mission` render modes), whole-DB
-> snapshots auto-captured before destructive verbs +
-> `mu undo` / `mu snapshot {list,show}`, evidence on lifecycle
-> verbs, schema v7 (v5 surrogate INTEGER PKs + per-workstream
-> UNIQUE on operator-facing names; v6 added the `archive_*`
-> family additively; v7 dropped the dead `approvals` table).
+> `snapshot`, `archive`, `db`, `me`) plus bare top-level verbs
+> (`state`, `doctor`, `sql`, `undo`). Every verb accepts `--json`
+> (one allow-listed exception, `mu agent attach`), per-agent VCS
+> workspaces (jj/sl/git/none), activity log with `--tail`
+> subscription, bare `mu` TTY dashboard, canonical static state card
+> (`mu state` default / `--tui` render modes), whole-DB snapshots
+> auto-captured before destructive verbs + `mu undo` /
+> `mu snapshot {list,show}`, evidence on lifecycle verbs, schema v8
+> (v5 surrogate INTEGER PKs + per-workstream UNIQUE on
+> operator-facing names; v6 added the `archive_*` family additively;
+> v7 dropped the dead `approvals` table; v8 adds `machine_identity`
+> and `workstream_sync` for db sync).
 > See [CHANGELOG.md](../CHANGELOG.md) for the release entry,
-> and [§ Not in 0.3.0](#whats-not-in-030-and-how-to-work-around-it)
+> and [§ Not in 0.4.1](#whats-not-in-041-and-how-to-work-around-it)
 > at the bottom for the gaps that still need workarounds.
 
 *If anything below disagrees with `mu --help`, trust `mu --help`.*
@@ -33,7 +34,8 @@ current verb list is in `## CLI — complete verb list` of
 2. [Get oriented (`mu doctor`)](#2-get-oriented)
 3. [Create a workstream (`mu workstream init`)](#3-create-a-workstream)
 4. [Plan some work as a DAG (`mu task add`)](#4-plan-some-work-as-a-dag)
-5. [See the graph (mission control)](#5-see-the-graph-mission-control)
+5. [See the graph (dashboard + state API)](#5-see-the-graph-dashboard--state-api)
+5b. [The TUI dashboard (interactive)](#5b-the-tui-dashboard-interactive)
 6. [Spawn a crew (`mu agent spawn`)](#6-spawn-a-crew)
 7. [Watch the crew live (`tmux attach`)](#7-watch-the-crew-live)
 8. [Send work to an agent (`mu agent send`)](#8-send-work-to-an-agent)
@@ -45,9 +47,10 @@ current verb list is in `## CLI — complete verb list` of
 14. [Recovery scenarios](#14-recovery-scenarios)
 15. [Cleanup](#15-cleanup)
 15.5. [Archives — cross-workstream preservation](#155-archives--cross-workstream-preservation-of-task-graphs)
+15.6. [Multi-machine sync](#156-multi-machine-sync)
 16. [One-shot demo script](#16-one-shot-demo-script)
 17. [Mental model in three sentences](#mental-model-in-three-sentences)
-18. [What's NOT in 0.3.0](#whats-not-in-030-and-how-to-work-around-it)
+18. [What's NOT in 0.4.1](#whats-not-in-041-and-how-to-work-around-it)
 19. [Where to go from here](#where-to-go-from-here)
 
 ---
@@ -140,6 +143,32 @@ tmux       # if you're not already in one
 
 ## 2. Get oriented
 
+For a human at an interactive terminal, bare `mu` is the home base:
+it launches the read-only TUI with every workstream on the machine
+loaded as tabs. Initial tab focus uses this ladder: `$MU_SESSION` when
+it names a loaded workstream; then the current tmux session name when
+it is `mu-<workstream>`; then best-effort cwd detection against
+registered workspace paths; then cwd equal to the VCS-derived project
+root of any loaded workstream's workspaces (ties broken by most-recent
+workstream activity); then tab 0. If no workstream exists yet, it
+prints help plus the one-paste start command:
+
+```bash
+mu
+# Get started: mu workstream init <name>
+```
+
+For scripts, agents, CI, and pipes, bare `mu` deliberately does NOT
+enter the TUI: when stdout is not a TTY it prints `mu --help`. Use
+explicit typed verbs and `--json` for the API surface:
+
+```bash
+mu state -w <workstream> --json
+MU_NO_TUI=1 mu             # force the non-TTY/help path even in a terminal
+```
+
+Run the diagnostic once to check tmux + DB health:
+
 ```bash
 mu doctor
 ```
@@ -222,9 +251,10 @@ $ mu task list -w foo --json
 ```
 
 `count` is `items.length` pre-computed so `jq '.count'` is one less
-hop than `jq '.items | length'`. Future siblings (e.g. `baseRef` on
-`mu workspace commits`, `behindCount` on `mu workspace list`) layer
-on without breaking the existing two fields.
+hop than `jq '.items | length'`. Future siblings layer on without
+breaking the existing two fields. Today `mu workspace commits --json`
+also includes `vcs`, `baseRef`, and `workspacePath` siblings because
+that verb already computes the workspace's fork metadata.
 
 Applies to: `mu task list / next / owned-by / notes`,
 `mu workstream list`, `mu workstream destroy --empty` (dry-run),
@@ -329,8 +359,8 @@ Tasks have **mandatory** `impact` (1–100) and `effort-days` (>0).
 Edges are blocks-relationships, modelled as **`--blocked-by`** on `mu
 task add` (and `mu task reparent`): `--blocked-by design` means "this
 task is blocked by `design`; it can't start until `design` closes."
-Tasks are **scoped to a workstream** — mission control only shows
-tasks for the workstream you're in.
+Tasks are **scoped to a workstream** — the dashboard and state views only show
+tasks for the workstream you're viewing.
 
 ```bash
 # --workstream can be omitted if you're inside the workstream's tmux
@@ -357,112 +387,299 @@ Each task validates its id (`/^[a-z][a-z0-9_-]{0,63}$/`) and rejects
 duplicates. If you tried `mu task add x --blocked-by y` while `y`
 already transitively depended on `x`, mu would refuse with a `CycleError`.
 
-**Task ids are globally unique** (PRIMARY KEY across all workstreams)
-but tasks are scoped to one workstream. Cross-workstream blocks-edges
-are forbidden — if `--blocks foo` resolves to a task in a different
+**Task ids are per-workstream unique.** The same local id can exist in
+multiple workstreams, so cross-workstream references use the qualified
+form `<workstream>/<id>` when a global scope is needed. Blocks-edges
+are always same-workstream — if a blocker resolves outside the target
 workstream, mu refuses with a `CrossWorkstreamEdgeError`.
 
 ---
 
-## 5. See the graph (mission control)
+## 5. See the graph (dashboard + state API)
 
-```bash
-mu --workstream auth-refactor
-# or, if your tmux session is mu-auth-refactor:
-mu
-```
+`mu` exposes one logical "what's going on?" view with two renderers:
 
-```
-mu-auth-refactor
+| Surface              | Use it for                                                      |
+| -------------------- | --------------------------------------------------------------- |
+| **bare `mu`**        | A human at a terminal — launches the interactive TUI dashboard. |
+| **`mu state --tui`** | Same TUI, explicitly opt-in. Useful in scripts / aliases.       |
+| **`mu state`**       | Static text card. JSON-friendly; pipeable; `watch`-able.        |
+| **`mu state --json`** | The canonical full snapshot. Agents and scripts read this.     |
 
-Agents (0)
-  (no agents)
+The interactive surface is large enough to deserve its own section —
+see [§ 5b. The TUI dashboard](#5b-the-tui-dashboard-interactive)
+immediately below. The rest of this section is the static / JSON
+contract.
 
-Tracks (1)
-  Track 1: review (3 tasks, 1 ready, track)
+### Static state card (`mu state`)
 
-Ready (1)
-┌────────┬─────────────────────┬────────┬────────┬──────┬───────┐
-│ id     │ title               │ impact │ effort │ ROI  │ owner │
-├────────┼─────────────────────┼────────┼────────┼──────┼───────┤
-│ design │ Design auth module  │ 80     │ 2      │ 40.0 │       │
-└────────┴─────────────────────┴────────┴────────┴──────┴───────┘
-```
-
-This is the answer to **"what should I work on next?"** without
-asking an LLM. Three sections:
-
-- **Agents** — registry rows, status detected from each pane's
-  scrollback, post-reconciliation
-- **Tracks** — independent subtrees the parallel-track union-find
-  found. When two goals share a prerequisite, mu collapses them into
-  ONE track ("merged") so two agents are never assigned tasks that
-  share a dependency
-- **Ready** — actionable now, sorted by ROI (impact / effort)
-
-### `mu state` render modes (default, `--hud`, `--mission`)
-
-`mu state` is one verb with three render modes — same data set,
-different presentation strategy. The flag picks the renderer; the
-JSON shape (`--json`) follows render mode (full vs stripped).
-
-```bash
-mu state                    # default: full top-to-bottom card
-mu state --hud              # dynamic-fit budget renderer (watch / popup / status-bar)
-mu state --mission          # stripped 5-col glance card
-mu                          # bare alias for `mu state --mission`
-```
-
-- **default (full card)** — every section: agents + orphans + tracks +
-  ready / in-progress / blocked / recent-closed + workspaces + recent
-  events. JSON-first by design (per Ilya's council critique: state
-  cards as the default attention surface; SQL/raw verbs as the
-  escape hatch underneath).
-
-- **`--hud`** — dynamic table layout that fills the terminal (or tmux
-  pane) height + width with as much useful data as fits.
-  `watch -n 5 mu state --hud -w X` for a refreshing pane;
-  `tmux display-popup -E 'mu state --hud -w X'` for an on-demand
-  popup; `#(mu state --hud -w X --json) | jq ...` for tmux
-  status-bar interpolation. Sections (priority order):
-  header / agents / ready / in-progress / tracks / recent-events.
-  Truncated tables get a `… +N more (<verb>)` footer; lower-priority
-  sections that can't fit are skipped entirely. Drops blocked /
-  recent-closed / workspaces (not glanceable); operator drops
-  `--hud` to see them.
-
-- **`--mission`** — stripped 5-col glance card (agents + orphans +
-  tracks + ready). The bare-`mu` muscle-memory orient call
-  ("what's going on?"). The full card with blocked / recent-closed /
-  workspaces is too much for that intent; `--mission` is the
-  intentional minimum-viable orient view.
-
-`--hud` and `--mission` are mutually exclusive.
-
-Multi-workstream: pass `-w` multiple values to render N workstreams
-in one card. `-w a,b,c`, `-w a -w b`, or any mix all work — see
-[CLI conventions](#cli-conventions-multi-value-flags). `--all` is
-sugar for "every workstream on this machine" (mutually exclusive with
-`-w`). N≥2 in `--hud` mode unions the per-ws sections with a leading
-`workstream` column; in default + `--mission` modes N≥2 stacks one
-per-workstream card after another. The `--json` envelope wraps in
-`{ workstreams: [...] }` when N≥2.
-
-JSON shapes (per render mode):
+For an agent/script or a static capture, use explicit `mu state`:
+
+```bash
+mu state -w auth-refactor          # human-readable card
+mu state -w auth-refactor --json   # full snapshot
+mu state --all --json              # every workstream on this machine
+```
+
+The static card includes every section the TUI cards summarize:
+agents + orphans + tracks + ready / in-progress / blocked /
+recent-closed tasks + workspaces + recent events. `--json` emits the
+same full snapshot shape regardless of `--tui`.
+
+**JSON shapes**
 
 - `mu state --json` (single-ws): flat `{ workstreamName, agents,
   orphans, tracks, ready, blocked, inProgress, recentClosed,
   workspaces, recent }`.
-- `mu state --hud --json`: SAME flat shape (`--hud` is a render flag;
-  it doesn't change the machine view).
-- `mu state --mission --json`: STRIPPED — only `{ workstreamName,
-  agents, orphans, tracks, ready }`.
-- bare `mu --json`: same as `--mission --json`.
+- `mu state --json` (multi-ws): wrapped `{ workstreams: [{...}, ...] }`.
+- bare `mu --json`: prints `--help` rather than entering the TUI;
+  use `mu state --json` for the full snapshot.
+- `--tui` is render-only and incompatible with `--json` (the TUI
+  has no JSON shape).
+
+**Multi-workstream**: pass `-w` multiple values, or `--all`. See
+[CLI conventions](#cli-conventions-multi-value-flags). In static
+mode N≥2 stacks one per-workstream card after another.
+
+> **Migrating from old state surfaces**: `mu state --hud` and
+> `mu state --mission` were removed in v0.4; use `mu state --tui`
+> for the interactive surface and `mu state --json` for the full
+> snapshot. `tmux display-popup -E 'mu state -w X'` keeps working
+> unchanged for popup-card use.
 
-> **Migrating from `mu hud`**: drop the `hud` verb and add `--hud`
-> to `mu state`. `tmux display-popup -E 'mu hud -w X'` becomes
-> `tmux display-popup -E 'mu state --hud -w X'`. The `mu hud` verb
-> was removed in v0.3 — see [CHANGELOG.md](../CHANGELOG.md).
+---
+
+## 5b. The TUI dashboard (interactive)
+
+The interactive TUI is mu's flagship human surface. It is **read-only
+by design** — every act-intent `y`anks the canonical `mu` command to
+your clipboard so you run mutations from your shell, with one
+documented escape (`t` in git-show drills runs `tuicr` in the project
+root, see below).
+
+### Launch
+
+```bash
+mu                              # bare; opens the TUI when stdout is a TTY
+mu state --tui                  # explicit; same surface
+mu state --tui -w a,b           # restrict to specific workstreams
+mu state --tui --all            # all workstreams (default for bare `mu`)
+MU_NO_TUI=1 mu                  # force the help path even in a TTY
+mu --json                       # also forces help; pipe `mu state --json`
+```
+
+Quit with `q` or `Ctrl-C`. The dashboard restores your scrollback
+on exit (alt-screen).
+
+**Initial active tab** is picked from this ladder:
+`$MU_SESSION` → current tmux session name (`mu-<ws>`) → cwd inside a
+registered workspace → cwd at the VCS-derived project root of any
+workstream (newest activity wins ties) → tab 0.
+
+### Layout: 10 cards, responsive columns
+
+The dashboard renders 10 toggleable cards with rounded borders and
+section headers inset into the top border line (lazygit / btop / k9s
+convention):
+
+| Slot | Card          | Toggle | Popup     | Content                                              |
+| ---- | ------------- | ------ | --------- | ---------------------------------------------------- |
+| 0    | Commits       | `0`    | `Shift+0` | Recent project-root commits (git / jj / sl)          |
+| 1    | Agents        | `1`    | `Shift+1` | Active agents + status + cli + role                  |
+| 2    | Tracks        | `2`    | `Shift+2` | Parallel tracks (union-find clusters)                |
+| 3    | Ready (Tasks) | `3`    | `Shift+3` | Ready-to-claim tasks (no open blockers)              |
+| 4    | Activity log  | `4`    | `Shift+4` | Recent `agent_logs` events                           |
+| 5    | Workspaces    | `5`    | `Shift+5` | Per-agent VCS workspaces + behind/dirty status       |
+| 6    | In-progress   | `6`    | `Shift+6` | IN_PROGRESS tasks owned by agents                    |
+| 7    | Blocked       | `7`    | `Shift+7` | Tasks with at least one open blocker                 |
+| 8    | Recent        | `8`    | `Shift+8` | Recently CLOSED tasks                                |
+| 9    | Doctor        | `9`    | `Shift+9` | Cheap health checks (schema, ghosts, orphans, …)    |
+| —    | DAG           | —      | `g`       | Full task DAG forest (keybind-only)                  |
+| —    | All tasks     | —      | `t`       | Sortable / filterable list of every task             |
+
+Digit toggles HIDE / SHOW the card on the dashboard; `Shift+digit`
+opens the matching fullscreen popup. **Single-popup invariant**: only
+one popup is visible at a time; `Esc` / `q` returns to the dashboard
+with all toggles + tick rate preserved.
+
+**Responsive layout**: cards stack below 120 cols, then reflow into
+pair-aware 2 / 3 / 4-column layouts at 120 / 180 / 240 cols. Each
+visible card gets a dynamic row budget so a noisy list cannot crowd
+out its siblings; overflow shows as `+N more · Shift+N` inset into
+the bottom border. On very short panes, the dashboard culls
+low-priority cards (Doctor → Recent → Workspaces → …) and shows
+`+N cards hidden · resize taller` until the surviving cards fit.
+
+Dashboard ordering is slot-stable: within each rendered column,
+non-stream cards are ordered by toggle digit ascending; stream cards
+(Commits, Activity log) sit as natural trailers, with slot 0 trailing
+last.
+
+### Multi-workstream tabs
+
+When the TUI is launched with N≥2 workstreams (e.g. bare `mu` on a
+machine with multiple workstreams, or `mu state --tui -w a,b,c`),
+a compact tab strip renders above the cards:
+
+```
+workstreams: ▸ auth-refactor · ui-rewrite · demo   (Tab / Shift-Tab)
+```
+
+- `Tab` cycles forward, `Shift-Tab` backward (suppressed inside
+  popups so the same key still navigates inside popups that bind
+  it locally).
+- The active tab name appears in the status bar's right zone next
+  to the tick rate.
+- Cards / popups always operate on the active tab — there's no
+  per-row workstream column.
+- For N=1 the strip renders nothing (frame is byte-identical to
+  single-ws TUI).
+- When the workstream set is wider than the terminal, the strip
+  windows around the active tab and shows `‹N` / `›N` counters
+  for hidden workstreams.
+
+### Popup drills
+
+`Enter` in any list popup drills into the focused row. Where the
+row is itself an entity (a task), a further `Enter` chains into the
+shared read-only task-detail leaf (notes timeline):
+
+- **Tracks popup (`Shift+2`)**: list of tracks → `Enter` opens the
+  track's task list → `Enter` opens that task's notes timeline.
+- **Ready / In-progress / Blocked / Recent / All-tasks**:
+  list of tasks → `Enter` opens notes; `y` yanks `mu task show <id>`
+  (or `mu task claim` / `mu task close` / `mu task tree` depending
+  on popup).
+- **Activity log popup (`Shift+4`)**: list of events → `Enter`
+  drills into the full untruncated payload of the focused event;
+  `y` yanks `mu log --since <seq-1> -n 1 -w <ws>`.
+- **Workspaces popup (`Shift+5`)**: list of workspaces → `Enter`
+  opens the commits-since-fork list → `Enter` on a commit opens
+  the inline `git show <sha> --stat -p` view; `y` yanks `git show
+  <sha>`; `t` launches `tuicr -r <sha>`.
+- **Commits popup (`Shift+0`)**: project-root recent commits →
+  `Enter` opens the backend's show view; `y` yanks the show
+  command; `t` launches `tuicr`.
+- **Doctor popup (`Shift+9`)**: list of checks → `Enter` opens
+  the remediation paragraph for the focused check.
+- **DAG popup (`g`)**: keybind-only; renders the active workstream's
+  full task DAG forest (one ASCII subtree per root, diamond-collapse
+  marker on repeated nodes).
+
+One `Esc` / `q` backs out per recursion level. Drills auto-refresh
+in step with the dashboard tick (fast 1s for SQL-derived bodies
+like notes, slow 10s for subprocess git-show / scrollback). Scroll
+position is preserved across refreshes; subprocess loaders keep the
+prior body visible until the new one arrives so there's no
+blank-flash mid-refetch.
+
+### Search / filter
+
+`/` inside any list popup enters an incremental case-insensitive
+substring filter (lazygit / k9s convention):
+
+- Every printable character appends to the query; `Backspace` pops
+  one.
+- `Esc` cancels (clears the query); `Enter` commits (keeps the
+  filter applied while letting `j/k` resume normal navigation).
+- Press `/` again on a committed filter to refine.
+- The filter blob is per-popup: agent name + status + cli + role;
+  track head id + title; task name + title + status + owner; log
+  verb + payload + source.
+- Filter state is per-popup and dies with the popup.
+
+Task-list popups also expose **per-status toggles** (`o` / `i` / `c`
+/ `r` / `d` toggle OPEN / IN_PROGRESS / CLOSED / REJECTED / DEFERRED
+visibility; default all-on).
+
+The All-tasks popup adds **sort cycle** on `s`: `roi` → `recency`
+→ `age` → `id`.
+
+### Mouse
+
+Navigation-in only:
+
+- Double-click a dashboard card → opens its popup.
+- Scroll-wheel inside a popup list / drill body → moves the focused
+  cursor / scrolls the body.
+- Double-click a popup row → drills one level deeper.
+
+There is intentionally **no mouse back binding** — use `Esc` / `q`
+to back out predictably.
+
+### Yank contract (`y`) and the `tuicr` escape (`t`)
+
+Every popup row exposes one canonical `mu` command via `y`. The
+command goes to your system clipboard (pbcopy / wl-copy / xclip /
+xsel / clip.exe with OSC-52 fallback). You run it in your shell.
+The TUI never executes a mutation.
+
+The one user-driven escape from the read-only pledge is **`t`**
+inside any `git show` drill (Workspaces popup or Commits popup):
+mu suspends its alt-screen, runs `tuicr -r <sha>` in the project
+root / workspace cwd, then restores the dashboard when tuicr exits.
+This is a deliberate handoff — the operator drives another TUI
+tool, not mu performing the mutation.
+
+Task-list cards and popups colour-code status cells consistently
+with the static CLI tables: OPEN cyan, IN_PROGRESS yellow, CLOSED
+green, REJECTED red, DEFERRED dim/gray.
+
+### Polling tiers
+
+The dashboard has two refresh tiers:
+
+- **Fast tick** (default 1s, adjustable with `+` / `-` / `=` /
+  `0`): SQL-only. Refreshes tasks, tracks, workspace registry rows,
+  and the activity log.
+- **Slow tick** (10s, fixed): subprocess-backed. Refreshes
+  tmux-derived agent liveness / orphans, workspace dirty flags,
+  recent project commits, and the Doctor summary.
+
+The last slow-tier result is merged into every fast render so cards
+do not flicker through a loading state. `r` / F5 refreshes both
+tiers immediately. Tab / Shift-Tab triggers an eager slow refresh
+for the newly active workstream.
+
+### Keymap reference
+
+| Mode      | Keys                         | Action                                                         |
+| --------- | ---------------------------- | -------------------------------------------------------------- |
+| dashboard | `0`-`9`                      | toggle card visibility                                         |
+| dashboard | `Shift+0`-`Shift+9`          | open the matching popup                                        |
+| dashboard | `g`                          | open DAG popup (keybind-only)                                  |
+| dashboard | `t`                          | open All-tasks popup (keybind-only)                            |
+| dashboard | `Tab` / `Shift-Tab`          | cycle workstream tabs (N≥2)                                   |
+| dashboard | `+` / `-` / `=` / `0`        | adjust fast tick rate (faster / slower / default / pause)      |
+| dashboard | `r` / `F5`                   | force refresh both tiers                                       |
+| dashboard | `?` / `F1`                   | open help overlay                                              |
+| any       | `q` / `Ctrl-C`               | quit (or back out of popup; quits at dashboard)                |
+| popup     | `j` / `k`                    | move cursor / scroll                                           |
+| popup     | `g` / `G`                    | jump top / bottom                                              |
+| popup     | `Ctrl-D` / `Ctrl-U`          | half-page down / up                                            |
+| popup     | `PgDn` / `PgUp`              | full page                                                      |
+| popup     | `Enter`                      | drill into focused row                                         |
+| popup     | `Esc` / `q`                  | back out one level                                             |
+| popup     | `y`                          | yank canonical `mu` command for focused row                    |
+| popup     | `/`                          | enter filter mode                                              |
+| filter    | (printable) / `Backspace`    | edit query                                                     |
+| filter    | `Esc`                        | cancel (clear query)                                           |
+| filter    | `Enter`                      | commit (keep filter, return to nav)                            |
+| task popup| `o` / `i` / `c` / `r` / `d`  | toggle OPEN / IN_PROGRESS / CLOSED / REJECTED / DEFERRED       |
+| All-tasks | `s`                          | cycle sort key (roi → recency → age → id)                       |
+| git-show  | `t`                          | launch `tuicr -r <sha>` (alt-screen handoff)                   |
+
+`?` shows the same table as a scrollable overlay (j/k/Ctrl-D/U/g/G
+also work inside the overlay).
+
+### Read-only invariant
+
+The TUI never executes a mutation. This is not a feature of the
+implementation; it's a load-bearing pledge in `docs/ROADMAP.md`. If
+a future TUI gesture tempts you to call into the SDK to mutate
+state, file a roadmap entry first — the yank-and-run pattern is the
+intentional cost we pay to keep the TUI inspectable, scriptable, and
+recoverable from any shell.
 
 ---
 
@@ -630,6 +847,28 @@ MU_SEND_DELAY_MS=300 mu agent send worker-1 "..."     # faster, less safe
 MU_SEND_DELAY_MS=1000 mu agent send worker-1 "..."    # slow remote
 ```
 
+If the target agent has a workspace that is **stale** (≥10 commits
+behind main — the same red bucket shown in `mu workspace list` and the
+TUI Workspaces card), `mu agent send` prints a yellow stderr warning
+but still sends by default:
+
+```bash
+WARN: worker-1 workspace is 14 commits behind main (≥10 = stale)
+Next:
+  Refresh first : mu workspace refresh worker-1 -w auth-refactor
+```
+
+Use `--strict-staleness` when a wrapper should refuse instead of
+warning:
+
+```bash
+mu agent send worker-1 "..." -w auth-refactor --strict-staleness
+```
+
+Agents without workspaces are skipped (common for read-only roles).
+`--json` output includes `staleness: null` or `{agentName,
+workstreamName, commitsBehindMain, isStale}`.
+
 ---
 
 ## 9. Read what an agent did
@@ -714,6 +953,29 @@ workstream prefix, `AgentNotFoundError` (exit 3, message names the
 workstream) when the named worker doesn't live there. Nothing is
 written on either failure.
 
+When `--for` targets an agent with a stale workspace (≥10 commits
+behind main), `mu task claim` warns on stderr and appends a refresh
+hint, but the claim still succeeds by default:
+
+```bash
+mu task claim build -w auth-refactor --for worker-2
+# stderr: WARN: worker-2 workspace is 14 commits behind main (≥10 = stale)
+# Next: Refresh first : mu workspace refresh worker-2 -w auth-refactor
+```
+
+Pass `--strict-staleness` to refuse the claim instead with typed
+`TaskClaimStaleWorkspaceError` (exit 4). This is useful for scripts
+that should never dispatch work onto a stale parent:
+
+```bash
+mu task claim build -w auth-refactor --for worker-2 --strict-staleness
+```
+
+`--json` output includes `staleness: null` or `{agentName,
+workstreamName, commitsBehindMain, isStale}`. Bare in-pane claims and
+`--self` claims do not run this check because they do not assign work
+to a named agent via `--for`.
+
 ### The orchestrator pattern: `--self`
 
 Not every action comes from a registered worker pane. Often the
@@ -723,7 +985,7 @@ a worker pane just for a 5-minute job. Two patterns split here:
 
 - **Worker** — a pane mu spawned (or you adopted). Has a row in the
   `agents` table. Identity = pane title. Claims with bare
-  `mu task claim <id>`. `tasks.owner` is set to the worker's name.
+  `mu task claim <id>`. `tasks.owner_id` points at the worker row.
 
 - **Actor** — anything that *causes* a state change. Includes
   workers, but also includes the orchestrator. May or may not have
@@ -745,13 +1007,13 @@ Three actionable next steps. Pick one based on intent:
 ```bash
 # Orchestrator does the work itself (most common):
 mu task claim some-task --self --evidence "trivial 5-line fix"
-#   -> tasks.owner stays NULL
+#   -> tasks.owner_id stays NULL
 #   -> agent_logs records 'task claim some-task by pi-mu --self (anonymous)'
 #   -> mu task show surfaces it as 'owner: (self: pi-mu)'
 
 # Orchestrator dispatches to a worker:
 mu task claim some-task --for worker-1
-#   -> tasks.owner = 'worker-1'
+#   -> tasks.owner_id points at worker-1
 
 # Orchestrator wants to BE a registered worker (rare):
 mu agent adopt %6441 -w <ws>  # only if pane is in mu-<ws> session
@@ -767,7 +1029,7 @@ to pane title, or `$USER`, or `unknown`):
 mu task claim deploy --self --actor deploy-bot --evidence "prod release"
 ```
 
-When `tasks.owner IS NULL` because of `--self`, `mu task show` looks
+When `tasks.owner_id IS NULL` because of `--self`, `mu task show` looks
 up the most recent `task claim` event for that task and surfaces it:
 
 ```
@@ -817,7 +1079,12 @@ verb stays useful on un-claimed tasks).
 Or, for ad-hoc shape, the SQL escape hatch:
 
 ```bash
-mu sql "SELECT author, content, created_at FROM task_notes WHERE task_id='design' ORDER BY id"
+mu sql "SELECT n.author, n.content, n.created_at
+        FROM task_notes n
+        JOIN tasks t ON t.id = n.task_id
+        JOIN workstreams w ON w.id = t.workstream_id
+       WHERE t.local_id='design' AND w.name='auth-refactor'
+       ORDER BY n.id"
 ```
 
 Convention for note content: `KEY: value` lines. Common keys are
@@ -845,6 +1112,18 @@ task re-enters the ready set (the canonical "hand it back to the
 pool" workflow). `--reopen` is the escape hatch for forcing `OPEN`
 from `CLOSED` / `REJECTED` / `DEFERRED`.
 
+When the closing actor has a per-agent workspace and that workspace
+has uncommitted edits, a successful close adds one extra `Next:` hint
+reminding the actor to commit before the next wave:
+
+```bash
+cd $(mu workspace path worker-1 -w auth-refactor) && git commit -am 'Design auth module'
+```
+
+The hint is best-effort: no workspace, a clean workspace, the `none`
+backend, or a failed VCS dirty check simply omit it. The same
+`nextSteps` entry is present in `--json` output.
+
 `--if-ready` is the umbrella-on-wave-done shape: an orchestrator
 fires `mu task close <umbrella> --if-ready` after each wave-task
 finishes (or unconditionally as a final action). It's a no-op while
@@ -885,8 +1164,9 @@ verbs don't cover: ad-hoc joins, manual recovery, exploring schema.
 The schema is 8 core tables (`workstreams`, `agents`, `tasks`,
 `task_edges`, `task_notes`, `agent_logs`, `vcs_workspaces`,
 `snapshots`), 5 archive tables (`archives`, `archived_tasks`,
-`archived_edges`, `archived_notes`, `archived_events`), 1 meta table
-(`schema_version`), plus three views (`ready`, `blocked`, `goals`):
+`archived_edges`, `archived_notes`, `archived_events`), 2 meta tables
+(`schema_version`, `machine_identity`), 1 sync table
+(`workstream_sync`), plus three views (`ready`, `blocked`, `goals`):
 
 ```bash
 mu sql "SELECT name FROM sqlite_master WHERE type IN ('table','view') ORDER BY type, name"
@@ -936,21 +1216,29 @@ one verify, one workspace recycle:
 # The dispatch-pipeline recipe: cycle until in_flight is empty.
 in_flight=( mufeedback-v03/foo mufeedback-v03/bar roadmap-v0-3/baz )
 while (( ${#in_flight[@]} > 0 )); do
-  closed=$(mu task wait "${in_flight[@]}" --first --timeout 90 --json \
-    | jq -r '.firing.qualifiedId // empty')
+  res=$(mu task wait "${in_flight[@]}" --first --timeout 90 --json)
+  closed=$(jq -r '.firing.qualifiedId // empty' <<<"$res")
   if [[ -z "$closed" ]]; then break; fi  # timeout or exit 6 — see below
 
-  # 1. Cherry-pick the worker's HEAD (the worker is named in the
-  #    nextSteps array — or use `mu task show` to look up).
-  worker=$(mu task show "${closed##*/}" -w "${closed%%/*}" --json | jq -r .ownerName)
+  worker=$(jq -r '.firing.owner // empty' <<<"$res")
   ws=${closed%%/*}
-  # `mu workspace commits --json` knows the workspace's parent_ref
-  # so this is one verb instead of `cd $(mu workspace path) && git log`.
-  sha=$(mu workspace commits "$worker" -w "$ws" --json | jq -r '.[-1].sha')
-  git cherry-pick "$sha"
+
+  # 1. Inspect, then run, the sha-pinned apply hint from nextSteps.
+  #    When the worker has commits since its fork point, the command is
+  #    `git cherry-pick <sha>` (or `<first>^..<last>` for multiple
+  #    commits). When the worker closed without committing, nextSteps
+  #    says so and points at manual `git diff` / `git apply` rescue.
+  apply=$(jq -r '.nextSteps[0].command' <<<"$res")
+  printf 'apply hint: %s\n' "$apply"
+  if [[ "$apply" == git\ cherry-pick* ]]; then
+    eval "$apply"
+  else
+    echo "manual rescue required; inspect the worker workspace before continuing"
+    break
+  fi
 
   # 2. Verify
-  npm run typecheck && npm run lint && npm run test && npm run build
+  npm run typecheck && npm run lint && npm run test:fast && npm run test && npm run build
 
   # 3. Refresh the workspace for the next dispatch (rebases onto
   #    fresh main WITHOUT killing the worker's LLM context). Default
@@ -1058,12 +1346,14 @@ mu sql "UPDATE tasks SET status='IN_PROGRESS'
 
 # What's blocking what (open tasks only) — same data as `mu task tree`
 # but as a flat join when you want a wider report. task_edges is keyed
-# by tasks.id, not local_id.
+# by tasks.id, not local_id; join workstreams to scope the report.
 mu sql "SELECT b.local_id AS blocked, t.local_id AS by_task
         FROM tasks b
+        JOIN workstreams w ON w.id = b.workstream_id
         JOIN task_edges e ON e.to_task_id = b.id
         JOIN tasks t ON t.id = e.from_task_id
-        WHERE t.status != 'CLOSED' AND b.status = 'OPEN'"
+        WHERE w.name='mufeedback-v03'
+          AND t.status != 'CLOSED' AND b.status = 'OPEN'"
 
 # Recursive CTE: every task that transitively blocks `launch` in a
 # given workstream (or use `mu task tree launch --json` for the same
@@ -1348,8 +1638,10 @@ failure leaves the registry intact (you can retry); if you only want
 the DB cleared, use `mu sql` directly:
 
 ```bash
-mu sql "DELETE FROM tasks  WHERE workstream='auth-refactor'"   # cascades
-mu sql "DELETE FROM agents WHERE workstream='auth-refactor'"
+mu sql "DELETE FROM tasks
+         WHERE workstream_id=(SELECT id FROM workstreams WHERE name='auth-refactor')"   # cascades
+mu sql "DELETE FROM agents
+         WHERE workstream_id=(SELECT id FROM workstreams WHERE name='auth-refactor')"
 ```
 
 Or nuke the entire DB:
@@ -1376,7 +1668,7 @@ subdirectory per source workstream:
 <bucket>/
   README.md           # bucket-level summary (every source-ws + dates + totals)
   INDEX.md            # union of all task tables; first column = source-ws
-  manifest.json       # bucketVersion: 2 + per-source-ws sha256 + per-task sha256
+  manifest.json       # bucketVersion: 2, manifest_version: 2, per-source-ws task summaries + sha256s
   <source-ws>/
     README.md         # per-source-ws (counts)
     INDEX.md          # per-source-ws (table of every task)
@@ -1386,12 +1678,21 @@ subdirectory per source workstream:
 Bucket exports are **additive**: `mu workstream export -w X --out
 <bucket>` creates the bucket scaffolding plus `X/` on first use,
 and a follow-up call with `-w Y --out <same-bucket>` appends a
-sibling `Y/` subdirectory without touching `X/`. Re-running with
+sibling `Y/` subdirectory without touching `X/`. The top-level
+`INDEX.md` is always the union from `manifest.sources`, so a later
+single-workstream refresh does not drop sibling workstreams from the
+bucket-wide task table. Re-running with
 the same `-w` is sha256-idempotent: only changed task files are
 rewritten (mtime preserved on identical files); tasks added since
 the previous export get fresh files; tasks deleted from the DB
 STAY on disk with a `> **Deleted from DB on <ts>**` banner so you
-never lose context that may already be git-blamed.
+never lose context that may already be git-blamed. `manifest_version:
+2` stores compact task summaries (`name`/`title`/`status`/`impact`/
+`effortDays`) beside the per-file sha256s; older v1 manifests are
+accepted on re-export; mu infers the missing summaries from existing
+per-task markdown when possible, falling back to placeholder values
+only if a task file is missing or unreadable, so the bucket remains
+appendable.
 
 ```bash
 # One-shot dump (bucket happens to contain just one source-ws)
@@ -1427,75 +1728,20 @@ Markdown only by design — no HTML/PDF, no embedded VCS, no
 cross-workstream merge. Operators can pandoc / `git init`
 themselves.
 
-### Cross-machine + collab — `mu workstream import`
+### Bucket exports are read-only artifacts
 
-The export above plus `mu workstream import <bucket-dir>` is the
-cross-machine + collaboration story. Push the bucket directory to
-git on machine A; pull it on machine B (or share it with a
-teammate); `mu workstream import` rebuilds the workstream + every
-task + edge + note locally.
+Bucket exports (`mu workstream export` and `mu archive export`) are
+now **read-only** artifacts for humans / git / docs. They are still
+excellent for grep, code review, project handoff, and historical
+write-ups, but they are no longer a load-bearing DB round-trip path.
 
-```bash
-# Machine A — author
-mu workstream export -w auth-refactor --out exports/auth
-(cd exports/auth && git init && git add . && git commit -m 'auth snapshot')
-git push origin main
+Use the typed surfaces for recovery and movement:
 
-# Machine B — pull + rehydrate
-git pull
-mu workstream import exports/auth                 # → workstream `auth-refactor`
-mu workstream import exports/auth --workstream auth-v2   # rename on import
-mu workstream import exports/auth --dry-run       # walk + parse + report; no DB writes
-mu workstream import exports/auth --json          # machine-readable per-source-ws result
-
-# Partial bucket import — multi-source bucket, but you only want
-# one (or a subset) restored. Two equivalent forms:
-mu workstream import exports/mu/roadmap-v0-2                  # Form 1 — per-source-ws subdir path
-mu workstream import exports/mu --source-ws roadmap-v0-2      # Form 2 — bucket + filter
-mu workstream import exports/mu --source-ws auth,ui           # Form 2 — X+Y, leave Z behind
-mu workstream import exports/mu --source-ws auth --source-ws ui  # repeat OR comma-separate; or both
-```
-
-Key properties:
-
-- **Markdown-only.** `.db` files are never imported (binary +
-  machine-specific). `mu undo` + snapshot files cover the
-  same-machine case; this verb covers cross-machine + collab.
-- **Per-source-ws transactional.** Each source-ws subdirectory is
-  imported in its own SQLite transaction. A failure in source A
-  rolls back A; sibling source B is unaffected.
-- **Refuses silent merges.** If the target workstream already
-  exists in the DB with tasks, the import errors with
-  `WorkstreamAlreadyExistsError`. Recourse:
-  `--workstream <new-name>` (single-source buckets only) or
-  destroy the existing workstream first.
-- **Owners reset.** Agents aren't exported, so the imported tasks
-  are unowned. The original owner name survives in the markdown
-  frontmatter — that's the audit trail.
-- **Tombstones skipped.** Files starting with the
-  `> **Deleted from DB on …**` banner (preserved by re-export of
-  a deleted task) are counted as `tombstones_skipped` and not
-  re-inserted.
-- **Forward edge refs are deferred.** `blocked_by` / `blocks`
-  arrays are validated against the bucket's id-set up front, then
-  inserted after every task in the source-ws is created.
-- **Partial import.** Multi-source buckets accept either a
-  per-source-ws subdir path (auto-detected via
-  `README.md` + `INDEX.md` + `tasks/` + a parent
-  `manifest.json` listing the subdir as a source) OR a
-  `--source-ws <names...>` filter on the bucket root
-  (variadic per `cli_audit_plurality_uniformity`: repeat,
-  comma-separate, or both). The two forms are equivalent for
-  single-source restores. `--workstream <new-name>` is allowed
-  whenever the resolved source-ws list has exactly one entry
-  (Form 1; or Form 2 with a single name); rejected for
-  multi-source filters. Passing `--source-ws` against a Form 1
-  per-source-ws subdir is refused (the subdir already implies one
-  source). A `--source-ws` name not in the bucket manifest raises
-  `ImportSourceNotInBucketError` (exit 4) and lists the valid
-  names. `--source-ws ',,'` (canonicalises to zero names) is a
-  `UsageError` (exit 2) so a typo doesn't silently fall back to
-  importing the entire bucket.
+| Need | Verb |
+| ---- | ---- |
+| Lossless un-archive | `mu archive restore <label> --as <new-ws> [--source <orig-ws>]` |
+| Laptop ↔ devserver handoff | `mu db export <file>` + `mu db import <file>` |
+| Manual recovery from a parked conflict | `mu db replay <sidecar>` |
 
 ---
 
@@ -1518,7 +1764,8 @@ mu archive add v0-3-wave -w roadmap-v0-3 --destroy   # cascade: archive THEN des
 mu archive list                                       # label | tasks | sources | created | last_added
 mu archive show v0-3-wave                             # detail card + per-source-workstream summary
 mu archive search 'oauth' [--label v0-3-wave]         # LIKE-search archived titles + note content (--limit N, --json)
-mu archive export v0-3-wave --out exports/v0-3-wave   # render every source-ws to a bucket directory (markdown)
+mu archive restore v0-3-wave --as restored-auth --source auth-refactor
+mu archive export v0-3-wave --out exports/v0-3-wave   # read-only markdown bucket for humans/git/docs
 ```
 
 Key properties:
@@ -1526,15 +1773,25 @@ Key properties:
 - **Globally-unique labels.** Archive labels live in their own
   namespace (separate from workstream names). Pick once, reuse
   across years.
-- **Additive accumulation.** `mu archive add <label> -w <ws>` is
-  idempotent at the (archive, source workstream) granularity.
-  Re-running on the same workstream is a no-op; adding a new task
-  to the source workstream and re-running picks up only the
-  delta. Two different workstreams under the same label coexist
-  as separate `(source_workstream, original_local_id)` rows.
+- **Snapshot-only accumulation.** `mu archive add <label> -w <ws>` is
+  idempotent at the (archive, source workstream) granularity and is
+  designed for end-of-milestone snapshot-and-destroy flows. Re-running
+  on the same workstream is task-incremental: newly-created tasks are
+  added, but notes and events for already-archived tasks stay pinned
+  to the original snapshot and are NOT refreshed. If you need a full
+  event-stream refresh for a source workstream, remove that source (or
+  delete/re-create the archive label) and add it again. Two different
+  workstreams under the same label coexist as separate
+  `(source_workstream, original_local_id)` rows.
 - **Outlives the source.** `archived_tasks.source_workstream` is
   TEXT (not an FK), so the source workstream can be destroyed and
   the archive's snapshot of it stays queryable forever.
+- **Lossless un-archive.** `mu archive restore <label> --as <new-ws>
+  [--source <orig-ws>]` copies tasks, edges, and notes directly from
+  `archived_*` tables into a fresh workstream. It refuses if `--as`
+  collides and snapshots before writing. Archives do not snapshot live
+  panes or the live event log, so agents, workspace paths, and
+  `agent_logs` are not restored.
 - **Reversible.** `mu archive delete <label> --yes` captures a
   snapshot first; `mu undo --yes` brings the whole archive back.
   `mu archive remove <label> -w <ws>` is the surgical version
@@ -1579,9 +1836,9 @@ mu archive add mu-v0-3 -w mufeedback-v03 --destroy
 - **No "default" / auto-archive.** `mu workstream destroy` does
   NOT auto-add to a fallback bucket. Either you picked a label
   deliberately or you didn't want one.
-- **No re-import.** The archive IS the workstream's afterlife.
-  If you need an archived task back as live work, copy it via
-  `mu sql` into a fresh workstream + `mu task add`.
+- **No bucket re-import.** The archive IS the workstream's afterlife.
+  If you need an archived source workstream back as live work, use
+  `mu archive restore <label> --as <new-ws> [--source <orig-ws>]`.
 - **No archive→archive merge / rename.** Operator-managed via
   `mu sql` if it ever matters.
 - **Snapshots vs archives are separate concerns.** Snapshots are
@@ -1591,6 +1848,71 @@ mu archive add mu-v0-3 -w mufeedback-v03 --destroy
 
 ---
 
+## 15.6 Multi-machine sync
+
+Use `mu db {export,import,replay}` when one user alternates a
+workstream between two machines (for example laptop ↔ devserver) over
+multi-day stretches. You own the transport: `rsync`, `scp`, Dropbox,
+git-lfs, USB, whatever moves a SQLite file plus its manifest.
+
+**Hard rule / user contract:** do not edit the same workstream on two
+machines concurrently. Other workstreams may keep moving locally, but
+for one workstream, finish or release in-flight claims before export:
+`mu agent list -w <ws>` shows current owners. `mu db import` does not
+carry owners because `owner_id` points at the machine-local `agents`
+table.
+
+```bash
+# Machine A — export the whole DB copy + ~/Dropbox/mu.db.manifest.json
+mu db export ~/Dropbox/mu.db --force
+# ship file (rsync / scp / Dropbox / git-lfs / USB)
+
+# Machine B — preview first, then commit
+mu db import ~/Dropbox/mu.db          # dry-run preview
+mu db import ~/Dropbox/mu.db --apply  # commits FAST_FORWARD / IMPORT rows
+```
+
+Dry-run output is a per-workstream decision table:
+
+```
+workstream   decision      delta
+-----------  ------------  -------------------------------
+auth         FAST_FORWARD  source 42, local 39, last_synced 39
+docs         IDENTICAL     source 12, local 12, last_synced 12
+local-only   LOCAL_AHEAD   source 0,  local 7,  re-export from this machine
+experiment   CONFLICT      source 55, local 58, needs --force-source
+```
+
+(The actual CLI also prints the numeric columns separately:
+`source_seq`, `local_seq`, `last_synced`, and `needs`.)
+
+Five case branches exist: `IDENTICAL` / `FAST_FORWARD` /
+`LOCAL_AHEAD` / `CONFLICT` / `IMPORT` (source-only or clean-machine
+import). `LOCAL_AHEAD` means the incoming file is stale for that
+workstream; re-export from this machine instead of applying it.
+`CONFLICT` means both sides advanced since the last sync and mu
+refuses by default.
+
+Recovery from an accidental concurrent edit is intentionally sharp:
+
+```bash
+mu db import ~/Dropbox/mu.db --apply --force-source
+# prints a parked loser like:
+# <state-dir>/divergence/auth-2026-05-14T10:00:00.000Z-a1b2c3d4.db
+
+mu db replay <state-dir>/divergence/auth-2026-05-14T10:00:00.000Z-a1b2c3d4.db
+mu db replay <state-dir>/divergence/auth-2026-05-14T10:00:00.000Z-a1b2c3d4.db --task local_fix --apply
+mu db replay <state-dir>/divergence/auth-2026-05-14T10:00:00.000Z-a1b2c3d4.db --all --apply
+```
+
+`--force-source` replaces the whole local workstream from the source
+file, but first parks the local divergent state as a divergence
+sidecar. `mu db replay` is the manual cherry-pick tool for that
+sidecar; it is dry-run by default, idempotent, and refuses when the
+same `local_id` exists locally with diverged content.
+
+---
+
 ## 16. One-shot demo script
 
 Copy-pasteable, end-to-end. Wipes any prior `~/.local/state/mu/mu.db`.
@@ -1611,8 +1933,8 @@ mu agent spawn worker-1 --workstream demo --cli sh
 mu agent spawn worker-2   --workstream demo --cli sh
 
 # Assign + observe
-mu sql "UPDATE tasks SET owner='worker-1', status='IN_PROGRESS' WHERE local_id='design'"
-mu --workstream demo
+mu task claim design -w demo --for worker-1 --evidence "demo assignment"
+mu state -w demo
 
 # Watch live (Ctrl+b d to detach)
 tmux attach -t mu-demo
@@ -1638,8 +1960,8 @@ rm -f ~/.local/state/mu/mu.db
    shared deps.
 
 3. **Agents claim tasks via their pane title — zero config.**
-   `mu task claim foo` from inside `worker-1`'s pane sets `tasks.owner='worker-1'`
-   atomically. mu reads the pane title via
+   `mu task claim foo` from inside `worker-1`'s pane sets the task's
+   `owner_id` to the `worker-1` agent row atomically. mu reads the pane title via
    `tmux display-message -t $TMUX_PANE -p '#{pane_title}'`, set on
    spawn. Two agents cannot claim the same task.
 
@@ -1649,9 +1971,9 @@ service of those three.
 
 ---
 
-## What's NOT in 0.3.0 (and how to work around it)
+## What's NOT in 0.4.1 (and how to work around it)
 
-<a id="whats-not-in-030-and-how-to-work-around-it"></a>
+<a id="whats-not-in-050-and-how-to-work-around-it"></a>
 
 The full roadmap with promotion criteria lives in
 [ROADMAP.md](ROADMAP.md). The short list of gaps you might hit
@@ -1660,13 +1982,13 @@ in real use:
 | Want                                          | Workaround                                                              | Status        |
 | --------------------------------------------- | ----------------------------------------------------------------------- | ------------- |
 | Multi-CLI status detection (per-CLI prompts)  | Braille spinner fallback (`f68838f`) covers pi/pi-meta + every TUI wrapper using standard spinner glyphs. Per-CLI permission-prompt patterns still pi-only. | partially shipped |
-| Pi extension (typed tools, HUD, wakeups)      | `mu state --hud` covers the HUD use-case (run via `watch` / `tmux display-popup` / `status-right`). Other extension tools deferred. | partially shipped |
+| Pi extension (typed tools, HUD, wakeups)      | `mu state --tui` (interactive) covers the dashboard use-case; plain `mu state` (static) is the `watch` / `tmux display-popup` / `status-right` substrate. Other extension tools deferred. | partially shipped |
 | Markdown agent-definition discovery           | Spawn accepts `--cli` and `--command` directly; no template registry    | dropped       |
 | `mu run script.ts` (JS DSL)                   | Use `--json` + bash + jq                                                | rejected      |
 | Sync to GitHub Issues / Linear / Asana        | Not in scope; explicitly rejected                                       | —             |
-| ~~`mu task blocked`~~ (removed; the `blocked` SQL view is the abstraction) | `mu sql "SELECT local_id, status, title FROM blocked WHERE workstream='X'"` | removed-with-recipe |
-| ~~`mu task goals`~~ (removed; same shape as `blocked` — view is the abstraction) | `mu sql "SELECT local_id, status, title FROM goals WHERE workstream='X'"` | removed-with-recipe |
-| ~~`mu task search <pat>`~~ (removed; case-insensitive LIKE is one SQL line) | `mu sql "SELECT local_id, status, title FROM tasks WHERE workstream='X' AND LOWER(title) LIKE '%pat%'"` (add `LEFT JOIN task_notes` for the old `--in-notes`; drop the `WHERE workstream=` clause for the old `--all`) | removed-with-recipe |
+| ~~`mu task blocked`~~ (removed; the `blocked` SQL view is the abstraction) | `mu sql "SELECT b.local_id, b.status, b.title FROM blocked b JOIN workstreams w ON w.id=b.workstream_id WHERE w.name='X'"` | removed-with-recipe |
+| ~~`mu task goals`~~ (removed; same shape as `blocked` — view is the abstraction) | `mu sql "SELECT g.local_id, g.status, g.title FROM goals g JOIN workstreams w ON w.id=g.workstream_id WHERE w.name='X'"` | removed-with-recipe |
+| ~~`mu task search <pat>`~~ (removed; case-insensitive LIKE is one SQL line) | `mu sql "SELECT t.local_id, t.status, t.title FROM tasks t JOIN workstreams w ON w.id=t.workstream_id WHERE w.name='X' AND LOWER(t.title) LIKE '%pat%'"` (add `LEFT JOIN task_notes` for the old `--in-notes`; drop the workstream join/filter for the old `--all`) | removed-with-recipe |
 
 Anything in this table that bites you in real use is a candidate
 for **promotion**. Criteria: proven friction in ≥2 real workflows +