@mu-crew/mu 3.8.1 → 3.10.0

package/dist/tui-sync-worker.js

@@ -0,0 +1,16 @@
+import {
+  ambientSyncPass,
+  openDb
+} from "./chunk-YIF3X32A.js";
+import "./chunk-4PACTXAB.js";
+import "./chunk-PZ5AY32C.js";
+
+// src/cli/tui/sync-worker.ts
+import { parentPort, workerData } from "worker_threads";
+var port = parentPort;
+if (port === null) throw new Error("tui-sync-worker must run as a worker_thread");
+var db = openDb({ path: workerData.dbPath });
+port.on("message", () => {
+  void ambientSyncPass(db, { quiet: true }).catch(() => null).then((result) => port.postMessage(result));
+});
+//# sourceMappingURL=tui-sync-worker.js.map

package/dist/tui-sync-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/tui/sync-worker.ts"],"sourcesContent":["// worker_thread entry for the TUI's ambient sync pass (built to\n// dist/tui-sync-worker.js). ingest and flush are synchronous SQLite and\n// file work (seconds on a first read, hundreds of ms per peer append on\n// a 40 MB segment), so on ink's thread they froze input and repaints.\n// Here they block only this thread. The worker owns its own connection\n// to the same DB file: WAL serves the TUI's reads meanwhile, and the\n// TUI sees the result on its next read.\n//\n// Protocol: the parent posts any message to start one pass, and the\n// worker replies with the pass's result (`null` if it threw) when the\n// pass is over. ambientSyncPass is total, and `quiet` keeps stderr off\n// the alternate screen.\n\nimport { parentPort, workerData } from \"node:worker_threads\";\nimport { openDb } from \"../../db.js\";\nimport { ambientSyncPass } from \"../../sync.js\";\n\nconst port = parentPort;\nif (port === null) throw new Error(\"tui-sync-worker must run as a worker_thread\");\nconst db = openDb({ path: (workerData as { dbPath: string }).dbPath });\nport.on(\"message\", () => {\n  void ambientSyncPass(db, { quiet: true })\n    .catch(() => null)\n    .then((result) => port.postMessage(result));\n});\n"],"mappings":";;;;;;;;AAaA,SAAS,YAAY,kBAAkB;AAIvC,IAAM,OAAO;AACb,IAAI,SAAS,KAAM,OAAM,IAAI,MAAM,6CAA6C;AAChF,IAAM,KAAK,OAAO,EAAE,MAAO,WAAkC,OAAO,CAAC;AACrE,KAAK,GAAG,WAAW,MAAM;AACvB,OAAK,gBAAgB,IAAI,EAAE,OAAO,KAAK,CAAC,EACrC,MAAM,MAAM,IAAI,EAChB,KAAK,CAAC,WAAW,KAAK,YAAY,MAAM,CAAC;AAC9C,CAAC;","names":[]}

package/dist/yank-T3AYQTVR.js

@@ -0,0 +1,12 @@
+import {
+  osc52Sequence,
+  probeClipboardBackend,
+  yank
+} from "./chunk-77GBZ2KR.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  osc52Sequence,
+  probeClipboardBackend,
+  yank
+};
+//# sourceMappingURL=yank-T3AYQTVR.js.map

package/dist/yank-T3AYQTVR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/docs/ARCHITECTURE.md

@@ -74,7 +74,7 @@ them, and is the only code that imports ink:
 **CLI and SDK surface.** Each operation is a typed SDK function plus a
 thin Commander wrapper. Public functions take operator-facing names and
 resolve them to surrogate ids exactly once. Typed errors map to exit
-codes 0-5. The same page covers testing layers and packaging:
+codes 0-7. The same page covers testing layers and packaging:
 [architecture/sdk.md](architecture/sdk.md).
 
 ## Module map
@@ -88,13 +88,14 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 
 | Module | Responsibility |
 | --- | --- |
-| `src/db.ts` | better-sqlite3 connection (WAL); schema v11 (11 tables, 3 views) in `applySchema`; installs capture; owns `SYNCED_ENTITIES`, `PORTABLE_TABLES`, `MACHINE_LOCAL_TABLES`; refuses older (`SchemaTooOldError`) or newer (`SchemaTooNewError`) DBs, exit 4 |
+| `src/db.ts` | better-sqlite3 connection (WAL); schema v11 (12 tables, 3 views) in `applySchema`; installs capture; owns `SYNCED_ENTITIES`, `PORTABLE_TABLES`, `MACHINE_LOCAL_TABLES`; refuses older (`SchemaTooOldError`) or newer (`SchemaTooNewError`) DBs, exit 4 |
 | `src/hlc.ts` | hybrid logical clock, serialized as sortable TEXT |
-| `src/capture.ts` | TEMP triggers recording each portable write as an op |
+| `src/capture.ts` | TEMP triggers recording each portable write as an op, and refusing natural-key changes |
 | `src/op-context.ts` | `withOpContext` (intent, actor, group); `withCaptureSuppressed` echo guard |
 | `src/apply.ts` | apply one op: per-field LWW, tombstones, substate pair repair, `reprojectDeferredOps` |
 | `src/undo.ts` | inverse ops for one group; refuses a superseded group |
 | `src/rebuild.ts` | replay the whole log into a new DB file |
