@brutalsystems/muster 0.7.2 → 0.7.4

package/CONTRACT_PROVENANCE.md

@@ -79,6 +79,105 @@ the same codename remediation via a history rewrite (`git filter-repo
 whose content or ancestry it touched. This is a historical acquisition
 record, not a claim that the commit is still reachable.
 
+## OpenCode v2 prompt endpoint: closed as routed around, not diagnosed
+
+Status as of 2026-09-20. Recorded because the underlying behaviour is not
+fixed, only avoided, and because the investigation produced three confident
+wrong answers before a right one. Deliberately not filed upstream.
+
+**Reproduced, with neither Muster nor Tin Can involved.** POST to the v2
+`/api/session/{id}/prompt` of a TUI-hosted OpenCode 1.18.31 session returns 200
+with an `admittedSeq`; a drain fires about 68ms later; the turn dies with
+`ModelUnavailableError` naming the session's own model. The TUI path resolves
+that same model string, in the same process, seconds either side:
+
+    20:42:30  stream providerID=fireworks-ai modelID=...qwen3p8-max   (TUI turn)
+    20:42:54  ERROR Failed to drain Session
+              ModelUnavailableError: fireworks-ai/...qwen3p8-max      (delivered)
+
+Observed across 14 distinct TUI-hosted sessions, 20 failures, two unrelated
+providers, no successes. An `opencode serve` session drains and resolves its
+model normally, failing only on an unrelated HTTP 401 — a strictly later stage.
+The v1 `/session/{id}/prompt_async` route runs turns on the same TUI sessions.
+
+**Not established.** That the drain path "cannot resolve the model" is a
+reading of an error string, not a claim from source. Nobody has read OpenCode's
+drain path the way its scheduling path was read. Two loose ends would weaken a
+report: a session that suffered a v2 failure appeared to stop running anything
+afterwards, including v1 calls that had worked moments earlier — one
+observation, never isolated, and if v2 failure corrupts session state then the
+20 failures are fewer independent events than the count suggests. And the
+`serve` control differed in credentials as well as host type.
+
+**Theories that were asserted and disproved**, kept because each looked
+convincing: that OpenCode never scheduled the turn (the drain fires, visibly);
+that the model was cold (TUI success and drain failure alternate 17-24s apart
+on one model); that Muster-supplied inline providers were invisible to the
+drain (a globally authenticated provider fails identically). Each was killed by
+a control that could have been run first.
+
+**Why it is closed.** Tin Can 0.6.0 delivers over v1, which works, so nothing
+in Muster or Tin Can depends on the v2 path. A report resting on an inferred
+mechanism is one a maintainer would reasonably bounce, and the cost of
+diagnosing it properly is not worth paying for a route neither project uses.
+If someone wants to reopen it, the missing step is reading the drain's
+model-resolution path in OpenCode 1.18.31.
+
+## Contract baseline moved to 0.6.4 — 2026-09-20
+
+Re-pinned from `0.6.0`. The suite was run against a real installed
+`@brutalsystems/tincan@0.6.4` and passed all four cases; 0.6.4's
+`canonical-id.json` was compared case by case with Muster's frozen copy and
+every pre-existing case is present with an unchanged expectation, with the same
+four additive opencode-specific cases introduced in 0.5.7. Naming is untouched.
+
+The intervening releases are about how the OpenCode plugin is delivered rather
+than about the address contract: 0.6.1 published the plugin as its own package,
+0.6.2 corrected its entry points so OpenCode's loader can actually execute it,
+and 0.6.4 fixed the publish ordering described below.
+
+**Do not pin `0.6.3`.** Its publish run put the server on the registry and then
+failed a post-publish verification with `ETARGET` — `npm view` had already
+answered for the version while `npm pack` still 404'd — and the plugin publish
+behind that check was skipped. So `@brutalsystems/tincan@0.6.3` exists and
+`@brutalsystems/tincan-opencode@0.6.3` does not. The tag was deliberately not
+moved, because the 0.6.3 server build is published with provenance pointing at
+that commit. 0.6.4 publishes both halves before any post-publish check.
+
+Muster's own pipeline already tolerates that lag: `Confirm published` polls for
+five minutes, and `Verify the published artifact` retries and then warns rather
+than failing when the tarball is not yet downloadable, failing only on a real
+file-list difference.
+
+## Contract baseline moved to 0.6.0 — 2026-09-20
+
+Tin Can 0.6.0 changes the endpoint it delivers to on the opencode leg, from the
+v2 `/api/session/{id}/prompt` to the v1 `/session/{id}/prompt_async`, and the
+change resolves the failure described in the 0.5.9 entry below. It is a minor
+rather than a patch because `urgent` was removed as a capability: the v1 route
+has no equivalent of v2's steer/queue distinction, so rather than accept it and
+ignore it, Tin Can now reports urgent as unsupported on every runtime. Muster
+never referenced that capability, so nothing here changes.
+
+Muster's contract suite was run against a real installed
+`@brutalsystems/tincan@0.6.0` and passed all four cases. Naming is untouched:
+0.6.0's `canonical-id.json` was compared case by case with Muster's frozen copy
+and every pre-existing case is present with an unchanged expectation, with the
+same four additive opencode-specific cases introduced in 0.5.7.
+
+Verified end to end rather than by the suite alone: a Muster-launched OpenCode
+session in a terminal received a Tin Can message, ran the turn, and replied to
+the sending Claude Code session. The OpenCode log for that session shows a
+started loop and a resolved model with no `Failed to drain` line, which is the
+signature the 0.5.9 entry documents as the failure.
+
+One operational trap worth recording, because it makes a working setup look
+broken: the OpenCode plugin is a **copy on disk** under
+`~/.config/opencode/plugin/`. Updating the npm package does not update it, and
+a stale plugin keeps posting to the old v2 route. The peer registry records
+`plugin_version`; confirm it matches the installed package before trusting a
+delivery result.
+
 ## Contract baseline moved to 0.5.9 — 2026-09-20
 
 Re-pinned from `0.5.7`, skipping a separate `0.5.8` pass, because the `notice`

package/README.md

@@ -309,6 +309,50 @@ muster run opencode --mcp tincan --permissions auto --sandbox workspace-write \
 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. 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 has no copy to go stale.
+
+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 a session actually loaded. It records the version, so
+compare that against what is installed:
+
+```sh
+grep plugin_version ~/.tincan/peers/opencode/ses_*.json
+tincan --version
+```
+
+Nothing else surfaces the difference.
+
+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.
@@ -380,6 +424,9 @@ claude --mcp-config '{"mcpServers":{"muster":{"command":"node","args":["/absolut
 
 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
 
@@ -390,6 +437,21 @@ 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.
@@ -413,18 +475,18 @@ 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 **Tin Can 0.5.9**. The suite spawns an installed binary as an MCP
+The verified contract baseline is **Tin Can 0.6.4**. 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:
 
 ```sh
 contract_dir=$(mktemp -d)
-npm install --prefix "$contract_dir" --no-save @brutalsystems/tincan@0.5.9
+npm install --prefix "$contract_dir" --no-save @brutalsystems/tincan@0.6.4
 MUSTER_TINCAN_BIN="$contract_dir/node_modules/.bin/tincan" npm run test:contract
 ```
 
-Verification uses the published 0.5.9 release installed in an isolated
+Verification uses the published 0.6.4 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

package/dist/codex-policy.js

@@ -3,7 +3,16 @@ import { promisify } from "node:util";
 import TOML from "@iarna/toml";
 import { codexMcpConfig } from "./mcp.js";
 const exec = promisify(execFile);
-export async function codexPolicyArgs(env, cwd, deadline = Date.now() + 8000, selected = []) {
+export async function codexPolicyArgs(env, cwd, deadline = Date.now() + 8000, selected = [], 
+/**
+ * True when the launch itself will pass `--ignore-user-config`, as task
+ * launches do. Enumeration has to agree with the launch: a server disabled
+ * here that the launch never loads is not merely redundant, it is harmful.
+ * `-c mcp_servers.<name>.enabled=false` CREATES the key when nothing else
+ * defines it, leaving an entry with no command and no url, and Codex then
+ * refuses the whole config with "invalid transport".
+ */
+ignoreUserConfig = false) {
     const args = [
         "--disable",
         "hooks",
@@ -37,12 +46,18 @@ export async function codexPolicyArgs(env, cwd, deadline = Date.now() + 8000, se
     }
     const inherited = await list(args);
     const usedNames = new Set(inherited.map((s) => s.name));
-    for (const server of inherited) {
-        if (typeof server.name !== "string" ||
-            !/^[a-zA-Z0-9_-]+$/.test(server.name))
-            throw new Error("Cannot safely disable an inherited MCP server with a non-simple name");
-        args.push("-c", `mcp_servers.${server.name}.enabled=false`);
-    }
+    // Nothing to disable when the launch ignores the config the servers come
+    // from: they are already absent. Disabling one anyway would CREATE the key
+    // with neither command nor url, and Codex refuses the whole config with
+    // "invalid transport". The names are still reserved below, so a requested
+    // server never collides with one the user happens to have defined.
+    if (!ignoreUserConfig)
+        for (const server of inherited) {
+            if (typeof server.name !== "string" ||
+                !/^[a-zA-Z0-9_-]+$/.test(server.name))
+                throw new Error("Cannot safely disable an inherited MCP server with a non-simple name");
+            args.push("-c", `mcp_servers.${server.name}.enabled=false`);
+        }
     const expected = [];
     for (const server of selected) {
         let name = server.name;
@@ -60,7 +75,14 @@ export async function codexPolicyArgs(env, cwd, deadline = Date.now() + 8000, se
         .map((s) => s.name)
         .sort();
     expected.sort();
-    if (JSON.stringify(enabled) !== JSON.stringify(expected))
+    // `codex mcp list` has no --ignore-user-config of its own, so when the launch
+    // ignores the user config the listing still reports its servers. They cannot
+    // reach the child — the flag is the guarantee — so the check is that every
+    // requested server is present, rather than that nothing else is.
+    const isolated = ignoreUserConfig
+        ? expected.every((name) => enabled.includes(name))
+        : JSON.stringify(enabled) === JSON.stringify(expected);
+    if (!isolated)
         throw new Error("Inherited Codex MCP servers remain enabled or requested servers are missing; refusing launch");
     return args;
 }

package/dist/plugins.js

@@ -3,15 +3,26 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
 export const pluginName = z.string().regex(/^[a-zA-Z0-9_-]+$/);
+/**
+ * A plugin is named either by a path on disk or by an npm specifier, never
+ * both. OpenCode accepts either in its `plugin` array; a path has to become a
+ * file URL, while a specifier must be passed through untouched so OpenCode can
+ * resolve and install it.
+ *
+ * The specifier form exists because a copied-on-disk plugin goes stale
+ * silently: an old copy keeps running against whatever it was built for, and
+ * an unloaded or outdated plugin is indistinguishable from no plugin at all.
+ */
 export const pluginSchema = z
-    .object({
-    path: z.string().min(1),
-})
-    .strict();
+    .union([
+    z.object({ path: z.string().min(1) }).strict(),
+    z.object({ npm: z.string().min(1) }).strict(),
+])
+    .refine((p) => "path" in p || "npm" in p, "a plugin needs either path or npm");
 /**
- * OpenCode wants plugins as file URLs. Operator definitions are written as
- * ordinary paths, so `~` and relative paths resolve here rather than in the
- * launch path, where a wrong answer would be harder to see.
+ * Operator definitions are written as ordinary paths, so `~` and relative
+ * paths resolve here rather than in the launch path, where a wrong answer
+ * would be harder to see.
  */
 function pluginUrl(path) {
     const expanded = path.startsWith("~/")
@@ -29,6 +40,10 @@ export function selectPlugins(req, config) {
             : undefined;
         if (!plugin)
             throw new Error(`Unknown plugin: ${name}`);
-        return { name, url: pluginUrl(plugin.path) };
+        // A specifier goes through verbatim: resolving it is OpenCode's job.
+        return {
+            name,
+            url: "npm" in plugin ? plugin.npm : pluginUrl(plugin.path),
+        };
     });
 }

package/dist/run.js

@@ -126,7 +126,7 @@ export class Muster {
             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);
+                policy = await codexPolicyArgs(runtimeEnv, req.cwd, deadline, prepared.servers, req.kind === "task");
                 argv.splice(1, 0, ...policy);
             }
             else if (req.runtime === "opencode" && req.kind === "session") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {