@mu-crew/mu 3.2.0 → 3.3.0

package/docs/guide/delegate.md

@@ -0,0 +1,87 @@
+# How to delegate a one-off task
+
+## Delegate from pi
+
+`mu link pi` installs the `mu_delegate` and `mu_delegate_cancel` tools
+in every pi session. Ask pi in plain words:
+
+- "Delegate a review of src/x.ts to a helper."
+- "Have three helpers investigate A, B, and C."
+
+pi calls `mu_delegate`. It spawns a pi agent in the reserved `scratch`
+workstream and returns at once with the delegate's name and attach
+command. The answer arrives later as a follow-up message; do not poll.
+Delegates called in one turn run in parallel.
+
+| Option | Meaning |
+| ------ | ------- |
+| `task` (required) | All the context. The delegate starts empty. |
+| `label` | Names the delegate: `review` gives `delegate-review`. |
+| `brief` | Ad hoc persona or ground rules, sent first. Not enforced. |
+| `cwd` | Start directory. Default: the caller's. Must exist. |
+| `timeout` | Seconds to wait for the answer (default 3600). After it, the answer does not come back; the follow-up gives the `mu agent wait` command. |
+| `workspace` | Own VCS checkout, for delegates that edit files. The follow-up names its path. It isolates repository edits only. |
+| `cli` | Key for `$MU_<CLI>_COMMAND` (default `pi`), e.g. a cheaper model. |
+| `keep` | Keep the pane after it finishes, to talk to it again. |
+
+- Watch or steer: run the attach command.
+- Stop: `mu_delegate_cancel`, or `mu agent abort <name> -w scratch`.
+- The pane closes after a clean finish; died or timed-out panes stay
+  as evidence.
+- pi's footer shows how many delegates this session is waiting on.
+- Each delegate costs a pane and a pi process.
+
+`MU_DELEGATE=0` hides the tool ([env vars](../reference/env.md)).
+
+## Delegate without pi
+
+From a script or other shell, run what the tool runs:
+
+```bash
+mu agent spawn helper-1 -w scratch
+mu agent send helper-1 -w scratch --fresh 'Investigate why foo.spec.ts fails. Report the cause.'
+mu agent wait helper-1 -w scratch --json
+```
+
+Use `--fresh`: a plain send to a reused agent carries the previous
+task's context.
+
+`mu agent wait` fires when the agent leaves busy (including to
+`needs_input`), never on an already idle agent. For pi, the `--json`
+row carries:
+
+- `outcome`: `done`, `empty`, `died`, `timeout`, or `pending`.
+- `lastText`: the final message, capped at 64 KiB.
+
+Exit codes: `0` met, `5` timeout, `6` pane died. Non-pi agents have no
+`lastText`; read the pane with `mu agent read helper-1 -w scratch -n 80`.
+
+## Keep a helper
+
+Pass `keep: true`, or spawn a named agent in `scratch`. It is created
+on first spawn, needs no tasks, and cannot be `init`ed.
+
+```bash
+mu agent spawn helper -w scratch
+mu agent send helper -w scratch 'Watch CI on PR 1234 and tell me when it is green'
+mu agent read helper -w scratch -n 50
+mu agent close helper -w scratch
+```
+
+A watcher's chat context does not survive compaction. Log each tick
+under your own `--kind`; read the latest entry on the next:
+
+```bash
+mu log -w scratch --kind pr-state 'pr=1234 sha=abc ci=red -> spawned fixer-1'
+mu log -w scratch --kind pr-state -n 1 --json
+```
+
+Act only on change. `--since <seq>` replays entries a dead watcher
+missed.
+
+## When to stop delegating
+
+Dependencies, several agents, or review need a real workstream: see
+[Getting started](getting-started.md) and
+[How to dispatch work](dispatch.md). There, `mu task wait` keys on the
+task and has `--on-stall`.

package/docs/guide/dispatch.md

