@brutalsystems/muster 0.7.18 → 0.7.20

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,16 @@ 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.
+    if (record.model)
+        lines.push(field("Model", clean(record.model)));
     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,121 @@ 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) {
     const extra = runtimeArgs(req);
+    const resolved = resolveModel(req, config);
+    // 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 +291,7 @@ export function launchArgs(req, config, mcp = [], bridgePath) {
                             ? ["--ask-for-approval", "never"]
                             : ["-c", 'approval_policy="never"']),
                     ]),
+            ...model,
             ...extra,
             "--",
             req.prompt,
@@ -244,6 +336,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/identity-cli.js

@@ -1,7 +1,7 @@
 import { identityAuthState } from "./identity-auth.js";
 import { IdentityError, identityDirExists, identityMetaSchema, identityNameSchema, identityPath, listIdentities, readIdentity, writeIdentity, } from "./identity-store.js";
 import { removeStoredToken, writeStoredToken, } from "./identity-token.js";
-import { captureClaudeToken, redactToken, } from "./identity-login.js";
+import { captureClaudeToken, redactToken, resolveOnPath, } from "./identity-login.js";
 /**
  * The one-time login for each agent. Muster never performs it: each is an
  * interactive OAuth flow, and a command that appeared to do it for you would be
@@ -25,7 +25,12 @@ export async function setupIdentity(opts) {
     // a codex or opencode identity, where the credential is an auth file the
     // agent's own login writes into the template, it has exactly one effect: a new
     // way to fail. Refused where the operator types it.
-    if (opts.tokenEnv && opts.agent !== "claude")
+    // Checked against undefined, not truthiness: `--token-env ""` is falsy, so a
+    // truthiness test let an empty name past every guard and then dropped it,
+    // leaving the identity on neither credential route without saying so (#69).
+    if (opts.tokenEnv !== undefined && opts.tokenEnv.trim() === "")
+        throw new IdentityError(opts.name, "--token-env takes the name of an environment variable holding the token, not the token and not an empty value");
+    if (opts.tokenEnv !== undefined && opts.agent !== "claude")
         throw new IdentityError(name, `--token-env applies only to a claude identity; ${opts.agent} authenticates from an auth file in the template, and a token variable here would only add a way for the launch to fail`);
     // Distinguish "no such identity" from "an identity that is there but unusable".
     // Overwriting the second would silently repurpose a directory that still holds
@@ -150,24 +155,30 @@ export async function interactiveSetup(opts) {
             stored: false,
             note: `Run this once, then check with \`muster identities\`:\n\n    ${created.login}\n`,
         };
+    // Asked before anything is spawned, so "could not be started" is a fact about
+    // the filesystem rather than an inference from what the child printed. That
+    // inference was platform-dependent: a missing executable emits nothing under
+    // macOS and an error into the pty under Linux (#69).
+    if (!(await resolveOnPath("claude", opts.env ?? process.env)))
+        throw new IdentityError(opts.name, "`claude` is not on PATH, so the login could not be started; nothing was changed");
     write(`Running: claude setup-token\n${"─".repeat(50)}\n`);
     const result = await captureClaudeToken({
         dir: created.path,
         env: opts.env ?? process.env,
         onData: write,
-        ...(opts.stdin ? { stdin: opts.stdin } : {}),
+        stdin: opts.stdin,
     });
     write(`${"─".repeat(50)}\n`);
     // Checked BEFORE the token branch, deliberately: a login that failed writes
     // no credential even if something token-shaped went past on the way down.
     //
-    // This is also the case where the child never started at all. node-pty does
-    // not throw for a missing executable — it exits 1 having emitted zero bytes —
-    // so an operator with no `claude` on PATH used to be told Muster could not
-    // parse output that never existed, with no identity name and no hint that
-    // nothing had run. The child's own output is the error here, whatever it was.
+    // Two different events land here and they need different explanations. node-pty
+    // does not throw for a missing executable — it exits 1 having emitted zero
+    // bytes — which is exactly the exit shape of a login that failed on its own or
+    // that the operator interrupted. The exit code cannot tell them apart; whether
+    // anything was ever printed can (#69).
     if (result.exitCode !== 0)
-        throw new IdentityError(opts.name, `\`claude setup-token\` failed (exit ${result.exitCode}) and no credential was stored; its own output above is the error. If nothing was printed above it could not be started at all — check that \`claude\` is on PATH.`);
+        throw new IdentityError(opts.name, `\`claude setup-token\` ended without storing a credential (exit ${result.exitCode}); its own output above is the error. If you interrupted it, nothing was stored and nothing was changed.`);
     if (result.token) {
         const { clearedRoute } = await storeIdentityToken({
             home: opts.home,

package/dist/identity-login.js

@@ -1,3 +1,28 @@
+import { access, constants } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+/**
+ * Where `name` is on PATH, or undefined. The same lookup `tmuxExecutable` does,
+ * and the reason the login asks it: whether a child "could not be started" has
+ * to be decided before spawning, not inferred from what it printed. node-pty
+ * does not throw for a missing executable — it exits 1, emitting nothing on
+ * macOS and an error into the pty on Linux, so output was never the discriminator
+ * it appeared to be (#69).
+ */
+export async function resolveOnPath(name, env) {
+    for (const dir of (env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, name);
+        try {
+            await access(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Not here, or not executable. Keep looking.
+        }
+    }
+    return undefined;
+}
 /**
  * A Claude long-lived OAuth token, as `claude setup-token` prints it. The length
  * floor is what separates a real token from the literal word in help text.
@@ -257,8 +282,8 @@ function attachInput(pty, input, signals) {
  * status quo.
  */
 export async function captureClaudeToken(opts) {
-    const module = await import("node-pty");
-    const pty = module.spawn("claude", ["setup-token"], {
+    const spawn = opts.spawn ?? (await import("node-pty")).spawn;
+    const pty = spawn("claude", ["setup-token"], {
         cwd: opts.dir,
         env: { ...opts.env, CLAUDE_CONFIG_DIR: opts.dir },
         name: "xterm-256color",
@@ -278,7 +303,7 @@ export async function captureClaudeToken(opts) {
     // up before rethrowing, and enters raw mode last of all.
     let detachInput = () => { };
     try {
-        detachInput = attachInput(pty, opts.stdin ?? process.stdin, opts.signals ?? process);
+        detachInput = attachInput(pty, opts.stdin, opts.signals ?? process);
         const filter = createTokenFilter(opts.onData);
         const dataSub = pty.onData((chunk) => filter.push(chunk));
         const exitCode = await new Promise((resolve) => {

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/muster.js

@@ -247,13 +247,21 @@ async function main() {
                 // year-long token to disk on the machine the operator explicitly asked
                 // to keep no credential at rest, while never recording the variable
                 // they named.
-                if (tokenEnv)
+                if (tokenEnv !== undefined && agent !== "claude")
+                    // Not the mutual-exclusion message: for codex and opencode
+                    // `--interactive` captures nothing and `--token-env` does not apply
+                    // at all, so describing them as two routes to choose between would
+                    // be describing Claude's behaviour at a different agent (#69).
+                    throw new IdentityError(identity, `--token-env applies only to a claude identity; ${agent} authenticates from an auth file in the template, and a token variable here would only add a way for the launch to fail`);
+                if (tokenEnv !== undefined)
                     throw new IdentityError(identity, "--interactive and --token-env are the two mutually exclusive credential routes: --interactive runs the login and stores a token in the identity, --token-env records the name of a variable to read one from instead. Pass one, not both.");
                 const result = await interactiveSetup({
                     home: musterHome(),
                     name: identity,
                     agent: agent,
                     isTTY: Boolean(process.stdin.isTTY),
+                    // The one place the operator's real keyboard is named.
+                    stdin: process.stdin,
                 });
                 process.stdout.write(`\n${result.note}\n`);
                 return;
@@ -265,7 +273,7 @@ async function main() {
                 home: musterHome(),
                 name: identity,
                 agent: agent,
-                ...(tokenEnv ? { tokenEnv } : {}),
+                ...(tokenEnv !== undefined ? { tokenEnv } : {}),
             })) + "\n");
         }
         else if (command === "identities") {

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,10 @@ 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 } : {}),
                             attach_hint: driver.attachHint(launched.hostRef),
                         };
                         if (req.open) {
@@ -859,6 +880,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 +907,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.18",
+  "version": "0.7.20",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {
@@ -12,7 +12,8 @@
   "scripts": {
     "build": "tsc && node scripts/prepare-bin.mjs",
     "test": "vitest run",
-    "check": "npm test && node scripts/check-tarball.mjs",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "check": "npm run typecheck && npm test && node scripts/check-tarball.mjs",
     "test:contract": "MUSTER_CONTRACT=1 vitest run test/contract.test.ts",
     "postinstall": "node scripts/prepare-pty.mjs",
     "pretest": "npm run build",