@brutalsystems/muster 0.7.19 → 0.7.21

package/README.md

@@ -105,7 +105,10 @@ piped output and `TERM=dumb` are always uncolored. JSON never includes colors.
 
 `run` accepts an optional `--` followed by runtime arguments. The normal
 allowlist is `--model` / `-m`, plus Claude's `--effort` and OpenCode's `--agent`
-and `--variant`. Unknown options, bundled short options, config injection and
+and `--variant`. For Claude and Codex a model named there is *consumed* rather
+than forwarded — it reaches the child through the same path as `--model`, so it
+appears once — and naming a model both ways is refused rather than resolved by
+precedence. Unknown options, bundled short options, config injection and
 raw permission overrides are refused, even with `allow_dangerous_flags`
 enabled. Use Muster's normalized permission flags. Prompt strings are always
 passed as one literal argument. Codex and Claude launches and OpenCode tasks put
@@ -396,7 +399,9 @@ claim implies that every external tool is OS-sandboxed.
 OpenCode keeps normal provider/model configuration and launches with `--pure`
 unless plugins are selected, which disables inherited external plugins.
 Providers declared under `[opencode.provider]` and a model named by
-`[opencode] model` or `--model` are supplied in the same verified overlay, so a
+`[opencode] model` or `--model` are supplied in the same verified overlay (a
+model named after `--` instead rides the child's argv and is left out of the
+overlay, so it is delivered once rather than twice), so a
 launch does not depend on the operator's own OpenCode configuration; provider
 definitions merge with any the child resolves for itself rather than replacing
 them. Secrets belong in `api_key_env_var`, read from the launching environment,

package/dist/format.js

@@ -38,10 +38,22 @@ function recordHuman(record, color) {
     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.identity)
+        lines.push(field("Identity", clean(record.identity)));
     if (record.permissions)
         lines.push(field("Permissions", clean(record.permissions)));
     if (record.sandbox)
         lines.push(field("Sandbox", clean(record.sandbox)));
+    // Only when known: a null means the child chose its own model, and "-" in a
+    // human listing would read as a value rather than an absence. The source is
+    // shown because "pinned by the caller" and "fell back to the configured
+    // default" are the distinction the field exists to make.
+    if (record.model)
+        lines.push(field("Model", `${clean(record.model)}${record.model_source === "request"
+            ? " (requested)"
+            : record.model_source === "config"
+                ? " (configured default)"
+                : ""}`));
     if (record.mcp)
         lines.push(field("MCP", record.mcp.length ? record.mcp.map(clean).join(", ") : "none"));
     for (const warning of record.mcp_warnings ?? [])

package/dist/guard.js

@@ -156,30 +156,125 @@ export function paramsFingerprint(req, permissions, mcp, plugins) {
     ]))
         .digest("hex");
 }