@@ -0,0 +1,144 @@
+# How to dispatch work to a worker
+
+This guide assumes you finished [Getting started](getting-started.md).
+The agent-facing loop and its traps are in
+[recipes/orchestrator-loop.md](../../skills/mu/recipes/orchestrator-loop.md). For several workers in
+one repo, see [waves](../../skills/mu/recipes/waves.md); for runs that
+last hours, see [long runs](../../skills/mu/recipes/long-run.md).
+
+## Claim before you send
+
+Always claim the task for the worker before the first send, even for a
+one-shot reviewer:
+
+```bash
+mu task claim build -w auth --for worker-1
+```
+
+`mu task wait` watches tasks, and the reaper returns a claimed task to
+`OPEN` when its pane dies. An unclaimed task gets neither. If no task
+exists, create one with `mu task add --note '<brief>'`.
+
+- `--for` takes a worker name or a qualified `<workstream>/<name>`.
+  The worker stays in its own workstream. Only the ownership crosses.
+- Inside a worker's pane, bare `mu task claim <id>` uses the pane
+  title as the worker name.
+- To do the task yourself, use `mu task claim <id> --self`.
+
+## Pick the send mode
+
+For a pi agent, `mu agent send` goes through the agent's control
+socket. Pick the mode by what the agent is doing:
+
+| Situation | Command |
+| --------- | ------- |
+| New task, any state | `mu agent send worker-1 --fresh '<brief>'` |
+| Busy, and you want to interrupt the current run | `mu agent send worker-1 --steer '<text>'` |
+| Answering a question, or adding to the same task | `mu agent send worker-1 '<text>'` |
+
+- `--fresh` starts a new pi session and sends the prompt into it as
+  one operation. It refuses with exit 4 while pi is busy. Run
+  `mu agent abort` first, or pass `--force` to drop the running turn.
+- Never send `/new` and then the prompt as two sends to pi. The prompt
+  can land during the reset and vanish.
+- A plain send to a busy agent queues as a follow-up.
+- `/new`, `/reload` and `/compact [instructions]` run inside pi through
+  the socket and report pi's answer (for example `Nothing to compact`).
+  They refuse with exit 4 while pi is busy; `--force` overrides. Any
+  other slash command exits 2; add `--via mux` to type it into the pane.
+- If the socket does not answer, the send fails with exit 1 and
+  pastes nothing. `--via mux` pastes into the pane on purpose.
+
+After a claim, spawn, or wait, the `Next:` block prints the right send.
+
+### Non-pi agents
+
+Agents other than pi have no control socket, so mu pastes the text
+into the pane. To start a new session, send `/new` (codex: `/clear`),
+then the prompt. If mu prints `warning: ... was NOT submitted`, the
+agent has not seen the text. Read the pane before you wait. On a slow
+tmux link, raise `MU_SEND_DELAY_MS` (default 500 ms).
+
+## Write the brief
+
+Put the full brief in a task note, so it survives context compaction
+and the next agent can read it. Send a short prompt that points at it:
+
+```bash
+mu task note build -w auth 'FILES: src/auth/\nVERIFY: npm test\nSCOPE: no schema changes'
+mu agent send worker-1 -w auth --fresh 'Work on build. Read: mu task notes build -w auth'
+```
+
+End the brief with the exact final action, for example:
+
+```text
+⚠️ FINAL ACTION
+git commit -am '...' THEN
+mu task close build -w auth --evidence '...'
+```
+
+Single-quote prompts that contain `$` or backticks. To see only what the worker wrote after the claim, run
+`mu task notes build -w auth --since-claim`.
+
+## Give each worker a workspace
+
+`mu agent spawn --workspace` creates a jj, sl, or git worktree for the
+agent (`cp -a` outside a repo). You cherry-pick from it.
+
+Refresh the workspace between tasks. The rebase keeps the agent's pi
+context:
+
+```bash
+mu workspace refresh worker-1 -w auth
+```
+
+It rebases onto the remote's main (`origin/HEAD`); without a remote,
+pass `--from main`. It refuses on a dirty tree. On a conflict it exits 5
+with a `cd` hint. To throw the workspace away instead, run
+`mu workspace free worker-1 -w auth`.
+
+Claim and send warn when the worker's workspace is 10 or more commits
+behind main. `--strict-staleness` makes that a refusal (exit 4).
+
+## Wait for the first task to close
+
+Wait on every in-flight task and handle the first one that closes:
+
+```bash
+mu task wait auth/build auth/docs --first --on-stall exit --json
+```
+
+- `--first` prints the closed ref and fills `firing` in `--json`.
+  `--any` leaves `firing` null even on success.
+- `nextSteps[0]` is the cherry-pick command for the worker's new
+  commits. If the worker closed without committing, it says so.
+- Exit codes: `0` met, `5` timeout, `6` the owner's pane died,
+  `7` the owner sat in `needs_input` for `--stuck-after` seconds
+  (default 300).
+
+Exit 7 has several causes: the worker finished but did not close, it
+asked a question, or it hit a prompt. In each case, run
+`mu agent read <owner>` first.
+
+Pipeline the work: merge one task, run your tests on the merged tree,
+then dispatch the next task. Waiting for a whole wave hides partial
+progress.
+
+## Close and park tasks
+
+```bash
+mu task close spike -w auth --as wontfix --why "superseded by v2"
+mu task close umbrella -w auth --if-ready
+mu task park polish -w auth --why "after the release"
+mu task release build -w auth
+```
+
+- Closed substates other than `done` need `--why`. Every `CLOSED`
+  substate satisfies a blocker.
+- `--if-ready` closes only when every blocker is closed. Otherwise it
+  lists the open blockers and exits 0.
+- A parked task leaves the ready set, and its dependents keep waiting.
+- `release` clears the owner and returns `IN_PROGRESS` to `OPEN`.
+
+To wait on something outside the repo, such as an upstream release,
+block on a placeholder task and close it when the thing lands.

