@brutalsystems/muster 0.6.0 → 0.7.0

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

@@ -13,7 +13,7 @@ const listSchema = z
     .strict();
 const idSchema = z.object({ id: z.string().min(1) }).strict();
 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>
@@ -65,7 +65,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()

package/dist/opencode-http.js

@@ -0,0 +1,241 @@
+import net from "node:net";
+import { z } from "zod";
+const REQUEST_TIMEOUT_MS = 2_000;
+const healthSchema = z.object({
+    healthy: z.boolean(),
+    version: z.string().min(1),
+});
+const sessionSchema = z.object({
+    id: z.string().min(1),
+    title: z.string(),
+    directory: z.string().min(1),
+    time: z.object({
+        created: z.number(),
+        updated: z.number(),
+    }),
+});
+const statusSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("idle") }),
+    z.object({ type: z.literal("busy") }),
+    z.object({
+        type: z.literal("retry"),
+        attempt: z.number(),
+        message: z.string(),
+        next: z.number(),
+        action: z
+            .object({
+            reason: z.string(),
+            provider: z.string(),
+            title: z.string(),
+            message: z.string(),
+            label: z.string(),
+            link: z.string().optional(),
+        })
+            .optional(),
+    }),
+]);
+const eventSchema = z
+    .object({
+    id: z.string().optional(),
+    type: z.string().min(1),
+    properties: z.unknown(),
+})
+    .passthrough();
+export class OpenCodeProtocolError extends Error {
+    code;
+    method;
+    path;
+    status;
+    name = "OpenCodeProtocolError";
+    constructor(message, code, method, path, status) {
+        super(`OpenCode protocol error: ${message}`);
+        this.code = code;
+        this.method = method;
+        this.path = path;
+        this.status = status;
+    }
+}
+function protocolError(message, code = "request", method, path, status) {
+    return new OpenCodeProtocolError(message, code, method, path, status);
+}
+function requestTimeout(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw protocolError("request timed out", "timeout");
+    return Math.min(remaining, REQUEST_TIMEOUT_MS);
+}
+function isJsonContentType(value) {
+    const mediaType = value?.split(";", 1)[0]?.trim().toLowerCase();
+    return mediaType === "application/json" || mediaType?.endsWith("+json");
+}
+function isLoopbackHostname(hostname) {
+    return hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/**
+ * Reserves an ephemeral loopback port only long enough to learn its number.
+ * The caller must still prove endpoint ownership during readiness because
+ * another process can claim the port after this function closes its listener.
+ */
+export function allocateLoopbackPort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                server.close();
+                reject(protocolError("could not allocate a loopback port"));
+                return;
+            }
+            const port = address.port;
+            server.close((error) => {
+                if (error)
+                    reject(protocolError("could not release allocated port"));
+                else
+                    resolve(port);
+            });
+        });
+    });
+}
+export class OpenCodeHttp {
+    baseUrl;
+    constructor(baseUrl) {
+        let parsed;
+        try {
+            parsed = new URL(baseUrl);
+        }
+        catch {
+            throw protocolError("endpoint must be a loopback HTTP URL using a literal loopback IP", "endpoint");
+        }
+        if (parsed.protocol !== "http:" ||
+            !isLoopbackHostname(parsed.hostname) ||
+            parsed.username !== "" ||
+            parsed.password !== "") {
+            throw protocolError("endpoint must be a loopback HTTP URL using a literal loopback IP", "endpoint");
+        }
+        this.baseUrl = new URL(parsed.origin);
+    }
+    health(deadline) {
+        return this.requestJson("GET", "/global/health", deadline, healthSchema);
+    }
+    sessions(deadline) {
+        return this.requestJson("GET", "/session", deadline, z.array(sessionSchema));
+    }
+    session(id, deadline) {
+        return this.requestJson("GET", `/session/${encodeURIComponent(id)}`, deadline, sessionSchema);
+    }
+    statuses(deadline) {
+        return this.requestJson("GET", "/session/status", deadline, z.record(statusSchema));
+    }
+    abort(id, deadline) {
+        return this.requestJson("POST", `/session/${encodeURIComponent(id)}/abort`, deadline, z.boolean());
+    }
+    async *events(deadline) {
+        const method = "GET";
+        const path = "/event";
+        const controller = new AbortController();
+        let timer = setTimeout(() => controller.abort(), requestTimeout(deadline));
+        try {
+            const response = await fetch(new URL(path, this.baseUrl), {
+                method,
+                headers: { accept: "text/event-stream" },
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            const streamTimeout = deadline - Date.now();
+            if (streamTimeout <= 0)
+                throw protocolError(`${method} ${path} timed out`, "timeout", method, path);
+            timer = setTimeout(() => controller.abort(), streamTimeout);
+            if (!response.ok)
+                throw protocolError(`${method} ${path} returned HTTP ${response.status}`, "http", method, path, response.status);
+            const mediaType = response.headers
+                .get("content-type")
+                ?.split(";", 1)[0]
+                ?.trim()
+                .toLowerCase();
+            if (mediaType !== "text/event-stream")
+                throw protocolError(`${method} ${path} returned the wrong content type`, "content_type", method, path);
+            if (!response.body)
+                throw protocolError(`${method} ${path} returned no event stream`, "invalid_payload", method, path);
+            const decoder = new TextDecoder();
+            let buffer = "";
+            for await (const chunk of response.body) {
+                buffer += decoder.decode(chunk, { stream: true });
+                let boundary;
+                while ((boundary = buffer.match(/\r?\n\r?\n/))) {
+                    const block = buffer.slice(0, boundary.index);
+                    buffer = buffer.slice(boundary.index + boundary[0].length);
+                    const data = block
+                        .split(/\r?\n/)
+                        .filter((line) => line === "data" || line.startsWith("data:"))
+                        .map((line) => line.slice(5).replace(/^ /, ""))
+                        .join("\n");
+                    if (data === "")
+                        continue;
+                    yield this.parseEvent(data);
+                }
+            }
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                throw protocolError(`${method} ${path} timed out`, "timeout", method, path);
+            if (error instanceof OpenCodeProtocolError)
+                throw error;
+            throw protocolError(`${method} ${path} request failed`, "request", method, path);
+        }
+        finally {
+            clearTimeout(timer);
+            controller.abort();
+        }
+    }
+    parseEvent(data) {
+        let value;
+        try {
+            value = JSON.parse(data);
+        }
+        catch {
+            throw protocolError("GET /event returned invalid JSON", "invalid_json", "GET", "/event");
+        }
+        const parsed = eventSchema.safeParse(value);
+        if (!parsed.success)
+            throw protocolError("GET /event returned an invalid event payload", "invalid_payload", "GET", "/event");
+        return parsed.data;
+    }
+    async requestJson(method, path, deadline, schema) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), requestTimeout(deadline));
+        try {
+            const response = await fetch(new URL(path, this.baseUrl), {
+                method,
+                headers: { accept: "application/json" },
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                throw protocolError(`${method} ${path} returned HTTP ${response.status}`, "http", method, path, response.status);
+            if (!isJsonContentType(response.headers.get("content-type")))
+                throw protocolError(`${method} ${path} returned the wrong content type`, "content_type", method, path);
+            let value;
+            try {
+                value = await response.json();
+            }
+            catch {
+                throw protocolError(`${method} ${path} returned invalid JSON`, "invalid_json", method, path);
+            }
+            const parsed = schema.safeParse(value);
+            if (!parsed.success)
+                throw protocolError(`${method} ${path} returned an invalid payload`, "invalid_payload", method, path);
+            return parsed.data;
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                throw protocolError(`${method} ${path} timed out`, "timeout", method, path);
+            if (error instanceof OpenCodeProtocolError)
+                throw error;
+            throw protocolError(`${method} ${path} request failed`, "request", method, path);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/opencode-policy.js

@@ -0,0 +1,382 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { resolvePermissions, runtimeArgs } from "./guard.js";
+const exec = promisify(execFile);
+const DEBUG_CONFIG_ERROR = "Cannot verify effective OpenCode MCP configuration";
+const ISOLATION_ERROR = "OpenCode MCP isolation could not be verified; refusing launch";
+const INLINE_CONFIG_ERROR = "Cannot safely compose the existing inline OpenCode config";
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function commandTimeout(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new Error(DEBUG_CONFIG_ERROR);
+    return Math.min(4000, remaining);
+}
+async function resolvedConfig(env, cwd, deadline, errorMessage = DEBUG_CONFIG_ERROR) {
+    try {
+        const { stdout } = await exec("opencode", ["--pure", "debug", "config"], {
+            env,
+            cwd,
+            timeout: commandTimeout(deadline),
+            maxBuffer: 1024 * 1024,
+            encoding: "utf8",
+        });
+        const value = JSON.parse(stdout);
+        if (!isRecord(value))
+            throw new Error("invalid config");
+        return value;
+    }
+    catch {
+        // OpenCode diagnostics and resolved config may contain credentials. Never
+        // include child output, inline config, or the underlying error here.
+        throw new Error(errorMessage);
+    }
+}
+function fixedEnvironmentName(server, key) {
+    const encode = (value) => Buffer.from(value, "utf8").toString("hex").toUpperCase();
+    return `MUSTER_OPENCODE_MCP_${encode(server)}_${encode(key)}`;
+}
+function environmentReference(name) {
+    return `{env:${name}}`;
+}
+export function openCodeMcpConfig(server) {
+    const config = server.config;
+    if (config.command) {
+        const environment = Object.fromEntries([
+            ...Object.keys(config.env).map((key) => [
+                key,
+                environmentReference(fixedEnvironmentName(server.name, key)),
+            ]),
+            ...config.env_vars.map((key) => [key, environmentReference(key)]),
+        ]);
+        return {
+            type: "local",
+            command: [config.command, ...config.args],
+            ...(Object.keys(environment).length ? { environment } : {}),
+            timeout: config.startup_timeout_sec * 1000,
+            enabled: true,
+        };
+    }
+    return {
+        type: "remote",
+        url: config.url,
+        ...(config.bearer_token_env_var
+            ? {
+                headers: {
+                    Authorization: `Bearer ${environmentReference(config.bearer_token_env_var)}`,
+                },
+            }
+            : {}),
+        timeout: config.startup_timeout_sec * 1000,
+        enabled: true,
+    };
+}
+function effectiveMcp(selected, inheritedMcpNames) {
+    const used = new Set(inheritedMcpNames);
+    return selected.map((server) => {
+        let name = server.name;
+        let suffix = 0;
+        while (used.has(name))
+            name = `muster_${server.name}_${++suffix}`;
+        used.add(name);
+        return { server, name };
+    });
+}
+function mcpPolicy(selected, inheritedMcpNames) {
+    const effective = effectiveMcp(selected, inheritedMcpNames);
+    const mcp = Object.fromEntries(inheritedMcpNames.map((name) => [name, { enabled: false }]));
+    const tools = Object.fromEntries(inheritedMcpNames.map((name) => [`${name}_*`, false]));
+    for (const { server, name } of effective) {
+        mcp[name] = openCodeMcpConfig(server);
+        tools[`${name}_*`] = true;
+        for (const tool of server.excludedTools)
+            tools[`${name}_${tool}`] = false;
+    }
+    return { effective, mcp, tools };
+}
+function permissions(req, config, tools) {
+    const policy = resolvePermissions(req, config);
+    const permission = {
+        "*": policy.permissions === "bypass"
+            ? "allow"
+            : policy.permissions === "auto"
+                ? "ask"
+                : "deny",
+    };
+    if (policy.permissions !== "bypass") {
+        for (const name of [
+            "read",
+            "glob",
+            "grep",
+            "list",
+            "lsp",
+            "todoread",
+            "question",
+        ])
+            permission[name] = "allow";
+    }
+    if (policy.permissions === "deny" || policy.sandbox === "read-only") {
+        for (const name of [
+            "edit",
+            "bash",
+            "task",
+            "external_directory",
+            "webfetch",
+            "websearch",
+        ])
+            permission[name] = "deny";
+    }
+    else if (policy.permissions === "auto") {
+        for (const name of ["external_directory", "webfetch", "websearch"])
+            permission[name] = "deny";
+        permission.question = "allow";
+    }
+    for (const [pattern, enabled] of Object.entries(tools))
+        permission[pattern] = enabled ? "allow" : "deny";
+    return permission;
+}
+export function openCodeConfig(req, config, selected, inheritedMcpNames) {
+    const { mcp, tools } = mcpPolicy(selected, inheritedMcpNames);
+    return {
+        share: "disabled",
+        server: { hostname: "127.0.0.1" },
+        permission: permissions(req, config, tools),
+        tools,
+        mcp,
+    };
+}
+function mergeRecords(base, override) {
+    return Object.fromEntries([...new Set([...Object.keys(base), ...Object.keys(override)])].map((key) => {
+        const original = base[key];
+        const replacement = override[key];
+        return [
+            key,
+            isRecord(original) && isRecord(replacement)
+                ? mergeRecords(original, replacement)
+                : replacement === undefined
+                    ? original
+                    : replacement,
+        ];
+    }));
+}
+function composeInlineConfig(env, overlay) {
+    let inherited = {};
+    const source = env.OPENCODE_CONFIG_CONTENT;
+    if (source !== undefined) {
+        try {
+            const value = JSON.parse(source);
+            if (!isRecord(value))
+                throw new Error("invalid inline config");
+            inherited = value;
+        }
+        catch {
+            throw new Error(INLINE_CONFIG_ERROR);
+        }
+    }
+    const inheritedMcp = inherited.mcp;
+    const overlayMcp = overlay.mcp;
+    if ((inheritedMcp !== undefined && !isRecord(inheritedMcp)) ||
+        !isRecord(overlayMcp))
+        throw new Error(INLINE_CONFIG_ERROR);
+    return {
+        ...inherited,
+        ...overlay,
+        // Preserve inherited inline definitions so provider/model configuration
+        // remains intact, but apply Muster's enabled state and selected definitions.
+        mcp: mergeRecords(inheritedMcp ?? {}, overlayMcp),
+    };
+}
+function envPatch(selected, overlay, env) {
+    const config = composeInlineConfig(env, overlay);
+    const patch = {
+        OPENCODE_CONFIG_CONTENT: JSON.stringify(config),
+    };
+    for (const server of selected)
+        for (const [key, value] of Object.entries(server.config.env))
+            patch[fixedEnvironmentName(server.name, key)] = value;
+    return patch;
+}
+function sameKeys(actual, expected) {
+    return (JSON.stringify(Object.keys(actual).sort()) ===
+        JSON.stringify(Object.keys(expected).sort()));
+}
+function resolveExpectedEnvironment(value, env) {
+    if (typeof value === "string")
+        return value.replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => env[name] === undefined ? "" : env[name]);
+    if (Array.isArray(value))
+        return value.map((item) => resolveExpectedEnvironment(item, env));
+    if (isRecord(value))
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            resolveExpectedEnvironment(item, env),
+        ]));
+    return value;
+}
+function equivalentMcpDefinition(actual, expected, env) {
+    const resolved = resolveExpectedEnvironment(expected, env);
+    return (isRecord(resolved) &&
+        sameKeys(actual, resolved) &&
+        JSON.stringify(actual) === JSON.stringify(resolved));
+}
+function denyOnly(value) {
+    if (value === "deny")
+        return true;
+    return (isRecord(value) &&
+        Object.values(value).length > 0 &&
+        Object.values(value).every(denyOnly));
+}
+async function verifyOverlay(overlay, selected, inheritedMcpNames, env, cwd, deadline) {
+    const patch = envPatch(selected, overlay, env);
+    const effectiveConfig = await resolvedConfig({ ...env, ...patch }, cwd, deadline, ISOLATION_ERROR);
+    const actualMcp = isRecord(effectiveConfig.mcp) ? effectiveConfig.mcp : {};
+    const actualTools = isRecord(effectiveConfig.tools)
+        ? effectiveConfig.tools
+        : {};
+    const actualPermission = isRecord(effectiveConfig.permission)
+        ? effectiveConfig.permission
+        : {};
+    const expectedPermission = isRecord(overlay.permission)
+        ? overlay.permission
+        : {};
+    const expected = mcpPolicy(selected, inheritedMcpNames);
+    const selectedNames = new Set(expected.effective.map(({ name }) => name));
+    for (const name of inheritedMcpNames) {
+        const value = actualMcp[name];
+        if (!isRecord(value) || value.enabled !== false)
+            throw new Error(ISOLATION_ERROR);
+    }
+    for (const { server, name } of expected.effective) {
+        const value = actualMcp[name];
+        if (!isRecord(value) ||
+            !equivalentMcpDefinition(value, openCodeMcpConfig(server), {
+                ...env,
+                ...patch,
+            }))
+            throw new Error(ISOLATION_ERROR);
+    }
+    for (const [name, value] of Object.entries(actualMcp))
+        if (!selectedNames.has(name) &&
+            !inheritedMcpNames.includes(name) &&
+            (!isRecord(value) || value.enabled !== false))
+            throw new Error(ISOLATION_ERROR);
+    for (const [pattern, enabled] of Object.entries(expected.tools))
+        if (actualTools[pattern] !== enabled)
+            throw new Error(ISOLATION_ERROR);
+    for (const [pattern, enabled] of Object.entries(actualTools))
+        if (enabled === true && expected.tools[pattern] !== true)
+            throw new Error(ISOLATION_ERROR);
+    for (const [pattern, action] of Object.entries(expectedPermission))
+        if (actualPermission[pattern] !== action)
+            throw new Error(ISOLATION_ERROR);
+    for (const [pattern, action] of Object.entries(actualPermission))
+        if (!(pattern in expectedPermission) && !denyOnly(action))
+            throw new Error(ISOLATION_ERROR);
+    if (effectiveConfig.share !== "disabled")
+        throw new Error(ISOLATION_ERROR);
+    const expectedServer = overlay.server;
+    if (!isRecord(expectedServer) ||
+        !isRecord(effectiveConfig.server) ||
+        JSON.stringify(effectiveConfig.server) !== JSON.stringify(expectedServer))
+        throw new Error(ISOLATION_ERROR);
+    return patch;
+}
+export async function openCodeMcpNames(env, cwd, deadline) {
+    const config = await resolvedConfig(env, cwd, deadline);
+    if (config.mcp === undefined)
+        return [];
+    if (!isRecord(config.mcp))
+        throw new Error(DEBUG_CONFIG_ERROR);
+    return Object.keys(config.mcp);
+}
+export async function openCodeSessionLaunch(req, config, selected, inheritedMcpNames, port, env, cwd, deadline) {
+    const extra = runtimeArgs(req);
+    const policy = resolvePermissions(req, config);
+    const overlay = {
+        ...openCodeConfig(req, config, selected, inheritedMcpNames),
+        server: { hostname: "127.0.0.1", port },
+    };
+    const patch = await verifyOverlay(overlay, selected, inheritedMcpNames, env, cwd, deadline);
+    return {
+        argv: [
+            "opencode",
+            "--pure",
+            "--hostname",
+            "127.0.0.1",
+            "--port",
+            String(port),
+            ...(policy.permissions === "auto" ? ["--auto"] : []),
+            ...extra,
+            "--prompt",
+            req.prompt,
+        ],
+        envPatch: patch,
+        port,
+        serverUrl: `http://127.0.0.1:${port}`,
+    };
+}
+export async function openCodeTaskLaunch(req, config, selected, inheritedMcpNames, env, cwd, deadline) {
+    const extra = runtimeArgs(req);
+    const policy = resolvePermissions(req, config);
+    const overlay = openCodeConfig(req, config, selected, inheritedMcpNames);
+    const patch = await verifyOverlay(overlay, selected, inheritedMcpNames, env, cwd, deadline);
+    return {
+        argv: [
+            "opencode",
+            "run",
+            "--format",
+            "json",
+            "--pure",
+            ...(policy.permissions === "auto" ? ["--auto"] : []),
+            ...extra,
+            "--",
+            req.prompt,
+        ],
+        envPatch: patch,
+    };
+}
+function parseVersion(value) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value.trim());
+    if (!match)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] !== undefined,
+    };
+}
+function atLeast(actual, minimum) {
+    for (const key of ["major", "minor", "patch"]) {
+        if (actual[key] !== minimum[key])
+            return actual[key] > minimum[key];
+    }
+    return !actual.prerelease || minimum.prerelease;
+}
+export async function assertOpenCodeVersion(env, minimum, deadline) {
+    const required = parseVersion(minimum);
+    if (!required)
+        throw new Error(`Invalid required OpenCode version: ${minimum}`);
+    let detected;
+    try {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new Error("deadline");
+        const { stdout } = await exec("opencode", ["--version"], {
+            env,
+            timeout: Math.min(4000, remaining),
+            maxBuffer: 64 * 1024,
+            encoding: "utf8",
+        });
+        detected = stdout.trim();
+    }
+    catch {
+        throw new Error(`OpenCode executable not found or version could not be determined; requires ${minimum}+`);
+    }
+    const actual = parseVersion(detected);
+    if (!actual)
+        throw new Error(`Unrecognized OpenCode version; requires compatible version ${minimum}+`);
+    if (!atLeast(actual, required))
+        throw new Error(`OpenCode ${detected} is unsupported; requires OpenCode ${minimum} or newer`);
+}

