@brutalsystems/muster 0.6.0 → 0.7.1

package/CONTRACT_PROVENANCE.md

@@ -38,6 +38,75 @@ with the keys `slugify`, `suffix`, `assign`, `resolve` in that order is:
 `a92936ef4b713641d29da3fbafccab0e6da79a54e27bfea3c6a779e801a925b3`.
 Both revisions produce this hash.
 
+## Privacy remediation edit — 2026-09-20
+
+`test/fixtures/canonical-id.json` originally copied a real internal project
+codename as an example `rawName`/`display`/`canonicalId` value. Tin Can made
+the same change to its own copy and asked Muster to match; both projects
+renamed the same two example strings to a neutral placeholder
+(`billing-api`).
+
+This is a **local text edit to the frozen 0.1.0 copy**, not a re-sync with
+Tin Can's current upstream fixture. By the time of this edit, Tin Can's
+fixture had moved to `tincan_version: 0.5.2` and gained real new content —
+`opencode` suffix rules, new fixture cases, and new `CANONICAL_ID.md`
+sections describing opencode session-id behavior. Muster's OpenCode
+integration explicitly defers Tin Can/address-format work (see
+`RELEASE_NOTES.md`), so adopting that upstream fixture wholesale would claim
+verification Muster does not have. Per this document's own earlier
+guidance — "their full-file hashes ... must not be compared to an entire
+newer upstream fixture to infer a format change" — only the two leaked
+strings were changed; every other byte of the 0.1.0-vintage fixture is
+unchanged, including its 31 cases and `tincan_version: 0.1.0`.
+
+New hash after this edit:
+
+| File | SHA-256 |
+| --- | --- |
+| `test/fixtures/canonical-id.json` | `974cef9e06370a562cef588f1cd6d5c1d83b49afdb64808487759d6280bffff2` |
+
+`CANONICAL_ID.md`'s hash is unchanged (`8cf4312d6af1c4d85ec0641d8739bec261be2feb35dd16bdd9d8be2b89551915`)
+— the codename never appeared there.
+
+Adopting Tin Can's opencode naming rules, if Muster's OpenCode/Tin Can
+integration is ever un-deferred, is a separate, deliberate compatibility
+check — not something this edit performs.
+
+The `at commit fbaaea5842fd4a5c86849d7f51c8e16b8683b058` provenance line
+above may no longer resolve in Tin Can's current history: Tin Can applied
+the same codename remediation via a history rewrite (`git filter-repo
+--replace-text`, force-pushed), which changes the hash of every commit
+whose content or ancestry it touched. This is a historical acquisition
+record, not a claim that the commit is still reachable.
+
+## Contract baseline moved to 0.5.2 — 2026-09-20
+
+`@brutalsystems/tincan@0.2.0`, this document's verified baseline, was
+withdrawn from the npm registry as part of Tin Can's own codename
+remediation (every version through 0.5.1 carried the same leaked string
+0.7.0's fixture did, in Tin Can's README and fixture). Withdrawn version
+numbers cannot be republished. This is a **registry availability problem,
+not a format change** — Tin Can diffed `src/naming.ts` between 0.2.0 and
+0.5.2 and found `slugify`, `suffixOf`, `assignNames`, and `resolvePeer`
+byte-identical; the only source change is the `RuntimeName` union widening
+to add `'opencode'`. `test/fixtures/canonical-id.json` gained new opencode
+cases with every pre-existing expectation unchanged.
+
+Muster's own contract suite was run against a real installed
+`@brutalsystems/tincan@0.5.2` and passed all four cases before this
+re-baseline was made.
+
+`0.3.0` through `0.5.1` were never verified by Muster's contract suite (see
+"Upgrade boundary" below) and have also been withdrawn from the registry.
+The verified, currently-available set is exactly `{0.5.2}`.
+
+One caveat for anyone reconstructing a baseline from Tin Can's git history
+rather than a published artifact: Tin Can's git tags predating 2026-09-20
+no longer match what npm ever served at that version number, because the
+history-rewrite in the section above applies retroactively to every commit,
+tagged ones included. Git content at an old tag is not evidence of what a
+withdrawn npm artifact actually contained.
+
 ## Upgrade boundary: listing and state
 
 The upstream release notes report that 0.3.0 expands