+| `src/compact.ts` | `mu db compact` (blank redundant note-tombstone payloads) and `mu db forget` (drop a torn-down workstream's ops); this machine only |
 | `src/legacy-ops.ts` | classifier for historical log-only intents; rebuild copies them unprojected |
 | `src/drift.ts` | cheap invariant (every row has an op) and `--deep` rebuild-diff |
 | `src/logs.ts` | typed reader over `ops`; `appendLog` and `emitEvent`, the writes triggers cannot cover |
@@ -105,6 +106,8 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | Module | Responsibility |
 | --- | --- |
 | `src/segments.ts` | JSONL segments: flush own ops, ingest peers from a watermark |
+| `src/segment-manifest.ts` | segment `.manifest` sidecar: read, write, seal, and the self-consistency check the owner's flush runs before trusting it |
+| `src/sha256-resumable.ts` | SHA-256 with a serialisable running state, so the segment manifest hashes only appended bytes |
 | `src/sync.ts` | peer status, the ambient hook, `--from`, `--repair` |
 | `src/file-lock.ts` | cross-process advisory lock through atomic `fs.mkdir` |
 | `src/fleet-hazards.ts` | mixed-fleet checks: DB inside `MU_SYNC_DIR`, network mount, case collisions |
@@ -121,13 +124,14 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | `src/agents/spawn-lock.ts` | per-session lock around topology and row insert |
 | `src/agents/transport.ts` | send routing: ctl for pi agents, mux paste otherwise, no fallback; `expectsCtl` |
 | `src/agents/abort.ts` | stop a pi turn through the control socket; abort + send (`--interrupt`) |
-| `src/agents/delegate.ts` | `delegateOutcome`: one wait result to `done` / `empty` / `died` / `timeout` / `pending` |
+| `src/agents/delegate.ts` | `delegateOutcome`: one wait result to `done` / `empty` / `error` / `died` / `timeout` / `pending` |
 | `src/agents/wait.ts` | block until task-less agents leave `busy` |
 | `src/agents/adopt.ts` | register an existing pane as an agent |
 | `src/agents/kick.ts` | `mu agent kick`: signal a wedged pane's foreground process group |
 | `src/agents/errors.ts` | typed agent errors |
 | `src/agent-state.ts` | runtime state from ctl, herdr or murmur; `unknown` with a reason |
 | `src/reconcile.ts` | ghost prune and orphan surfacing |
+| `src/mux/index.ts` | cluster barrel that `src/mux.ts` re-exports |
 | `src/mux/types.ts` | `MuxBackend` interface; `MuxError`, `PaneNotFoundError`, `NoMultiplexerError` |
 | `src/mux/detect.ts` | `MU_MUX` → `HERDR_ENV` → `$TMUX` → `PATH` ladder; `activeMux()` |
 | `src/mux/tmux.ts` | tmux backend: the `tmux()` wrapper, bracketed-paste send, pane validation |
@@ -139,7 +143,7 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 | `src/ctl/client.ts` | `ctlRequest`, `ctlProbe`, version and unknown-op errors |
 | `extension/mu-pi.ts` | pi extension, child side: serves `$MU_CTL_SOCK`; built to `dist/extension/mu-pi.js` |
 | `extension/delegate.ts` | pi extension, parent side: `mu_delegate` / `mu_delegate_cancel`, which shell out to `mu` |
-| `extension/nudge.ts` | pi extension: the keep-driving nudge. Arms on a `mu` dispatch, checks `mu state --json` at `agent_before_settle`, injects the SKILL.md rule once per prompt, logs `--kind nudge`. Also the close nudge (worker settles owning a task) and the refute nudge (`task claim --for` on a task with no refute decision in `mu task notes --json`; one notice, no continuation) |
+| `extension/nudge.ts` | pi extension: the keep-driving nudge. Arms on a `mu` dispatch, checks `mu state --json` at `agent_before_settle`, injects the SKILL.md rule once per prompt, logs `--kind nudge`. Also the close nudge (worker settles owning a task) and the refute nudge (`task claim --for` on a task with no refute decision in `mu task notes --json`; one notice, no continuation). `parallelSettle` runs the three settle checks in parallel behind one `agent_before_settle` handler and merges their entries; `mu log` breadcrumbs are not awaited |
 | `src/link.ts` | `mu link pi`: extension shim, skill symlink, `inspectLinks` for doctor |
 
 ### Tasks, workspaces and workstreams
@@ -165,14 +169,18 @@ hub that re-exports them. `src/tasks.ts`, `src/agents.ts`, `src/mux.ts`,
 
 | Module | Responsibility |
 | --- | --- |
-| `src/cli.ts` | Commander wiring (`buildProgram`) |
+| `src/main.ts` | the `mu` bin (`dist/cli.js`): enables the compile cache, then `import()`s `src/cli.ts` |
+| `src/compile-cache.ts`, `src/state-dir.ts` | best-effort V8 compile cache under `<state>/compile-cache`; builtins-only state-dir resolution |
+| `src/cli.ts` | Commander wiring (`buildProgram`, `runCli`) |
 | `src/cli/*.ts` | one file per verb namespace, thin wrappers over the SDK; `format.ts` renders tables, `handle.ts` maps errors to exit codes and runs ambient sync |
 | `src/cli/tasks/*.ts` | the `mu task` namespace, including `mu me tasks` / `mu me next` |
 | `src/cli/dispatch-hints.ts` | dispatch-time `Next:` hints for pi agents (`--fresh`, `--interrupt`, abort) |
 | `src/cli/stdin.ts` | `-` as a text argument: reads note / send text from stdin (heredoc prose) |
 | `src/cli/agents-remote.ts` | `mu agent remote-env`: prints the ssh forward and env, runs nothing |
 | `src/cli/tui-launch-focus.ts` | initial-tab focus ladder for bare `mu` and `mu state --tui` |
+| `src/cli/tui-load.ts` | lazy `import()` of the TUI with `NODE_ENV` defaulted to `production` (React prod build) |
 | `src/cli/tui/` | the ink TUI; the only place ink and react are imported |
+| `src/cli/tui/sync-worker.ts` | worker_thread (`dist/tui-sync-worker.js`) running the TUI's slow-tick sync pass off ink's thread |
 | `src/output.ts`, `src/shell-quote.ts` | `printNextSteps` / `errorNextSteps`; POSIX quoting for hints |
 | `src/glyphs.ts` | the one glyph vocabulary (single-cell Nerd Font codepoints) |
 | `src/index.ts` | SDK entry point |

package/docs/VISION.md

@@ -109,7 +109,7 @@ which task.
 A workstream is a mux session: a tmux session on tmux, a herdr workspace
 on herdr. Its agents are panes in that session, so
 `tmux a -t mu-<workstream>` shows the whole crew. Workstreams on one
-machine are separate sessions, partitioned in the DB by `session_id`.
+machine are separate sessions, partitioned in the DB by `workstream_id`.
 The crew survives detach and reattach.
 
 The multiplexer is a backend chosen by detection
@@ -161,7 +161,7 @@ win32-x64) or a C++ toolchain.
 - **Read views**: the `ready`, `blocked`, and `goals` views, and
   `mu state` as the state card.
 - **Typed verbs** that map to resource transitions (`task claim`,
-  `task close`, `agent spawn --workspace`, `workstream destroy`).
+  `task close`, `agent spawn --workspace`, `workstream teardown`).
 - **`--json` on every read verb**, so scripts use `jq`, not table parsing.
 - **`mu sql`** underneath, as the explicit escape hatch.
 
