# Vocabulary Canonical terms for mu. **Use these exact words in code, docs, error messages, and the LLM-facing skill.** When two words could mean the same thing, the one in this doc wins. If another doc uses a term not defined here, fix the doc. If you need a new term, add it here first. --- ## TL;DR — canonical terms | Use this | For… | Don't use | | --------------------- | ------------------------------------------------------------------------ | -------------------------------------------------- | | **workstream** | The unit of organization. One workstream = one **mux session** = one DB partition | "project", "session" (ambiguous), "context" | | **multiplexer** / **mux** | The terminal substrate that owns panes. Two supported: **tmux** and **herdr**. "mux" is the short form used in code (`src/mux/`, `MU_MUX`); "multiplexer" is the prose form. Exactly one is active per mu invocation, chosen by **mux detection** — mu never drives two at once. | "terminal", "emulator", "backend" (alone — say **mux backend**) | | **mux backend** | An implementation of the `MuxBackend` interface (`src/mux/tmux.ts`, `src/mux/herdr.ts`). Owns everything backend-specific: session/window/pane topology, the send protocol, scrollback capture, **pane id** validation, and **actor** identity fallback. Sibling of **VCS backend**; same `src/vcs/` shape. | "driver", "provider", "adapter" | | **mux session** | The mux-level container holding one workstream's panes. On tmux it is a **tmux session** named `mu-`; on herdr it is a herdr *workspace* labelled `mu-`. Use the generic term in cross-backend prose and the specific term when the backend matters. | "mux workspace" (collides with mu's VCS **workspace**), "session" alone | | **mux detection** | The ladder that picks the active **mux backend**: `MU_MUX` override → `HERDR_ENV=1` → `$TMUX` → whichever binary is on `PATH` (tmux wins a tie as the incumbent) → `NoMultiplexerError`. `HERDR_ENV` outranks `$TMUX` because it is the narrower signal: only a herdr-managed pane sets it, and herdr may itself be running inside tmux. | "auto-detect" (vague), "probe" | | **scratch workstream**| The reserved workstream named `scratch` for off-the-cuff agent use — spin up a helper you'll keep talking to without crew/DAG ceremony. Explicit `-w scratch` (no implicit fallback); auto-created on first spawn; `mu workstream init scratch` is rejected (loud). Agents in it are still **agents**, NOT pi-subagents. Task-less is fine; the DAG stays opt-in. | "throwaway ws", "temp workstream", "subagent" | | **tmux session** | The literal tmux session a workstream lives in — the tmux flavour of a **mux session** | "session" alone (ambiguous) | | **window** | The mid-level grouping inside a **mux session** (tmux window / herdr tab); identified by `window_name` | "tab" (except as the frontmatter field name) | | **pane** | One shell view inside a **window**; identified by **pane id** | "terminal", "shell" | | **pane id** | The mux's stable handle for a **pane**. Shape is backend-specific — tmux `%15`, herdr `w1:p1` — so validation lives on the **mux backend**, never as a global regex. Stable for the pane's lifetime; never reused after close. Distinct from a tmux pane *index* (`0`, `1`, …), which is volatile and must never be stored. | "pane number", "pane index" | | **pane title** | The string identifying which **agent** occupies a pane. **Equals the agent's name.** Set via `select-pane -T` on tmux, and via `herdr pane rename` (the pane *label*) on herdr. A fallback for **actor** identity — `$MU_AGENT_NAME` is consulted first. | "pane name" | | **window name** | The **window**'s name. **Equals the agent's `tab:` value** (groups one or more agents). | "tab name" (in code; `tab:` only in frontmatter) | | **agent** | A named worker running in a pane; identity = `$MU_AGENT_NAME`, falling back to **pane title**; row in `agents` table | "subagent" (reserved for pi-subagents), "worker" (only the specific role) | | **worker** | An **agent** in its role-as-task-claimer. Synonym for the registered side of identity — a row in `agents`, owns tasks via the FK. | (when ambiguous, prefer **agent**) | | **actor** | The party that *caused* a state change. May or may not be a registered worker. Recorded in `ops.actor` for every op. The orchestrator running mu from a top-level shell is an actor but not a worker. | "caller", "author" (only on notes) | | **crew** | *Informal* collective noun for the agents in a workstream | (no API surface; prose only) | | **task** | A node in the DAG. Has mandatory `impact` and `effort_days`. Status one of `OPEN`, `IN_PROGRESS`, `CLOSED`, `REJECTED`, `DEFERRED` (see **task status** below). | "issue", "ticket", "item" | | **task status** | One of 5 states. **OPEN** = ready to be claimed; **IN_PROGRESS** = claimed and active; **CLOSED** = work completed (the only state that satisfies a `--blocked-by` edge); **REJECTED** = terminal 'won't do' (out of scope, duplicate, wontfix); **DEFERRED** = parked, may revisit. REJECTED and DEFERRED both still BLOCK downstream by design — only CLOSED unblocks. | "state" | | **reject** | Verb: stamp a task `REJECTED`. Refuses if open dependents would be stranded; pass `--cascade` to apply to the whole sub-tree. | "wontfix", "close as wontfix" | | **defer** | Verb: stamp a task `DEFERRED`. Same stranded-dependent guard as reject. Reopen with `mu task open`. | "park", "snooze", "backlog" | | **task DAG** / **graph** | The directed acyclic graph of tasks. | "task list", "todo", "tree" (it's a DAG, not a tree) | | **edge** | A `blocks` relationship between two tasks. The single edge type. `A blocks B` = A must close before B can start. | "dependency" (use only in prose) | | **track** | An independent subtree of the DAG identified by parallel-track detection | "branch", "lane" | | **diamond merge** | When two tracks share a prerequisite, parallel-track detection collapses them into one track to prevent two agents from colliding on the shared dependency. | "join", "converge" | | **ready** | An OPEN task with no unresolved blockers. Exposed as the `ready` SQL view. | "unblocked", "available" | | **goals** | Tasks with no outgoing blocks-edges (graph endpoints). Exposed as the `goals` SQL view. | "leaves", "targets" | | **sort key** | Argument to `mu task list / next / ready --sort `. One of `roi` (impact / effort_days, default for `next` / `ready`), `recency` (`updated_at` DESC — "what did I touch most recently"), `age` (`created_at` ASC — "what's gone stale"), `id` (`local_id` ASC, default for `task list`). The two time-based keys also render an `updated`/`created` relative-time column in the table view. | "order by", "sort by" | | **subtree** / **scope** | The set of tasks reachable from a root via blocks-edges | "subgraph" (only for technical descriptions) | | **note** | An append-only piece of context attached to a task | "comment" (reserved for VCS), "log" (reserved for the **ops log**) | | **log entry** | A rendered **op**, as shown by `mu log`. Not a distinct table — the ops log is the only log. Prose comes from the op's **intent** via ONE formatter (`src/log-render.ts`), shared by `mu log`, `mu state`, and the TUI. Rows with no intent (operator writes / a **log ledger**) are shown verbatim. One hidden exception: a parent-row *touch* (payload is only `updated_at`) is a real op but not a log line. | "message" (overloaded), "event" (overloaded) | | **kind** | The operator-chosen channel tag on a **log entry** — `mu log --kind ` sets it on write and filters to it on read. Stored as the op's `entity`. A different axis from **intent**: **kind** is what the *operator* labels a hand-written line, **intent** is what *mu* records about a state change. Captured ops get their entity from the table they mutate (`task`, `note`, `edge`, `workstream`), and machine-local ops use `agent` / `workspace`; `message` is the default for a bare `mu log "text"`. | "category", "type" (overloaded) | | **log ledger** | A doc-only *convention* (not a feature): use a custom `--kind` tag as a durable, append-only dedupe/memory ledger for a watcher loop. Each tick records last-seen external state (`mu log --kind pr-state 'pr=N sha=.. ci=..'`); the next tick reconstructs it with `mu log --kind pr-state -n 1 --json`. State lives in SQLite, so it survives `/loop` or `/watch` death and context compaction — no in-session bookkeeping. | "state file", "dedupe cache" | | **claim** | Verb: set `tasks.owner` to an agent. Atomic CAS. | "assign" (use only in prose), "lock" | | **owner** | The **worker** name in `tasks.owner`. Set by claim. NULL when the task is unowned OR was claimed via `--self` (anonymous, attributed via `ops.actor` instead). Owners are **machine-local** — they reference `agents`, so ownership never syncs. | "claimer", "assignee" | | **anonymous claim** | A claim made via `--self` where the **actor** isn't a registered **worker**. `tasks.owner` stays NULL; the actor is recorded in `ops.actor` for the auto-emitted `task.claim` op. The orchestrator-doing-direct-work pattern. | "self-claim" (in code; "anonymous claim" in prose), "unowned claim" | | **release** | Verb: clear `tasks.owner` | "unclaim", "unassign" | | **free** | Verb: mark an agent's `status = 'free'` (idle, available) | "park", "idle" (verb) | | **status** | Persisted enum on `agents` (busy/needs_input/free/...) | "state" (use only "lifecycle state") | | **lifecycle state** | A position in the agent state machine | "state" alone, "phase" | | **role** | `full-access` or `read-only` capability flag | "permission" (avoid), "tier" | | **persistent** | Agent that stays alive across tasks | "long-lived" (only in prose) | | **one-shot** | Agent that exists for a single task and then terminates | "ephemeral", "transient" | | **workspace** | A VCS-isolated checkout (jj workspace / sl worktree / git worktree / cp). **In mu, "workspace" is always the VCS sense** — never the mux sense. herdr calls its session-level container a "workspace" too; in mu docs and code that is a **mux session**. | "branch" (it has one but isn't one), "checkout" (only for `none` backend), the herdr sense | | **ghost** | An `agents` row whose `pane_id` no longer exists in the **mux**. Pruned by **reconcile**, which runs in `mu agent list` and `mu doctor`. | "dead agent" (a dead agent may still have a pane), "stale row" | | **reaper** | The part of reconcile that releases a **ghost**'s tasks: `IN_PROGRESS → OPEN`, owner cleared. Makes `mu task wait` exit 6. | "garbage collector", "janitor" | | **workspace orphan** | A directory under `/workspaces//` with no row in `vcs_workspaces`. Blocks subsequent `--workspace` spawns. Surfaced by `mu workspace orphans -w X` and `mu state -w X`. | "stray dir", "leftover workspace" | | **stale workspace** | A workspace whose `parent_ref` is N commits behind the project's default branch HEAD (per the workspace's local refs cache). Rendered as a color-coded `behind` column (green ≤2, yellow 3–9, red ≥10) in `mu workspace list` and `mu state`; ≥10 triggers a one-line warn in `mu state`, `mu task claim --for`, and `mu agent send` (or refusal on the two dispatch verbs with `--strict-staleness`). Pure observation — mu never auto-fetches. | "out of date", "drifting" | | **refresh** | `mu workspace refresh ` — rebase the agent's workspace onto a fresh base (default = backend's tracked main; `--from ` overrides) WITHOUT touching the agent or pane. Refuses on dirty WC; surfaces conflicts as exit 5 with a resolve-in-place hint. The `none` backend errors (no VCS to rebase). | "recycle", "reset" (overloaded) | | **recreate** | `mu workspace recreate ` — free + create the agent's workspace in one shot. The between-wave "prep this worker for the next dispatch" verb. Reuses the previous backend unless `--backend` overrides; bases on current main unless `--from ` overrides. Refuses on dirty WC the same way `free` does; `--force` discards the dirty edits (lossy). Sibling of **refresh**: refresh PRESERVES the worker's commits (rebases them onto fresh main); recreate THROWS THEM AWAY. | "recycle", "reset" (overloaded), "free+create" (only in commit messages) | | **backend** | Implementation of `MuxBackend` or `VcsBackend`. Always qualify which (**mux backend** / **VCS backend**) when both are in scope. | "driver", "provider" | | **detector** | Per-CLI pattern matcher for busy/permission/ready, used when the **mux backend** cannot report status itself. On tmux that is always (`detectPiStatus` in `src/detect.ts`, covering vanilla pi + any TUI wrapper using Braille spinner glyphs); on herdr the mux classifies panes natively across its known agent kinds, so the detector is bypassed. The seam is the optional `MuxBackend.paneStatus?()`: absent means "ask the detector". herdr's states map `working` → `busy`, `blocked` → `needs_permission`, and `idle` / `done` / `unknown` → `needs_input` — `unknown` never becomes `free`, since herdr documents that it does not prove completion, and no detector of either kind may mint `free`. Other CLIs spawned via `--cli ` may misclassify on tmux; trust scrollback over the emoji. | "matcher", "parser" | | **op** | The atomic unit of change: one row in the `ops` table, written by a trigger inside the same transaction as the mutation it records. Carries `(hlc, machine_id, group_id, actor, intent, entity, key, op, payload)`. A **semantic partial update** — the payload holds only the columns that actually changed, which is what makes per-field merge free. | "event", "delta", "change" (all overloaded) | | **ops log** | The `ops` table: the single append-only record of every change, and the substrate **sync**, **undo**, **archive**, and history are all queries or replays over. Canonical and ACID because it lives in `mu.db` alongside the tables it records. | "event log", "journal", "WAL" (reserved by SQLite) | | **intent** | The semantic label on an **op** (`task.close`, `task.reparent`, `agent.spawn`). Set once per public SDK function via **op context**, not per mutation. `mu log` renders prose from it through one formatter. | "verb" (overloaded by CLI verbs), "action" | | **group** | A set of ops sharing a `group_id` — one user-visible action. A cascade close writes N ops in one group, so `mu undo ` reverts them as a unit. Ids are uuids, so every verb that takes one (`mu undo `, `mu log --group`) accepts any unique PREFIX via the shared `groupIdFromPrefix` — the affordance git gives for shas. An ambiguous prefix is a conflict (exit 4), never a guess. | "transaction" (reserved by SQLite), "batch" | | **op context** | The per-connection `_op_ctx` temp table holding `(group_id, actor, intent, applying)` for the current transaction. Triggers read it to stamp ops; `applying=1` suppresses capture while ingesting a peer's ops (echo-loop guard). Set through the scoped `withOpContext(db, {...}, fn)` / `withCaptureSuppressed(db, fn)` helpers in `src/op-context.ts`, never by writing the table directly — the scoping is what guarantees a throw cannot leak a stale intent onto later ops. Two sibling temp tables support it: `_op_clock` (holds "now" for one trigger firing so the HLC advance reads a single consistent value) and `_op_dying` (natural keys of rows mid-DELETE, so FK-cascaded children can still resolve a key after their parent row is gone). | "ambient context", "thread local" | | **apply** | Verb: land one **op** into the portable tables, honouring the **merge rules**. `applyOp` / `applyOps` in `src/apply.ts`. Always runs capture-suppressed (`applying=1`), so applying never mints a new op — that is the echo guard. Idempotent: applying the same op twice changes nothing, which is what makes `mu sync --repair` merely "re-read that peer's **segment** from zero". Distinct from **ingest**, which is the sync-side loop that reads a segment and calls apply per op. | "merge" (that's the rule set), "import", "replay" (replay is undo/archive) | | **merge rules** | The per-entity conflict policy the **apply** path implements. note/message = **grow-only set**; task/workstream = **per-field LWW**; edge = **LWW-element-set**; machine-local entities are rejected. One rule per entity, chosen so that convergence needs no coordination between machines. | "conflict resolution" (implies prompting a human), "CRDT" (only loosely true) | | **per-field LWW** | Last-writer-wins applied PER FIELD, not per row: each field of a task independently keeps the value written by the newest **HLC** that touched THAT field. Free, because ops are **semantic partial updates**. Row-level LWW is explicitly rejected — with agent crews on two machines, a crew closing a task while the operator edits its impact is concurrent by construction, and row-level would silently discard one edit. | "row LWW", "column versioning" (implies version vectors we don't need) | | **grow-only set** | An entity that is only ever inserted, never updated: **notes** and log messages. Two machines therefore cannot disagree about a note's content, so there is nothing to resolve — apply is insert-if-absent. Identity is `(task, author, content)`, since a note's surrogate id is assigned per machine and cannot identify it across machines. | "append-only log" (that's the ops log), "set" | | **LWW-element-set** | The rule for **edges**: set membership where both the add and the remove carry an **HLC**, so a remove and a later re-add converge in either arrival order. An edge has no fields worth merging — it is present or absent. | "add-wins set", "2P-set" (a 2P-set can't re-add) | | **tombstone** | An `op='del'` row. There is NO tombstone table: a tombstone is an ordinary op carrying an **HLC**, so out-of-order arrival is just "compare HLCs", the same comparison the update path makes. A late **put** older than a seen tombstone loses; a tombstone older than a seen put loses. | "deletion marker", "grave" | | **resurrection** | A **put** with an HLC NEWER than a seen **tombstone** for the same key, which legitimately recreates the row. Distinguishable from a stale put (older than the tombstone, and must lose) because **provenance** outlives the row: ops are never deleted when a table row is. | "undelete" (that's `mu undo`), "revive" | | **provenance** | Which **HLC** last wrote a given field of a given key — what **per-field LWW** compares against. DERIVED from the **ops log** by query, never stored in a side table: `ops` already records which fields each HLC touched, so a side table would be a denormalisation that can disagree with the log with no procedure to decide which side is right. Costs zero extra storage and survives row deletion for free, which is what makes **resurrection** work. | "version vector", "clock table", "field metadata" | | **inverse op** | The op that reverts another: `del` for a **put** that created a row, a `put` restoring prior field values for a put that changed them, a `put` restoring the row for a `del`. Written through the normal capture path, so it carries a fresh **HLC** and is an ordinary op — which is why an undo syncs and is itself undoable. | "rollback", "revert commit", "compensating transaction" | | **superseded** | Of a **group**: a later group has written the same field(s) since, so emitting **inverse ops** would discard that newer work. `mu undo` refuses (exit 4) and names the conflict rather than clobbering or silently skipping; `--force` overrides. Detected PER FIELD, so a later edit to a different field of the same row does not block the undo. | "stale", "conflicted" (conflict is the exit-code label) | | **drift** | Divergence between the **ops log** and the live tables. Means capture missed a mutation or **apply** is lossy — always a BUG, never operator error, and never transient. Detected by `mu doctor` (shallow: every live row must have at least one op naming its key) and `mu doctor --deep` (full rebuild + field-level diff). Exits 5. Remediation is NOT 'rebuild': if capture missed the mutation, the live tables hold work the log never saw. | "inconsistency", "corruption" (corruption is the SQLite file being damaged, which is different) | | **shallow / deep check** | The two drift tiers. Shallow is ~3ms and runs in every `mu doctor`; deep rebuilds the whole log (~0.6ms per op) and runs only under `--deep`. Shallow is a smoke alarm, not a proof — it cannot see an uncaptured UPDATE because the row's key still has ops. | "quick/full scan", "fsck" | | **mixed fleet** | More than one machine sharing state, where the machines differ in OS or filesystem semantics. The three hazards mu checks for: the DB living inside the sync dir, the DB on a network mount, and workstream names that differ only by case (fine on ext4, colliding on APFS/NTFS). | "cluster" (implies coordination mu does not have), "multi-device" | | **portable** | Of a table or entity: syncable across machines. Portable = `workstreams`, `tasks`, `task_edges`, `task_notes`. **Machine-local** = `agents` (holds `pane_id`), `vcs_workspaces` (absolute paths differ across macOS/Linux), `machine_identity`, `schema_version`, `sync_peers` (local watermarks), and `ops` itself — the ops table is never wholesale-copied; individual op *rows* ship, filtered by synced entity and carried by **segments**. Machine-local ops are still recorded (so `mu log` shows them) but never leave the machine. Declared as code in `src/db.ts`: `PORTABLE_TABLES` / `MACHINE_LOCAL_TABLES` / `SYNCED_ENTITIES`, guarded so the two table lists must partition `EXPECTED_TABLES`. | "shared", "global" | | **HLC** | Hybrid logical clock: `(wall_ms, counter, machine_id)` serialized to a sortable TEXT. The ordering key for every op. Monotonic — never regresses — so a laptop waking with a skewed clock cannot resurrect stale edits. Persisted in `machine_identity` because every mu invocation is a fresh process. | "timestamp", "version" (both imply wall clock) | | **machine_id** | Per-state-directory uuid seeded on first `openDb` and stored in `machine_identity`. Identifies one mu DB as a **peer** and names its **segment**; users do not configure it. | "device id", "host id" | | **segment** | An append-only JSONL file at `/.jsonl` holding one machine's ops. **Single-writer-per-file**: a machine appends only to its own and read-onlys every other, so no file is ever contended and any file-mover (Syncthing, rsync, scp, git, USB) is adequate transport. Derived and regenerable from the `ops` table, so losing one costs a re-flush. | "replica", "shard", "stream" | | **peer** | Another machine, discovered implicitly as a `.jsonl` **segment** in the sync dir. There is no membership list to configure or keep consistent — dropping a segment in the folder joins the cluster. Referred to by `machine_id`, or any unique PREFIX of one (the affordance git gives for shas); an ambiguous prefix is a conflict, never a guess. NOT by hostname: `machine_identity.hostname` is machine-local and never ships, so a hostname display would need the membership file `MU_SYNC_PEERS` was rejected for being. A peer is **stale** when its segment file has not moved in 24h — a display threshold, not an env var. | "node", "replica", "remote" | | **watermark** | Per-peer integer in `sync_peers.last_applied_seq`: how far into that peer's **segment** we have applied, counted in LINES of that segment (not the peer's `ops.seq`, which is a local-only cursor on their machine and means nothing here). One integer suffices because segments are append-only and ordered. Advanced only as far as the last GOOD record, so damage is re-read rather than skipped. | "offset", "cursor" (cursor is reserved by `mu log`) | | **flush** / **ingest** | The two halves of sync. Flush appends local ops to my own **segment**; ingest reads each peer segment from its **watermark** and applies. Both run ambiently on every mu invocation when `MU_SYNC_DIR` is set — there is no daemon. | "push"/"pull" (imply mu moves files; it does not) | | **reprojection** | The pass that lands **ops** which could not be applied when they arrived because the row they hang off was not here yet — an `edge` or `note` whose task came from a DIFFERENT **peer**'s **segment**. Runs once after every **ingest** pass (never per peer: an edge in one segment may name a task in another, so only the union suffices) and asks the **ops log** which of them are resolvable NOW, rather than keeping a retry queue that could disagree with the log and would not survive a short-lived mu process. Excludes ops whose parent is gone and keys with a newer `del`, so it never resurrects a deleted edge. `reprojectDeferredOps` in `src/apply.ts`. | "retry queue", "pending ops", "deferred apply" | | **marker** | An op (`entity='marker'`, `intent='archive.add'`, key `