@brutalsystems/muster 0.11.0 → 1.0.0

package/README.md

@@ -1,24 +1,118 @@
+<img src="docs/assets/muster-logo.png" alt="" width="120" align="left" hspace="12" vspace="4">
+
 # Muster
 
 [![license](https://img.shields.io/github/license/BrutalSystems/muster)](./LICENSE)
 
-Muster launches instructed Codex, Claude Code, or OpenCode agents on this machine. A
-`session` returns an address only after its runtime is reachable. A `task`
-runs once, captures output, and never advertises a peer address.
+<br clear="left">
+
+**Launch coding agents on your machine, under containment you chose, and get
+back an address you can actually reach.**
+
+Muster starts Claude Code, Codex and OpenCode sessions on your behalf. You say
+what the agent may do; Muster arranges it, verifies the session is genuinely
+alive, and hands you a durable address for it. If a session never becomes
+reachable, you get a diagnosis naming what stopped it — not a process that looks
+fine and isn't.
 
-**Live launch verification:** Codex and Claude both launched and answered their
-initial prompts without terminal interaction. OpenCode 1.18.31 passed the
-loopback API and local-provider protocol checks. Claude requires a directory
-already trusted by the operator. The automated suite uses fake runtimes, not
-real models.
+It is the launching half of a small family: Muster starts agents,
+[tincan](https://github.com/BrutalSystems/tincan) lets them message each other,
+[birddog](https://github.com/BrutalSystems/birddog) watches what they do.
+
+## What it's for
+
+Running more than one agent, deliberately. One session reviewing while another
+builds; a task that runs once and captures its output; an agent launched under a
+separate account so its work never touches your own configuration. Muster is the
+part that makes those launches repeatable, contained and addressable instead of
+a terminal tab you have to remember.
+
+A `session` returns an address only after its runtime is reachable. A `task`
+runs once, captures output, and never advertises a peer address.
 
-## Install
+## What makes it different
+
+- **Containment is two separate questions, and both are answered.** Whether the
+  agent stops to ask you, and what it may touch — the second enforced by the OS,
+  not by asking nicely. Every launch records which of the two it actually got.
+- **A session is only reported ready when it is reachable.** Muster asks each
+  runtime in its own language — a session record, an RPC call, an HTTP endpoint
+  — and does not confuse "the process started" with "the agent is listening".
+- **It refuses instead of guessing.** An unrecognised flag, a contradictory pair
+  of options, an identity belonging to a different runtime: all errors, before
+  anything is started. Nothing half-launched is left behind.
+- **Other machines can ask, within limits you set.** An enrolled caller launches
+  inside a profile's ceiling — the directories it may use, the strongest
+  containment it may request. Configuration is the grant; the request never
+  widens it.
+- **Every claim here was measured.** Runtime behaviour is established by
+  driving the real programs and recording what they did — see
+  [Verification](docs/verification.md). Where a finding later proved wrong, the
+  correction is in the release notes rather than quietly edited away.
+
+Claude requires a directory already trusted by the operator, or
+`--options auto-approve-path`. The automated suite uses fake runtimes, not real
+models; behaviour against real ones is verified by hand and recorded in
+`RELEASE_NOTES.md`.
+
+## Quick start
 
 ```sh
 npm install -g @brutalsystems/muster
-muster --version
+
+# A session: an agent you can reach, addressed once it is genuinely alive.
+muster run claude --prompt 'Review this project' --cwd . --level work
+
+# A task: runs once, captures output, advertises nothing.
+muster run codex --kind task --prompt 'Summarise the failing tests' --level read
+muster output <id>
+
+# What is running, and stopping it.
+muster list --format human
+muster stop <id>
 ```
 
+`--level` names a containment pair. `read` can look but not change; `work` can
+edit its working directory; `open` removes the sandbox and needs
+`allow_dangerous_flags` in config.
+
+| Level  | The agent asks before acting | What it may touch |
+| ------ | ---------------------------- | ----------------- |
+| `read` | always                       | nothing on disk   |
+| `work` | no                           | its cwd           |
+| `open` | no                           | everything        |
+
+Claude asks to trust a directory the first time. That is a one-time review you
+do yourself — or `--options auto-approve-path`, which records it for you after
+checking the directory ships no hooks. See
+[Claude workspace trust](docs/claude-trust.md).
+
+## Requirements
+
+**Node 22.12+** (tested on 24.16), and a POSIX host with `ps` and `lsof`.
+Terminals use tmux or node-pty. The OS sandbox is seatbelt, so kernel-enforced
+containment is macOS only; everywhere else `enforcement` reports what was
+actually applied rather than pretending.
+
+Then whichever agents you mean to launch, installed and logged in. Verified
+against **Claude Code 2.1.274**, **Codex 0.155.1** and **OpenCode 1.18.31** or
+newer — a newer OpenCode must keep the CLI and loopback HTTP API Muster uses.
+What that verification covers is in [Verification](docs/verification.md).
+
+## Documentation
+
+|                                                      |                                                        |
+| ---------------------------------------------------- | ------------------------------------------------------ |
+| [How a launch runs](docs/launching.md)               | hosts, terminals, lifetimes, repeated requests         |
+| [Configuration and permissions](docs/permissions.md) | containment, config file, remote callers               |
+| [Agent identities](docs/identities.md)               | running as a named account                             |
+| [Claude workspace trust](docs/claude-trust.md)       | the one-time dialog, and the two gates behind it       |
+| [Command-line reference](docs/cli.md)                | output formats, runtime pass-through                   |
+| [MCP servers and plugins](docs/mcp.md)               | tools for launched agents, and Muster's own MCP server |
+| [Verification](docs/verification.md)                 | what is tested, what is checked by hand                |
+
+## Keeping it up to date
+
 Publishing a release does not touch an installed copy: `muster --version` keeps
 reporting the old version until you update it.
 
@@ -46,33 +140,9 @@ It is not everything CI does: CI additionally runs the suite across the Node
 version matrix, and the contract suite runs only on release. Passing `check` is
 necessary rather than sufficient.
 
-Requires Node 22.12+ (tested with 24.16), TypeScript 5, Codex 0.155.1, Claude
-Code 2.1.267, and OpenCode 1.18.31 or newer. Newer OpenCode releases must retain
-the CLI and loopback HTTP API used by Muster. Terminal drivers use tmux or
-node-pty. Process discovery currently requires a POSIX host with `ps` and
-`lsof`; the terminal interface itself is platform-neutral. The macOS Terminal
-driver is an unavailable v1 stub.
-
-Before launching a Claude session, open Claude normally in the target directory
-and complete its workspace-trust review yourself, then exit that setup session.
-This is a one-time prerequisite for each directory Claude requires you to trust,
-and trust is **not inherited**: accepting `~/Source/arm` says nothing about
-`~/Source/arm/centrumx`, which still stops at its own dialog. Muster never
-accepts trust prompts or changes trust settings. An untrusted directory blocks
-startup; Muster times out and cleans up that launch.
-
-A session sitting on that dialog has no registry record at all, so the timeout
-used to look identical to a hung or crashed launch. Muster now reads
-`hasTrustDialogAccepted` for the working directory out of the profile's
-`.claude.json` when a Claude launch times out with nothing registered, and
-either names the untrusted directory and the one-time fix or rules trust out
-and sends you to the terminal for whatever else is holding the session — a
-login prompt, or another one-time confirmation. It deliberately does not guess
-which: trust is the only one of them Muster can check, and a message that names
-the wrong screen costs what the vague one did. That read happens only on the
-failure path and only ever reads. A
-`--kind task` launch into the same directory is the cheap discriminator by
-hand: it runs headless and never sees the dialog.
+Beyond the runtime requirements above, building needs TypeScript 5. The
+terminal interface itself is platform-neutral; the macOS Terminal driver is an
+unavailable v1 stub.
 
 ```sh
 npm ci
@@ -80,7 +150,7 @@ npm run build
 node dist/muster.js run codex --prompt 'Review the authentication flow'
 node dist/muster.js run claude --prompt 'Summarize the project' --host tmux
 node dist/muster.js run opencode --prompt 'Review this project'
-node dist/muster.js run opencode --prompt 'Build a plan' -- --model coldfire-local/qwen3-30b-a3b
+node dist/muster.js run opencode --prompt 'Build a plan' -- --model local-provider/qwen3-30b
 node dist/muster.js run codex --kind task --prompt 'Explain the test layout'
 node dist/muster.js run opencode --kind task --prompt 'Summarize the tests'
 node dist/muster.js list
@@ -96,1006 +166,6 @@ emit JSON; `output` prints the captured task output. `stop` also accepts an
 unambiguous peer name or canonical address, refusing ambiguity with candidates.
 Use the durable ID to stop a session whose runtime has renamed it.
 
-For readable terminal output, add `--format human` to `run`, `list`, `stop`, or
-`doctor`:
-
-```sh
-muster run codex --prompt 'Review this project' --format human
-muster list --format human
-muster stop THREAD_OR_SESSION_OR_RUN_ID --format human
-```
-
-Human output keeps full IDs and shows directory, host, state, and relevant
-attach/output/stop commands with actual IDs. pty sessions are labeled as not
-watchable or attachable. `--format json` is explicit JSON; omitting the flag
-still returns JSON. Put Muster options before any `-- RUNTIME_OPTIONS`.
-`output` always prints captured task text and does not accept `--format`.
-MCP tools retain their existing JSON responses.
-
-Human output uses subtle colors in interactive terminals: green for idle or
-running, yellow for busy or starting, gray for ended states and field labels,
-red for failures or nonzero exit codes, and cyan for follow-up commands. IDs
-and paths retain the normal text color. Set `NO_COLOR=1` to disable colors;
-piped output and `TERM=dumb` are always uncolored. JSON never includes colors.
-
-`run` accepts an optional `--` followed by runtime arguments. The normal
-allowlist is `--model` / `-m`, plus Claude's `--effort` and OpenCode's `--agent`
-and `--variant`. For Claude and Codex a model named there is *consumed* rather
-than forwarded — it reaches the child through the same path as `--model`, so it
-appears once — and naming a model both ways is refused rather than resolved by
-precedence. Unknown options, bundled short options, config injection and
-raw permission overrides are refused, even with `allow_dangerous_flags`
-enabled. Use Muster's normalized permission flags. Prompt strings are always
-passed as one literal argument. Codex and Claude launches and OpenCode tasks put
-that value after `--`; OpenCode sessions use the dedicated `--prompt` value.
-
-A tmux session is stopped after 30 minutes with no pane activity. Set
-`--idle-timeout 2h` to lengthen it, `--idle-timeout off` to disable it for one
-launch, or `[session] idle_timeout` in `config.toml` to change the default for
-every launch. `--ttl` adds a hard ceiling regardless of activity, for a session
-that looks busy only because something is looping inside it. A session with a
-client attached is never stopped. The limit applies to tmux sessions only: pty
-and macos-terminal sessions die with the process that launched them, and a task
-ends when its prompt does.
-
-OpenCode inherits the provider and model definitions from its normal user and
-project configuration, so configured local OpenAI-compatible providers such as
-`coldfire-local/qwen3-30b-a3b` remain available. Muster never rewrites those
-files. Put runtime options after `--`, as in the local-model example above.
-
-```sh
-muster run opencode --prompt 'Review this project'
-muster run opencode --prompt 'Build a plan' -- --model coldfire-local/qwen3-30b-a3b
-muster run opencode --kind task --prompt 'Summarize the tests'
-muster run opencode --mcp tincan --permissions auto --sandbox workspace-write --prompt 'Coordinate'
-```
-
-## Terminal lifetime
-
-Add `--open` to display the launched session in a new Terminal.app window on macOS:
-
-```sh
-muster run codex --open --prompt "Review this project" --format human
-muster run claude --open --terminal ghostty --prompt "Review this project" --format human
-muster run opencode --open --terminal iterm2 --prompt "Review this project" --format human
-muster run codex --open --terminal iterm2 --prompt "Review this project" --format human
-```
-
-MCP `run` accepts `open: true`. This requires tmux and selects it when the host
-is auto; explicit pty hosts and tasks are rejected. Detached launch remains the
-default. `--terminal auto|terminal|iterm2|ghostty` requires `--open`; omitted or
-`auto` uses Terminal.app. MCP accepts the same `terminal` values. Explicit
-choices never silently fall back. iTerm2 and Ghostty must be installed as
-`iTerm.app` or `Ghostty.app` in `/Applications` or `~/Applications`.
-The host remains tmux. Successful results include `terminal_opened: true` and
-the resolved `terminal` (a launch event, not a live window-status check).
-Closing the Terminal window leaves the session running; use `muster stop <id>`
-to stop it. Terminal.app and iTerm2 may require macOS Automation permission.
-Ghostty opens a separate app instance that exits when its last window closes;
-that instance disables saved-window restoration so previous tabs and windows
-are not duplicated. It uses the [Ghostty macOS launch interface](https://github.com/ghostty-org/ghostty/discussions/9221).
-Terminal.app creates the requested window before activation
-to avoid also opening a default shell window on startup.
-iTerm2 uses its [documented scripting interface](https://iterm2.com/documentation-scripting.html).
-If the launch request to the viewer fails,
-Muster stops the launched session and returns an error.
-
-Auto-selection tries tmux, then pty. Every peer includes `host`, `capabilities`
-and `attach_hint`. Watchability is separate from the runtime's idle/busy state.
-
-- **tmux:** each agent has its own session on the dedicated `muster` tmux
-  server. `MUSTER_TMUX_SERVER` names a different one, for a caller that must not
-  share the machine's Muster server — Muster's own test suite sets it, so a gate
-  run cannot leave sessions beside yours. Opening or exiting one agent does not
-  switch another agent's viewer.
-  Watchable and attachable; survives the CLI or MCP server exiting.
-  Use the returned attach hint to reconnect to that agent.
-- **pty:** not watchable or attachable. The CLI prints the peer record and stays
-  running to own the terminal. Ctrl-C stops it. MCP-owned pty sessions stop when
-  the MCP server disconnects. There is no persistent pty daemon.
-- **task:** a per-run worker captures stdout/stderr and exit status after the
-  launching CLI exits. It supervises one task, with no retry or restart behavior.
-
-`list` refreshes live session metadata and shows ended runs distinctly. A timeout
-or startup failure cleans the process tree and host window, logs failure, and
-returns an error instead of a peer record.
-
-Each OpenCode session owns a separate HTTP server bound to `127.0.0.1` on a
-Muster-selected port. Muster verifies that the listener belongs to the launched
-process tree, stores its `server_url` and durable `session_id`, and never attaches
-to an existing personal OpenCode server. `list` refreshes the session through
-that endpoint; `stop` aborts it best-effort and still performs authoritative
-process-tree cleanup. The URL is local control metadata, not a public address.
-OpenCode sessions otherwise use the same tmux/pty, viewer, list, stop, and human
-output behavior described above; OpenCode tasks use the same detached output
-and exit-status lifecycle as other tasks.
-
-## Repeating a launch request
-
-`--request-key KEY` (MCP: `requestKey`) names the launch *request*, not the
-session it produces. Sending the same key again returns the launch it already
-produced instead of starting a second agent:
-
-```sh
-muster run codex --prompt "Review the auth flow" --request-key review-auth-7f3a
-```
-
-A key is bound to the parameters it was first seen with — runtime, kind,
-resolved working directory, the instruction, the effective permissions, the
-selected MCP servers and plugins, and the model. Sending the same key with any
-of those changed is **refused**, rather than answered with a session that does
-something other than what was asked. Launching something genuinely different
-means using a different key.
-
-The fingerprint is computed here, after validation, rather than accepted from
-the caller: two machines canonicalize a path differently, and a fingerprint
-computed before validation would disagree with itself.
-
-What a repeat returns depends on what the first attempt did:
-
-| First attempt | A repeat gets |
-| --- | --- |
-| Reachable session or running task | That session or task, unchanged |
-| Still launching | Refused — ask for its status instead |
-| Failed, exited or stopped | Refused, naming the recorded outcome |
-| Outcome unknown | Refused, and told to inspect first (below) |
-
-A repeat never consumes launch capacity, including when the concurrency cap is
-full of the very launch being asked about. Omitting the key leaves behaviour
-exactly as it was: every request is its own launch.
-
-## When an outcome is unknown
-
-If Muster dies between starting a process and recording it, the entry says
-`unknown` rather than `failed`, and `muster list` reports it that way.
-
-The distinction is not cosmetic. `failed` means nothing is running and retrying
-is safe; `unknown` means a session may be running that Muster never got to
-record, and relaunching would be how a second agent appears in the same
-directory. A repeat under the same request key is refused for exactly that
-reason.
-
-Only the half of the window that provably never reached a spawn is still called
-`failed` — an owner that died before Muster marked itself about to start a
-process. Resolving an `unknown` entry is manual today: look for the session,
-stop it if it is there, and launch again under a new key.
-
-## Where a launch may run
-
-By default any directory the account can read is a legal target, which is the
-behaviour Muster has always had. Two config settings narrow it:
-
-```toml
-allowed_roots = ["/Users/you/Source"]
-
-[projects]
-muster = "/Users/you/Source/brutalsystems/muster"
-```
-
-With either configured, a launch outside all of them is refused. A configured
-project is a grant in its own right — naming a directory there permits it
-without also permitting its parent.
-
-```sh
-muster run codex --project muster --prompt "Review the auth flow"
-```
-
-`--project NAME` (MCP: `project`) is used instead of `--cwd`; naming both is an
-error rather than a precedence rule. A project name is also portable in a way an
-absolute path is not, since the same name can point somewhere different on
-another machine.
-
-The check resolves symlinks before comparing, so a link inside an allowed root
-that points elsewhere does not escape it, and compares path-relatively, so
-`/work/project-other` is not treated as part of `/work/project`.
-
-This constrains **where a session starts, not what it can then reach**. It is
-not a sandbox: a launched agent still has whatever access the OS account has.
-Permission modes and the sandbox settings below are the controls for that.
-
-## Process ownership
-
-Muster identifies a launched process by its **pid paired with its start time**,
-and revalidates that pair whenever the registry is touched — including after
-Muster itself restarts.
-
-This is not a compromise chosen for convenience. On macOS it is the strongest
-check the public platform offers:
-
-- There is no cgroup. Process groups and sessions are the nearest approximation
-  and are escapable by design, so they bound a tree rather than owning it.
-- The kernel's unique process identifier is not exposed in the public SDK.
-- The audit-token route requires a message from the target process, which a
-  supervisor observing arbitrary children never has.
-
-Two consequences worth stating, because both look like redundant work to a
-reader who does not know why they are there:
-
-- **Identity is revalidated at the moment of use, not at discovery.** Every
-  signal, every status answer and every registry pass re-checks the pair. A pid
-  discovered a moment ago may already belong to something else.
-- **Revalidation after a Muster restart is deliberate.** Comparable supervisors
-  trust what they recorded before they died. Muster does not, which is why a
-  session that ended while Muster was not running is reported as ended rather
-  than as running.
-
-Process-tree membership uses two signals, because neither is sufficient alone.
-The parent chain is exact while it holds, and stops holding the moment an
-intermediate process exits — its children reparent to launchd and are no longer
-reachable from the root, though they are still doing the session's work. The
-process group survives that, since reparenting changes no process's group.
-
-Muster records the group the launched root leads and takes the union. A stop
-reaches reparented workers, and a session whose root has died but whose group is
-still busy is reported as running rather than ended.
-
-Only a group the root *leads* is used. A process that merely belongs to someone
-else's group shares it with whatever else is there — a shell, a tmux pane, the
-terminal — and treating that as membership would reach far outside the session.
-Both terminal hosts start their root in a new session, so in practice it does
-lead its own group. A process that calls `setsid()` for itself still escapes;
-nothing on macOS prevents that.
-
-## Configuration and permissions
-
-Muster reads `~/.muster/config.toml` once at startup and **never writes it**.
-Missing configuration uses these defaults:
-
-```toml
-host = "auto"
-tmux_status = "off"
-terminal = "terminal"
-launch_timeout_sec = 30
-max_concurrent = 4
-permissions = "deny"
-sandbox = "read-only"
-allow_dangerous_flags = false
-default_mcp = []
-```
-
-Choose `sandbox = "workspace-write"` yourself when agents should edit files.
-`full-access` and `permissions = "bypass"` require `allow_dangerous_flags = true`.
-The old config spelling `danger-full-access` remains accepted as an alias.
-
-Per-launch `--permissions` and `--sandbox` override these config defaults. The
-same named fields are accepted by MCP `run`. Both session and task launches
-support them:
-
-```sh
-muster run codex --permissions auto --sandbox workspace-write \
-  --prompt 'Implement the change' --format human
-muster run claude --permissions auto --sandbox workspace-write \
-  --prompt 'Implement the change' --format human
-```
-
-| Muster permissions | Codex translation            | Claude Code translation             | OpenCode translation                                                            |
-| ------------------ | ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------- |
-| `deny` (default)   | Approval policy `never`      | Permission mode `dontAsk`           | Deny write, shell, task, external-directory, web, and unselected MCP operations |
-| `auto`             | `--approve-for-me`           | Permission mode `auto`              | `--auto` with explicit deny rules                                               |
-| `bypass`           | Bypass approvals and sandbox | Permission mode `bypassPermissions` | Allow supported operations                                                      |
-
-`deny` refuses actions that would require approval; it does not prohibit tools
-already allowed by the sandbox or permission rules. `auto` delegates permission
-review to the runtime and may still reject an action; it is not blanket approval.
-Auto mode requires `workspace-write` in Muster because the Codex preset selects
-that sandbox. Explicitly select it; Muster never widens a read-only request.
-Bypass requires `full-access`; combinations claiming a sandbox while bypassing
-it are refused. `deny` can be combined with any authorized sandbox setting.
-
-`full-access` disables the runtime command sandbox and requires operator-owned
-config authorization even without bypass. Muster never writes that config.
-Config defaults apply to subsequent launches; overrides apply to one launch.
-Resolved `permissions` and `sandbox` are returned in records, shown in human
-output, persisted for listing, and written in the pre-launch log. Old records
-without those fields remain readable; their settings are not guessed.
-
-The runtimes' enforcement differs: Codex reviews sandbox escalation requests;
-Claude's classifier reviews tool permission requests while its Bash sandbox is
-separate. Auto-mode availability and decisions remain subject to runtime,
-model, account, and managed policy. These fields describe Muster's resolved
-launch settings, not a continuous attestation of remote policy or user changes.
-See [Codex auto-review](https://learn.chatgpt.com/docs/sandboxing/auto-review) and
-[Claude permission modes](https://code.claude.com/docs/en/permission-modes).
-
-OpenCode permissions are tool policy, not an OS-level filesystem sandbox.
-Muster's read-only OpenCode policy denies editing, shell, subagent,
-external-directory, web, and MCP operations except explicitly selected MCP
-tools; it does not claim kernel-enforced isolation. Auto still requires
-`workspace-write`, and bypass still requires authorized `full-access`.
-
-The concurrency cap is shared by separate CLI/MCP processes, including pending
-launches. Settings apply to both kinds; tasks are read-only by default.
-
-Codex defaults to an explicit sandbox and never-ask approval policy. Muster enumerates
-and explicitly disables inherited MCP servers, enables only the selected
-operator definitions, then verifies the effective server selection. Hooks, plugins, app connectors, automatic skill-MCP installation
-and external notifications are disabled for the child. Unknown MCP names that
-cannot be addressed safely are refused.
-
-Claude's built-in tools default to enabled. Unless full access is selected, its command sandbox is enabled,
-requires availability, and forbids unsandboxed retries. File-writing tools and
-sandbox writes are denied in read-only mode; default permissions use `dontAsk` so an
-unattended child does not auto-grant escalations. User/project settings and MCP
-servers are not inherited. Detected managed policy is refused because the CLI
-cannot prove that inline settings override it. Enterprise remote policy can
-arrive after startup; this v1 is not an enterprise policy-enforcement layer.
-Claude permissions and its command sandbox are different mechanisms; neither
-claim implies that every external tool is OS-sandboxed.
-
-**`workspace-write` does not fence Claude's Write tool, only its Bash.** This
-is measured, not inferred — see "Write/Bash fence asymmetry" in
-[PROBE_RESULTS.md](./PROBE_RESULTS.md). At `--level work` an agent's Bash write
-outside the working tree is refused with `Operation not permitted`, while the
-Write tool creates the same path successfully. The practical consequence is
-that **an agent can create files outside the tree that it cannot then delete**,
-because creation goes through Write and cleanup goes through Bash. No setting
-Muster writes expresses the missing fence: the alternative, `deny`, blocks the
-Write tool everywhere rather than by path, including inside the tree. Treat
-`work` as "Bash is confined to the workspace", not "writes are". If that
-distinction matters for a given launch, the containment that does hold for both
-is `read`.
-
-OpenCode keeps normal provider/model configuration and launches with `--pure`
-unless plugins are selected, which disables inherited external plugins.
-Providers declared under `[opencode.provider]` and a model named by
-`[opencode] model` or `--model` are supplied in the same verified overlay (a
-model named after `--` instead rides the child's argv and is left out of the
-overlay, so it is delivered once rather than twice), so a
-launch does not depend on the operator's own OpenCode configuration; provider
-definitions merge with any the child resolves for itself rather than replacing
-them. Secrets belong in `api_key_env_var`, read from the launching environment,
-not in `config.toml`. Before launch, Muster inspects the
-effective OpenCode configuration, disables every inherited MCP server and tool
-family, enables only the selected Muster definitions, and fails closed if a
-higher-precedence managed policy prevents that isolation from being proven.
-
-These child restrictions prevent automatically propagating spawn authority.
-External tools are enabled only through the operator configuration and launch
-selection described below. Codex and Claude runtime inboxes remain reachable
-from an external Tin Can even when they have no MCP tools of their own. An
-OpenCode session is reachable as a Tin Can peer only when the Tin Can plugin is
-selected with `--plugin`; the plugin, not the MCP server, is what advertises the
-session to other runtimes.
-No user-level runtime configuration is rewritten, and workspace-trust dialogs
-are never accepted automatically.
-
-Launch intent is fsynced to `~/.muster/launches.jsonl` before a runtime starts;
-ready/failure outcomes follow. For a local requester the log contains the
-**full prompt**, cwd, requester, runtime, kind and host. A non-local requester
-gets metadata-only logging instead — no prompt text and no environment values,
-see [Requester profiles and enrolments](#requester-profiles-and-enrolments)
-below. Registry and task outputs also live under `~/.muster`, with private
-file permissions. An abandoned `registry.lock` fails closed: verify no Muster
-operation is running before removing that directory. There is no automatic
-time-based lock theft. `launches.jsonl` rotates at 8 MiB: the file is renamed
-to `launches.jsonl.1`, replacing any previous generation, and a fresh file is
-opened at mode `0600`. One prior generation is kept; this bounds the file
-without adding a retention policy nobody asked for.
-
-### Containment levels
-
-Two axes, answering different questions:
-
-- **`--permissions` decides whether the agent stops to ask a human.** It
-  configures the runtime's own approval prompting — a setting the agent's
-  process honours.
-- **`--sandbox` decides what the agent may touch, and the kernel enforces it.**
-  On macOS that is seatbelt. Nothing the agent does talks its way past it.
-
-The difference is not academic: a permissions refusal arrives as a prompt or a
-tool error the agent can read and react to, while a sandbox refusal arrives as
-`EPERM` from the kernel, with no negotiation and often no explanation the agent
-can interpret. `enforcement` below records which of the two a launch actually
-got.
-
-`--level` names a legal `--permissions` / `--sandbox` pair. It is a spelling,
-not a second policy path, and naming both a level and either flag is an error.
-
-| Level  | Equivalent to                                                                        |
-| ------ | ------------------------------------------------------------------------------------- |
-| `read` | `--permissions deny --sandbox read-only`                                              |
-| `work` | `--permissions auto --sandbox workspace-write`                                        |
-| `open` | `--permissions bypass --sandbox full-access` (still requires `allow_dangerous_flags`) |
-
-`deny` with `workspace-write` or `full-access` has no level and stays available
-through the flags.
-
-Every launch also records how strongly its containment was imposed:
-
-| `enforcement` | Meaning                                                                     |
-| ------------- | ---------------------------------------------------------------------------- |
-| `kernel`      | Codex or Claude Code with an OS sandbox configured and active.              |
-| `tool-policy` | OpenCode — rules the agent is asked to respect, with no kernel enforcement. |
-| `none`        | `full-access` — the sandbox is deliberately disabled.                       |
-
-#### What a sandboxed launch may write
-
-Muster names the write roots rather than leaving them to default. Under
-`workspace-write` a launched Claude session may write its cwd, `$TMPDIR`, and
-**its own configuration directory** — the `CLAUDE_CONFIG_DIR` the child will
-actually use, which an identity launch or a requester profile's `env_defaults`
-may relocate. That last root is granted because an agent's memory lives there:
-without it every Bash write to memory failed with `EPERM` while the in-process
-file tools succeeded, which reads from inside the session as a path bug rather
-than a boundary.
-
-Under `read` nothing is writable, including the config dir. Under `full-access`
-there is no sandbox to grant into.
-
-One path stays denied that muster cannot open: **`$CLAUDE_CONFIG_DIR/projects/`**
-(and `shell-snapshots/`). Claude Code refuses writes there in a sandboxed Bash
-regardless of what muster grants — naming those directories explicitly in
-`allowWrite` changes nothing, which is presumably deliberate, since a session's
-own transcripts live there. Project-scoped memory under
-`projects/<cwd-slug>/memory` is therefore reachable only through the file tools,
-which are in-process and not kernel-sandboxed. Note that `work` implies auto
-mode, which asks the model to prefer shell commands for file edits, so a session
-saving project-scoped memory has to be told to use `Write`/`Edit` instead.
-
-### Requester profiles and enrolments
-
-A non-local caller — one reached through a transport such as Tin Can rather
-than the local CLI or a local MCP client — is identified by an `(authority,
-subject)` tuple supplied by whatever already authenticated it. That tuple must
-be enrolled in `config.toml` and bound to a profile, or the request is
-refused. Two additions to `configSchema`, following the existing record style
-of `[projects]`, `[mcp_servers]` and `[plugins]`:
-
-```toml
-[requester_profiles.research]
-allowed_roots = ["/Users/mikewilliams/Source/brutalsystems"]
-level = "read"
-min_enforcement = "kernel"      # "tool-policy" to admit OpenCode here
-env_allow = ["GH_TOKEN"]
-env_defaults = { PATH = "/usr/bin:/bin", LANG = "en_US.UTF-8" }
-identities = ["research"]       # bounds which identities this requester may name
-
-[[requesters]]
-authority = "example.peer.v1"
-subject = "<opaque authenticated key id>"
-label = "m4pro"
-profile = "research"
-```
-
-`[[requesters]]` is an array of tables rather than a record keyed by
-`"authority:subject"`, so no separator can be ambiguous inside a subject. Two
-enrolments with the same `(authority, subject)` are a configuration error
-rather than a precedence rule. `label` is optional and never read for policy.
-
-`allowed_roots` is **required** on a profile and must be non-empty — it is the
-one key with no safe default, since the global `allowed_roots` defaults to
-empty and empty is read as permitting anything the account can reach. Every
-other key defaults to its narrowest value: `level` defaults to `read` and
-excludes `open` (no remote request may disable the sandbox), `min_enforcement`
-defaults to `kernel` (the default admits Codex and Claude Code; `tool-policy`
-is what admits OpenCode), and `env_allow`/`env_defaults` default to empty.
-Where a key appears in both, `env_defaults` wins — a profile that pins a value
-and also allows the key means the value it pinned, not the accepting shell's. A
-profile written as nothing but a required `allowed_roots` is therefore the
-most restrictive profile expressible.
-
-`identities` bounds which named identities (see [Agent
-identities](#agent-identities) above) a non-local requester may launch under,
-and it also defaults to its narrowest value — empty:
-
-- **Empty or omitted** refuses any identity the request names — the launch
-  falls back to lending the operator's own ambient account, same as before
-  identities existed.
-- **Exactly one** makes that identity the default: a request naming no
-  identity gets it anyway, and a request naming it explicitly gets the same
-  launch.
-- **Several** require the request to choose: a request naming none of them is
-  refused rather than guessing, and a request naming one outside the list is
-  refused too.
-
-A local requester has no profile and no ceiling here either — it may name any
-identity that exists, exactly as it may reach any root.
-
-A request naming no level resolves to its profile's level — never to the
-receiving machine's own `config.permissions` / `config.sandbox` defaults,
-which would let an unconfigured local default hand a remote caller more than
-its profile grants.
-
-**The `env_allow` trap.** A non-local launch's environment is composed from
-nothing — an allowlist, not the accepting shell's environment filtered by a
-denylist. That means a remote profile must list in `env_allow` (or supply in
-`env_defaults`) everything the runtime's own toolchain needs — not just what
-the agent's task needs. A missing entry does not present as a policy refusal;
-it presents as a **broken runtime** — a launch that starts and then fails in
-ways that look like a bug in Codex, Claude Code or OpenCode rather than a
-missing environment variable. This is exactly the diagnosis-confusing failure
-shape the rest of this feature avoids, so test a first remote profile with a
-trivial launch before relying on it.
-
-**`env_allow` is not the whole environment.** Two configured things still
-contribute variables read from the accepting process's unfiltered environment,
-exactly as for a local launch. A selected MCP server contributes its own declared
-`env_vars` and its `bearer_token_env_var`. And on every OpenCode launch, each
-configured `[opencode.provider]` contributes its API key, because the provider
-configuration handed to the runtime is built from them — so a remote OpenCode
-launch reaches this machine's model providers even with `env_allow = []`. That is the same principle applied
-one level up: a configured credential authenticates, one that merely happens to
-be present does not. It does mean a remote request may not choose which servers
-or plugins run: naming `mcp` or `plugin` is refused as not expressible
-remotely, and a remote launch gets this machine's configured `default_mcp` and
-`default_plugins`. To withhold a credential from a remote requester, withhold
-the server — a profile cannot withhold the variable alone. Provider keys cannot
-be withheld per requester at all today; a machine that must not lend its model
-providers should not enrol a remote requester for OpenCode.
-
-**What this does and does not defend against.** Muster does not authenticate
-its caller. A trusted local invoker that has already authenticated a remote
-peer passes along the provenance it established, and Muster applies least
-privilege to that provenance. This is not a defence against a compromised
-same-user process: anything able to exec Muster can already rewrite the very
-`config.toml` it reads, including its own enrolment and profile. The value is
-in what a legitimately-authenticated remote peer is confined to, not in
-resisting an attacker who is already running as the same local user.
-
-**Stop and output are asymmetric.** A local operator may stop or read the
-output of any launch on the machine, as before. A non-local requester may
-`stop` or read `output` for only the launches it asked for — an attempt to act
-on another requester's launch is refused. An entry with no recorded requester
-(older data, or a local launch) reads as local and is therefore protected the
-same as any other local launch. `list` is not scoped this way: every caller
-sees every launch on the machine, so the asymmetry covers acting on a launch,
-not seeing that it exists.
-
-## Agent identities
-
-An **identity** is a named, pre-authenticated template configuration for one
-agent, stored under `~/.muster/identities/<name>` at mode `0700`. Launching
-under one makes a launch state which account it runs as instead of silently
-inheriting whatever the environment happened to imply.
-
-```sh
-muster setup-identity --identity work --agent claude --interactive
-muster setup-identity --identity ci-bot --agent codex
-muster setup-identity --identity research --agent opencode
-```
-
-Claude needs a credential of its own: its keychain credential is keyed to the
-template directory's own path, and a launch runs from a per-launch copy whose
-path hashes to a different keychain service name, so a token is the only thing
-that can authenticate a Claude identity launch. `muster run --identity` refuses
-a Claude identity with neither route configured rather than spawning an agent
-that cannot log in. There are two ways to give it one:
-
-- **`--interactive` (recommended).** Runs `claude setup-token` itself inside a
-  pty with your terminal attached both ways — you see the flow and approve the
-  browser step, and anything it asks you (the `Paste code here if prompted:`
-  fallback, say, which is what an ssh session gets) reaches it from your
-  keyboard. It captures the token from the output and stores it at
-  `~/.muster/identities/<name>/token`, mode `0600` — the same directory
-  Codex and OpenCode identities already hold their own `auth.json` in. The
-  command prints a redacted confirmation of what it stored, never the token
-  (`muster identities` later reports only that a stored token is present). If
-  the login's output format ever changes so the token isn't recognised, this
-  fails open: nothing is redacted or captured, the token appears exactly as it
-  does today, and the command says it could not store one and points you at
-  `--token-env` to record the one now on your screen. It needs a terminal, and
-  refuses when stdin is not one.
-- **`--token-env NAME`**, for a machine that should keep no credential at
-  rest — CI, say. It names the environment variable holding a Claude Code
-  token (from a `claude setup-token` run yourself) — never the token itself.
-  It applies to Claude **only**; Codex and OpenCode authenticate from an auth
-  file inside the template, so `--token-env` is refused for them — it could
-  only ever add a way for the launch to fail.
-
-An identity holds exactly one of these routes at a time: storing a token
-clears a declared `--token-env`, and passing `--token-env` deletes a stored
-token. `setup-identity` says which route it removed, if either. Passing
-`--interactive` and `--token-env` in the same command is refused rather than
-resolved by precedence — they ask for opposite things, and choosing one for
-you would be choosing where the credential lives.
-
-`setup-identity` creates the template (or reuses an existing one for the same
-agent — it refuses to repurpose one that belongs to a different agent) and
-reports whether a credential is already configured. Without `--interactive`
-it prints the **one-time login** for that agent to run yourself instead of
-running it for you:
-
-```sh
-CLAUDE_CONFIG_DIR=~/.muster/identities/work claude setup-token   # then export it, or use --interactive
-CODEX_HOME=~/.muster/identities/ci-bot codex login
-OPENCODE_CONFIG_DIR=~/.muster/identities/research opencode auth login
-```
-
-Muster never performs a login without `--interactive` — each is an
-interactive OAuth flow, and a command that appeared to do it for you without
-showing you the flow would be hiding a credential prompt. Run the printed
-command, complete the flow, then check the result:
-
-```sh
-muster identities
-```
-
-Launch under a named identity with `--identity`:
-
-```sh
-muster run claude --identity work --cwd ~/projects/thing --prompt 'Ship it'
-```
-
-At launch, Muster copies a declared subset of that identity's files into a
-fresh per-launch directory under `~/.muster/identities-live/<launchId>/` and
-points the runtime's own configuration-location variable
-(`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, or `OPENCODE_CONFIG_DIR` +
-`XDG_DATA_HOME`) at that copy — never at the template itself, so one launch
-can never mutate another's credential.
-
-The copy lives only as long as the launch. `muster stop` removes it directly,
-and otherwise it is removed by the **first `muster list` after the entry
-reaches a terminal status** (`exited`, `failed`, `stopped`, `unknown`). There
-is no prune operation — an earlier draft of this documentation said the copy
-was retained until the entry was pruned, and that was never what was built.
-This matters for two reasons: an agent writes its own session transcript into
-its configuration directory, so that transcript goes with the copy moments
-after the launch ends (capture it while the launch is still running if you
-need it), and resume/fork (#32) cannot assume a copy is still there.
-
-Launching without `--identity` sets none of this: behaviour is exactly as
-before, using the ambient environment.
-
-**That is the right choice for profile work, which is counter-intuitive.** If
-you already work in a shell whose `CLAUDE_CONFIG_DIR` selects an account —
-`~/.claude-armdev`, say — a launch with no `--identity` inherits it, and the
-session lands on that account with no flag at all. `launchEnv` blocks
-`CLAUDECODE`, `CLAUDE_CODE_*`, `CODEX_THREAD_ID`, `TMUX`, `TMUX_PANE` and
-`MCP_*` from reaching the child, and deliberately lets `CLAUDE_CONFIG_DIR`
-through for exactly this reason. Passing `--identity` there does not add
-containment to that account — it **replaces** it, pointing the runtime at a
-copy of a different one, so the session appears under an account you did not
-mean to use. Reach for `--identity` to choose an account Muster manages, not to
-harden the one your shell already selected.
-
-Session discovery follows the same relocated path, so a Claude identity's
-sessions are found even though `CLAUDE_CONFIG_DIR` no longer points at
-`~/.claude` — this was previously refused outright as an unsupported
-configuration.
-
-Five things worth stating plainly, because each is a sharp edge:
-
-1. **`muster identities` reports *configured*, never *valid*.** A keychain
-   item, an auth file, a stored token or a set variable proves a credential
-   exists — not that it still works. Tokens expire and are revoked; there is
-   no way to check that without exercising the credential, and `identities`
-   does not do that.
-2. **The identity store holds credentials at rest**, for every agent that
-   keeps one there. Codex and OpenCode always do, because their own logins
-   write auth files directly into the template. A Claude identity created
-   with `--interactive` does too, at `~/.muster/identities/<name>/token` —
-   the same directory, the same `0700`/`0600` protection, nothing more:
-   storing it does not make it any safer at rest than Codex's or OpenCode's
-   `auth.json` sitting right beside it, it just makes Claude consistent with
-   them instead of relying on the operator's shell rc file. Directories are
-   `0700`, and deleting an identity deletes whatever credential it holds —
-   there is no separate secret to revoke elsewhere first. The one route with
-   nothing at rest is `--token-env`: it names a variable instead, so the
-   credential lives only in whichever environment sets that variable.
-3. **Use `--interactive`, or `claude setup-token` with `--token-env` — never
-   `ANTHROPIC_API_KEY`.** The OAuth token from `setup-token` bills the
-   account's Claude subscription. An `ANTHROPIC_API_KEY` silently moves the
-   same account onto pay-per-token API billing instead — same agent, very
-   different bill, no error either way.
-4. **A Claude identity's token is briefly written to disk during a launch.**
-   The tmux host serialises the whole launch specification — environment
-   included — to a temporary `launch.json` at mode `0600` and removes it once
-   the launch is recorded. That is the same treatment every other launch
-   variable gets, not special handling for this one, but it does mean a
-   long-lived subscription token passes through disk; a launch whose host
-   temp directory leaks (a crash before cleanup, a misconfigured `TMPDIR`)
-   leaves it there.
-5. **A requester profile with no `identities` lends the operator's own
-   account** to that requester, because the launch falls back to the ambient
-   environment exactly as it did before identities existed. That is preserved
-   for compatibility, not a recommendation — an operator should set
-   `identities` on any requester profile whose access they actually care
-   about bounding.
-
-A Claude launch under an identity also marks the launch's working directory
-trusted *inside that launch's own copy* of the configuration, so a brand-new
-directory starts as a registered session without anyone accepting a trust
-dialog. This is distinct from the ordinary Claude prerequisite described
-above: it only ever writes to the per-launch copy, never to the operator's own
-`~/.claude.json`, and only applies to launches under an identity. A launch
-without `--identity` still requires the operator to have trusted the directory
-themselves beforehand.
-
-Automated tests use fake runtimes, so they prove the plumbing — the copy, the
-variables, the trust flag, the lifecycle — but not that a real agent starts
-authenticated from a copy. See
-[docs/identity-verification.md](./docs/identity-verification.md) for the
-manual checklist that covers that, and for which agents have actually been
-verified.
-
-## Optional tools for launched agents
-
-MCP servers are optional. Muster does not require or install Tin Can (or any
-other MCP server). Register only servers you want launched agents to use in
-`~/.muster/config.toml`. For example, to use an already-installed Tin Can:
-
-```toml
-# Optional personal defaults for sessions. Omit to keep launches MCP-free.
-default_mcp = ["tincan"]
-
-[mcp_servers.tincan]
-command = "tincan"
-tools = ["peers", "send_peer", "message_log"]
-required = false
-```
-
-Then any runtime can use it:
-
-```sh
-muster run codex --mcp tincan --prompt 'Coordinate with the other agent'
-muster run claude --mcp tincan --prompt 'Coordinate with the other agent'
-muster run opencode --mcp tincan --permissions auto --sandbox workspace-write \
-  --prompt 'Coordinate'
-muster run codex --no-mcp --prompt 'Work without external tools'
-```
-
-A plugin is named either by `path` or by an `npm` specifier, never both. A path
-becomes a file URL; a specifier is passed through untouched for OpenCode to
-resolve and install:
-
-```toml
-[plugins.tincan]
-npm = "@brutalsystems/tincan-opencode"
-
-[plugins.local-thing]
-path = "~/.config/opencode/plugin/local-thing.ts"
-```
-
-Prefer `npm` where the plugin is published — but not because it avoids a stale
-copy. Both routes keep one. A copied file goes stale in silence: the package
-updates, the copy does not, and the old code keeps running against whatever it
-was built for. A specifier keeps its copy somewhere less obvious. OpenCode
-resolves the specifier once, writes a generated `package.json` pinning the
-resolved version alongside a lockfile, and caches that under the range it was
-asked for:
-
-```sh
-~/.cache/opencode/packages/@brutalsystems/tincan-opencode@latest
-```
-
-Publishing a new version does not change that directory and nothing warns, so
-the stale plugin keeps running and keeps reporting. Deleting it forces
-re-resolution on the next launch:
-
-```sh
-rm -rf ~/.cache/opencode/packages/@brutalsystems/tincan-opencode@latest
-```
-
-Muster passes the specifier through untouched, so pin a version where the
-staleness should be deliberate and visible in config rather than implicit in a
-cache. OpenCode keys a pinned specifier to its own directory, leaving the
-`@latest` copy alone:
-
-```toml
-[plugins.tincan]
-npm = "@brutalsystems/tincan-opencode@0.7.1"
-```
-
-A specifier needs the package to declare an entry point OpenCode's loader
-actually reads. It looks for `exports["./server"]` and falls back to `main`; it
-does not read `exports["."]`. A package declaring only the latter is fetched,
-its `package.json` is read, the session runs — and the plugin never executes,
-with nothing logged. If a specifier-named plugin appears to do nothing, check
-the package's entry points before looking anywhere else.
-
-Either way, confirm what is actually loaded. `muster doctor` checks every
-path-configured plugin against the package it came from:
-
-```sh
-muster doctor --format human
-```
-
-```
-tincan @brutalsystems/tincan-opencode
-  Status: stale — copy predates 0.7.2, published 2026-09-21
-  Path: /Users/you/.config/opencode/plugin/tincan.ts
-
-1 stale plugin. Replace path with npm = "@brutalsystems/tincan-opencode" in [plugins.tincan], or re-copy the file.
-```
-
-The copied file carries no version of its own, so the check compares its mtime
-against the registry's publish time for the current release. That means a file
-re-copied recently reads as current even when its contents are old: doctor
-under-reports and never cries wolf. It exits 1 when anything is stale, and an
-unreachable registry is reported as such rather than failing the command.
-
-Muster knows the packages for the plugins it ships with. Name anything else,
-or override the default, with `published`:
-
-```toml
-[plugins.mine]
-path = "~/src/mine.ts"
-published = "@acme/mine-opencode"
-```
-
-Plugins named by `npm` are not checked: they keep no copy of their own, and
-clearing OpenCode's cache above is that remedy instead. For what a running
-session loaded rather than what is on disk, the records still carry the version:
-
-```sh
-grep plugin_version ~/.tincan/peers/opencode/ses_*.json
-tincan --version
-```
-
-Registering Muster itself is the one case to think twice about. A definition
-whose command runs `muster mcp` gives every session that selects it `run`,
-`list`, `stop` and `output` — launch authority, held by an agent rather than by
-you. Put it in `default_mcp` and every session muster launches can launch more,
-which is the propagation the child restrictions above exist to prevent;
-`max_concurrent` caps simultaneous launches but does not stop a tree forming.
-Nothing in Muster refuses this, so the restraint has to be yours. If you want
-an orchestrating agent, give exactly that one session an explicit
-`--mcp muster` and leave `default_mcp` alone. See "MCP installation" below for
-the same stance applied to a runtime's own shared configuration.
-
-`--mcp NAME` is repeatable and **replaces** personal defaults. `--no-mcp` clears
-them and cannot be combined with `--mcp`. MCP `run` takes `mcp: ["tincan"]`;
-`mcp: []` disables all servers. Omitted selection uses `default_mcp` for sessions.
-Tasks have no defaults, but accept an explicit selection.
-
-Definitions support either `command` plus optional `args`, `env`, and `env_vars`
-for stdio, or `url` plus optional `bearer_token_env_var` for Streamable HTTP.
-`tools` is a required nonempty list of exact tool names. Use `env_vars` and
-`bearer_token_env_var` to reference credentials in the launch environment;
-credentials are not written to launch logs. HTTP OAuth setup shared across
-runtimes, plugin/app tools, MCP resources and prompts are outside this interface.
-Server and tool names must contain only letters, digits, underscores or hyphens.
-Relative stdio commands run from the requested working directory; prefer an
-absolute executable path or a command on PATH.
-
-Before agent launch, Muster initializes each selected server and checks its tool
-catalog. No tool is called during preflight. An explicit `--mcp` selection is
-required: a missing server, missing credential, or missing configured tool fails
-that launch. Defaults are optional unless their definition sets `required = true`;
-an unavailable optional default is skipped with `mcp_warnings`. Each preflight is
-bounded by `startup_timeout_sec` (default 10, maximum 60) and the launch deadline.
-JSON results and `list` report selected logical names in `mcp`; human output shows
-`MCP:` and any warnings. These describe launch configuration, not continuous
-server health.
-
-Codex receives isolated definitions, using a fresh runtime name when an inherited
-server has the same name, and its native tool allowlist. Claude receives a private
-Muster stdio connection that filters both tool discovery and calls; newly added
-upstream tools cannot bypass the selection. Only selected tools are preapproved.
-OpenCode disables inherited definitions and tool families in its verified
-per-launch overlay, then enables only selected definitions. A launch that
-selects MCP servers omits the wildcard `*` permission entry and names the
-built-in tools it denies instead: in OpenCode a `*` entry suppresses MCP tools
-outright, and an explicit allow for the tool does not restore them. The
-built-in list is fixed, so a tool added by a future OpenCode release would not
-be denied by it; launches that select no MCP server keep the wildcard. With no plugins
-selected it also uses `--pure` and pins an empty plugin list, so inherited
-plugins do not enter the child process. Selecting a plugin with `--plugin`
-necessarily relaxes that: OpenCode merges project-local plugin discovery into
-any non-empty plugin list, so the child also loads whatever plugins the target
-repository ships. It globs both spellings — `.opencode/plugin` and
-`.opencode/plugins` — so auditing only one of them misses half of what a
-repository can load. Select plugins only for repositories trusted with that.
-`--plugin NAME` is repeatable and replaces whatever plugins the configuration
-selects by default, rather than adding to them; `--no-plugin` selects none and
-is how a launch gets the `--pure` treatment above when the configuration would
-otherwise have chosen some. Both apply to OpenCode only.
-Claude connection specifications are stored with owner-only permissions under
-`~/.muster/mcp`, removed on stop, task completion, or when `list` observes an ended
-session. MCP server access is separate from filesystem sandbox permissions: a
-selected external tool may have its own write or network capabilities.
-
-## MCP installation
-
-Installed deliberately, in the one session that should hold spawn authority —
-never at user scope.
-
-Muster exposes `run`, `list`, `stop`, and `output` over stdio. `mcp` starts the
-server, and so does no arguments when stdin is not a terminal — which is what an
-MCP client provides. Typing `muster` at a terminal prints the usage text and a
-short status instead, because a server waiting for JSON-RPC on stdin is
-indistinguishable from a hang. `muster mcp` starts the server either way, so it
-can still be driven by hand to debug it. Diagnostics go to stderr, never protocol stdout.
-Schemas match the CLI (`args` is the array of optional runtime arguments).
-
-For a single Codex session, use per-invocation configuration:
-
-```sh
-codex -c 'mcp_servers.muster.command="node"' \
-  -c 'mcp_servers.muster.args=["/absolute/path/to/muster/dist/muster.js","mcp"]'
-```
-
-For a single Claude session:
-
-```sh
-claude --mcp-config '{"mcpServers":{"muster":{"command":"node","args":["/absolute/path/to/muster/dist/muster.js","mcp"]}}}'
-```
-
-Do not add Muster to `~/.codex/config.toml`, Claude's user-scope MCP registry,
-or another shared configuration that grants launch authority to every agent.
-The same applies to Muster's own `[mcp_servers]`: a definition that runs
-`muster mcp`, selected by `default_mcp`, grants that authority to every session
-Muster launches.
-
-## Tin Can compatibility
-
-Muster has no Tin Can build or runtime dependency. Each tool implements the
-written address contract independently. Vendored mechanics carry source-commit
-headers and the original MIT license in `TINCAN_LICENSE`.
-
-Addresses belong to running sessions and can expire or collide. Store
-`thread_id` / `session_id`, and re-resolve through Tin Can's `peers` before
-sending instead of caching a launch address. Canonical IDs are not unique keys.
-
-One OpenCode behaviour is worth knowing if you deliver to a session yourself
-rather than through Tin Can. A message posted to the v2
-`/api/session/{id}/prompt` of a **TUI-hosted** session is admitted with a 200
-and an `admittedSeq`, schedules a turn, and then dies with
-`ModelUnavailableError` naming the session's own model — while the TUI resolves
-that same model in the same process. A session hosted by `opencode serve` does
-not do this, and the v1 `/session/{id}/prompt_async` route does not either.
-Tin Can 0.6.0 delivers over v1, so nothing here depends on the v2 path.
-
-The failure is silent from the caller's side: a success response, nothing
-written into the session, and the only trace a line in OpenCode's own log. The
-investigation, what it did and did not establish, and why it was not filed
-upstream are recorded in
-[CONTRACT_PROVENANCE.md](./CONTRACT_PROVENANCE.md).
-The frozen cases intentionally preserve Tin Can's known naming defects.
-
-Codex `idle` means reachable and not known to be busy, not guaranteed free.
-The querying app-server can report `notLoaded` for a live thread; Muster maps
-that to `idle`. Claude state comes from its session registry.
-
-OpenCode peers expose a durable `session_id` and loopback-only `server_url` so a
-future Tin Can adapter has a stable integration seam. Tin Can does not yet send
-to OpenCode through Muster: choosing native OpenCode messaging versus A2A, and
-updating Tin Can for that transport, are explicitly deferred follow-up work.
-
-## Verification
-
-```sh
-npm test
-npm run build
-npm run test:contract
-```
-
-The ordinary suite requires tmux, node-pty, POSIX `ps`/`lsof`, and Python 3 for
-real file locks in the fake Codex executable. It uses isolated runtime homes and
-no model APIs. It skips the four explicitly invoked compatibility cases.
-
-The verified contract baseline is the Tin Can named by `tincan_version` in the
-frozen fixture, `test/fixtures/canonical-id.json`. That field is the single place
-recording which release the vendored copies describe, and both `RELEASING.md` and
-`publish.yml` derive their pin from it. The suite spawns an installed binary as
-an MCP subprocess, compares durable IDs, and verifies delivery to fake runtimes
-through both terminal hosts. A missing binary or missing durable field fails the
-test. For reproducible verification, install that exact release outside Muster —
-derived here too, rather than typed, so this command cannot name a release the
-fixture has moved past:
-
-```sh
-contract_dir=$(mktemp -d)
-ver=$(node -p "require('./test/fixtures/canonical-id.json').tincan_version")
-npm install --prefix "$contract_dir" --no-save "@brutalsystems/tincan@$ver"
-MUSTER_TINCAN_BIN="$contract_dir/node_modules/.bin/tincan" npm run test:contract
-```
-
-Verification uses that published release installed in an isolated temporary
-directory. No Tin Can source edits are made.
-Fixture version metadata alone does not indicate address-format drift: compare
-the case arrays. Those arrays cover naming only, not peer-list membership or
-state semantics. Upgrades require separate compatibility verification; passing
-fixture hashes alone does not establish compatibility. The tests locate the
-launched peer by canonical ID and compare its durable ID; they do not assert a
-total peer count, exclude same-runtime peers, or assert Tin Can's busy state.
-`CONTRACT_PROVENANCE.md` records both types of integrity checks.
-
-One-time live probes are separate from the automated suite. Both runtimes
-launched and answered an initial prompt with the versions listed above; Claude
-used a directory already trusted by its operator. `npm test` does not run
-real models.
-
 ## License and releases
 
 MIT © 2026 Mike Williams. See [LICENSE](./LICENSE). Vendored Tin Can code