+const MODEL_FLAGS = ["--model", "-m"];
+/**
+ * The flag half of any pass-through arg, lowercased with `_` mapped to `-`.
+ * Extracted from `runtimeArgs`, which already normalised this way inline, and
+ * now shared with the resolver so the two cannot disagree about whether a
+ * given spelling names a model: one deciding a model was named while the other
+ * forwards it is exactly how a model reaches the child's argv twice.
+ */
+export function normaliseFlag(arg) {
+    return arg.split("=")[0].toLowerCase().replaceAll("_", "-");
+}
+/** A model named inside the runtime pass-through, if one is there. */
+function modelInArgs(args) {
+    const found = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!MODEL_FLAGS.includes(normaliseFlag(arg)))
+            continue;
+        if (arg.includes("=")) {
+            const value = arg.slice(arg.indexOf("=") + 1);
+            // `--model=` names a model and supplies none. Accepting it would deliver
+            // nothing and record `model: null` — "the child chose" — which is the
+            // accepted-and-silently-ignored behaviour this feature exists to remove.
+            if (!value)
+                throw new Error(`Missing value for ${arg}`);
+            found.push(value);
+            continue;
+        }
+        const value = args[i + 1];
+        // A bare flag with no usable value is left alone: `runtimeArgs` raises
+        // "Missing value for --model" on the same input and words it well.
+        if (value && !value.startsWith("-"))
+            found.push(value);
+    }
+    // Taking the first would let OpenCode forward both to a child whose last flag
+    // wins, leaving the run record naming a model the child did not run.
+    if (found.length > 1)
+        throw new Error(`Model named twice in runtime options: ${found.join(" and ")}. Name it once.`);
+    return found[0];
+}
+/**
+ * The one place a launch's model is decided. `launchArgs`, the registry write
+ * and the OpenCode overlay all call this, so what is recorded on the run and
+ * what is handed to the child are one computation rather than two that agree
+ * by luck — which is the whole point of recording it at all.
+ */
+export function resolveModel(req, config) {
+    const inArgs = modelInArgs(req.args);
+    if (req.model !== undefined && inArgs !== undefined)
+        throw new Error(`Model named twice: --model ${req.model} and ${inArgs} in runtime options. Name it once.`);
+    const named = req.model ?? inArgs;
+    if (named !== undefined) {
+        // OpenCode's native form IS provider/model; claude and codex take a bare
+        // id, and a slash there is a mistake worth catching at this boundary
+        // rather than in the child's argument parser.
+        if (req.runtime !== "opencode" && named.includes("/"))
+            throw new Error(`--model for ${req.runtime} takes a bare model id, not PROVIDER/MODEL (got ${named})`);
+        return {
+            model: named,
+            source: "request",
+            origin: req.model !== undefined ? "flag" : "args",
+        };
+    }
+    const configured = req.runtime === "opencode" ? config.opencode.model : undefined;
+    return configured === undefined
+        ? null
+        : { model: configured, source: "config", origin: "config" };
+}
+/**
+ * Per runtime: which pass-through options ride to the child, and which are
+ * recognised but delivered by `resolveModel` instead. A consumed flag must not
+ * be refused — naming a model in `args` is still a supported way to ask, and
+ * it is the only way that worked before `--model` reached these runtimes.
+ * OpenCode is deliberately absent from `consumed`: it already forwards a model
+ * from `args` onto its argv and `test/opencode-policy.test.ts` pins that.
+ */
+const RUNTIME_OPTIONS = {
+    claude: { forwarded: ["--effort"], consumed: MODEL_FLAGS },
+    codex: { forwarded: [], consumed: MODEL_FLAGS },
+    opencode: {
+        forwarded: ["--model", "-m", "--agent", "--variant"],
+        consumed: [],
+    },
+};
 export function runtimeArgs(req) {
     const result = [];
-    const allowed = req.runtime === "claude"
-        ? ["--model", "-m", "--effort"]
-        : req.runtime === "opencode"
-            ? ["--model", "-m", "--agent", "--variant"]
-            : ["--model", "-m"];
+    const { forwarded, consumed } = RUNTIME_OPTIONS[req.runtime];
     for (let i = 0; i < req.args.length; i++) {
-        const arg = req.args[i], flag = arg.split("=")[0].toLowerCase().replaceAll("_", "-");
-        if (!allowed.includes(flag))
+        const arg = req.args[i], flag = normaliseFlag(arg);
+        const keep = forwarded.includes(flag);
+        if (!keep && !consumed.includes(flag))
             throw new Error(`Runtime option refused: ${arg}`);
-        if (arg.includes("="))
-            result.push(arg);
+        if (arg.includes("=")) {
+            if (keep)
+                result.push(arg);
+        }
         else {
+            // The value is stepped over for a consumed flag exactly as for a
+            // forwarded one, so a missing value is still an error and the next
+            // option is not mistaken for this one's value.
             const value = req.args[++i];
             if (!value || value.startsWith("-"))
                 throw new Error(`Missing value for ${arg}`);
-            result.push(arg, value);
+            if (keep)
+                result.push(arg, value);
         }
     }
     return result;
 }
 export function launchArgs(req, config, mcp = [], bridgePath) {
+    // Before `runtimeArgs`, so this function owns every model error on its own
+    // rather than by its caller's discipline: `Muster.launch` happens to resolve
+    // first, but `launchArgs` is exported and an input carrying both a model
+    // conflict and a refused option must report the model conflict.
+    const resolved = resolveModel(req, config);
     const extra = runtimeArgs(req);
+    // OpenCode never reaches here — `run.ts` branches it to the OpenCode launch
+    // builders, which carry the model in their config overlay.
+    const model = resolved ? ["--model", resolved.model] : [];
     const policy = resolvePermissions(req, config);
     if (req.runtime === "codex")
         return [
@@ -200,6 +295,7 @@ export function launchArgs(req, config, mcp = [], bridgePath) {
                             ? ["--ask-for-approval", "never"]
                             : ["-c", 'approval_policy="never"']),
                     ]),