package/README.md

@@ -2,21 +2,24 @@
 
 [![license](https://img.shields.io/github/license/BrutalSystems/muster)](./LICENSE)
 
-Muster launches instructed Codex or Claude Code agents on this machine. A
+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.
 
 **Live launch verification:** Codex and Claude both launched and answered their
-initial prompts without terminal interaction. Claude requires a directory
-already trusted by the operator. The automated suite uses fake runtimes,
-not real models.
+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.
 
 ## Build and run locally
 
-Requires Node 22.12+ (tested with 24.16), TypeScript 5, and Codex 0.155.1 / Claude
-Code 2.1.267. 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.
+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.
@@ -29,7 +32,10 @@ npm ci
 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 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
 node dist/muster.js list --format human
 node dist/muster.js list --kind task
@@ -64,11 +70,25 @@ 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`. 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 passed as a single literal argument after the runtime's option terminator.
+`run` accepts an optional `--` followed by runtime arguments. The normal
+allowlist is `--model` / `-m`, plus Claude's `--effort` and OpenCode's `--agent`
+and `--variant`. 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.
+
+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
 
@@ -77,6 +97,7 @@ Add `--open` to display the launched session in a new Terminal.app window on mac
 ```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
 ```
 
@@ -116,6 +137,16 @@ and `attach_hint`. Watchability is separate from the runtime's idle/busy state.
 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.
+
 ## Configuration and permissions
 
 Muster reads `~/.muster/config.toml` once at startup and **never writes it**.
@@ -146,11 +177,11 @@ muster run claude --permissions auto --sandbox workspace-write \
   --prompt 'Implement the change' --format human
 ```
 
-| Muster permissions | Codex translation | Claude Code translation |
-|---|---|---|
-| `deny` (default) | Approval policy `never` | Permission mode `dontAsk` |
-| `auto` | `--approve-for-me` | Permission mode `auto` |
-| `bypass` | Bypass approvals and sandbox | Permission mode `bypassPermissions` |
+| 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
@@ -175,6 +206,12 @@ 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.
 
@@ -194,10 +231,17 @@ 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.
 
+OpenCode keeps normal provider/model configuration but launches with `--pure`,
+which disables inherited external plugins. 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. The child's runtime inbox remains reachable from an
-external Tin Can even when it has no MCP tools of its own.
+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. OpenCode
+delivery remains deferred as documented under Tin Can compatibility.
 No user-level runtime configuration is rewritten, and workspace-trust dialogs
 are never accepted automatically.
 
@@ -224,11 +268,13 @@ tools = ["peers", "send_peer", "message_log"]
 required = false
 ```
 
-Then either runtime can use it:
+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'
 ```
 
@@ -261,6 +307,9 @@ Codex receives isolated definitions, using a fresh runtime name when an inherite
 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. It also uses
+`--pure`, so inherited plugins do not enter the child process.
 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
@@ -306,6 +355,11 @@ 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
@@ -325,7 +379,7 @@ For reproducible verification, install that exact release outside Muster:
 
 ```sh
 contract_dir=$(mktemp -d)
-npm install --prefix "$contract_dir" --no-save @brutalsystems/tincan@0.2.0
+npm install --prefix "$contract_dir" --no-save @brutalsystems/tincan@0.5.2
 MUSTER_TINCAN_BIN="$contract_dir/node_modules/.bin/tincan" npm run test:contract
 ```
 

package/dist/format.js

@@ -35,6 +35,8 @@ function recordHuman(record, color) {
     ];
     if (record.canonical_id)
         lines.push(field("Address", clean(record.canonical_id)));
+    if (record.runtime === "opencode" && record.server_url)
+        lines.push(field("Control URL", clean(record.server_url)));
     lines.push(field("Directory", clean(record.cwd)));
     if (record.permissions)
         lines.push(field("Permissions", clean(record.permissions)));

package/dist/guard.js

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { mcpName, claudeMcpConfig } from "./mcp.js";
 export const runSchema = z
     .object({
-    runtime: z.enum(["codex", "claude"]),
+    runtime: z.enum(["codex", "claude", "opencode"]),
     prompt: z
         .string()
         .refine((s) => s.trim().length > 0, "prompt must not be blank"),
@@ -37,12 +37,16 @@ export function resolvePermissions(req, config) {
         throw new Error("--permissions bypass requires --sandbox full-access");
     return { permissions, sandbox };
 }
-function extras(req) {
+export function runtimeArgs(req) {
     const result = [];
+    const allowed = req.runtime === "claude"
+        ? ["--model", "-m", "--effort"]
+        : req.runtime === "opencode"
+            ? ["--model", "-m", "--agent", "--variant"]
+            : ["--model", "-m"];
     for (let i = 0; i < req.args.length; i++) {
         const arg = req.args[i], flag = arg.split("=")[0].toLowerCase().replaceAll("_", "-");
-        if (!["--model", "-m", "--effort"].includes(flag) ||
-            (flag === "--effort" && req.runtime !== "claude"))
+        if (!allowed.includes(flag))
             throw new Error(`Runtime option refused: ${arg}`);
         if (arg.includes("="))
             result.push(arg);
@@ -56,7 +60,7 @@ function extras(req) {
     return result;
 }
 export function launchArgs(req, config, mcp = [], bridgePath) {
-    const extra = extras(req);
+    const extra = runtimeArgs(req);
     const policy = resolvePermissions(req, config);
     if (req.runtime === "codex")
         return [

package/dist/identity/opencode.js

@@ -0,0 +1,86 @@
+import { realpath } from "node:fs/promises";
+import { OpenCodeHttp, OpenCodeProtocolError, } from "../opencode-http.js";
+import { command, delay, descendants, processRef } from "./processes.js";
+const POLL_INTERVAL_MS = 50;
+function rawName(session) {
+    return session.title.trim() === "" ? null : session.title;
+}
+export async function openCodeEndpointOwnedBy(rootPid, serverUrl, deadline) {
+    try {
+        const endpoint = new URL(serverUrl);
+        const port = Number(endpoint.port);
+        if (!Number.isInteger(port) || port <= 0 || deadline <= Date.now())
+            return false;
+        const family = new Set(await descendants(rootPid, deadline));
+        const output = await command("lsof", [
+            "-nP",
+            "-a",
+            `-iTCP@${endpoint.hostname}:${port}`,
+            "-sTCP:LISTEN",
+            "-Fp",
+        ], Math.max(1, Math.min(1000, deadline - Date.now())));
+        const listeners = output
+            .split("\n")
+            .filter((line) => /^p\d+$/.test(line))
+            .map((line) => Number(line.slice(1)));
+        return listeners.length > 0 && listeners.every((pid) => family.has(pid));
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolveOpenCode(rootPid, serverUrl, cwd, createdAfter, deadline) {
+    const resolvedCwd = await realpath(cwd);
+    const client = new OpenCodeHttp(serverUrl);
+    let ownershipProven = false;
+    while (Date.now() < deadline) {
+        if (!(await processRef(rootPid)))
+            return;
+        if (!ownershipProven &&
+            !(await openCodeEndpointOwnedBy(rootPid, serverUrl, deadline))) {
+            const remaining = deadline - Date.now();
+            if (remaining > 0)
+                await delay(Math.min(POLL_INTERVAL_MS, remaining));
+            continue;
+        }
+        ownershipProven = true;
+        try {
+            const health = await client.health(deadline);
+            if (health.healthy) {
+                const sessions = await client.sessions(deadline);
+                if (!(await processRef(rootPid)))
+                    return;
+                const candidates = sessions.filter((session) => session.directory === resolvedCwd &&
+                    session.time.created >= createdAfter);
+                const statuses = candidates.length
+                    ? await client.statuses(deadline)
+                    : {};
+                if (!(await processRef(rootPid)))
+                    return;
+                if (!(await openCodeEndpointOwnedBy(rootPid, serverUrl, deadline))) {
+                    ownershipProven = false;
+                    continue;
+                }
+                const matches = candidates.filter((session) => Object.prototype.hasOwnProperty.call(statuses, session.id));
+                if (matches.length > 1)
+                    throw new Error("Multiple OpenCode sessions matched the launch endpoint, cwd, and creation window");
+                const match = matches[0];
+                if (match)
+                    return {
+                        id: match.id,
+                        pid: rootPid,
+                        rawName: rawName(match),
+                        cwd: resolvedCwd,
+                        serverUrl,
+                    };
+            }
+        }
+        catch (error) {
+            if (!(error instanceof OpenCodeProtocolError))
+                throw error;
+        }
+        const remaining = deadline - Date.now();
+        if (remaining > 0)
+            await delay(Math.min(POLL_INTERVAL_MS, remaining));
+    }
+}

package/dist/muster.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { parseArgs } from "node:util";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -12,12 +13,14 @@ const listSchema = z
     .object({ kind: z.enum(["session", "task"]).optional() })
     .strict();
 const idSchema = z.object({ id: z.string().min(1) }).strict();
+const { version } = createRequire(import.meta.url)("../package.json");
 const help = `Usage:
-  muster run <codex|claude> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [--terminal APP] [-- RUNTIME_OPTIONS]
+  muster run <codex|claude|opencode> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [--terminal APP] [-- RUNTIME_OPTIONS]
   muster list [--kind session|task] [--format json|human]
   muster stop <id> [--format json|human]
   muster output <id>
   muster mcp
+  muster --version
 
 run also accepts --format json|human, --permissions auto|deny|bypass,
 and --sandbox read-only|workspace-write|full-access before -- RUNTIME_OPTIONS.
@@ -40,6 +43,10 @@ async function main() {
         process.stdout.write(help);
         return;
     }
+    if (argv[0] === "--version" || argv[0] === "-v") {
+        process.stdout.write(`${version}\n`);
+        return;
+    }
     const mcp = argv.length === 0 || argv[0] === "mcp";
     if (mcp && argv.length > 1)
         throw new Error("mcp takes no arguments");
@@ -56,7 +63,7 @@ async function main() {
             });
         });
     if (mcp) {
-        const server = new Server({ name: "muster", version: "0.6.0" }, { capabilities: { tools: {} } });
+        const server = new Server({ name: "muster", version }, { capabilities: { tools: {} } });
         server.setRequestHandler(ListToolsRequestSchema, async () => ({
             tools: [
                 {
@@ -65,7 +72,10 @@ async function main() {
                     inputSchema: {
                         type: "object",
                         properties: {
-                            runtime: { type: "string", enum: ["codex", "claude"] },
+                            runtime: {
+                                type: "string",
+                                enum: ["codex", "claude", "opencode"],
+                            },
                             prompt: { type: "string", minLength: 1 },
                             cwd: { type: "string" },
                             kind: {

package/dist/naming.js

@@ -1,5 +1,6 @@
-/** Vendored from Tin Can src/naming.ts at fbaaea5842fd4a5c86849d7f51c8e16b8683b058 (MIT). */
-/** Peer naming per the handoff §7: slug for humans, canonical id for the log. */
+export function runtimeName(runtime) {
+    return runtime === "claude" ? "claude-code" : runtime;
+}
 export function slugify(raw) {
     return raw
         .toLowerCase()