package/docs/guide/getting-started.md

@@ -0,0 +1,180 @@
+# Getting started
+
+In this tutorial we install mu, plan two tasks where one blocks the
+other, hand the first task to a pi worker, and merge its commit. It
+takes about ten minutes.
+
+You need Node.js, the pi coding agent, tmux 3.0
+or later, and a git repository to work in. Run every command from
+inside a tmux session, in the root of that repository.
+
+## Install mu and link pi
+
+First, install mu and connect it to pi:
+
+```bash
+npm i -g @mu-crew/mu
+mu link pi
+mu doctor
+```
+
+`mu link pi` installs the mu pi extension and the mu skill. In the
+output of `mu doctor`, the extension, skill, and `ctl` rows say `ok`.
+If pi was already running, restart it so it loads the extension.
+
+## Create a workstream
+
+A workstream is one project: one tmux session, its agents, and its
+task graph.
+
+```bash
+mu workstream init auth
+```
+
+```
+Created workstream auth (mux session mu-auth)
+Next:
+  Attach the session : tmux attach -t mu-auth
+  ...
+```
+
+Every verb ends with a `Next:` block of follow-up commands. We use
+them as we go.
+
+## Plan two tasks
+
+Now add two tasks. Each needs an impact (1–100) and an effort in
+days. `--blocked-by` makes `build` wait for `design`:
+
+```bash
+mu task add design -w auth -t "Design the auth module" -i 80 -e 2
+mu task add build  -w auth -t "Build the auth module"  -i 80 -e 5 --blocked-by design
+mu task next -w auth
+```
+
+```
+┌────────┬────────┬────────────────────────┬────────┬────────┬──────┬───────┐
+│ name   │ status │ title                  │ impact │ effort │ ROI  │ owner │
+├────────┼────────┼────────────────────────┼────────┼────────┼──────┼───────┤
+│ design │ OPEN   │ Design the auth module │ 80     │ 2      │ 40.0 │ —     │
+└────────┴────────┴────────────────────────┴────────┴────────┴──────┴───────┘
+```
+
+Only `design` is ready. `build` appears when `design` closes.
+
+## Spawn a worker
+
+Spawn a pi agent with its own git worktree:
+
+```bash
+mu agent spawn worker-1 -w auth --workspace
+```
+
+```
+Spawned worker-1 (pi) in window worker-1 of mu-auth, pane %15 with auto-workspace
+  workspace: ~/.local/state/mu/workspaces/auth/worker-1 (git)
+```
+
+The worker runs in a new window of the `mu-auth` session. To watch
+it, run `tmux attach -t mu-auth`. Detach with `Ctrl+b d`.
+
+## Claim the task for the worker
+
+Assign the task before you send any text. The claim is what
+`mu task wait` watches.
+
+```bash
+mu task note design -w auth 'SCOPE: write docs/auth.md with the token design'
+mu task claim design -w auth --for worker-1
+```
+
+```
+Claimed design for worker-1 (OPEN → IN_PROGRESS)
+```
+
+## Send the task
+
+`--fresh` starts a new pi session and sends the prompt into it in
+one step:
+
+```bash
+mu agent send worker-1 -w auth --fresh 'Work on task design. Read: mu task notes design -w auth.
+When done: git commit -am "Design auth", then mu task close design -w auth --evidence "<what you verified>"'
+```
+
+The worker reads its notes, does the work, commits in its worktree,
+and closes the task.
+
+## Wait for the task to close
+
+```bash
+mu task wait design -w auth --first --on-stall exit
+```
+
+```
+auth/design
+any-of 1 reached CLOSED in 41094ms
+Next:
+  Cherry-pick worker-1's commit onto your branch : git cherry-pick 26278f1...
+  Refresh worker-1's workspace onto current main : mu workspace refresh worker-1 -w auth
+```
+
+The exit code tells you what happened:
+
+| Exit | Meaning | Next move |
+| ---- | ------- | --------- |
+| `0` | the task closed | merge the work |
+| `5` | `--timeout` expired (default 600 s) | wait again |
+| `6` | the worker's pane died and the task went back to `OPEN` | spawn and claim again |
+| `7` | the worker sat in `needs_input` for 5 minutes | `mu agent read worker-1 -w auth`, then answer it |
+
+Without `--on-stall exit`, a stalled worker only prints a warning and
+the wait keeps running.
+
+## Merge the commit
+
+Run the cherry-pick command from the `Next:` block, then run your
+tests on the result:
+
+```bash
+git cherry-pick 26278f1
+```
+
+Before the next task, rebase the worker's worktree onto the new main.
+The worker keeps its pi context:
+
+```bash
+mu workspace refresh worker-1 -w auth
+```
+
+The default target is the remote's main branch (`origin/HEAD`). In a
+repository without a remote, name the branch: `--from main`.
+
+## Check the graph
+
+```bash
+mu task next -w auth
+```
+
+`build` is ready now. You can claim it for `worker-1` and repeat the
+claim, send, wait, and merge steps.
+
+## Close the worker
+
+When you are done, free the worktree and close the agent:
+
+```bash
+mu workspace free worker-1 -w auth
+mu agent close worker-1 -w auth
+```
+
+`mu agent close` refuses while the worktree has commits or edits that
+mu has not freed. That protects work you have not merged.
+
+## Next steps
+
+- [Dispatch work to a worker](dispatch.md) covers more than one
+  worker and the `--fresh`, `--steer`, and plain send choices.
+- [Use the TUI dashboard](tui.md): run bare `mu` to see every
+  workstream at once.
+- [Clean up](cleanup.md) when the workstream is finished.