+            ...model,
             ...extra,
             "--",
             req.prompt,
@@ -244,6 +340,7 @@ export function launchArgs(req, config, mcp = [], bridgePath) {
         JSON.stringify(claudeMcpConfig(mcp, bridgePath)),
         "--settings",
         JSON.stringify(settings),
+        ...model,
         ...extra,
         "--",
         req.prompt,

package/dist/help.js

@@ -55,7 +55,10 @@ export const COMMANDS = [
             ["--no-mcp", "launch with no MCP servers"],
             ["--plugin NAME", "repeatable; replaces configured defaults (OpenCode)"],
             ["--no-plugin", "launch with no plugins"],
-            ["--model PROVIDER/MODEL", "select the OpenCode model"],
+            [
+                "--model MODEL",
+                "model for the launch: a bare id for claude and codex, PROVIDER/MODEL for opencode",
+            ],
             [
                 "--request-key KEY",
                 "name the request; sending it again returns the same launch",

package/dist/mcp-tools.js

@@ -80,7 +80,7 @@ export const MCP_TOOLS = [
                 model: {
                     type: "string",
                     minLength: 1,
-                    description: "PROVIDER/MODEL, overriding the configured [opencode] model. OpenCode only.",
+                    description: "Model for the launch. A bare model id for claude and codex; PROVIDER/MODEL for opencode, where it overrides the configured [opencode] model. Recorded on the run and reported by `list`.",
                 },
                 identity: {
                     type: "string",

package/dist/opencode-policy.js

@@ -1,7 +1,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { resolvePermissions, runtimeArgs } from "./guard.js";
-import { openCodeModel, openCodeProviders } from "./providers.js";
+import { resolveModel, resolvePermissions, runtimeArgs, } from "./guard.js";
+import { openCodeProviders } from "./providers.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";
@@ -173,7 +173,15 @@ function permissions(req, config, tools) {
 }
 export function openCodeConfig(req, config, selected, inheritedMcpNames, plugins = [], source = {}) {
     const { mcp, tools } = mcpPolicy(selected, inheritedMcpNames);
-    const model = openCodeModel(req.model, config);
+    // An `args`-named model is already forwarded onto the child's argv by
+    // `runtimeArgs`, so it must not also enter the verified overlay: that would
+    // deliver one model by two routes and rewrite a config the caller never
+    // changed. The overlay carries only what `--model` or `[opencode] model`
+    // named, exactly as before this resolver existed.
+    const resolved = resolveModel(req, config);
+    const model = resolved && resolved.origin !== "args"
+        ? resolved.model
+        : config.opencode.model;
     const provider = openCodeProviders(config, source);
     return {
         share: "disabled",

package/dist/providers.js

@@ -75,7 +75,3 @@ export function openCodeProviders(config, source) {
         ];
     }));
 }
-/** `--model` beats the configured default; OpenCode decides when neither is set. */
-export function openCodeModel(requested, config) {
-    return requested ?? config.opencode.model;
-}

package/dist/run.js

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { loadConfig } from "./config.js";
-import { runSchema, agentBaseEnv, assertAllowedWorkspace, assertLevelExclusive, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, runtimeArgs, } from "./guard.js";
+import { runSchema, agentBaseEnv, assertAllowedWorkspace, assertLevelExclusive, resolveModel, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, runtimeArgs, } from "./guard.js";
 import { enforcementGrade } from "./enforcement.js";
 import { LOCAL } from "./requester.js";
 import { assertEnforcementMeetsMinimum, assertLevelWithinCeiling, assertMayAct, resolveIdentityForRequest, resolveRequesterPolicy, RequesterPolicyRefusal, } from "./requester-policy.js";
@@ -37,6 +37,12 @@ function taskHandle(entry, pid) {
         mcp: entry.mcp ?? [],
         ...(entry.mcp_warnings ? { mcp_warnings: entry.mcp_warnings } : {}),
         ...(entry.enforcement ? { enforcement: entry.enforcement } : {}),
+        ...(entry.identity ? { identity: entry.identity } : {}),
+        // `run` returns this, while `list` builds its own record: a field added to
+        // one and not the other makes the two disagree about the same launch.
+        ...(entry.model !== undefined
+            ? { model: entry.model, model_source: entry.modelSource ?? null }
+            : {}),
         id: entry.id,
         runtime: entry.runtime,
         state: "running",
@@ -226,6 +232,10 @@ export class Muster {
         const selectedMcp = selectMcp(effective, this.config);
         const selectedPlugins = req.runtime === "opencode" ? selectPlugins(effective, this.config) : [];
         let argv = [];
+        // Resolved here, at the seam that already exists to refuse a bad launch
+        // before anything is reserved: a malformed model must not leave a
+        // registry entry behind.
+        const model = resolveModel(effective, this.config);
         if (req.runtime === "opencode")
             runtimeArgs(effective);
         else
@@ -247,6 +257,13 @@ export class Muster {
             cwd: req.cwd,
             ...permissions,
             enforcement,
+            model: model?.model ?? null,
+            modelSource: model?.source ?? null,
+            // Recorded here rather than only at the patch below, because `list`
+            // now publishes it: an entry that dies between this line and that one
+            // would otherwise report no identity, which reads as "ran on the
+            // ambient environment" for a launch that named an account.
+            ...(identityName ? { identity: identityName } : {}),
         }, this.config.max_concurrent, req.requestKey
             ? {
                 requestKey: req.requestKey,
@@ -519,6 +536,13 @@ export class Muster {
                             pid: identity.pid,
                             host: driver.id,
                             capabilities: driver.capabilities(),
+                            // The RESOLVED name, matching what the entry records and what
+                            // `list` projects: a launch result and a listing must not
+                            // disagree about which account this ran as.
+                            ...(identityName ? { identity: identityName } : {}),
+                            // Same reason, for the same pair of records.
+                            model: model?.model ?? null,
+                            model_source: model?.source ?? null,
                             attach_hint: driver.attachHint(launched.hostRef),
                         };
                         if (req.open) {
@@ -859,6 +883,13 @@ export class Muster {
                     // From the entry, not the peer: a listing must report the same fact a
                     // launch result does, and an entry predating the field has none.
                     ...(e.enforcement ? { enforcement: e.enforcement } : {}),
+                    ...(e.identity ? { identity: e.identity } : {}),
+                    // Absent on an entry written before the field, which is a different
+                    // fact from an explicit null: that one means Muster resolved nothing
+                    // and the child chose. Both are more useful than a guess.
+                    ...(e.model !== undefined
+                        ? { model: e.model, model_source: e.modelSource ?? null }
+                        : {}),
                     id: e.id,
                     runtime: e.peer?.runtime ?? e.runtime,
                     state: e.status === "running" ? (e.peer?.state ?? "idle") : e.status,
@@ -879,6 +910,13 @@ export class Muster {
                         ? { permissions: e.permissions, sandbox: e.sandbox }
                         : {}),
                     ...(e.enforcement ? { enforcement: e.enforcement } : {}),
+                    ...(e.identity ? { identity: e.identity } : {}),
+                    // Absent on an entry written before the field, which is a different
+                    // fact from an explicit null: that one means Muster resolved nothing
+                    // and the child chose. Both are more useful than a guess.
+                    ...(e.model !== undefined
+                        ? { model: e.model, model_source: e.modelSource ?? null }
+                        : {}),
                     id: e.id,
                     runtime: e.runtime,
                     cwd: e.cwd,

package/package.json

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