@@ -249,10 +249,17 @@ mu agent spawn reviewer-1 --cli pi_big
    The exceptions are `mu log --tail` and the TUI (`mu state --tui`, or
    bare `mu` on a TTY). Both are:
    - owned by a human or parent script and gone when it ends;
-   - read-only: TUI actions copy the `mu <verb>` command to the
-     clipboard and exit, so every write is a fresh CLI call;
-   - limited to stdin, stdout, and a poll timer: no sockets, watches, or
-     subprocesses;
+   - free of user actions: TUI keys copy the `mu <verb>` command to
+     the clipboard and exit, so every change the operator asks for is a
+     fresh CLI call. The TUI's slow tick still does the housekeeping
+     any `mu` invocation does: ambient sync (ingest peer ops, flush the
+     local segment) and reconcile (prune agents whose pane died, which
+     reopens their tasks with a `[reaper]` note, and refresh pane
+     titles);
+   - limited to stdin, stdout, and a poll timer: no sockets or watches.
+     The TUI's slow tick runs short-lived probes (mux liveness, VCS
+     status) and ambient sync, and its handoffs (lazygit, tuicr, attach,
+     clipboard) run one foreground child each; none outlives the TUI;
    - TTY-gated: pipes, CI, `--json`, and `MU_NO_TUI=1` never enter the
      TUI, and plain `mu state` prints the static card.
 
@@ -276,5 +283,5 @@ the work, pi plus manual tmux is more transparent than mu.
 
 Known gaps, none promoted yet: `--evidence` grounds but does not verify,
 mutations have no declared idempotency keys, most mutations have no dry
-run (`workstream destroy`, `task delete`, and `undo` do), and the `role`
+run (`workstream teardown`, `task delete`, and `undo` do), and the `role`
 field is stored but not enforced.

package/docs/VOCABULARY.md

@@ -15,7 +15,7 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | Term | Meaning | Don't use |
 | --- | --- | --- |
 | **workstream** | The unit of organization: one **mux session** and one DB partition. | "project", "session" (alone), "context" |
