@brutalsystems/muster 3.1.1 → 3.2.0

package/CANONICAL_ID.md

@@ -288,7 +288,7 @@ sessions; the send was a reply, so `reply_misrouted` caught it, but a new
 message would have gone through.
 
 This is not an exotic collision. It happens whenever a short name and a longer
-one built on it coexist — `muster` / `muster-b1`, `ferry` / `ferry-9b`.
+one built on it coexist — `muster` / `muster-b1`, `atlas` / `atlas-9b`.
 
 **It is kept because it cannot be fixed from the listing alone.** The hazard is
 indistinguishable from the behaviour directly above it in this document: `auth`

package/CONTRACT_PROVENANCE.md

@@ -513,7 +513,7 @@ The entire delta across both files is three hunks:
 - `CANONICAL_ID.md`: the normative version line, `1.9.2` → `2.0.0`.
 - `CANONICAL_ID.md`: the new paragraph described above.
 - the fixture: `tincan_version`, and one `rawName` in the prefix-collision
-  case, `cxx-be` → `billing-api`.
+  case, renamed to `billing-api`.
 
 `naming.ts` does not appear and no expected value moved. The renamed peer is
 **input**, not an expected output, and that case's expected `canonicalId`
@@ -528,6 +528,19 @@ fixture moved `publish.yml`, `RELEASING.md` and `docs/verification.md` on
 their own. Only the two frozen hashes in `test/naming.test.ts` are hand-written,
 and those are the third site behaving as documented.
 
+## Local text edit — 2026-10-17
+
+One example pair in `CANONICAL_ID.md`'s prefix-collision paragraph used a
+project name from a real machine; it now reads `atlas` / `atlas-9b`. The
+example illustrates the hazard and is not normative, so no rule, case or
+expected value changed. The fixture is untouched.
+
+| File | SHA-256 |
+| --- | --- |
+| `CANONICAL_ID.md` | `516d55ba07d191a29c68b74ea1181bc79149ab53b6c821cc9fe6dab14a78b58a` |
+
+A future re-sync takes upstream's text for that line.
+
 ## What the vendored copy covers, and what it deliberately does not
 
 The copies pin **the address format Muster generates** — slugify, suffix,

package/README.md

@@ -77,6 +77,10 @@ muster run codex --kind task --prompt 'Review' --on-exit 'notify "$MUSTER_STATE"
 # What is running, and stopping it.
 muster list --format human
 muster stop <id>