package/dist/reach/opencode.js

@@ -0,0 +1,17 @@
+export async function openCodeReachable(client, identity, deadline) {
+    const session = await client.session(identity.id, deadline);
+    if (session.id !== identity.id)
+        throw new Error("OpenCode session detail returned no matching session");
+    const statuses = await client.statuses(deadline);
+    const status = statuses[identity.id];
+    const rawName = session.title.trim() === "" ? null : session.title;
+    if (!status || status.type === "idle")
+        return { rawName, state: "idle" };
+    if (status.type === "retry")
+        return {
+            rawName,
+            state: "busy",
+            diagnostic: `OpenCode retry attempt ${status.attempt}: ${status.message}`,
+        };
+    return { rawName, state: "busy" };
+}

package/dist/run.js

@@ -4,19 +4,23 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { loadConfig } from "./config.js";
-import { runSchema, launchArgs, launchEnv, resolvePermissions, } from "./guard.js";
+import { runSchema, launchArgs, launchEnv, resolvePermissions, runtimeArgs, } from "./guard.js";
 import { Registry } from "./registry.js";
 import { LaunchLog } from "./log.js";
 import { hosts, selectHost } from "./hosts/index.js";
 import { processRef, isSame, stopTree, delay, descendants, } from "./identity/processes.js";
 import { resolveCodex } from "./identity/codex.js";
 import { resolveClaude } from "./identity/claude.js";