-| **scratch workstream** | The reserved workstream `scratch` for helpers outside any task DAG. Auto-created on first spawn with explicit `-w scratch`; `mu workstream init scratch` is rejected. | "throwaway ws", "temp workstream" |
+| **scratch workstream** | The reserved workstream `scratch` for helpers outside any task DAG. Auto-created on first spawn with explicit `-w scratch`; `mu workstream init scratch` is rejected. Its session keeps a `_mu` window, so it stays open after the last agent closes; `teardown --empty` skips it. | "throwaway ws", "temp workstream" |
 | **multiplexer** / **mux** | The terminal program that owns panes: **tmux** or **herdr**. "mux" in code (`src/mux/`, `MU_MUX`), "multiplexer" in prose; one is active per invocation. | "terminal", "emulator", "backend" (alone) |
 | **mux backend** | An implementation of `MuxBackend` (`src/mux/tmux.ts`, `src/mux/herdr.ts`). Owns everything backend-specific. | "driver", "provider", "adapter" |
 | **mux detection** | Picks the mux backend: `MU_MUX` → `HERDR_ENV=1` → `$TMUX` → binary on `PATH` (tmux wins a tie) → `NoMultiplexerError`. | "auto-detect", "probe" |
@@ -105,7 +105,7 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | **op** | One `ops` row, written by a trigger in the mutation's transaction. Holds only changed columns. | "event", "delta", "change" |
 | **ops log** | The `ops` table: the append-only record that sync, undo, and history read. | "event log", "journal", "WAL" |
 | **log entry** | An op as rendered by `mu log`, through one formatter (`src/log-render.ts`). | "message", "event" |
-| **kind** | The operator's channel tag on a log entry (`mu log --kind`), stored as the op's `entity`. | "category", "type" |
+| **kind** | The operator's channel tag on a log entry (`mu log --kind`), stored as the op's `entity`. `workstream`, `task`, `edge`, and `note` are reserved. | "category", "type" |
 | **log ledger** | A convention: a custom `--kind` used as a watcher loop's durable dedupe record. | "state file" |
 | **intent** | The semantic label on an op (`task.close`), set once per SDK function via **op context**. | "verb", "action" |
 | **group** | The ops of one user action (`group_id`), undone as a unit. Any unique id prefix works. | "transaction", "batch" |
@@ -119,7 +119,7 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | **resurrection** | A put newer than a seen tombstone, which legitimately recreates the row. | "undelete", "revive" |
 | **provenance** | Which HLC last wrote a field, derived from the ops log by query, never stored. | "version vector" |
 | **inverse op** | The op that reverts another; an ordinary op, so undo syncs and is undoable. | "rollback" |
-| **superseded** (group) | A later group wrote the same field, so `mu undo` refuses (exit 4) without `--force`. | "stale" |
+| **superseded** (group) | A later group wrote the same field (other than `updated_at`), so `mu undo` refuses (exit 4) without `--force`. | "stale" |
 | **teardown** | Kill a workstream's mux session and delete its rows. `mu undo` restores rows, not panes or dirs. | "destroy", "nuke", "purge" |
 | **drift** | The ops log and live tables disagree. Always a bug. | "inconsistency", "corruption" |
 | **shallow / deep check** | Drift checks in `mu doctor` and `mu doctor --deep` (full rebuild). | "fsck" |
@@ -128,7 +128,7 @@ agent names, and file paths are in [reference/naming.md](reference/naming.md).
 | **machine_id** | Per-state-dir uuid naming this DB's **peer** and **segment**. | "device id", "host id" |
 | **segment** | `<sync-dir>/<machine_id>.jsonl`: one machine's ops, single writer. | "replica", "shard" |
 | **peer** | Another machine, found by its segment; named by `machine_id` prefix. **Stale** after 24h unchanged. | "node", "remote" |
-| **watermark** | `sync_peers.last_applied_seq`: how many lines of a peer's segment have been applied. | "offset", "cursor" |
+| **watermark** | `sync_peers.last_applied_seq`: how many lines of a peer's segment file have been applied. A conflict copy has its own, keyed by its file stem. | "offset", "cursor" |
 | **flush** / **ingest** | Write my ops to my segment; apply peers' from their watermarks. Every invocation, when `MU_SYNC_DIR` is set. | "push", "pull" |
 | **reprojection** | After ingest, apply deferred ops whose parent arrived from another peer. | "retry queue" |
 | **mixed fleet** | Machines sharing state across different OSes or filesystems. | "cluster" |
@@ -222,5 +222,4 @@ deprecated, always `spawning`, and never read.
 | **pi session** | pi's conversation |
 | **agent session** | Colloquial for an agent's lifetime; avoid in code |
 
-New columns and variables say `workstream_id`, not `session_id`. The
-`agents.session_id` column keeps its name for schema stability.
+Columns and variables say `workstream_id`, never `session_id`.

package/docs/architecture/control-socket.md