+
+# Show a session in a terminal: terminal, iterm2, ghostty, or one you define
+# under [open.apps] in config.toml (see docs/launching.md).
+muster run claude --prompt 'Review this project' --open kitty
 ```
 
 **A Claude launch with no containment flag opens exactly as you would open it

package/dist/agents.js

@@ -7,8 +7,7 @@ import { setCodexWorkspaceTrust, setWorkspaceTrust } from "./identity-copy.js";
  * child's argv twice.
  *
  * Exactly these two spellings. Anything else a caller passes after `--` is in
- * neither list and is refused, which is what keeps `--config=sandbox_mode=...`
- * an error rather than something quietly dropped.
+ * neither list and is refused rather than quietly dropped.
  */
 export const MODEL_FLAGS = ["--model", "-m"];
 /**
@@ -20,7 +19,10 @@ export const AGENTS = {
     claude: {
         configHomeVar: "CLAUDE_CONFIG_DIR",
         enforcement: "kernel",
-        runtimeOptions: { forwarded: ["--effort"], consumed: MODEL_FLAGS },
+        runtimeOptions: {
+            forwarded: ["--effort", "--name"],
+            consumed: MODEL_FLAGS,
+        },
         trustWorkspace: setWorkspaceTrust,
         beforeStop: null,
         refreshMetadata: refreshClaude,
@@ -28,7 +30,10 @@ export const AGENTS = {
     codex: {
         configHomeVar: "CODEX_HOME",
         enforcement: "kernel",
-        runtimeOptions: { forwarded: [], consumed: MODEL_FLAGS },
+        runtimeOptions: {
+            forwarded: ["--add-dir", "-c", "--sandbox"],
+            consumed: MODEL_FLAGS,
+        },
         trustWorkspace: setCodexWorkspaceTrust,
         beforeStop: null,
         refreshMetadata: refreshCodex,

package/dist/config.js

@@ -6,6 +6,7 @@ import { z } from "zod";
 import { mcpName, mcpServerSchema } from "./mcp.js";
 import { pluginName, pluginSchema } from "./plugins.js";
 import { openCodeSectionSchema } from "./providers.js";
+import { builtinTerminals } from "./hosts/types.js";
 import { identityNameSchema } from "./identity-store.js";
 import { authoritySchema, subjectSchema } from "./requester.js";
 import { RequesterConfigError } from "./requester-policy.js";
@@ -13,7 +14,7 @@ import { RequesterConfigError } from "./requester-policy.js";
  * What a remote requester is permitted here.
  *
  * `level` defaults to `normal`: an enrolled remote caller gets a launch like
- * the operator's own, as a local one does (Mike, 2026-10-14). Naming `read` or
+ * the operator's own, as a local one does. Naming `read` or
  * `work` is how a profile caps it. `min_enforcement` follows the level it is
  * written beside — `none` for a normal profile, which muster does not enforce,
  * and `kernel` for a capped one — unless the profile names it.
@@ -68,6 +69,46 @@ export const requesterEnrolmentSchema = z
     profile: z.string().min(1),
 })
     .strict();
+const openerPlaceholder = /\{([^{}]*)\}/g;
+const openerPlaceholders = new Set(["tmux", "server", "target"]);
+/**
+ * An extra `--open` target: the argv to run, with `{tmux}`, `{server}` and
+ * `{target}` filled in per launch. An argv array and not a string, so a value
+ * is never re-parsed by a shell; a program that needs one says so itself, as in
+ * `["sh", "-c", "{tmux} -L {server} attach -t {target}"]`.
+ */
+const openerSchema = z
+    .object({
+    command: z
+        .array(z.string().min(1))
+        .min(1)
+        .superRefine((argv, ctx) => {
+        for (const arg of argv)
+            for (const m of arg.matchAll(openerPlaceholder))
+                if (!openerPlaceholders.has(m[1]))
+                    ctx.addIssue({
+                        code: "custom",
+                        message: `unknown placeholder {${m[1]}}; use {tmux}, {server} or {target}`,
+                    });
+        if (!argv.some((a) => a.includes("{target}")))
+            ctx.addIssue({
+                code: "custom",
+                message: "command must contain {target}",
+            });
+    }),
+})
+    .strict();
+const openSectionSchema = z
+    .object({
+    apps: z
+        .record(z
+        .string()
+        .regex(/^[a-zA-Z0-9_-]+$/)
+        .refine((name) => !["auto", ...builtinTerminals].includes(name), "built-in terminal names cannot be redefined"), openerSchema)
+        .default({}),
+})
+    .strict()
+    .default({});
 /** Raw strings, not parsed durations: a bad value in config.toml must fail with
  *  the same message a bad flag does, and that parser lives in one place. */
 const sessionSectionSchema = z
@@ -83,7 +124,7 @@ const sessionSectionSchema = z
 })
     .strict()
     .default({});
-export const configSchema = z
+const configObject = z
     .object({
     host: z.enum(["auto", "tmux", "pty", "macos-terminal"]).default("auto"),
     /**
@@ -97,9 +138,8 @@ export const configSchema = z
      * hardcoded to Terminal.app, so a developer on Ghostty or iTerm2 had to pass
      * `--terminal` on every launch with no way to state it once.
      */
-    terminal: z
-        .enum(["auto", "terminal", "iterm2", "ghostty"])
-        .default("terminal"),
+    terminal: z.string().min(1).default("terminal"),
+    open: openSectionSchema,
     launch_timeout_sec: z.number().finite().positive().max(600).default(30),
     max_concurrent: z.number().int().positive().max(1000).default(4),
     allowed_roots: z.array(z.string().min(1)).default([]),
@@ -143,7 +183,18 @@ export const configSchema = z
     // stay strict for the same reason — an unknown key inside a requester
     // profile is a policy statement that would not apply.
     .strip();
-const knownConfigKeys = new Set(Object.keys(configSchema.shape));
+export const configSchema = configObject.superRefine((config, ctx) => {
+    const t = config.terminal;
+    if (t !== "auto" &&
+        !builtinTerminals.includes(t) &&
+        !config.open.apps[t])
+        ctx.addIssue({
+            code: "custom",
+            path: ["terminal"],
+            message: `terminal "${t}" is not a built-in (${builtinTerminals.join(", ")}) or defined under [open.apps.${t}]`,
+        });
+});
+const knownConfigKeys = new Set(Object.keys(configObject.shape));
 /**
  * Top-level keys this build does not know, sorted. Reported rather than
  * refused, so a newer config degrades to "this Muster ignores that" instead of

package/dist/format.js

@@ -88,7 +88,7 @@ function recordHuman(record, color) {
     if (record.host)
         lines.push(field("Host", `${clean(record.host)}${record.host === "pty" ? " (not watchable or attachable)" : ""}`));
     if (record.terminal_opened)
-        lines.push(field("Terminal", `${record.terminal === "ghostty" ? "Ghostty" : record.terminal === "iterm2" ? "iTerm2" : "Terminal.app"} (opened at launch)`));
+        lines.push(field("Terminal", `${record.terminal === "ghostty" ? "Ghostty" : record.terminal === "iterm2" ? "iTerm2" : record.terminal && record.terminal !== "terminal" ? record.terminal : "Terminal.app"} (opened at launch)`));
     if (record.exit_code !== undefined)
         lines.push(field("Exit code", badExit ? paint(clean(record.exit_code), 31) : clean(record.exit_code)));
     if (record.signal)

package/dist/guard.js

@@ -6,6 +6,7 @@ import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import TOML from "@iarna/toml";
 import { claudeConfigDir } from "./identity/claude.js";
+import { builtinTerminals } from "./hosts/types.js";
 import { mcpName } from "./mcp.js";
 import { claudeMcpConfig } from "./claude-policy.js";
 import { pluginName } from "./plugins.js";
@@ -28,7 +29,10 @@ export const runSchema = z
     kind: z.enum(["session", "task"]).default("session"),
     host: z.enum(["auto", "tmux", "pty", "macos-terminal"]).optional(),
     open: z.boolean().optional(),
-    terminal: z.enum(["auto", "terminal", "iterm2", "ghostty"]).optional(),
+    terminal: z
+        .string()
+        .regex(/^[a-zA-Z0-9_-]+$/)
+        .optional(),
     permissions: z.enum(["auto", "deny", "bypass"]).optional(),
     sandbox: z.enum(["read-only", "workspace-write", "full-access"]).optional(),
     mcp: z.array(mcpName).optional(),
@@ -431,17 +435,33 @@ export function resolveTitle(req, titleable) {
         throw new Error(`--title applies to tmux sessions; this launch is ${req.kind === "task" ? "a task" : `hosted on ${req.host ?? "the configured host"}`}`);
     return sanitiseTitle(req.title);
 }
+/**
+ * `--sandbox` and `-c` are passed to Codex, so they must not be a way round the
+ * policy Muster sets: no full-access sandbox, and no config override of the
+ * sandbox or the approval policy.
+ */
+function refuseWidening(flag, value) {
+    if (flag === "--sandbox" && /full-access/i.test(value))
+        throw new Error(`Runtime option refused: --sandbox ${value}`);
+    if (flag === "-c" && /^\s*(sandbox|approval_policy)/i.test(value))
+        throw new Error(`Runtime option refused: -c ${value}`);
+}
 export function runtimeArgs(req) {
     const result = [];
     const { forwarded, consumed } = AGENTS[req.runtime].runtimeOptions;
     for (let i = 0; i < req.args.length; i++) {
         const arg = req.args[i], flag = normaliseFlag(arg);
-        const keep = forwarded.includes(flag);
-        if (!keep && !consumed.includes(flag))
+        // A single-dash flag is case-sensitive: codex's `-C` (working directory)
+        // must not pass as `-c` (config override) just because `flag` is lowercased.
+        const caseChanged = !arg.startsWith("--") && arg.split("=")[0] !== flag;
+        const keep = !caseChanged && forwarded.includes(flag);
+        if (caseChanged || (!keep && !consumed.includes(flag)))
             throw new Error(`Runtime option refused: ${arg}`);
         if (arg.includes("=")) {
-            if (keep)
+            if (keep) {
+                refuseWidening(flag, arg.slice(arg.indexOf("=") + 1));
                 result.push(arg);
+            }
         }
         else {
             // The value is stepped over for a consumed flag exactly as for a
@@ -450,8 +470,10 @@ export function runtimeArgs(req) {
             const value = req.args[++i];
             if (!value || value.startsWith("-"))
                 throw new Error(`Missing value for ${arg}`);
-            if (keep)
+            if (keep) {
+                refuseWidening(flag, value);
                 result.push(arg, value);
+            }
         }
     }
     return result;
@@ -542,9 +564,15 @@ export function normalizeOpenFlag(argv) {
  * app, so it defers to config exactly as an absent value does.
  */
 export function resolveTerminal(req, config) {
-    if (req.terminal && req.terminal !== "auto")
-        return req.terminal;
-    return config.terminal === "auto" ? "terminal" : config.terminal;
+    const name = req.terminal && req.terminal !== "auto"
+        ? req.terminal
+        : config.terminal === "auto"
+            ? "terminal"
+            : config.terminal;
+    if (!builtinTerminals.includes(name) &&
+        !config.open.apps[name])
+        throw new Error(`Unknown terminal "${name}": use ${builtinTerminals.join(", ")}, or define it under [open.apps.${name}] in config.toml`);
+    return name;
 }
 export function launchArgs(req, config, mcp = [], bridgePath, env = process.env, 
 /** Muster's own home, write-protected at workspace-write (#44). */

package/dist/help.js

@@ -45,7 +45,7 @@ export const COMMANDS = [
             ["--identity NAME", "run as a configured identity"],
             [
                 "--open [APP]",
-                "display the tmux session in a terminal (macOS); APP is terminal, iterm2 or ghostty, defaulting to the configured terminal",
+                'display the tmux session in a terminal; APP is terminal, iterm2, ghostty (macOS) or a name from [open.apps] in config.toml, defaulting to the configured terminal. An app is an argv template, e.g. [open.apps.kitty] command = ["kitty", "-e", "{tmux}", "-L", "{server}", "attach-session", "-t", "{target}"]',
             ],
             [
                 "--terminal APP",

package/dist/hosts/terminal.js

@@ -1,9 +1,13 @@
 import { access, realpath } from "node:fs/promises";
+import { spawn } from "node:child_process";
 import { homedir } from "node:os";
+import { builtinTerminals } from "./types.js";
 import { constants } from "node:fs";
 import { delimiter, join } from "node:path";
 import { command } from "../identity/processes.js";
-export async function terminalAvailable(platform = process.platform, terminal = "terminal") {
+export async function terminalAvailable(platform = process.platform, terminal = "terminal", opener) {
+    if (!isBuiltin(terminal))
+        return opener ? openerAvailable(opener) : false;
     if (platform !== "darwin")
         return false;
     try {
@@ -31,6 +35,63 @@ export async function terminalAvailable(platform = process.platform, terminal =
         return false;
     }
 }
+function isBuiltin(terminal) {
+    return builtinTerminals.includes(terminal);
+}
+/** The command a configured opener runs: an absolute path, or a name on PATH. */
+async function openerExecutable(file) {
+    const dirs = file.includes("/")
+        ? [""]
+        : (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        const path = file.includes("/") ? file : join(dir, file);
+        try {
+            await access(path, constants.X_OK);
+            return path;
+        }
+        catch { }
+    }
+}
+async function openerAvailable(opener) {
+    return (await openerExecutable(opener[0])) !== undefined;
+}
+/**
+ * A configured opener's argv with the placeholders filled in. The values are
+ * validated by the caller; each argv element stays one element, so nothing here
+ * is parsed by a shell.
+ */
+export function openerArgv(opener, values) {
+    return opener.map((arg) => arg.replace(/\{(tmux|server|target)\}/g, (_, key) => values[key]));
+}
+/**
+ * Starts a configured opener without waiting for it to finish: a terminal that
+ * stays in the foreground (`kitty -e …`) runs until its window closes, so
+ * waiting would kill it at the timeout. Success is a clean spawn that has not
+ * failed within a short grace; a spawn error or a non-zero exit inside the
+ * grace is reported.
+ */
+function startOpener(name, file, args, timeout) {
+    const grace = Math.min(1500, timeout);
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, { detached: true, stdio: "ignore" });
+        const fail = (why) => reject(new Error(`Opener "${name}" failed: ${why}`));
+        const timer = setTimeout(() => {
+            child.unref();
+            resolve();
+        }, grace);
+        child.once("error", (e) => {
+            clearTimeout(timer);
+            fail(e.message);
+        });
+        child.once("exit", (code, signal) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve();
+            else
+                fail(signal ? `killed by ${signal}` : `exit ${code}`);
+        });
+    });
+}
 export async function tmuxExecutable() {
     for (const dir of (process.env.PATH ?? "").split(delimiter)) {
         if (!dir)
@@ -44,12 +105,26 @@ export async function tmuxExecutable() {
     }
     throw new Error("Cannot locate tmux executable for terminal viewer");
 }
-export async function openTerminal(tmux, server, hostRef, deadline, terminal = "terminal") {
+export async function openTerminal(tmux, server, hostRef, deadline, terminal = "terminal", opener) {
     if (!/^[a-zA-Z0-9_-]+$/.test(server) || !/^@\d+$/.test(hostRef))
         throw new Error("Invalid tmux terminal target");
     if (Date.now() >= deadline)
         throw new Error("Launch deadline expired before opening terminal");
     const timeout = Math.max(1, Math.min(10000, deadline - Date.now()));
+    if (!isBuiltin(terminal)) {
+        if (!opener)
+            throw new Error(`No opener configured for terminal "${terminal}"`);
+        const [file, ...args] = openerArgv(opener, {
+            tmux,
+            server,
+            target: hostRef,
+        });
+        const found = await openerExecutable(file);
+        if (!found)
+            throw new Error(`Opener "${terminal}": cannot find command "${file}"`);
+        await startOpener(terminal, found, args, timeout);
+        return;
+    }
     if (terminal === "ghostty") {
         await command("/usr/bin/open", [
             "-na",

package/dist/hosts/tmux.js

@@ -176,11 +176,11 @@ export class TmuxHost {
             return false;
         }
     }
-    openAvailable(terminal = "terminal") {
-        return terminalAvailable(process.platform, terminal);
+    openAvailable(terminal = "terminal", opener) {
+        return terminalAvailable(process.platform, terminal, opener);
     }
-    async open(hostRef, deadline, terminal = "terminal") {
-        await openTerminal(await tmuxExecutable(), this.server, hostRef, deadline, terminal);
+    async open(hostRef, deadline, terminal = "terminal", opener) {
+        await openTerminal(await tmuxExecutable(), this.server, hostRef, deadline, terminal, opener);
     }
     capabilities() {
         return { watchable: true, attachable: true, survivesParentExit: true };

package/dist/hosts/types.js

@@ -1 +1 @@
-export {};
+export const builtinTerminals = ["terminal", "iterm2", "ghostty"];

package/dist/mcp-tools.js

@@ -38,8 +38,7 @@ export const MCP_TOOLS = [
                 },
                 terminal: {
                     type: "string",
-                    enum: ["auto", "terminal", "iterm2", "ghostty"],
-                    description: "Viewer app; requires open. Auto uses Terminal.app.",
+                    description: "Viewer app; requires open. terminal, iterm2, ghostty, or a name defined under [open.apps] in config. Auto uses the configured default.",
                 },
                 permissions: {
                     type: "string",

package/dist/run.js

@@ -404,9 +404,12 @@ export class Muster {
         const driver = req.kind === "session"
             ? await selectHost(req.open ? "tmux" : requestedHost, this.drivers)
             : undefined;
+        const opener = this.config.open.apps[terminal]?.command;
         if (req.open &&
-            (!driver?.open || !(await driver.openAvailable?.(terminal))))
-            throw new Error(`--open requires the selected terminal (${terminal}) installed on macOS and tmux`);
+            (!driver?.open || !(await driver.openAvailable?.(terminal, opener))))
+            throw new Error(opener
+                ? `--open: the command for "${terminal}" was not found (${opener[0]}); check [open.apps.${terminal}] in config.toml, and that tmux is installed`
+                : `--open requires the selected terminal (${terminal}) installed on macOS and tmux`);
         // Managed policy is refused because muster cannot prove its own inline
         // settings win over it. A normal launch has no settings of muster's to
         // prove, and obeys managed policy exactly as a hand launch does.
@@ -865,7 +868,7 @@ export class Muster {
                     };
                     if (req.open) {
                         openingTerminal = true;
-                        await driver.open(launched.hostRef, deadline, terminal);
+                        await driver.open(launched.hostRef, deadline, terminal, this.config.open.apps[terminal]?.command);
                         peer.terminal_opened = true;
                         peer.terminal = terminal;
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {
@@ -14,6 +14,7 @@
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.check.json",
     "check": "npm run typecheck && npm test && node scripts/check-tarball.mjs",
+    "check:public": "scripts/check-public.sh --tree",
     "test:contract": "MUSTER_CONTRACT=1 vitest run test/contract.test.ts",
     "postinstall": "node scripts/prepare-pty.mjs",
     "pretest": "npm run build",