@martintrojer/mu 0.3.1 → 0.4.0

package/docs/USAGE_GUIDE.md

@@ -1,26 +1,26 @@
 # 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-track).
 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 wave (pre-1.0). ~60 typed verbs across 8
 > 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
+> `--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 v7 (v5 surrogate INTEGER PKs + per-workstream
 > UNIQUE on operator-facing names; v6 added the `archive_*`
 > family additively; v7 dropped the dead `approvals` table).
 > 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.0](#whats-not-in-040-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 +33,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)
@@ -47,7 +48,7 @@ current verb list is in `## CLI — complete verb list` of
 15.5. [Archives — cross-workstream preservation](#155-archives--cross-workstream-preservation-of-task-graphs)
 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.0](#whats-not-in-040-and-how-to-work-around-it)
 19. [Where to go from here](#where-to-go-from-here)
 
 ---
@@ -140,6 +141,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 +249,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 +357,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 +385,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.
+
+---
+
+## 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
 
-> **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).
+```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.
 
 ---
 
@@ -561,9 +776,9 @@ mu agent list -w auth-refactor   # surfaces orphans at the bottom
 # Orphan panes (1)
 #   %15 title=worker-2 cli=pi
 
-mu adopt %15 -w auth-refactor                    # adopt by pane id
-mu adopt worker-2 -w auth-refactor               # adopt by pane title (same effect)
-mu adopt %15 --name investigator -w auth-refactor  # adopt and rename the pane
+mu agent adopt %15 -w auth-refactor                    # adopt by pane id
+mu agent adopt worker-2 -w auth-refactor               # adopt by pane title (same effect)
+mu agent adopt %15 --name investigator -w auth-refactor  # adopt and rename the pane
 ```
 
 The pane title becomes the agent name (`mu`'s claim protocol
@@ -630,6 +845,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 +951,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 +983,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
@@ -737,7 +997,7 @@ If the orchestrator tries `mu task claim some-task` directly:
 conflict: claimer 'pi-mu' (pane %6441) is not a registered mu agent.
   Working directly?           Pass --self to attribute via log instead.
   Dispatching to a worker?    Pass --for <worker> to assign.
-  Want full registration?     Run: mu adopt %6441
+  Want full registration?     Run: mu agent adopt %6441
 ```
 
 Three actionable next steps. Pick one based on intent:
@@ -745,16 +1005,16 @@ 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 adopt %6441 -w <ws>      # only if pane is in mu-<ws> session
+mu agent adopt %6441 -w <ws>  # only if pane is in mu-<ws> session
 mu task claim some-task     # now works as a normal worker claim
 ```
 
@@ -767,7 +1027,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:
 
 ```
@@ -790,10 +1050,39 @@ mu task note design "DECISION: JWT, 24h expiry, refresh via cookie"
 mu task note design "FILES: src/auth.rs:45-120"
 ```
 
-Read them via the SQL escape hatch:
+Read them via the typed verb:
+
+```bash
+mu task notes design                          # all notes, oldest first
+mu task notes design --tail 3                 # only the last 3 (alias --last)
+mu task notes design --since 2026-01-01       # only notes after an ISO 8601 cutoff
+mu task notes design --since-claim            # only notes since the most recent
+                                              # 'task claim' event for this task
+                                              # (auto-resolved from agent_logs)
+mu task notes design --tail 5 --json          # collection envelope {items, count}
+```
+
+Filters compose: `--tail` slices the last N of whatever survived
+the timestamp filter. `--since` and `--since-claim` are mutually
+exclusive (both define a cutoff) — pick one. With no filters the
+output is unchanged from prior versions (every note, oldest-first).
+
+`--since-claim` is the orchestrator-friendly form: dispatch flows
+often drop a multi-screen SPEC note BEFORE claiming, then the
+worker appends progress notes AFTER the claim. `--since-claim`
+slices off the SPEC so you see only the worker's reports. If no
+claim event exists for the task, it degrades to no filter (so the
+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
@@ -821,6 +1110,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
@@ -912,21 +1213,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
@@ -934,6 +1243,10 @@ while (( ${#in_flight[@]} > 0 )); do
   #    overrides. Refuses on dirty WC; conflicts exit 5 with a `cd`
   #    hint to resolve in-place.
   mu workspace refresh "$worker" -w "$ws"
+  # Alt: `mu workspace recreate "$worker" -w "$ws"` does free + create
+  #      atomically — same shortcut, but throws away the worker's local
+  #      changes (the lossy escape: requires --force on a dirty WC).
+  #      Use when you don't care about replaying the worker's commits.
 
   # 4. Drop $closed from in_flight, dispatch the next task, repeat.
   in_flight=( "${in_flight[@]/$closed}" )
@@ -1030,12 +1343,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
@@ -1078,7 +1393,32 @@ Reconciliation runs on every `mu agent list` / `mu`. Three steps:
 3. **Surface orphan panes** — panes in the workstream's tmux session
    whose `pane.command` looks like an agent CLI (pi) but
    that aren't in the registry. **Not** auto-adopted; mu shows them
-   under "Orphan panes" and tells you `mu adopt <pane-id>` to register
+   under "Orphan panes" and tells you `mu agent adopt <pane-id>` to register
+
+### A worker is wedged on an unbounded tool subprocess
+
+A worker ran `find / -maxdepth 6 ...` (30-60 minutes on a populated
+home directory) or a busy-wait loop. `mu agent send` queues steering
+messages until the tool returns; `tmux send-keys C-c` against the
+pane doesn't propagate (the wrapping pi/claude/codex CLI catches it
+as TUI input). The escape hatch:
+
+```bash
+mu agent kick worker-1                       # SIGINT (graceful, default)
+mu agent kick worker-1 --signal SIGTERM      # polite escalation
+mu agent kick worker-1 --signal SIGKILL      # hammer
+```
+
+`mu agent kick` looks up the pane's TTY via `tmux display-message
+-p '#{pane_tty}'`, asks `ps -t <tty>` for the foreground process
+group (the row whose `stat` field contains `+`), and signals the
+whole pgrp directly. Refuses with `NoForegroundProcessError` when
+the foreground IS the wrapping CLI itself — use `mu agent close`
+to close the agent.
+
+Prevention: don't prompt workers to run filesystem-wide `find`,
+broad `grep -r /`, or unbounded busy-wait loops. Pass paths
+explicitly or scope to `$WORKSPACE`.
 
 ### You closed your terminal session
 
@@ -1219,6 +1559,19 @@ mu agent close reviewer-1
 `mu agent close` is idempotent: `killPane` swallows "pane already gone"
 errors; `deleteAgent` returns false (not throws) on a missing row.
 
+If the agent has a workspace, behaviour depends on its state:
+
+- **Clean** (no uncommitted changes AND no commits since fork) — the
+  workspace is silently auto-freed alongside the close, so a
+  `--workspace` spawn that did no real work doesn't make you type
+  `--discard-workspace` just to clean up.
+- **Dirty** (uncommitted changes OR commits since fork) — close refuses
+  with `WorkspacePreservedError` (exit 4). Two resolutions: (a) `mu
+  workspace free <agent>` first (optionally with `--commit` to capture
+  pending changes), then `mu agent close <agent>`; or (b) `mu agent
+  close <agent> --discard-workspace` to free both in one shot (lossy:
+  any work in the workspace is gone).
+
 ### Tear down the whole workstream
 
 `mu workstream destroy` is the symmetric counterpart of `mu workstream init`: it kills the
@@ -1282,8 +1635,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:
@@ -1310,7 +1665,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)
@@ -1320,12 +1675,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)
@@ -1399,7 +1763,7 @@ Key properties:
   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
+  exists in the DB, the import errors with
   `WorkstreamAlreadyExistsError`. Recourse:
   `--workstream <new-name>` (single-source buckets only) or
   destroy the existing workstream first.
@@ -1413,8 +1777,6 @@ Key properties:
 - **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.
-- **Pre-0.3 layouts refuse.** Buckets without a `bucketVersion: 2`
-  manifest throw `ImportLegacyLayoutError` with a re-export hint.
 - **Partial import.** Multi-source buckets accept either a
   per-source-ws subdir path (auto-detected via
   `README.md` + `INDEX.md` + `tasks/` + a parent
@@ -1462,12 +1824,16 @@ 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.
@@ -1547,8 +1913,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
@@ -1574,8 +1940,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.
 
@@ -1585,9 +1951,9 @@ service of those three.
 
 ---
 
-## What's NOT in 0.3.0 (and how to work around it)
+## What's NOT in 0.4.0 (and how to work around it)
 
-<a id="whats-not-in-030-and-how-to-work-around-it"></a>
+<a id="whats-not-in-040-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
@@ -1596,13 +1962,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 +