@mu-crew/mu 3.13.3 → 4.1.0

package/dist/tui-sync-worker.js

@@ -1,17 +0,0 @@
-import { createRequire as __muCreateRequire } from "node:module"; const require = __muCreateRequire(import.meta.url);
-import {
-  ambientSyncPass,
-  openDb
-} from "./chunk-45KQLMEL.js";
-import "./chunk-WI6AWCMK.js";
-import "./chunk-3BARPJLY.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

@@ -1 +0,0 @@
-{"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-XDOONQSL.js

@@ -1,13 +0,0 @@
-import { createRequire as __muCreateRequire } from "node:module"; const require = __muCreateRequire(import.meta.url);
-import {
-  osc52Sequence,
-  probeClipboardBackend,
-  yank
-} from "./chunk-QITLNZEM.js";
-import "./chunk-3BARPJLY.js";
-export {
-  osc52Sequence,
-  probeClipboardBackend,
-  yank
-};
-//# sourceMappingURL=yank-XDOONQSL.js.map

package/dist/yank-XDOONQSL.js.map

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

package/docs/ROADMAP.md

@@ -1,123 +0,0 @@
-# Roadmap
-
-If a feature is not here, it is not planned. Shipped work is in
-[CHANGELOG.md](../CHANGELOG.md). Pillars are in [VISION.md](VISION.md).
-
-## Promotion criteria
-
-A roadmap item is built when all three hold:
-
-1. **Proven friction.** A real user hit the gap in a real workflow at
-   least twice.
-2. **No pillar refactor.** It fits without bending a
-   [VISION](VISION.md) pillar.
-3. **Bounded scope.** It fits in <300 LOC, or a smaller subset does.
-
-Data-loss footguns ship on the first occurrence. Polish (bug fixes,
-ergonomics, error wording, docs) needs no promotion: ship it through the
-green gate.
-
-## Anti-feature pledges
-
-mu does not add these unless one earns its way back under the criteria:
-
-- **A config file.** Config is CLI flags and env vars.
-- **A daemon, watcher, or background process** beyond tmux and SQLite.
-- **Abstractions with no current consumer** (the cautionary tale: a
-  `RunContext` trait with no implementor).
-- **Wrappers around wrappers** (`TextStream`/`TextState`/`StreamResult`).
-- **Codegen, an embedded JS engine, macros, or decorators.** No workflow
-  DSL.
-- **Templates or definitions for agent roles.** Spawn flags and the first
-  message are the definition.
-- **Render layers beyond `cli-table3` + `picocolors`**, except `ink` in
-  `src/cli/tui/`. If `ink` stops paying off, replace it. Never run two
-  TUI stacks.
-- **Bundling pi.** It is a peer dependency.
-- **A plugin runtime, web UI, RPC, chat or docs integrations, a memory
-  system, or a workflow engine.** A prior internal runtime collected all
-  of these. Not inheriting them is the point.
-
-## Candidates
-
-Each has a design but no proven friction yet. Most come from the prior
-runtime, which hit the gap and fixed it its own way. Parked tasks may
-track them; delete the row when one ships.
-
-| Item | Gap today | Shape | Size |
-| --- | --- | --- | --- |
-| **Tag mux sessions with their DB** | `teardown --empty` never removes a `mu-*` session that has no DB row, because another DB may own it. | Set `@mu_db=<abs path>` at session creation. Remove unregistered sessions whose tag matches this DB, and keep foreign or untagged ones. Optional mux method, since herdr may have no equivalent. | ~60 LOC |
-| **Token usage per run** | Orchestrators cannot budget a fan-out. | The extension reports pi's usage for the run, and `wait --json` carries it. Unknown stays unknown, never 0. No dollar estimates. | ~80 LOC |
-| **Global delegate cap** | `MU_DELEGATE_MAX` applies per pi session. Several orchestrators, plus workers running `mu agent spawn -w scratch`, are not capped in total. | Count live `scratch` agents from the DB in the queue check. | ~30 LOC |
-| **Wait for a non-pi CLI's prompt** | `spawn --send` treats a blank or booting screen as calm and can paste before the CLI is ready. | Settle only once the CLI has drawn its input prompt. This needs a screen pattern for each CLI, so it waits for real friction. | ~40 LOC |
-| **Absolute deadline in `wait`** | A delegate re-armed after `/reload` restarts its countdown. | Report `deadline` (epoch ms) alongside `timeoutS`. | ~20 LOC |
-| **Bounded `task tree`** | No depth or node limit. | Cap depth, nodes and edges, and report which cap was hit. | ~30 LOC |
-| **Design-doc review angles** | `review-panel`'s angles are for diffs. | Add rollout and back-compat, alternatives, and integration angles. Synthesize into unanimous findings, tensions, and the strongest objection. | recipe |
-| **Sender framing on sends** | The receiving agent cannot tell a peer's message from its human's. | Prefix text sent by a mu agent with `[mu: from <agent>]`. This touches prompts, so it follows logging the sender. | ~20 LOC |
-| **A third mux backend** | None: tmux and herdr are the two implementations that justify `MuxBackend`. | zellij, wezterm or kitty. A third needs its own friction evidence; the existing interface is not evidence. | — |
-| **Subscription-based wakeups** | `mu log --tail` polls once a second. | SQLite update hooks or `fs.watch` on the WAL. Lower latency for more machinery. | — |
-
-## Next breaking release
-
-- **Schema v12 drops `agents.status`.** In v11 it stays for
-  compatibility and always holds `spawning`.
-- **`mu agent list --json` becomes `{items, count}`.** It emits
-  `{workstreamName, agents, orphans}`, the one collection off the
-  documented shape (SKILL.md notes the exception). Conforming breaks
-  `.agents` readers, `mu_delegate` among them.
-
-## Open questions
-
-- **Capability tags on operations.** Today the only authorization is
-  "the agent ran the verb". Enforce capabilities when an agent does real
-  damage.
-- **Per-workstream config.** Resisted by the pledges, but "this
-  workstream uses a different pi binary" is a gap env vars solve poorly.
-  Revisit when a second user hits it.
-
-## Explicitly rejected
-
-- **A JS or Lisp DSL** (`mu run`, `mu eval`, `mu repl`) <!-- doc-cli-drift:skip -->. bash, `jq`,
-  and `--json` cover it.
-- **A `defineOperation()` registry.** No consumer after the DSL went.
-- **Markdown agent-definition discovery.** Spawn flags and the first
-  message are the definition.
-- **mu as only a pi extension or only a library.** Children and humans
-  could not drive it from a shell, and processes would fight over the DB.
-- **Two binaries (`mu-agents` + `mu-tasks`).** Agents and tasks need one
-  transactional surface.
-- **A `TaskSurface` adapter.** The built-in graph is the point.
-- **Live sync through a daemon or remote backend.** Sync rides on
-  ordinary mu calls and mu only reads and writes files. See
-  [Rejected sync substrates](#rejected-sync-substrates).
-- **Network-opening verbs (`mu remote check`, `mu sync --push/--pull`)** <!-- doc-cli-drift:skip -->.
-  Every network hop is an operator command. Spawn passes it through
-  `--command` for the mux to run, or mu prints it as a next step. mu's
-  own process stays ssh-free.
-- **An HTTP API over SQLite** or **a hosted mu.**
-- **Personal agent names (`alice`, `bob`).** Use role names
-  (`worker-1`, `reviewer-1`).
-- **Pane scraping as a state fallback.** No state source means `unknown`.
-- **Runtime agent state in `mu.db`.** The copy goes stale. The control
-  socket, herdr, or murmur owns the current reading.
-- **Reading murmur's `state.db`.** Use its public contract.
-- **murmur as a hard dependency.** pi agents and the task graph do not
-  need it.
-
-### Rejected sync substrates
-
-mu syncs through the SQLite ops log plus append-only JSONL segments.
-These alternatives were rejected:
-
-| Substrate | Why not |
-| --------- | ------- |
-| **Litestream** | Daemon, single writer, one-way to object storage, and `restore` overwrites the whole file. It does disaster recovery, not laptop↔devserver merges. |
-| **LiteFS** | FUSE, which on macOS means a macFUSE kernel extension. |
-| **rqlite / dqlite / Marmot** | A consensus cluster and daemons to sync two machines that are rarely both awake. |
-| **cr-sqlite** | Merges rows by primary key. mu's `INTEGER PRIMARY KEY AUTOINCREMENT` ids collide across machines and merge silently. Also WIP upstream, no DDL sync, and a native build matrix. |
-| **RocksDB / LMDB for the op log** | No triggers, so a forgotten capture silently corrupts undo and sync. Single-process access forces a daemon. Loses SQL views, JOINs, and `mu sql`. |
-| **SQLite file per peer** | A torn transfer makes the whole file unreadable instead of one JSONL line. `-wal`/`-shm` sidecars in a synced folder corrupt DBs. Page churn defeats delta transfer. |
-| **`MU_SYNC_PEERS` list** | A config file that must match on every machine. Peers come from segment filenames instead. |
-| **`mu sync --push/--pull <host>` <!-- doc-cli-drift:skip -->** | mu's first ssh egress, with ssh config, auth, and error mapping. mu prints an rsync line instead. |
-
-The chosen design adds no dependency beyond `better-sqlite3`.

package/docs/VISION.md

@@ -1,298 +0,0 @@
-# VISION: A persistent crew of agents
-
-Terms are defined in [VOCABULARY.md](VOCABULARY.md).
-
-## What mu is
-
-mu is a small, durable control plane for a persistent crew of AI agents
-in multiplexer panes. Agents have names and roles, outlive sessions, and
-work on a built-in task graph, each in its own VCS workspace. Humans and
-agents drive them through one CLI. State lives in one SQLite file. Every
-feature is a typed verb over that state or a reconciled view of reality.
-
-```bash
-mu agent spawn worker-1   --tab Backend --workspace
-mu agent spawn reviewer-1 --tab Review  --workspace --role read-only
-mu task add --title "Build auth" --impact 80 --effort-days 3
-mu task claim build_auth --for worker-1 --evidence "have implementation plan"
-mu agent send worker-1 "Implement build_auth per the description"
-mu state                                # canonical state card
-mu log --tail                           # subscribe to every state change
-```
-
-Everything else makes those lines recover from failure and scale to
-dozens of agents and hundreds of tasks.
-
-## Why it exists
-
-Existing tools force a choice:
-
-- **Hidden subagents** (pi-subagents, the Claude Code and Codex task
-  tools) hand one-shot work to a child you cannot see, steer, or keep
-  talking to. Its transcript collapses into a result.
-- **tmux orchestration tools** spawn agents in panes but leave
-  coordination to chat transcripts or filesystem conventions.
-- **Task trackers** (GitHub Issues, Linear) model the work but do not
-  run the agents.
-- **Large orchestration platforms** hold the coordination state but
-  carry breadth that costs more to maintain than it returns. See
-  [What a prior runtime taught us](#what-a-prior-runtime-taught-us).
-
-mu joins the first three without becoming the fourth.
-
-## Design principles
-
-### 1. The CLI is the product
-
-Everything mu does works from a shell with no pi extension loaded. A
-feature that needs the extension does not ship. The pi extension
-(`mu link pi`) serves the control socket and the `mu_delegate` tool, and
-three rules keep it thin:
-
-1. **The DB is canonical.** The extension reads and writes through the
-   same modules as the CLI. It keeps no state of its own.
-2. **Every operation works from the CLI.** No extension tool has logic
-   the CLI lacks.
-3. **The skill teaches the CLI.** A pi session without the extension
-   still gets a working mu from [skills/mu/SKILL.md](../skills/mu/SKILL.md).
-
-Delegation is CLI: `mu agent spawn -w scratch`, `mu agent send`, and
-`mu agent wait --json`. `mu_delegate` only adds the callback that puts
-the answer into the parent conversation.
-
-### 2. One DB is canonical
-
-All state lives in `~/.local/state/mu/mu.db` (SQLite WAL, safe for
-concurrent processes). In-memory state is a cache. The extension and the
-CLI share the DB, so they cannot diverge.
-
-### 2b. One log records every change
-
-The `ops` table is the only change record. SQLite triggers write it in
-the same transaction as the mutation, so capture cannot be forgotten or
-drift from the data. Sync, undo, rebuild, and history are queries or
-replays over that log.
-
-Reads still go to the tables. mu is not event-sourced: the tables are
-the materialized view and triggers keep them in step with the ops.
-`mu doctor` rebuilds into a temp DB and diffs, so that is verified, not
-assumed. A capture bug therefore breaks sync, undo, and rebuild at once,
-which is why the drift check is load-bearing.
-
-### 2c. Local-first, transport-agnostic
-
-Every machine keeps a complete DB. Machines exchange append-only JSONL
-segments, one per machine with a single writer, so no file is contended
-and any file mover works (Syncthing, rsync, scp, git, a USB stick). mu
-reads and writes files. The user owns transport. mu has no network
-code, no daemon, and no membership config: peers are found from the
-segment files present.
-
-### 3. Reality wins reconciliation
-
-`mu agent list` queries the mux, prunes ghosts, and surfaces orphans.
-The DB records what mu last observed.
-
-### 4. Agents are dumb workers; the task graph is the brain
-
-The task DAG is the center of mu, not a sidecar. Tasks require `impact`
-and `effort_days`. Edges are `blocks` relations. `ready`, `blocked`, and
-`goals` are SQL views. The parallel-track detector runs union-find and
-merges diamonds, so two agents never collide on a shared dependency.
-
-"What next?" and "can we parallelize?" are deterministic queries. The
-LLM decides what to type to an agent. The graph decides which agent gets
-which task.
-
-### 5. One workstream per mux session
-
-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 `workstream_id`.
-The crew survives detach and reattach.
-
-The multiplexer is a backend chosen by detection
-(`MU_MUX` → `HERDR_ENV` → `$TMUX` → `PATH`), like the VCS backend.
-Topology, the paste protocol, scrollback capture, pane-id validation,
-and identity fallback live behind `MuxBackend` in `src/mux/`. There are
-two implementations. A third needs its own friction evidence.
-
-### 6. Pi-first, with reported agent state
-
-mu never infers agent state from pane text. Each state source reports it:
-
-| Agent | Send, abort, wait | State |
-| --- | --- | --- |
-| pi (any backend, local or remote over `ssh -L`) | control socket, exact | control socket |
-| other CLI on herdr | mux | herdr |
-| other CLI on tmux | mux (bracketed paste) | murmur |
-
-With no source, state is `unknown` with a reason. A pi agent whose
-socket does not answer fails loudly; mu never falls back to pasting.
-murmur is optional for pi agents.
-
-`MU_PI_COMMAND="pi-alt --some-flag"` swaps the pi command for every
-spawn. First-class support for other CLIs is not planned. It can earn promotion
-under the [ROADMAP](ROADMAP.md) criteria: spawn accepts any command and
-`agents.cli` is TEXT.
-
-### 7. TypeScript on Node
-
-mu uses a few well-known npm dependencies (`commander`,
-`better-sqlite3`, `cli-table3`, `picocolors`, `execa`, and `ink` for the
-TUI). There is no native code to maintain and no build matrix.
-
-- **Types pay.** The typed error classes map to exit codes in
-  `handle()`. The `assertXInWorkstream` family stays type-safe across
-  namespaces. `noUncheckedIndexedAccess` has caught real bugs.
-- **`better-sqlite3` fits.** Synchronous calls match a short-lived CLI,
-  and `db.transaction()` is the right shape.
-- **Iteration is fast.** Several substantive changes a day land in
-  about 99k lines of `src/` and `test/`.
-
-The weak spot is cold start: Node takes 30–50 ms to boot, which matters
-only in tight loops. If that changes, Rust is the port target.
-`better-sqlite3` needs prebuilds (darwin-arm64/x64, linux-x64/arm64,
-win32-x64) or a C++ toolchain.
-
-### 8. Schema-first: typed verbs over read views, SQL as escape hatch
-
-- **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 teardown`).
-- **`--json` on every read verb**, so scripts use `jq`, not table parsing.
-- **`mu sql`** underneath, as the explicit escape hatch.
-
-There is no DSL, no plugin system, no workflow engine, and no verb
-registry. The commander wiring in `src/cli.ts` is the verb surface. A new
-verb is one SDK function plus one commander block.
-
-### 9. Observed vs claimed
-
-A mutating verb records what the caller said it relied on.
-`mu task close design --evidence "npm test exit 0"` lands in the ops log
-with the evidence. mu does not run the tests, but `mu log` can search
-the grounding for every change.
-
-### 10. Get out of the model's way
-
-mu coordinates agents and does not reason about them. It does not own:
-
-- **Model selection or thinking levels.** No tiers, no provider matrix.
-  pi already takes `--model` and `--thinking`. Pass them through the
-  spawn command.
-- **Prompts.** No system-prompt templates and no role registry. The
-  prompt is the spawn command plus the first message.
-- **Tool routing.** The agent CLI owns tool allowlists, MCP servers, and
-  extensions.
-- **Output interpretation.** mu does not parse panes for state, facts,
-  or tool calls. `--evidence` is recorded as given.
-
-The whole vendor surface is one lookup: `--cli <key>` reads
-`$MU_<KEY>_COMMAND`. Per-role models are a convention in your shell rc:
-
-```bash
-export MU_PI_MINI_COMMAND="pi --model haiku:off"   # → --cli pi_mini
-export MU_PI_BIG_COMMAND="pi --model opus:high"    # → --cli pi_big
-
-mu agent spawn worker-1   --cli pi_mini
-mu agent spawn reviewer-1 --cli pi_big
-```
-
-The skill's [model tiers](../skills/mu/recipes/models.md) are advice to
-the agent choosing; mu reads none of it.
-
-## What it enables
-
-- **Visible crews.** Spawn agents once and send them work all day. Each
-  sits in a pane you can attach to.
-- **Isolation.** Each agent gets a jj workspace, sl clone, git worktree,
-  or `cp -a` copy, detected automatically and freed by `mu agent close`.
-- **Wakeups without a daemon.** `mu log --tail` and event-driven
-  `mu agent wait` replace polling.
-- **Crash recovery.** The reaper reopens a dead agent's IN_PROGRESS
-  tasks with a note.
-
-## What it is not
-
-- **Not an orchestrator.** mu provides primitives. The policy (when to
-  spawn, what to assign, when to free) is yours: bash, `jq` over
-  `--json`, or an LLM following the bundled skill. There is no workflow
-  engine and no `mu run script.ts`. <!-- doc-cli-drift:skip -->
-- **Not a chat protocol.** Agents communicate through notes, claims, and
-  the ops log.
-- **Not a hidden-subagent runner.** A delegate is an ordinary agent in a
-  visible pane: attach, steer, abort, or keep talking to it. It costs one
-  pane and one pi process. A hidden subagent is lighter for many tiny
-  calls. mu bets that visibility and steering are worth the cost. There
-  are no agent types: the brief is plain text. A delegate's answer is
-  not recorded in mu; only what the caller writes back (a note, a state
-  change) is. The one extension-held list with no pane is the delegate
-  queue: bounded, shown in pi's footer, cancellable, and named at
-  shutdown when it is dropped.
-- **DB-undoable, not substrate-undoable.** `mu undo <group> --yes`
-  restores rows. It does not revive killed panes or freed workspace
-  directories. Reconciliation then reports ghosts and orphans.
-
-## Key constraints
-
-1. **A multiplexer is required** (tmux or herdr). `mu doctor` reports
-   the backend. Agent verbs exit 5 when none is reachable.
-2. **The agent never acknowledges a send.** For pi, the control socket
-   confirms that pi accepted the message. On the mux path, mu confirms
-   only that the text reached the pane and warns when it cannot confirm
-   submission. Use `mu agent wait` or `mu log --tail` to see the effect.
-3. **Recursion is opt-in.** `mu_delegate` is hidden in agents mu spawned
-   (`MU_MANAGED_AGENT`). Agents have `mu` on PATH, but the skill tells
-   them they are not the orchestrator.
-4. **Every invocation is short-lived, except two interactive readers.**
-   No daemon, no resident state outside SQLite, no background process.
-   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;
-   - 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.
-
-   The control socket is not a third exception. The pi process serves it
-   and it dies with that process. Any other long-lived process needs its
-   own promotion; the [anti-feature pledges](ROADMAP.md#anti-feature-pledges)
-   stand.
-
-## What a prior runtime taught us
-
-A council review of mu's design ancestor, a larger internal multi-agent
-runtime, found it justified only as a durable coordination control
-plane. Its minimal core: sessions, an agent registry, a task graph,
-workspace ownership, an event log, wakeups, human approvals, a typed
-control API, read-only state cards, and orphan recovery. Everything else
-(chat, workflow DSLs, memory, dashboards) had to prove its worth.
-
-mu ships nine of the ten. Approvals are missing because 200+ dogfooded
-tasks never needed them. Below the point where coordination is itself
-the work, pi plus manual tmux is more transparent than mu.
-
-Two lessons back the orchestrator-pull remote design. The runtime built
-multiplexing, flow control, keepalive and retries above a transport that
-already provided them, then deleted them: don't rebuild what the
-transport gives. A child never dials its parent; the parent pulls.
-Tasks injected as prompts and read back through sentinel markers broke
-on line wrapping and lost notes: state belongs in the DB, not in pane
-text.
-
-Known gaps, none promoted yet: `--evidence` grounds but does not verify,
-mutations have no declared idempotency keys, most mutations have no dry
-run (`workstream teardown`, `task delete`, and `undo` do), and the `role`
-field is stored but not enforced.

package/docs/architecture/control-socket.md

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