@mu-crew/mu 3.13.3 → 4.1.0

package/docs/architecture/dag.md

@@ -1,117 +0,0 @@
-# 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.
-- **No hidden edges.** Every edge comes from a verb the caller ran (`block`,
-  `add --blocked-by`, `reparent --blocked-by`); no write adds edges
-  on its own or wires a task to a top goal. A hidden edge makes phantom
-  blockers and false cycles, and `unblock` appears to do nothing.
-- **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|triage`, `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` and `OPEN/triage` are excluded from `ready`
-  but stay in `goals`; `claim` refuses both without `--force`.
-- **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

@@ -1,167 +0,0 @@
-# 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 `workstream_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`. 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. 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
-  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

@@ -1,160 +0,0 @@
-# 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 only when they must be.** 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, so the puts can sit under an
-  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, 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)
-
-The log is append-only except for two operator verbs in `src/compact.ts`,
-both dry-run by default, both backing up beside the DB and running the
-drift check after:
-
-- **`mu db compact`** blanks note tombstones a put under the same key
-  already explains: the slim form capture writes now, applied to older
-  rows. Undo and sync unaffected.
-- **`mu db forget <workstream...>`** deletes every op of named
-  torn-down workstreams (keys `<ws>` and `<ws>/...`). Their rows are
-  already gone from the tables, so rebuild and drift stay consistent;
-  `mu undo` of those teardowns is gone on purpose.
-
-Neither touches sync segments. A peer is not affected: watermarks only
-read forward, so a peer never re-sends forgotten history.
-
-## 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.

package/docs/architecture/sdk.md

@@ -1,187 +0,0 @@
-# CLI and SDK surface
-
-Every user-visible operation is a typed SDK function plus a thin
-Commander wrapper. This page covers the boundary rules, errors, tests
-and packaging. Overview: [ARCHITECTURE.md](../ARCHITECTURE.md).
-
-## One surface, two callers
-
-`src/cli.ts` (`buildProgram`) and the namespace files under `src/cli/`
-are the verb surface: no generated registry, no DSL, no separate
-operation schema. Programmatic callers import the same functions from
-`src/index.ts`. Agents and scripts compose verbs with `--json`.
-
-A verb's path:
-
-1. The Commander block calls a `cmd<Verb>` wrapped in `handle()`.
-2. `handle()` opens the DB, runs ambient sync ingest
-   ([sync.md](sync.md#the-ambient-hook)), and calls the SDK function.
-3. The SDK function opens `db.transaction(fn)()` for multi-statement
-   writes. Agent ops call the mux (and jj, sl or git for workspaces);
-   task ops are pure SQL. Read paths reconcile against the mux.
-4. Capture triggers record ops in the same transaction
-   ([ops-log.md](ops-log.md)). Machine-local changes go through
-   `emitEvent`. `mu log --tail` sees them on its next 1-second poll.
-5. On error the transaction rolls back and the typed error reaches
-   `handle()`, which maps it to an exit code. Flush runs on both paths.
-
-Output is self-documenting: `src/output.ts` (`printNextSteps`,
-`errorNextSteps`) prints `Next:` hints, quoted by `src/shell-quote.ts`
-so they paste cleanly.
-
-## Surrogate-PK and SDK-boundary discipline
-
-Every entity table has this shape:
-
-```
-(
-  id            INTEGER PRIMARY KEY AUTOINCREMENT,   -- surrogate; internal
-  <scope_id>    INTEGER NOT NULL REFERENCES <parent>(id) ON DELETE CASCADE,
-  <name>        TEXT NOT NULL,                        -- operator-facing; mutable
-  -- ... domain attributes
-  UNIQUE (<scope_id>, <name>)                         -- per-scope unique
-)
-```
-
-FKs reference `<parent>_id` (INTEGER), never the TEXT name. The name is
-an attribute: searchable, displayable, cheap to rename. The surrogate
-id is the identity.
-
-**TEXT by design:**
-
-- the workstream's own `name` (it is the mux session name; globally
-  unique);
-- `task_notes.author` and `ops.actor` (free-text labels such as
-  `"orchestrator"`);
-- `ops.entity` (open enum; a new entity needs no migration);
-- `agents.cli` (a new CLI needs no schema change);
-- every column of `ops`. The log is FK-free and addresses rows by
-  natural key, so an op outlives its row and its workstream.
-
-**The boundary rule** matches REST: the external API uses business
-identifiers, the internal layer uses primary keys.
-
-> **Public SDK functions take operator-facing names.**
-> **Internal helpers take surrogate ids.**
-> **Resolution happens at the public-function entry, exactly once.**
-
-```ts
-// PUBLIC: takes operator-facing names
-export function claimTask(
-  db: Db,
-  workstream: string,
-  localId: string,
-  opts?: ClaimOptions,
-): ClaimResult {
-  const wsId = resolveWorkstreamId(db, workstream);
-  const taskId = tryResolveTaskId(db, wsId, localId);
-  if (taskId === null) throw new TaskNotFoundError(localId);
-  const agentId = resolveCurrentAgentId(db, wsId);
-  return claimTaskById(db, taskId, agentId, opts);
-}
-
-// INTERNAL: takes surrogate ids; never re-resolves
-function claimTaskById(db, taskId, agentId, opts): ClaimResult { ... }
-```
-
-Resolving once gives three things: no double resolution; no
-workstream context needed below the boundary, because the FKs make
-scope implicit; and one place for error mapping.
-`WorkstreamNotFoundError` comes from `resolveWorkstreamId` in
-`src/db.ts`. `TaskNotFoundError` and `AgentNotFoundError` are raised by
-callers wrapping a `tryResolve*` null, so exit 3 holds whichever lookup
-missed.
-
-**Workstream scoping is mandatory at the CLI boundary.** TEXT names
-(`tasks.local_id`, `agents.name`) are unique per workstream, so the
-same name can exist in two. Every public function taking such a name
-also takes the workstream; internal SQL filters by
-`(workstream_id, name)`.
-
-**`--json` keeps operator-facing names.** Surrogate ids never appear in
-`--json`, error payloads, log lines or exports. Exposing them would
-bring back a global namespace.
-
-## State of truth
-
-- The DB (`~/.local/state/mu/mu.db`, or `MU_DB_PATH`) is canonical.
-  Everything else is a cache, including pane titles.
-- Writes go through the typed SDK functions, which validate, transact
-  and reconcile. Op capture is the triggers' job.
-- In-memory state lives only for one command's connection.
-- Multiple `mu` processes share the file safely through SQLite WAL.
-
-## Errors
-
-Errors are typed classes per layer (`src/agents/errors.ts`,
-`src/tasks/errors.ts`, `MuxError` with `TmuxError` / `HerdrError`, and
-so on). Nothing swallows them. `src/cli/handle.ts` maps them to exit
-codes:
-
-| Code | Meaning |
-| --- | --- |
-| 0 | success |
-| 1 | generic error |
-| 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 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.
-
-## Testing layers
-
-Fast tier (`npm run test:fast`) excludes `*.integration.test.ts` and
-`*.smoke.test.ts`. It uses real SQLite in per-test temp DBs and a
-mocked mux (`installMux()` from `test/_mux.ts`). Integration tests use
-real tmux or herdr, and real git, jj or sl in `os.tmpdir()`; jj and sl
-tests skip when the binary is missing. Conventions live in
-[AGENTS.md](../../AGENTS.md) and `test/README.md`.
-
-| Area | What the tests pin |
-| --- | --- |
-| `src/capture.ts`, `src/op-context.ts` | payloads hold only changed columns (asserted by key count); echo suppression; cascade grouping; FK-CASCADE tombstone keys; the null-intent fail-safe |
-| `src/apply.ts` | injected HLCs, no sleeps: field convergence in both orders; same-field LWW determinism; all four put and del orderings; resurrection; grow-only notes; the set-to-NULL trap; `owner_id` stripping; replay idempotence |
-| `src/rebuild.ts` | round trip row by row per portable table (a count-only check passes on a garbage rebuild); tombstones; byte-identical ops; `machine_id` and clock carried |
-| `src/drift.ts`, `src/fleet-hazards.ts` | drift planted the way a capture bug would (`withCaptureSuppressed` plus a direct write), with equal weight on false positives |
-| `src/dormant.ts` | `updated_at` written directly; weighted to the boundary between `finished` and `abandoned` |
-| `src/disk-recon.ts` | a per-test `MU_STATE_DIR` with the on-disk shape built by hand, both directions |
-| `src/segments.ts`, `src/sync.ts` | two temp DBs and one shared dir; each robustness layer; machine-local ops never reaching a file |
-| `src/hlc.ts` | an injected clock: backward jumps, stalled milliseconds, concurrent minting |
-| `sync-session.integration` | 8 rounds of two machines: byte-identical portable content, no `--deep` drift, a quiet round adds zero ops |
-| `test/acceptance.integration.test.ts` | the end-to-end gate: 10 tasks, 3 agents |
-
-`npm run test:stress` repeats the suite with per-run timeouts,
-optionally in parallel (`MU_TEST_STRESS_MODE=parallel`).
-
-Two fixture traps:
-
-- A convergence fixture must share one creation op. Two independent
-  `task add` calls for the same id make the later creation win every
-  field.
-- An ordering-sensitive sync test must rename segments to pin ingest
-  order, since peers are discovered by `localeCompare` over random-UUID
-  filenames.
-
-Treat a test that passes alone and fails under load as a concurrency
-bug first. Drive wait and reaper tests from poll-loop seams, not fixed
-timers, and wait for stable Ink output instead of sleeping.
-
-## Distribution
-
-One npm package, `mu`. `tsup` bundles three entries:
-
-| Output | Role |
-| --- | --- |
-| `dist/cli.js` | `bin: { mu: ./dist/cli.js }` |
-| `dist/index.js`, `dist/index.d.ts` | SDK and types |
-| `dist/extension/mu-pi.js` | the pi extension `mu link pi` points at |
-
-`skills/` and `docs/` ship alongside. There is no build step on the user's
-machine. pi stays a peer dependency: the extension types pi's API
-structurally. Per-role agent guidance lives in the user's repo, not in
-mu. The rule for adding a dependency is in
-[ROADMAP § Anti-feature pledges](../ROADMAP.md#anti-feature-pledges).