+import { openCodeEndpointOwnedBy, resolveOpenCode, } from "./identity/opencode.js";
 import { codexReachable } from "./reach/codex.js";
 import { claudeReachable } from "./reach/claude.js";
+import { openCodeReachable } from "./reach/opencode.js";
 import { assertClaudePolicy } from "./claude-policy.js";
 import { codexPolicyArgs } from "./codex-policy.js";
 import { CodexRpc } from "./codex-rpc.js";
-import { assignNames, resolvePeer } from "./naming.js";
+import { allocateLoopbackPort, OpenCodeHttp } from "./opencode-http.js";
+import { assertOpenCodeVersion, openCodeMcpNames, openCodeSessionLaunch, openCodeTaskLaunch, } from "./opencode-policy.js";
+import { assignNames, resolvePeer, runtimeName, } from "./naming.js";
 import { selectMcp, prepareMcp, mcpEnvironment } from "./mcp.js";
 export class Muster {
     config;
@@ -64,7 +68,11 @@ export class Muster {
             throw new Error("--open requires a tmux session on macOS");
         const permissions = resolvePermissions(req, this.config);
         const selectedMcp = selectMcp(req, this.config);
-        let argv = launchArgs(req, this.config);
+        let argv = [];
+        if (req.runtime === "opencode")
+            runtimeArgs(req);
+        else
+            argv = launchArgs(req, this.config);
         const driver = req.kind === "session"
             ? await selectHost(req.open ? "tmux" : requestedHost, this.drivers)
             : undefined;
@@ -74,6 +82,8 @@ export class Muster {
         let policy = [];
         if (req.runtime === "claude")
             await assertClaudePolicy(this.env);
+        if (req.runtime === "opencode")
+            await assertOpenCodeVersion(this.env, "1.18.31", Date.now() + 4000);
         const reservation = await this.registry.reserve({ runtime: req.runtime, kind: req.kind, cwd: req.cwd, ...permissions }, this.config.max_concurrent);
         this.owned.add(reservation.launchId);
         let entry = reservation;
@@ -96,7 +106,7 @@ export class Muster {
                 ...permissions,
             });
             const prepared = await prepareMcp(selectedMcp, mcpEnvironment(selectedMcp, this.env, this.sourceEnv), req.cwd, deadline);
-            const runtimeEnv = mcpEnvironment(prepared.servers, this.env, this.sourceEnv);
+            let runtimeEnv = mcpEnvironment(prepared.servers, this.env, this.sourceEnv);
             entry = await this.registry.update(entry.launchId, prepared.summary);
             let bridgePath;
             if (req.runtime === "claude" && prepared.servers.length) {
@@ -108,11 +118,29 @@ export class Muster {
                 });
                 await writeFile(bridgePath, JSON.stringify(Object.fromEntries(prepared.servers.map((s) => [s.name, s.config]))), { mode: 0o600 });
             }
-            argv = launchArgs(req, this.config, prepared.servers, bridgePath);
+            if (req.runtime !== "opencode")
+                argv = launchArgs(req, this.config, prepared.servers, bridgePath);
             if (req.runtime === "codex") {
                 policy = await codexPolicyArgs(runtimeEnv, req.cwd, deadline, prepared.servers);
                 argv.splice(1, 0, ...policy);
             }
+            else if (req.runtime === "opencode" && req.kind === "session") {
+                const port = await allocateLoopbackPort();
+                const inheritedMcpNames = await openCodeMcpNames(runtimeEnv, req.cwd, deadline);
+                const launch = await openCodeSessionLaunch(req, this.config, prepared.servers, inheritedMcpNames, port, runtimeEnv, req.cwd, deadline);
+                argv = launch.argv;
+                runtimeEnv = { ...runtimeEnv, ...launch.envPatch };
+                entry = await this.registry.update(entry.launchId, {
+                    server_url: launch.serverUrl,
+                    opencode_port: launch.port,
+                });
+            }
+            else if (req.runtime === "opencode" && req.kind === "task") {
+                const inheritedMcpNames = await openCodeMcpNames(runtimeEnv, req.cwd, deadline);
+                const launch = await openCodeTaskLaunch(req, this.config, prepared.servers, inheritedMcpNames, runtimeEnv, req.cwd, deadline);
+                argv = launch.argv;
+                runtimeEnv = { ...runtimeEnv, ...launch.envPatch };
+            }
             if (this.closing)
                 throw new Error("Launch cancelled: Muster is closing");
             if (req.kind === "task")
@@ -133,7 +161,9 @@ export class Muster {
             await this.registry.update(entry.launchId, entry);
             let diagnostic = req.runtime === "claude"
                 ? "no Claude session registry found (check terminal for workspace trust or login prompts)"
-                : "no descendant runtime identity found";
+                : req.runtime === "opencode"
+                    ? "no OpenCode session matched the launch endpoint, cwd, and creation window"
+                    : "no descendant runtime identity found";
             if (req.runtime === "codex")
                 rpc = new CodexRpc(this.env, req.cwd);
             while (Date.now() < deadline) {
@@ -169,15 +199,21 @@ export class Muster {
                                 return false;
                             }
                         })
-                        : await resolveClaude(root.pid, this.env, deadline);
+                        : req.runtime === "opencode"
+                            ? await resolveOpenCode(root.pid, entry.server_url, req.cwd, startedAt, deadline)
+                            : await resolveClaude(root.pid, this.env, deadline);
                     if (identity) {
                         diagnostic =
                             req.runtime === "codex"
                                 ? "thread id reserved but no rollout"
-                                : "registry exists but inbox socket is not accepting connections";
+                                : req.runtime === "opencode"
+                                    ? "OpenCode session exists but its endpoint status is not readable"
+                                    : "registry exists but inbox socket is not accepting connections";
                         let metadata;
                         if (req.runtime === "codex")
                             metadata = await codexReachable(rpc, identity.id, deadline);
+                        else if (req.runtime === "opencode")
+                            metadata = await openCodeReachable(new OpenCodeHttp(entry.server_url), identity, deadline);
                         else {
                             const claude = identity;
                             if (!(await claudeReachable(claude.socketPath, deadline)))
@@ -188,7 +224,10 @@ export class Muster {
                             throw new Error("readiness completed after launch deadline");
                         if (!(await isSame(root)) || !(await processRef(identity.pid)))
                             throw new Error("process exited before readiness completed");
-                        const runtime = req.runtime === "codex" ? "codex" : "claude-code";
+                        if (req.runtime === "opencode" &&
+                            !(await openCodeEndpointOwnedBy(root.pid, entry.server_url, deadline)))
+                            throw new Error("OpenCode endpoint listener is not owned by the launched process tree");
+                        const runtime = runtimeName(req.runtime);
                         const named = assignNames([
                             { runtime, uuid: identity.id, rawName: metadata.rawName },
                         ])[0];
@@ -203,7 +242,12 @@ export class Muster {
                             cwd: req.cwd,
                             ...(req.runtime === "codex"
                                 ? { thread_id: identity.id }
-                                : { session_id: identity.id }),
+                                : req.runtime === "opencode"
+                                    ? {
+                                        session_id: identity.id,
+                                        server_url: entry.server_url,
+                                    }
+                                    : { session_id: identity.id }),
                             pid: identity.pid,
                             host: driver.id,
                             capabilities: driver.capabilities(),
@@ -318,6 +362,17 @@ export class Muster {
     }
     async stopEntry(entry) {
         try {
+            const openCodeSessionId = entry.peer?.session_id;
+            const abortDeadline = Date.now() + 1000;
+            if (entry.runtime === "opencode" &&
+                entry.root &&
+                entry.server_url &&
+                typeof openCodeSessionId === "string" &&
+                (await isSame(entry.root)) &&
+                (await openCodeEndpointOwnedBy(entry.root.pid, entry.server_url, abortDeadline)))
+                await new OpenCodeHttp(entry.server_url)
+                    .abort(openCodeSessionId, abortDeadline)
+                    .catch(() => { });
             await this.stopEntryProcesses(entry);
         }
         finally {
@@ -353,7 +408,7 @@ export class Muster {
             throw new Error(`Ambiguous durable id: ${exact.map((e) => e.runtime + ":" + e.id).join(", ")}`);
         const peers = all.filter((e) => e.kind === "session" && e.status === "running" && e.peer);
         const named = peers.map((e) => ({
-            runtime: e.runtime === "codex" ? "codex" : "claude-code",
+            runtime: runtimeName(e.runtime),
             uuid: e.id,
             rawName: String(e.peer.name),
             slug: String(e.peer.canonical_id)
@@ -389,6 +444,23 @@ export class Muster {
                 rpc = new CodexRpc(this.env, entry.cwd);
                 metadata = await codexReachable(rpc, entry.id, deadline);
             }
+            else if (entry.runtime === "opencode") {
+                if (!entry.server_url)
+                    throw new Error("session endpoint missing");
+                if (!(await isSame(entry.root)) ||
+                    !(await openCodeEndpointOwnedBy(entry.root.pid, entry.server_url, deadline)))
+                    throw new Error("session endpoint is not owned by the launch");
+                metadata = await openCodeReachable(new OpenCodeHttp(entry.server_url), {
+                    id: entry.id,
+                    pid: entry.root.pid,
+                    rawName: null,
+                    cwd: entry.cwd,
+                    serverUrl: entry.server_url,
+                }, deadline);
+                if (!(await isSame(entry.root)) ||
+                    !(await openCodeEndpointOwnedBy(entry.root.pid, entry.server_url, deadline)))
+                    throw new Error("session endpoint ownership changed during refresh");
+            }
             else {
                 const identity = await resolveClaude(entry.root.pid, this.env, deadline);
                 if (!identity ||
@@ -399,7 +471,7 @@ export class Muster {
             }
             const named = assignNames([
                 {
-                    runtime: entry.runtime === "codex" ? "codex" : "claude-code",
+                    runtime: runtimeName(entry.runtime),
                     uuid: entry.id,
                     rawName: metadata.rawName,
                 },
@@ -410,6 +482,9 @@ export class Muster {
                     state: metadata.state,
                     name: named.display,
                     canonical_id: named.canonicalId,
+                    ...(entry.runtime === "opencode"
+                        ? { server_url: entry.server_url }
+                        : {}),
                 },
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {
@@ -62,5 +62,8 @@
     "CANONICAL_ID.md",
     "CONTRACT_PROVENANCE.md",
     "test/fixtures/canonical-id.json"
-  ]
+  ],
+  "allowScripts": {
+    "node-pty@1.1.0": true
+  }
 }

package/test/fixtures/canonical-id.json

@@ -31,8 +31,8 @@
     },
     {
       "case": "claude peers are qualified with their runtime",
-      "peers": [ { "runtime": "claude-code", "rawName": "cohort-api", "uuid": "5af69d42-2214-41d9-b13f-9c3177eb60ce" } ],
-      "expect": [ { "display": "cohort-api", "canonicalId": "claude-code:cohort-api.0ce" } ]
+      "peers": [ { "runtime": "claude-code", "rawName": "billing-api", "uuid": "5af69d42-2214-41d9-b13f-9c3177eb60ce" } ],
+      "expect": [ { "display": "billing-api", "canonicalId": "claude-code:billing-api.0ce" } ]
     },
     {
       "case": "collision: every colliding peer is suffixed, and only those",