package/docs/guide/recovery.md

@@ -0,0 +1,135 @@
+# How to recover from a broken state
+
+Start with `mu doctor`. Each row that is not `ok` prints the command
+that fixes it. mu reports and never cleans up for you, because an
+orphan directory can hold the only copy of uncommitted work. Agents
+read the same rules in
+[recipes/recovery.md](../../skills/mu/recipes/recovery.md).
+
+```bash
+mu doctor           # exit 0 healthy, 5 on drift
+mu doctor --deep    # rebuild the ops log and diff every field
+mu doctor --disk    # add per-workspace byte usage
+```
+
+## An agent's pane died
+
+Run `mu agent list` or `mu state`. Each run reconciles the registry
+with the multiplexer:
+
+- An agent row whose pane is gone is a ghost. mu deletes the row, and
+  its `IN_PROGRESS` task returns to `OPEN`. A `mu task wait` on that
+  task exits 6.
+- A pane in the session that runs an agent CLI but has no row is an
+  orphan. mu lists it with an adopt hint and does not adopt it.
+
+To register an orphan pane, or a pi you started by hand:
+
+```bash
+mu agent adopt %15 -w auth
+mu agent adopt %15 -w auth --name investigator
+```
+
+The pane title becomes the agent name. The pane must be in the
+`mu-<workstream>` session. An adopted pi has no control socket until
+you restart it with the `MU_CTL_SOCK` path that `adopt` prints.
+
+## A pi agent shows `ctl missing` or `ctl refused`
+
+mu reaches pi agents only through the control socket, and never falls
+back to pasting.
+
+| State | Means | Fix |
+| ----- | ----- | --- |
+| `ctl missing` | no socket: the extension is not loaded | run `mu link pi`, then respawn the agent |
+| `ctl refused` | the socket exists but does not answer | respawn the agent; for a remote agent, check the ssh forward |
+| `extension X older than installed Y` | pi loaded an older mu build | type `/reload` in the pane, or respawn |
+
+To send `/reload` without attaching:
+
+```bash
+mu agent send worker-1 -w auth '/reload' --via mux
+```
+
+`/reload` keeps the pi session. A `send --fresh` or `abort` against an
+outdated extension fails with exit 4 and prints the same two fixes.
+
+## A new pi agent is stuck at `needs_input`
+
+pi asks whether to trust a project folder on first start. Run
+`/trust` in the pane once, or spawn with
+`--command 'pi --approve'`. `--approve` trusts every directory,
+including workspace forks, so use it only on your own code.
+
+## You closed your terminal
+
+The tmux session keeps running. Reattach with `tmux attach -t mu-auth`.
+Every `mu` command is a short process that reads the DB, so nothing
+needs restarting.
+
+## You ran the wrong command
+
+Every action is one group of ops. Find it, preview the inverse, then
+apply:
+
+```bash
+mu undo                   # list recent groups
+mu undo 6380dd3d          # preview
+mu undo 6380dd3d --yes    # apply
+```
+
+- Any unique prefix of a group id works.
+- The undo is its own group, so undoing it again is redo.
+- If later work changed the same fields, undo exits 4 and names the
+  conflict. `--force --yes` overrides and discards the newer work.
+- Undo restores rows only. Killed panes and freed workspace
+  directories do not come back.
+
+## `mu doctor` reports drift
+
+Drift means the ops log and the live tables disagree. `--deep` names
+the table, key, and field. Do not rebuild by reflex: if capture missed
+a write, the live table holds real work that a rebuild would discard.
+
+```bash
+mu db backup /tmp/mu-drift-evidence.db     # 1. keep the evidence
+mu rebuild /tmp/mu-rebuilt.db              # 2. replay the log into a new file
+MU_DB_PATH=/tmp/mu-rebuilt.db mu sql "SELECT local_id, title FROM tasks"   # 3. compare
+```
+
+Decide which side is right, then report the drift as a bug with the
+named field. `mu rebuild` never writes in place. It prints the swap
+command.
+
+## The `disk` section of `mu doctor` warns
+
+| Row | Means |
+| --- | ----- |
+| `ws-rows` | a workspace row whose directory is gone; the next send fails in the VCS |
+| `ws-dirs` | a workspace directory with no row; it blocks the next `--workspace` spawn with that name |
+| `ws-empty` | a workstream directory with no checkouts |
+| `db-copies` | stray `mu.db*` files that nothing reads |
+| `exports` | output left by the removed export verb |
+| `locks` | lock directories older than one hour, from a spawn or flush that died |
+
+To list workspace orphans with cleanup commands, run
+`mu workspace orphans -w auth`. Remove a git-backed orphan with
+`git worktree remove --force <path>` from the project root.
+
+## Rename a workstream
+
+There is no rename verb. Every child table cascades on the name:
+
+```bash
+mu sql "UPDATE workstreams SET name='auth-refactor' WHERE name='auth-refator'"
+tmux rename-session -t mu-auth-refator mu-auth-refactor
+```
+
+Names start with a lowercase letter, use letters, digits, `_`, or
+`-`, are at most 32 characters, and do not start with `mu-`.
+
+## Report a bug
+
+Include the exact command, its full output, the `environment` block of
+`mu doctor`, and your platform. To reproduce without your real data,
+set `MU_DB_PATH=/tmp/mu-debug.db` and `MU_SYNC_DIR=` (empty).