@@ -132,7 +132,11 @@ probes `refused`, and `mu agent close` or the reaper deletes it.
 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`
+`outcome` into a follow-up message. A call runs one
+`mu agent spawn --next-free --send <task> --json` (mu picks the free
+name under its spawn lock and returns the send's `runs`), then one
+`mu agent wait --after-runs <runs>` in the background; with `record`,
+a `mu task show` comes first. `delegateOutcome`
 (`src/agents/delegate.ts`) maps one wait result to `done`, `empty`,
-`died`, `timeout` or `pending`. The extension imports nothing from pi;
+`error`, `died`, `timeout` or `pending`. The extension imports nothing from pi;
 it types pi's API structurally.

package/docs/architecture/mux.md

@@ -5,7 +5,7 @@ mu runs agents in multiplexer panes, tmux or herdr, behind one
 
 ## One mux session per workstream
 
-One workstream is one mux session and one `session_id` partition in
+One workstream is one mux session and one `workstream_id` partition in
 `~/.local/state/mu/mu.db`. Workstreams on one machine are independent
 mux sessions.
 
@@ -107,7 +107,9 @@ as a capability, not a name check:
   reads before the first claim report `unknown`. A pi agent skips the
   fixed wait: mu checks the pane on every handshake tick (a dead pane
   rolls back at once) and scans for startup errors when the handshake
-  ends.
+  ends. After an ok handshake the scan skips shell exec-failure lines
+  (`command not found`, `No such file or directory`): pi demonstrably
+  started, and a resumed session can show such lines as old tool output.
 - **herdr.** mu creates a bare pane and calls `startAgentInPane`, which
   subsumes both checks.
 - **pi, either backend.** After the agent starts, mu polls its control

package/docs/architecture/ops-log.md

@@ -103,7 +103,8 @@ prefix previews, and `--yes` applies.
   old key (drift-641). The `task_notes` delete trigger records `OLD.*`
   only when no put under the current key is in the log, and `'{}'`
   otherwise; `planUndo` folds the puts first and falls back to the
-  tombstone payload. For the same reason `src/drift.ts` matches notes on
+  tombstone payload, and `applyOp` deletes by the payload's content
+  identity, falling back to the put under the same key. For the same reason `src/drift.ts` matches notes on
   the task-key prefix.
 
 ## Rewriting history (local only)

package/docs/architecture/sdk.md

@@ -125,7 +125,9 @@ codes:
 | 2 | usage error (Commander's default) |
 | 3 | not found (agent, task, workspace) |
 | 4 | conflict (name collision, double claim, dirty tree, schema too old or new, outdated extension) |
-| 5 | substrate unavailable (no multiplexer, DB locked) |
+| 5 | substrate unavailable or unsafe (no multiplexer, mux or VCS failure, DB locked, ops-log drift, a `mu doctor` FAIL row, timeout) |
+| 6 | `mu task wait`: the reaper reopened a watched task (its pane died) |
+| 7 | `mu task wait`: a watched task stalled (`--on-stall exit`) |
 
 Errors carry structured context (operation, target, attempted action)
 so `mu doctor` can show them readably.

package/docs/architecture/sync.md

@@ -15,14 +15,26 @@ Litestream, cr-sqlite or a peer list, and why the DB must never sit in
 - `flushSegment` appends this machine's unflushed ops to
   `<MU_SYNC_DIR>/<machine_id>.jsonl`.
 - `ingestSegment` reads a peer segment from its watermark into
-  `applyOp`.
+  `applyOp`. Ambient ingest skips a peer that is caught up: the manifest
+  counts the watermark, and the segment's size, exact mtime and
+  manifest sha256 equal what the last clean read to the end recorded
+  (in `sync_fingerprints`). Any change, including a rewrite with a
+  backdated mtime, fails that check, so the full read hashes the file
+  and reports the mismatch. `mu sync` always reads every line.
 - Peer discovery is implicit: every non-self `*.jsonl` is a peer. A
   peer disappears only when its segment is deleted.
+- A Syncthing conflict copy (`<machine>.sync-conflict-….jsonl`) is
+  ingested too, with its own watermark keyed by the file stem: it can
+  diverge from the original, so line counts are not comparable.
 
 **Single writer per file.** A machine appends only to its own segment,
 so nothing is contended and any folder syncer is adequate. Segments
 are regenerable, so there is no fsync. `src/file-lock.ts` stops two
-local `mu` processes from interleaving partial lines.
+local `mu` processes from interleaving partial lines. A flush never
+appends without that lock: if another process still holds it after
+2 s (15 s for `mu sync`), the flush writes nothing, the ops stay
+pending in `ops`, and the next invocation appends them. A stale lock
+(holder crashed, older than 30 s) is broken as before.
 
 **Only `SYNCED_ENTITIES` and only this machine's ops are flushed.**
 Pane ids and absolute paths never leave the machine, and peers never
@@ -35,8 +47,10 @@ anything else, unwrapping on ingest.
 
 ## Robustness layers
 
-Four checks stop ingest at the first bad record and advance the
-watermark only that far:
+The first three checks stop ingest at the first bad record and advance
+the watermark only that far. The fourth is whole-file: it reports the
+defect without halting, because every line still present is valid, and
+only a fresh copy of the file clears it:
 
 | Layer | Catches |
 | --- | --- |
@@ -54,8 +68,9 @@ distinguishes three cases:
 
 | Line | Result |
 | --- | --- |
-| damaged | halt |
+| damaged (including a blank line) | halt |
 | a known machine-local entity | reported defect, skipped |
+| a historical log-only intent (`workstream.export` prose from mu < 1.1) | skipped silently, as flush and `--from` skip it |
 | an unrecognised entity | applied as a no-op, no defect (a reader behind the writer is normal in a mixed fleet) |
 
 `mu sync` suggests `--repair` only for defects a re-read can clear.
@@ -71,8 +86,9 @@ poll outliving a command. It happens because you already run `mu`
 constantly.
 
 The seam is `handle()` (`src/cli/handle.ts`), which every verb passes
-through and which is already async. `syncPass` is async because it
-takes the file lock, while most verb bodies are synchronous
+through and which is already async. It awaits `ambientIngest` and
+`ambientFlush`; the flush is async because it takes the file lock,
+while most verb bodies are synchronous
 better-sqlite3 code. One `await` before `fn(db)` and one after cover
 every verb.
 
@@ -86,7 +102,8 @@ every verb.
 `src/sync.ts` holds `ambientIngest`, `ambientFlush`, `ambientSyncPass`,
 `peerStatuses`, `ingestFromDb` (`mu sync --from <path>`) and
 `repairPeer` (`mu sync --repair <peer>`, a unique prefix; ambiguity is
-exit 4).
+exit 4). A prefix names a machine, so it resets the watermark of the
+peer's segment and of every conflict copy of it.
 
 ### Carve-outs
 
@@ -110,8 +127,13 @@ edge puts that are resolvable now but unprojected. It skips ops whose
 parent task is gone and keys with a newer `del`, so a deleted edge is
 never resurrected and an orphan is not retried forever. It runs once
 per ingest pass, not per peer, because an edge in one segment may name
-a task in another. On a healthy DB it is two indexed queries returning
-zero rows.
+a task in another. Ambient ingest runs it only while SQLite's
+`user_version` is 1. `applyIncomingOp` sets that marker in the same
+transaction whenever an op changes a row or defers (`absent`), whether
+it came from a segment, `--from`, or an SDK caller; the repair clears
+it. A process that dies between
+the two leaves the marker set, so the next invocation runs the repair.
+`mu sync` and `--from` always run it.
 
 There is no retry queue. A queue would be a second source of truth and
 would not survive a short-lived `mu` process when the parent arrives

package/docs/architecture/tui.md

@@ -30,9 +30,10 @@ Press `?` in the TUI for the keymap.
 | `index.ts`, `escapes.ts` | `runTui` entry; alt-screen and SGR mouse-mode lifecycle; pure escape bytes |
 | `app.tsx` | `<App>` root: popup state machine, global keymap, tabs, footer |
 | `state.ts` | `useDashboardSnapshot` poll loop (fast and slow tiers) |
-| `keys.ts`, `keymap-spec.ts`, `help.tsx` | pure key dispatch; the keymap source of truth that drives both dispatch and the `?`/F1 overlay |
+| `keys.ts`, `keymap-spec.ts`, `help.tsx` | pure key dispatch; the keymap source of truth that drives both dispatch and the `?` overlay |
 | `mouse.ts`, `use-popup-action-queue.ts` | vendored SGR mouse parser with double-click; one queued popup action per render |
 | `layout.ts`, `columns.ts`, `wrap-ansi.ts`, `use-terminal-size.ts` | responsive columns and row budgets; aligned clipping; ANSI-aware wrapping; resize hook |
+| `popup-input.ts` | `usePopupInput`: popup keyboard, off while the help overlay covers the popup |
 | `titled-box.tsx`, `popup-shell.tsx`, `list-row.tsx`, `padded-rows.tsx`, `status-bar.tsx`, `tab-strip*.ts(x)` | chrome primitives |
 | `format-helpers.ts`, `agent-display.ts` | shared formatters and agent-row display |
 | `use-popup-filter.tsx`, `use-status-filter.tsx`, `use-notes-drill.ts` | `/` filter; status (`o`/`i`/`c`) and substate (`p`/`w`) toggles; shared notes drill |
@@ -45,9 +46,12 @@ Press `?` in the TUI for the keymap.
 `<App>` owns:
 
 - **Popup state:** `null` (dashboard) or one popup id. One popup at a
-  time; `Esc` or `q` returns to the dashboard.
+  time; `Esc` or `q` returns to the dashboard. `?` over a popup hides
+  it (`display="none"`) and turns its keyboard off rather than
+  unmounting it, so its cursor, filter and drill survive the overlay.
 - **Card visibility:** toggled by `0`-`9`.
-- **Tick rate:** fast tick, 1s default, adjusted with `+` `-` `=` `0`.
+- **Tick rate:** fast tick, 1s default, adjusted with `+` / `=` and
+  `-`. There is no reset key: `0` toggles the Commits card.
 - **Active workstream tab:** `Tab` / `Shift-Tab` cycles when there are
   two or more. A torn-down workstream keeps its tab position and
   renders dimmed with strikethrough until the name is recreated. A
@@ -98,7 +102,7 @@ the right border.
 
 Every popup row exposes one canonical `mu` command through `y`.
 `yank.ts` probes pbcopy, wl-copy, xclip, xsel and clip.exe, then falls
-back to OSC-52 over stderr.
+back to OSC-52 written to `/dev/tty`, since ink owns stdout.
 
 The handoffs leave the alt screen, disable mouse mode, run a
 foreground subprocess, and restore both on exit:
@@ -114,16 +118,22 @@ A TUI gesture that mutates state needs a ROADMAP entry first.
 
 Mouse support uses SGR mouse mode. `mouse.ts` parses
 `ESC[<button;x;y;M/m`, detects double-clicks, and exposes `useMouse()`.
-A double-click on a card emits `setCursor` then `drill` through the
-action queue, which consumes one action per render, so the cursor lands
-before the drill reads the focused row.
+A double-click on a card opens its popup. A double-click on a popup row
+emits one `clickRow` action (the 0-based body row) through the action
+queue. The popup maps that row through its own scroll window and
+header strips (`clickedItem` in `popups/scroll.ts`), then focuses and
+drills the item. App cannot do the mapping: only the popup knows its
+window start and strip rows.
 
 `keys.ts` holds `dispatchGlobalKey` (dashboard), `dispatchPopupKey`
 (popup), and `shouldSwallowGlobalKey` (keys a popup consumes).
 
 ## Drill recursion
 
-List popups drill with `Enter`. `DrillScrollView`
+List popups drill with `Enter`. Each popup pins the drilled row's
+identity at `Enter` (task, agent, check, commit sha, log seq, track
+goals), so a refresh that reorders or extends the list cannot move an
+open drill to another row. `DrillScrollView`
 (`popups/drill.tsx`) is the shared scrollable text leaf: Workspaces'
 git show, Agents' scrollback, Activity log payloads, and Doctor
 remediation. Task popups drill into `TaskDetailDrill`

package/docs/guide/backends.md

@@ -27,7 +27,7 @@ mu picks the backend from the first rule that matches:
 | Workstream | session `mu-<ws>` | workspace labelled `mu-<ws>` |
 | Window | window | tab |
 | Pane id | `%15` | `w1:p1` |
-| Attach | `tmux attach -t mu-<ws>` | `herdr session attach mu-<ws>` |
+| Attach | `tmux attach -t mu-<ws>` | `herdr workspace focus <id>`, then `herdr` outside a herdr pane |
 | pi agent state | control socket | control socket |
 | Other agents' state | murmur | herdr |
 | Send to non-pi agents | bracketed paste, then Enter | one atomic `agent prompt` |
@@ -44,8 +44,10 @@ Where each agent's state comes from, per backend:
   `/proc/<pid>/fd/0`, which macOS does not have.
 - `mu agent read --lines` cannot recover rows that scrolled off a pane
   on the alternate screen.
-- `MU_<CLI>_COMMAND` overrides apply on tmux only. herdr picks the
-  agent binary itself.
+- herdr starts the agent binary itself (`herdr agent start --kind
+  <cli>`), so spawn refuses `--command` and `MU_<CLI>_COMMAND` with
+  exit 2 instead of running a different binary. Unset the variable, or
+  spawn with `MU_MUX=tmux`.
 - herdr creates every workspace detached. Run `herdr workspace focus`
   yourself.
 

package/docs/guide/cleanup.md

@@ -22,14 +22,18 @@ mu workstream teardown auth --yes    # kills the session, deletes the rows
 Teardown kills the tmux session first, then deletes the agents, tasks,
 edges, notes, and workspaces. Running it again is a no-op.
 
-To sweep every workstream that has no tasks, agents, or workspaces,
-including `mu-*` tmux sessions with no DB row:
+To sweep every workstream that has no tasks, agents, or workspaces:
 
 ```bash
 mu workstream teardown --empty
 mu workstream teardown --empty --yes
 ```
 
+The sweep skips `scratch`, whose idle session is kept open on purpose.
+It never takes a `mu-*` session that has no workstream row in this DB:
+it may be a live workstream from another DB. The output names
+such sessions; tear one down by name once you know it is unused.
+
 ## Undo a teardown
 
 Teardown writes tombstone ops, so the ops log keeps everything. You do
@@ -40,7 +44,8 @@ mu workstream list --torn-down
 mu undo 7a40e6cc --yes
 ```
 
-The list shows one row per teardown, newest first. `← recreated since`
+The list shows one row per teardown, newest first. A `--empty` sweep
+writes one row per workstream, so undo each one. `← recreated since`
 means the name is in use again, so the undo would change nothing.
 Killed panes and freed workspace directories do not come back.
 

package/docs/guide/delegate.md

@@ -95,7 +95,9 @@ Exit codes: `0` met, `5` timeout, `6` pane died. Non-pi agents have no
 ## 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.
+on first spawn, needs no tasks, and cannot be `init`ed. Its `mu-scratch`
+session stays open after the last agent closes; remove it with
+`mu workstream teardown scratch --yes`.
 
 ```bash
 mu agent spawn helper -w scratch

package/docs/guide/dispatch.md

@@ -58,6 +58,10 @@ socket. Pick the mode by what the agent is doing:
   pastes nothing. `--via mux` pastes into the pane on purpose.
 
 After a claim, spawn, or wait, the `Next:` block prints the right send.
+`mu agent spawn --send <text>` spawns and sends the first prompt in one
+call; `--next-free` takes the next free name when `<name>` is taken
+(`worker-1` → `worker-2`; the stem is cut to keep the name within 32
+chars, and it gives up with exit 4 when no free name is near).
 
 ### Non-pi agents
 
@@ -103,9 +107,11 @@ 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`.
+pass `--from main`. It refuses on a dirty tree. On a conflict it exits 5:
+git and sl abort the rebase and leave the workspace as it was, while jj
+keeps the rebase with the conflicts committed in place. After you resolve,
+run refresh again so mu records the new base. 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).

