@mu-crew/mu 3.2.0 → 3.3.0

package/docs/architecture/control-socket.md

@@ -0,0 +1,133 @@
+# Control socket
+
+mu drives a pi agent through a unix socket served by mu's own pi
+extension inside the agent's interactive pi. The pane stays pi's TUI,
+so a human attached to it shares the same session. There is no
+`pi --mode rpc`, no screen scraping and no daemon: the server lives and
+dies with the pi process. Overview: [ARCHITECTURE.md](../ARCHITECTURE.md).
+
+## Path derivation
+
+`ctlSocketPath(ws, agent)` (`src/ctl/path.ts`) is
+`<state dir>/sock/<ws>/<agent>.sock`. The state dir is
+`dirname($MU_DB_PATH)` or the default. If the path exceeds 103 bytes
+(the macOS `sun_path` limit), it becomes
+`<state dir>/sock/h/<sha1(ws/agent)[:16]>.sock`.
+
+Nothing is stored. Spawn creates the directory (mode 0700), removes any
+stale socket file at the path, and injects the path as `MU_CTL_SOCK`
+into every pane. Every later verb derives the path again.
+
+## Protocol v1
+
+`src/ctl/protocol.ts` imports nothing from mu, so the extension loads
+it standalone. Framing is JSON lines, one request per connection. Every
+reply carries `v: 1`; the client (`src/ctl/client.ts`) throws
+`CtlVersionError` on anything else.
+
+| op | does |
+| --- | --- |
+| `hello` | identity plus `ops` (served ops) and `extVersion` (the mu version the extension was built from) |
+| `status` | `state` (`busy` / `idle` / `needs_input`), `since`, `runs`, `pending` |
+| `send` | `pi.sendUserMessage`; when busy, `mode` is `steer` or `followUp` (default) |
+| `wait` | resolves on pi's `agent_settled` after `afterRuns`, with the run's `lastText` |
+| `abort` | `ctx.abort()` (pi's Esc) |
+| `fresh` | new session plus prompt as one operation, through the internal `/mu-fresh` command; replies once the new run starts; refused with `busy` unless `force` |
+| `command` | `name` `new`, `reload` or `compact` (with optional `instructions`), through the internal `/mu-new`, `/mu-reload`, `/mu-compact` commands, which call `ctx.newSession()`, `ctx.reload()`, `ctx.compact()`. `new` replies once the session is replaced, `reload` after the `session_start` it causes, `compact` when compaction starts or with pi's error (`Nothing to compact ...`). Refused with `busy` unless `force` |
+
+`pi.sendUserMessage` dispatches only extension commands, not pi's
+built-in `/new`, `/reload`, `/compact`. Each internal command is an
+extension command, triggered with `expandPromptTemplates: true`, and
+its handler gets the command context that can replace or reload the
+session.
+
+These back `mu agent send` (`--fresh`, `--steer`, session commands), `mu agent wait`,
+`mu agent abort`, the agent state reading, and `mu_delegate`.
+
+## Version skew
+
+An op the extension does not serve returns `unknown op: <op>` with its
+`ops` list. mu raises `AgentExtensionOutdatedError` (exit 4), whose
+next steps are `/reload` through the mux (an extension that lacks the
+`command` op cannot run it over ctl) or a respawn. `mu doctor`
+probes every pi agent's socket (the `ctl` row) and flags an
+`extVersion` older than the installed mu or a missing op. Its extension
+row reports whether `mu link pi` installed the extension.
+
+## Extension lifecycle
+
+`extension/mu-pi.ts` is inert unless `MU_CTL_SOCK` is set.
+
+- pi re-creates extension runtimes per session. The server, the run
+  counters and an in-flight `fresh` therefore live in a process-global
+  map (`Symbol.for("mu.pi.ctl")`).
+- Session replacement (`new`, `resume`, `fork`, `reload`) keeps the
+  socket and its connections. Quit closes it.
+
+**Binding never steals a live socket.**
+
+1. If the path already answers, another pi serves it (a nested `pi -p`
+   inherited `MU_CTL_SOCK`). The extension leaves it alone and says so
+   on stderr.
+2. Otherwise it listens on a private name in the same directory, sets
+   mode 0600, and hard-links that name onto the public path. libuv
+   unlinks the listened-on name at close, so the public path must never
+   be that name. `link()` fails on an existing path, so a racing pi
+   keeps its socket.
+3. It records the inode of the public path.
+
+On quit it unlinks the public path only if the inode is still its own,
+because another pi may own the path by then. On `session_start`, a
+server whose file was deleted or replaced closes and rebinds. That is
+how `/reload` recovers a lost socket file.
+
+## No silent fallback
+
+`src/agents/transport.ts` routes sends. `expectsCtl` is true when the
+cli key resolves to pi (`pi` or `pi-meta` as argv0), or when a socket
+file exists at the agent's derived path. The file case covers
+`--cli helper --command "pi-meta ..."`, whose command is not stored.
+
+A pi agent whose socket does not answer raises
+`AgentCtlUnreachableError` for send and abort, and reads as `unknown`
+with reason `ctl missing` or `ctl refused` for state. mu never pastes
+into it or asks murmur instead.
+
+The mux paste path (bracketed paste, `MU_SEND_DELAY_MS`,
+`MU_SEND_READINESS_MS`) serves only:
+
+- non-pi CLIs;
+- adopted panes without ctl;
+- an explicit `--via mux`.
+
+A pi agent's `/new`, `/reload` and `/compact [instructions]` go
+through the `command` op. Any other slash command to a pi agent raises
+`AgentSlashCommandUnsupportedError` (exit 2), whose next step is the
+same text with `--via mux`. Text such as `/tmp/x.log ...` is a plain
+prompt, not a slash command. A pi agent therefore never reaches
+`capturePane` or the paste timing in `src/mux/input-timing.ts`.
+
+## Remote agents
+
+The user's `ssh` command carries `-L <local derived path>:<remote path>`
+and puts `MU_CTL_SOCK=<remote path>` in the remote env.
+`mu agent remote-env` prints both and runs nothing
+(`src/cli/agents-remote.ts`). mu always connects to the local path, so
+local and remote agents share one transport, and state, send, wait and
+abort are exact without murmur.
+
+ssh does not create the local directory, which is why spawn makes it
+first. When ssh dies it leaves the local socket file behind. That file
+probes `refused`, and `mu agent close` or the reaper deletes it.
+
+## Parent side: `mu_delegate`
+
+`extension/delegate.ts` registers the `mu_delegate` and
+`mu_delegate_cancel` tools in the operator's own pi. They are hidden
+when `MU_MANAGED_AGENT` is set (inside a mu-spawned pane) or
+`MU_DELEGATE=0`. The tools shell out to the `mu` CLI (spawn, send,
+`wait --json`, read, abort, close) and only format the CLI's
+`outcome` into a follow-up message. `delegateOutcome`
+(`src/agents/delegate.ts`) maps one wait result to `done`, `empty`,
+`died`, `timeout` or `pending`. The extension imports nothing from pi;
+it types pi's API structurally.

package/docs/architecture/dag.md

@@ -0,0 +1,113 @@
+# The task DAG
+
+mu coordinates work through a directed acyclic graph of tasks. Without
+it mu is only an agent runner. Overview:
+[ARCHITECTURE.md](../ARCHITECTURE.md). Terms:
+[VOCABULARY.md](../VOCABULARY.md).
+
+## Model
+
+- **Tasks** are nodes with mandatory `impact` (1-100) and
+  `effort_days`. `ROI = impact / effort` drives prioritization.
+- **One edge type: `blocks`.** `A → B` means A must close before B can
+  start. More edge types would make "can this start?" ambiguous.
+- **Status lifecycle:** `OPEN → IN_PROGRESS → CLOSED`. Status alone
+  decides edge satisfaction: any `CLOSED` task satisfies its blockers.
+- **Substate** qualifies status and never touches edges:
+  `OPEN/todo|parked`, `IN_PROGRESS/active`,
+  `CLOSED/done|rejected|wontfix|duplicate|superseded`. The rule is
+  "store intent, derive graph facts": ready and blocked stay derived
+  from edges. `OPEN/parked` is excluded from `ready` but stays in
+  `goals`.
+- **Notes** are append-only per task. They survive LLM context loss
+  and agent restarts, which fixes context loss at the task level
+  rather than the agent level.
+
+## Substate integrity
+
+The legal pairs live in the `task_substates` lookup table, seeded from
+code on every open (machine-local, never synced). `tasks` has a
+composite FK `(status, substate) → task_substates`,
+`DEFERRABLE INITIALLY DEFERRED`. That FK is the only guard on the pair.
+
+SQLite checks it at COMMIT, so apply's one-field-at-a-time UPDATEs
+pass as long as the pair is legal when the transaction ends. That is
+why `applyOp` wraps each task put in `db.transaction`. In autocommit
+the first per-field UPDATE would fail the FK.
+
+Every lifecycle write sets `status` and `substate` in one UPDATE, so
+one op carries both under one HLC. A pair can still split across ops:
+a status-only op from a v10 peer, an unknown substate from a newer
+peer, or a concurrent close and park on two machines. Before commit,
+`repairTaskPair` (`src/apply.ts`) sets the substate to the one implied
+by the newest op in the log that writes a substate, resolved against
+the row's current status. If that pair is illegal, it falls back to
+the status default.
+
+Substate is therefore not per-field LWW. Reading the log instead of
+the row makes the result a pure function of the op set plus the row's
+status, so every peer converges whatever the arrival order. For the
+same reason the repair records no op: each peer computes the identical
+repair from the identical log.
+
+## Built-in views
+
+| View | Returns |
+| --- | --- |
+| `ready` | `OPEN/todo` tasks with no unresolved blockers: work that can start now |
+| `blocked` | OPEN tasks waiting on something |
+| `goals` | tasks with no dependents: graph endpoints |
+
+Agents and humans query these views directly through `mu sql`. There
+is no separate query layer.
+
+## Parallel tracks
+
+The Tracks section of `mu state` and bare `mu` runs union-find
+(`src/tracks.ts`) to find independent subtrees that different agents
+can work in parallel.
+
+Diamonds merge. If two roots share a prerequisite, they collapse into
+one track, so two agents never collide on the shared dependency:
+
+```
+  Independent (2 tracks):       Diamond (1 merged track):
+
+    goal_a    goal_b              goal_a   goal_b     ← Spawn 2 agents
+       |         |                   \      /
+    task_a    task_b                  shared          ← Spawn 1 (would
+       |         |                      |               collide otherwise)
+    leaf_a    leaf_b                  leaf
+```
+
+The graph algorithm decides, not the LLM.
+
+## Claim protocol
+
+`mu task claim <task>` resolves the claimer, then atomically sets
+`tasks.owner`, flips `status` to `IN_PROGRESS`, and records a
+`task.claim` op carrying the resolved `actor`. The claim is a CAS in
+SQLite, so two agents cannot claim the same task.
+
+Identity resolution (`resolveWorkerIdentity`, `src/tasks/claim.ts`) is
+a two-rung ladder:
+
+1. **`$MU_AGENT_NAME`**, injected into the pane's environment at spawn.
+   It is backend-independent.
+2. **`backend.currentAgentName()`**, the mux fallback. On tmux it reads
+   the pane title (`display-message -p '#{pane_title}'`), never the
+   window name, because one window can hold several agents. On herdr
+   the name is registered with the mux and looked up by pane id.
+
+The fallback exists for **adopted** panes (`mu agent adopt`), which
+predate the env injection and carry only a title. The agent does not
+need to know its own name.
+
+## Scoped subtree views
+
+`mu task tree <id>` and the task queries show the part of the graph
+reachable from a task. Scoping is a `WHERE` clause, which makes
+recursive delegation work: a sub-orchestrator inspects its slice
+without an LLM inferring the scope. `src/dag.ts` (`loadFullDag`,
+`renderForest`, `renderTaskTree`) serves both `mu task tree` and the
+TUI DAG popup.

package/docs/architecture/mux.md

@@ -0,0 +1,162 @@
+# Mux topology, backends and reconciliation
+
+mu runs agents in multiplexer panes, tmux or herdr, behind one
+`MuxBackend` interface. Overview: [ARCHITECTURE.md](../ARCHITECTURE.md).
+
+## One mux session per workstream
+
+One workstream is one mux session and one `session_id` partition in
+`~/.local/state/mu/mu.db`. Workstreams on one machine are independent
+mux sessions.
+
+| mu term | tmux | herdr |
+| --- | --- | --- |
+| **mux session** | session | workspace |
+| **window** | window | tab |
+| **pane** | pane (`%15`) | pane (`w1:p1`) |
+
+herdr's own "session" is server-level (one socket), which is the wrong
+granularity, so a herdr workspace plays the mux-session role.
+
+```
+  tmux session: mu-auth-refactor              (one mu workstream)
+  ┌───────────────────────────────────────────────────────────┐
+  │  Window: Backend             Window: Review               │
+  │  ┌──────────┐ ┌──────────┐   ┌────────────────────────┐   │
+  │  │ worker-1 │ │ worker-2 │   │ reviewer-1             │   │
+  │  │ (pi)     │ │ (pi)     │   │ (pi, role=read-only)   │   │
+  │  └──────────┘ └──────────┘   └────────────────────────┘   │
+  │  Window: mu-orchestrator                                  │
+  │  ┌────────────────────────────────────────────────────┐   │
+  │  │  pi (you, with mu extension loaded)                │   │
+  │  └────────────────────────────────────────────────────┘   │
+  └───────────────────────────────────────────────────────────┘
+```
+
+- The first `mu agent spawn` creates the session if needed. Name it
+  with `mu workstream init <name>` or `MU_SESSION=<name>`.
+- `tmux attach -t mu-<workstream>` shows the whole crew (herdr:
+  `herdr workspace focus <id>`). Killing the session kills the
+  workstream, with no leaked panes, and the crew survives a closed
+  laptop.
+- `mu agent list` is scoped to one workstream; `-w` picks another.
+- `mu doctor` warns about orphan panes, ghost rows, and agents whose
+  mux session is gone.
+
+**Window vs pane.** Each agent gets its own window, named by `--tab`
+(default: the agent name). Agents sharing a `--tab` value share a
+window. Identity never depends on the window: each pane gets
+`$MU_AGENT_NAME` plus a **pane title** fallback. The title carries
+durable context only (agent name and owned tasks), re-pushed by
+`composeAgentTitle` after each relevant change. mu enables the top
+border and leaves `pane-border-format` to the user's tmux config. The
+canonical tmux protocol is the comment block at the top of
+`src/mux/tmux.ts`.
+
+## The `activeMux()` seam
+
+Every call site reaches its multiplexer through
+`(await activeMux()).<method>()`. Nothing outside `src/mux/` names a
+backend. `src/mux/detect.ts` picks one: `MU_MUX` → `HERDR_ENV` →
+`$TMUX` → `PATH`. An unknown `MU_MUX` value fails the invocation
+instead of falling back to tmux.
+
+Each call site has decided what "no reachable multiplexer" means:
+
+| | On `NoMultiplexerError` | Examples |
+| --- | --- | --- |
+| **Load-bearing** | propagate; `handle()` maps it to exit 5 | spawn, send, read, kill, adopt, kick, reconcile, session create and destroy |
+| **Best-effort** | `try`/`catch`, degrade | actor identity, pane titles, pane borders, workstream listings, liveness polls, TUI attach |
+
+`resolveWorkerIdentity()` in `src/tasks/claim.ts` is the canonical
+best-effort shape. `reconcile()` is load-bearing on purpose: treating
+an unreachable mux as "zero panes" would prune every agent as a ghost
+and reap its in-progress tasks.
+
+Three concerns belong to the backend, because each would otherwise
+hardcode a tmux string a herdr user sees:
+
+- `attachHint()` and `attachCommands()`: the printed recipe and the
+  TUI's executed argv.
+- `healthCheck()`: version and env facts as data; `mu doctor` renders.
+- `paneNotFoundNextSteps()`: borrowed by `PaneNotFoundError` from the
+  backend that raised it.
+
+`src/tmux.ts` survives as a re-export for tmux-only concerns: the
+`MU_TMUX_SOCKET` test-isolation seam and the shared `sleep` /
+`setSleepForTests` poll seam.
+
+## Spawn: create-and-run vs create-then-start
+
+tmux creates a pane and runs a command in one call. herdr has no
+create-and-run form: its creation verbs start a plain shell, and
+`agent start` needs an existing pane at its prompt. mu expresses this
+as a capability, not a name check:
+
+| | tmux | herdr |
+| --- | --- | --- |
+| `NewWindowOptions.command` | carries the command | refused if non-empty |
+| `startAgentInPane()` | absent | implemented |
+| after start | mu checks pane life and startup errors | the mux returns once the agent is ready |
+
+`spawnAgent` branches on `mux.startAgentInPane !== undefined`.
+
+- **tmux.** After `MU_SPAWN_LIVENESS_MS` (default 1500, `0` skips) mu
+  verifies the pane survived and scans its tail for provider or auth
+  startup errors. mu does not wait for murmur to claim the pane: state
+  reads before the first claim report `unknown`.
+- **herdr.** mu creates a bare pane and calls `startAgentInPane`, which
+  subsumes both checks.
+- **pi, either backend.** After the agent starts, mu polls its control
+  socket until the extension answers (`MU_SPAWN_CTL_MS`, default 30s;
+  `--no-ctl` or `0` skips). A timeout is reported but not rolled back:
+  the pane and pi are fine, only control is missing. See
+  [control-socket.md](control-socket.md).
+
+A creation verb refuses a command it cannot honour. A dropped command
+would leave an empty shell that mu believes hosts an agent. The
+refusal and every failure before the handshake route through
+`rollbackSpawn`, so no agent row survives for an empty pane.
+
+Spawns serialize per mux session (`src/agents/spawn-lock.ts`, over
+`src/file-lock.ts`) only around the topology check-then-act and the
+row insert. Agent start and the readiness waits sit outside the lock,
+so a parallel fan-out still runs in parallel.
+
+## Reconciliation
+
+`mu agent list` reconciles the registry against the mux before
+returning. `src/reconcile.ts` is the only implementation, and
+`mu doctor` calls the same routine.
+
+1. **Prune ghosts.** Delete each `agents` row whose `pane_id` no longer
+   exists.
+2. **Surface orphans.** List panes in the workstream's session that
+   have no row but whose title looks like an agent name. mu never
+   adopts them; the user runs `mu agent adopt <pane> [--name X]`.
+
+The mux is the source of truth for which panes exist.
+
+## Agent state
+
+Runtime state is read on demand and never persisted.
+`src/agent-state.ts` picks one source per agent:
+
+| Agent | Source |
+| --- | --- |
+| pi (`expectsCtl`) | its control socket, probed in parallel for all pi agents |
+| other CLI on herdr | herdr's native `paneStatus()` |
+| other CLI on tmux | murmur: one `list-panes -a` reads `@murmur_pane_state` / `@murmur_pane_since`; agents without a local option fall back to `murmur status --json`, cached 10s |
+
+- ctl `idle` maps to `needs_input`. murmur maps `working` → `busy`,
+  `blocked` → `needs_permission`, and `idle` / `done` / `crashed` →
+  `needs_input`. herdr supplies mu's states directly. See murmur's
+  [stable contract](https://github.com/mu-crew/murmur/blob/main/ARCHITECTURE.md#contract).
+- An absent reading is `unknown` with a reason: `ctl missing`,
+  `ctl refused`, `murmur not installed`, `murmur pi extension not
+  linked`, `murmur has no row`, `remote snapshot stale`, `herdr reports
+  no state`, or `pane gone`.
+- `src/mux/input-timing.ts` reads pane text only to decide when tmux
+  input can be submitted on the paste path. It does not report state.
+- `agents.status` is deprecated. Inserts write `spawning` to satisfy the
+  schema; nothing reads it as runtime state.

package/docs/architecture/ops-log.md

@@ -0,0 +1,140 @@
+# The ops log
+
+mu keeps one append-only table, `ops`. History, undo, sync, rebuild and
+drift detection are all queries or replays over it. Overview:
+[ARCHITECTURE.md](../ARCHITECTURE.md).
+
+## Capture is a trigger
+
+Every INSERT, UPDATE and DELETE on a portable table (`workstreams`,
+`tasks`, `task_edges`, `task_notes`) is recorded as an **op** by a
+SQLite trigger, in the same transaction as the mutation. No SDK
+function decides to record history, so no call site can forget to, and
+the log cannot drift from the data, even on power loss.
+
+The tables are the materialized view; the log is the record. Reads hit
+the tables as ordinary indexed SQL. Nothing replays the log to answer
+a query. The log is what the tables are derived from and can be
+rebuilt from.
+
+```
+  mu task close t3
+     │
+     ▼
+  UPDATE tasks SET status=... ──┬──► tables   (what reads see)
+                                └──► ops     (what everything else reads)
+                          one transaction
+```
+
+| Feature | Over the log |
+| --- | --- |
+| history | `mu log` is a typed reader over `ops` (`src/logs.ts`) |
+| undo | `mu undo <group>` emits the inverse ops for one group |
+| sync | each machine appends its own ops to a JSONL segment and applies each peer's from a watermark ([sync.md](sync.md)) |
+| rebuild | `mu rebuild <file>` replays the whole log into a new DB |
+| drift | `mu doctor --deep` rebuilds into a temp DB and diffs it against the live tables |
+
+**Ops are semantic partial updates.** An UPDATE op carries only the
+columns that changed. That makes per-field merge free: two machines
+editing different fields of one task both keep their edit. A full-row
+payload would silently regress this to row-level last-writer-wins.
+
+**The cost:** one capture bug breaks history, undo and sync at once,
+silently. Hence the two drift tiers below.
+
+**Ordering** across machines comes from the **HLC** (`src/hlc.ts`) on
+every op: a hybrid logical clock serialized as sortable TEXT
+`<wall_ms:15>.<counter:6>.<machine_id>`, so bytewise `ORDER BY hlc` is
+causal order. Clock state lives in `machine_identity`.
+
+**Machine-local tables** (`agents`, `vcs_workspaces`) have no capture
+triggers. Their contents are pane ids and absolute paths, which mean
+nothing on another machine. Their changes are recorded as log-only
+events through `emitEvent`. `appendLog` writes operator prose
+(`mu log "text"`).
+
+## Trigger mechanics
+
+- **Capture triggers are TEMP triggers**, reinstalled per connection
+  by `src/capture.ts`. SQLite refuses a main-schema trigger that
+  references the temp `_op_ctx` table. Two consequences follow:
+  - DELETE keys are captured inline, with the parent stashing its
+    natural key in `_op_dying` first. FK CASCADE fires child triggers
+    after the parent is gone.
+  - The HLC is minted in SQL, because a trigger cannot call into JS.
+- **Op context** (`src/op-context.ts`): `withOpContext(db, {intent,
+  actor, group}, fn)` labels every op in a scope and restores in a
+  `finally`. Nested scopes inherit the group, which puts a cascade
+  under one `mu undo`. `withCaptureSuppressed` is the echo guard used
+  by the apply path.
+- An importer must synthesize **ops, not rows**. A direct INSERT is
+  invisible to sync and reported as drift.
+
+## Apply and merge
+
+`src/apply.ts` is capture's counterpart: given one op, local or from a
+peer, it makes the tables reflect it.
+
+- **Merge is per entity.** Notes are grow-only sets. Tasks and
+  workstreams merge per field by HLC. Edges are an LWW-element-set.
+- A **tombstone** is an ordinary op with an HLC, so out-of-order
+  arrival is a comparison and resurrection falls out.
+- Never use `json_patch`: RFC 7396 reads a null member as
+  delete-the-key.
+- Task `status` and `substate` are repaired as a pair, not merged per
+  field. See [dag.md](dag.md#substate-integrity).
+
+## Undo
+
+`src/undo.ts` derives the inverse ops for one `group_id` from log
+provenance. It refuses a superseded group (exit 4; `--force`
+overrides). Bare `mu undo` lists undoable groups (`-n` widens), a group
+prefix previews, and `--yes` applies.
+
+- **Undo and restore write through the tables**, so capture records
+  them like any other write.
+- `restore` records and applies under the **same** HLC. `applyOp`
+  excludes an op's own HLC from provenance. A fresher HLC would make
+  the row outrank the op and lose every field to an insert default.
+- **Note tombstones are self-describing.** Every other `del` carries
+  `'{}'`, because its key plus earlier puts describe the row. A note's
+  key embeds its rowid (`<ws>/<task>#<id>`), and a rebuild or
+  reprojection reassigns rowids. The `task_notes` delete trigger
+  therefore records `OLD.*`, and `planUndo` falls back to the
+  tombstone payload when folding the puts finds nothing. For the same
+  reason `src/drift.ts` matches notes on the task-key prefix.
+
+## Rebuild
+
+`src/rebuild.ts` (`rebuildInto`) replays the whole log into a new DB
+file through `applyOp`. The verb prints counts, supports `--json`,
+suggests an `mv` swap, and warns that `agents` and `vcs_workspaces`
+cannot be reconstructed.
+
+Rebuild is not ingest:
+
+- Ingest filters to `SYNCED_ENTITIES`. Rebuild replays everything, so
+  log-only entities are copied verbatim, or `mu log` comes back empty.
+- `src/legacy-ops.ts` classifies historical log-only intents whose
+  entity looks projectable. Rebuild copies them without projection;
+  flush never emits them.
+- `machine_identity` carries across whole: id, hostname and HLC clock.
+  Otherwise the rebuilt DB is a different peer minting HLCs below
+  every replayed op.
+
+## Drift
+
+`src/drift.ts` has two tiers:
+
+| Tier | Runs | Checks |
+| --- | --- | --- |
+| cheap (`checkCheapDriftInvariant`) | default `mu doctor` | every live row has at least one op naming its key |
+| deep (`checkDrift`) | `mu doctor --deep` | rebuilds into a temp DB and diffs field by field |
+
+The deep diff matches rows by natural key and excludes `owner_id`,
+because a rebuild always has NULL owners. `driftRemediation` prints the
+fix.
+
+For disaster recovery, `mu db backup <file>` writes one scp-able file
+through `VACUUM INTO`. It never overwrites; it is the copy
+`SchemaTooOldError` tells you to take.