package/docs/guide/remote.md

@@ -0,0 +1,74 @@
+# How to run a worker on another machine
+
+The pane is local and the pi process is remote. mu runs no ssh
+itself. `mu agent remote-env` prints the ssh pieces, and you put them
+in the spawn command. The full recipe, with recording, collecting,
+and the traps, is in
+[skills/mu/recipes/remote-workers.md](../../skills/mu/recipes/remote-workers.md).
+Read it before your first remote spawn.
+
+## Prepare the host
+
+On the remote host:
+
+1. Install mu and run `mu link pi`, so the remote pi loads the mu
+   extension.
+2. Allow unix-socket forwards in the host's sshd:
+   `AllowStreamLocalForwarding yes`.
+3. Create the worker's checkout yourself. `--workspace` works only
+   for local agents:
+
+   ```bash
+   ssh dev 'git -C ~/repo worktree add ~/ws/worker-1'
+   ```
+
+Use one orchestrator DB on your machine. Do not run a second mu on the
+host for the same work: task ownership points into your local
+`agents` table.
+
+## Spawn the agent
+
+```bash
+eval "$(mu agent remote-env worker-1 -w auth --shell)"   # sets MU_SSH_ARGS, MU_REMOTE_ENV
+mu agent spawn worker-1 -w auth --command \
+  "ssh $MU_SSH_ARGS dev -t 'cd ~/ws/worker-1 && $MU_REMOTE_ENV \$SHELL -ilc \"pi --approve\"'"
+```
+
+What each part does:
+
+- `MU_SSH_ARGS` forwards the remote pi's control socket to the local
+  path mu connects to. It includes `-o ControlMaster=no -o
+  ControlPath=none`, because a multiplexed ssh connection never binds
+  the local end of the forward.
+- `MU_REMOTE_ENV` sets the agent's identity inside the remote shell.
+  tmux `-e` variables do not cross the ssh hop.
+- `$SHELL -ilc` starts pi in an interactive login shell, so the
+  remote `~/.zshrc` or `~/.bashrc` loads PATH and provider keys.
+  Without it, ssh's non-interactive shell skips them and pi can die at
+  startup.
+- `pi --approve` skips pi's project-trust prompt. It trusts whatever
+  directory the pane starts in, so use it only on your own code.
+
+If the spawn reports `ctl refused`, check `AllowStreamLocalForwarding`
+on the host.
+
+## Drive it like a local agent
+
+Claim, `mu agent send --fresh`, `mu agent wait`, and `mu agent abort`
+all go through the forwarded socket and behave as they do locally:
+
+```bash
+mu task note build -w auth 'REMOTE: dev:~/ws/worker-1'
+mu task claim build -w auth --for worker-1
+mu agent send worker-1 -w auth --fresh 'Work on build. Read: mu task notes build -w auth'
+```
+
+The `REMOTE: <host>:<path>` note line is how `mu state` lists remote
+workers. Collect the work by fetching from the remote checkout:
+
+```bash
+git fetch "ssh://dev/~/ws/worker-1" HEAD && git cherry-pick FETCH_HEAD
+```
+
+`mu agent kick` does not reach a remote process. Use `mu agent abort`,
+or close the pane.