package/docs/guide/recovery.md

@@ -7,7 +7,7 @@ read the same rules in
 [recipes/recovery.md](../../skills/mu/recipes/recovery.md).
 
 ```bash
-mu doctor           # exit 0 healthy, 5 on drift
+mu doctor           # exit 0 healthy (WARN rows too), 5 on drift or a FAIL row
 mu doctor --deep    # rebuild the ops log and diff every field
 mu doctor --disk    # add per-workspace byte usage
 ```
@@ -30,6 +30,8 @@ mu agent adopt %15 -w auth
 mu agent adopt %15 -w auth --name investigator
 ```
 
+On herdr, pass its pane id instead (`mu agent adopt w1:p2 -w auth`).
+
 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.
@@ -86,7 +88,8 @@ 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.
+  conflict. A later write to `updated_at` alone, such as `mu task note`,
+  does not count. `--force --yes` overrides and discards the newer work.
 - Undo restores rows only. Killed panes and freed workspace
   directories do not come back.
 
@@ -113,21 +116,29 @@ command.
 | `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 |
+| `db-copies` | stray `mu.db*` files that nothing reads, including the `pre-compact` / `pre-forget` backups |
 | `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.
+`mu workspace orphans -w auth`. An orphan has no row, so
+`mu workspace free` cannot remove it. Remove a git-backed orphan with
+`git worktree remove --force <path>` from the project root, and any
+other with `rm -rf <path>`.
 
 ## Rename a workstream
 
-There is no rename verb. Every child table cascades on the name:
+There is no rename verb, and `mu sql` refuses to change
+`workstreams.name`. The name is part of the key that every op is filed
+under, so a raw rename leaves the ops log on the old name: `mu doctor`
+reports drift, and sync or `mu rebuild` brings the old name back.
+Re-create the workstream instead:
 
 ```bash