package/docs/guide/sql.md

@@ -0,0 +1,76 @@
+# How to query and script mu
+
+Use typed verbs with `--json` first. Use `mu sql` for ad-hoc joins,
+reports, and repairs that no verb covers.
+
+## Script with `--json`
+
+Every verb takes `--json`.
+
+- Collection reads print `{"items": [...], "count": N}`.
+- Single objects, such as `mu task show`, print an object with named
+  fields.
+- `mu sql --json` prints a bare array of rows.
+- `mu log --tail --json` prints one JSON object per line.
+- Errors go to stderr as `{error, message, nextSteps, exitCode}`.
+
+```bash
+mu state -w auth --json
+mu task list -w auth --json | jq '.count'
+```
+
+Exit codes: `2` usage error, `3` not found, `4` conflict, `5`
+timeout or a multiplexer, VCS, or drift failure, `6` reaped pane,
+`7` stall.
+
+## Read the schema
+
+The schema has 11 tables and 3 views (`ready`, `blocked`, `goals`).
+Four tables travel between machines: `workstreams`, `tasks`,
+`task_edges`, and `task_notes`. List them all:
+
+```bash
+mu sql "SELECT type, name FROM sqlite_master WHERE type IN ('table','view') ORDER BY type, name"
+```
+
+Task ids (`local_id`) are unique per workstream only. Join
+`workstreams` in every query, or you hit a same-named task elsewhere.
+Edges and notes reference `tasks.id`, not `local_id`.
+
+## Run common queries
+
+Blocked tasks and the goals view, which replaced removed verbs:
+
+```bash
+mu sql "SELECT b.local_id, b.title FROM blocked b JOIN workstreams w ON w.id = b.workstream_id WHERE w.name = 'auth'"
+mu sql "SELECT g.local_id, g.title FROM goals g JOIN workstreams w ON w.id = g.workstream_id WHERE w.name = 'auth'"
+```
+
+Search task titles:
+
+```bash
+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 = 'auth' AND LOWER(t.title) LIKE '%token%'"
+```
+
+Every task that blocks `launch`, directly or not:
+
+```bash
+mu sql "WITH RECURSIVE prereqs(id) AS (
+          SELECT t.id FROM tasks t JOIN workstreams w ON w.id = t.workstream_id
+           WHERE t.local_id = 'launch' AND w.name = 'auth'
+          UNION
+          SELECT e.from_task_id FROM task_edges e JOIN prereqs ON e.to_task_id = prereqs.id
+        )
+        SELECT t.local_id, t.title, t.status FROM prereqs JOIN tasks t ON t.id = prereqs.id"
+```
+
+`mu sql` runs writes too and prints the number of rows changed. Writes
+are captured as ops, so `mu undo` can revert them.
+
+## Pass list flags
+
+A flag with `<value...>` in its help takes repeats, commas, or both:
+`--blocked-by a,b` equals `--blocked-by a --blocked-by b`. An empty
+fragment from a stray comma is dropped. A blank fragment such as
+`" "` is a usage error.