-mu sql "UPDATE workstreams SET name='auth-refactor' WHERE name='auth-refator'"
-tmux rename-session -t mu-auth-refator mu-auth-refactor
+mu db backup /tmp/mu-before-rename.db
+mu workstream init auth-refactor
+# re-add the tasks you still need, with -w auth-refactor
+mu workstream teardown auth-refator --yes
 ```
 
 Names start with a lowercase letter, use letters, digits, `_`, or

package/docs/guide/sql.md

@@ -20,12 +20,12 @@ 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.
+timeout, a locked DB, or a multiplexer, VCS, drift, or `mu doctor`
+FAIL-row failure, `6` reaped pane, `7` stall.
 
 ## Read the schema
 
-The schema has 11 tables and 3 views (`ready`, `blocked`, `goals`).
+The schema has 12 tables and 3 views (`ready`, `blocked`, `goals`).
 Four tables travel between machines: `workstreams`, `tasks`,
 `task_edges`, and `task_notes`. List them all:
 
@@ -66,7 +66,14 @@ mu sql "WITH RECURSIVE prereqs(id) AS (
 ```
 
 `mu sql` runs writes too and prints the number of rows changed. Writes
-are captured as ops, so `mu undo` can revert them.
+are captured as ops under one `sql.write` group per call, so `mu undo`
+reverts the whole call. `--confirm-rows N` counts rows removed by
+`ON DELETE CASCADE` too: deleting a task with one edge counts 2.
+
+`mu sql` refuses to change a natural-key column (`workstreams.name`,
+`tasks.workstream_id`, `tasks.local_id`, a note's task, or an edge's
+endpoints). The ops log files every change under that key, so changing
+it would desync sync, undo, and `mu doctor`. Add a new row instead.
 
 ## Pass list flags
 

package/docs/guide/stop-a-worker.md

@@ -55,7 +55,9 @@ freed with it. If the workspace has edits or commits, close refuses
 with exit 4. Then do one of these:
 
 - Run `mu workspace free worker-1 -w auth --commit` to commit pending
-  changes and free the workspace, then close.
+  changes and free the workspace, then close. For git, if the commits
+  are on no branch, mu keeps them on a new branch
+  `mu/<workstream>/<agent>-<sha>`.
 - Run `mu agent close worker-1 -w auth --discard-workspace` to free
   and close in one step. You lose the changes.