@brutalsystems/muster 0.10.0 → 0.11.1

package/README.md

@@ -120,7 +120,7 @@ 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`. For Claude and Codex a model named there is *consumed* rather
+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
@@ -212,7 +212,7 @@ and exit-status lifecycle as other tasks.
 
 ## Repeating a launch request
 
-`--request-key KEY` (MCP: `requestKey`) names the launch *request*, not the
+`--request-key KEY` (MCP: `requestKey`) names the launch _request_, not the
 session it produces. Sending the same key again returns the launch it already
 produced instead of starting a second agent:
 
@@ -233,12 +233,12 @@ computed before validation would disagree with itself.
 
 What a repeat returns depends on what the first attempt did:
 
-| First attempt | A repeat gets |
-| --- | --- |
-| Reachable session or running task | That session or task, unchanged |
-| Still launching | Refused — ask for its status instead |
-| Failed, exited or stopped | Refused, naming the recorded outcome |
-| Outcome unknown | Refused, and told to inspect first (below) |
+| First attempt                     | A repeat gets                              |
+| --------------------------------- | ------------------------------------------ |
+| Reachable session or running task | That session or task, unchanged            |
+| Still launching                   | Refused — ask for its status instead       |
+| Failed, exited or stopped         | Refused, naming the recorded outcome       |
+| Outcome unknown                   | Refused, and told to inspect first (below) |
 
 A repeat never consumes launch capacity, including when the concurrency cap is
 full of the very launch being asked about. Omitting the key leaves behaviour
@@ -329,7 +329,7 @@ Muster records the group the launched root leads and takes the union. A stop
 reaches reparented workers, and a session whose root has died but whose group is
 still busy is reported as running rather than ended.
 
-Only a group the root *leads* is used. A process that merely belongs to someone
+Only a group the root _leads_ is used. A process that merely belongs to someone
 else's group shares it with whatever else is there — a shell, a tmux pane, the
 terminal — and treating that as membership would reach far outside the session.
 Both terminal hosts start their root in a new session, so in practice it does
@@ -339,10 +339,21 @@ nothing on macOS prevents that.
 ## Configuration and permissions
 
 Muster reads `~/.muster/config.toml` once at startup and **never writes it**.
+
+A key this build does not know is reported and ignored, so a config written for
+a newer Muster does not stop an older one from running — a strict top level is
+what made every 0.10.0 command fail with `unrecognized_keys` the moment
+`terminal` was added in 0.11.0. Values are still validated, and the nested
+policy tables stay strict: a dropped `sandbox` value would launch under the
+default rather than the pair that was written, and an unknown key inside a
+requester profile is a policy statement that would not apply.
+
 Missing configuration uses these defaults:
 
 ```toml
 host = "auto"
+tmux_status = "off"
+terminal = "terminal"
 launch_timeout_sec = 30
 max_concurrent = 4
 permissions = "deny"
@@ -472,10 +483,24 @@ without adding a retention policy nobody asked for.
 
 ### Containment levels
 
+Two axes, answering different questions:
+
+- **`--permissions` decides whether the agent stops to ask a human.** It
+  configures the runtime's own approval prompting — a setting the agent's
+  process honours.
+- **`--sandbox` decides what the agent may touch, and the kernel enforces it.**
+  On macOS that is seatbelt. Nothing the agent does talks its way past it.
+
+The difference is not academic: a permissions refusal arrives as a prompt or a
+tool error the agent can read and react to, while a sandbox refusal arrives as
+`EPERM` from the kernel, with no negotiation and often no explanation the agent
+can interpret. `enforcement` below records which of the two a launch actually
+got.
+
 `--level` names a legal `--permissions` / `--sandbox` pair. It is a spelling,
 not a second policy path, and naming both a level and either flag is an error.
 
-| Level  | Equivalent to                                                                        |
+| Level  | Equivalent to                                                                         |
 | ------ | ------------------------------------------------------------------------------------- |
 | `read` | `--permissions deny --sandbox read-only`                                              |
 | `work` | `--permissions auto --sandbox workspace-write`                                        |
@@ -487,7 +512,7 @@ through the flags.
 Every launch also records how strongly its containment was imposed:
 
 | `enforcement` | Meaning                                                                     |
-| ------------- | ---------------------------------------------------------------------------- |
+| ------------- | --------------------------------------------------------------------------- |
 | `kernel`      | Codex or Claude Code with an OS sandbox configured and active.              |
 | `tool-policy` | OpenCode — rules the agent is asked to respect, with no kernel enforcement. |
 | `none`        | `full-access` — the sandbox is deliberately disabled.                       |
@@ -739,7 +764,7 @@ configuration.
 
 Five things worth stating plainly, because each is a sharp edge:
 
-1. **`muster identities` reports *configured*, never *valid*.** A keychain
+1. **`muster identities` reports _configured_, never _valid_.** A keychain
    item, an auth file, a stored token or a set variable proves a credential
    exists — not that it still works. Tokens expire and are revoked; there is
    no way to check that without exercising the credential, and `identities`
@@ -777,7 +802,7 @@ Five things worth stating plainly, because each is a sharp edge:
    about bounding.
 
 A Claude launch under an identity also marks the launch's working directory
-trusted *inside that launch's own copy* of the configuration, so a brand-new
+trusted _inside that launch's own copy_ of the configuration, so a brand-new
 directory starts as a registered session without anyone accepting a trust
 dialog. This is distinct from the ordinary Claude prerequisite described
 above: it only ever writes to the per-launch copy, never to the operator's own

package/dist/config.js

@@ -64,6 +64,20 @@ const sessionSectionSchema = z
 export const configSchema = z
     .object({
     host: z.enum(["auto", "tmux", "pty", "macos-terminal"]).default("auto"),
+    /**
+     * Off by default. Muster's tmux runs on its own server with `-f /dev/null`,
+     * so this bar is never the developer's configured one, and a Muster session
+     * is one window running one agent.
+     */
+    tmux_status: z.enum(["on", "off"]).default("off"),
+    /**
+     * Which terminal `--open` uses when the launch does not name one. Was
+     * 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"),
     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([]),
@@ -91,7 +105,32 @@ export const configSchema = z
         .default({}),
     requesters: z.array(requesterEnrolmentSchema).default([]),
 })
-    .strict();
+    // Deliberately NOT strict, unlike the nested schemas above. A config written
+    // for a newer Muster must not brick an older one: when `terminal` arrived in
+    // 0.11.0 a strict top level made EVERY command on 0.10.0 fail with
+    // `unrecognized_keys` — not a warning, a dead CLI, `list` and `stop`
+    // included. Unknown keys here are reported by `unknownConfigKeys` and
+    // dropped.
+    //
+    // Values are still validated, which is the half that matters for safety: a
+    // silently ignored `sandbox = "workspce-write"` would launch under the
+    // default rather than the pair the operator wrote. The nested policy tables
+    // 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));
+/**
+ * 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
+ * refusing to run at all.
+ */
+export function unknownConfigKeys(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return [];
+    return Object.keys(raw)
+        .filter((k) => !knownConfigKeys.has(k))
+        .sort();
+}
 export const musterHome = () => join(homedir(), ".muster");
 export async function loadConfig(home = musterHome()) {
     let value = {};
@@ -102,6 +141,10 @@ export async function loadConfig(home = musterHome()) {
         if (e.code !== "ENOENT")
             throw e;
     }
+    const ignored = unknownConfigKeys(value);
+    if (ignored.length)
+        process.stderr.write(`[muster] ignoring unknown config key${ignored.length > 1 ? "s" : ""}: ` +
+            `${ignored.join(", ")} — written for a different version of muster?\n`);
     const result = configSchema.parse(value);
     const seen = new Set();
     for (const e of result.requesters) {

package/dist/guard.js

@@ -2,8 +2,8 @@ import { z } from "zod";
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { realpath } from "node:fs/promises";
-import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import { claudeConfigDir } from "./identity/claude.js";
 import { mcpName, claudeMcpConfig } from "./mcp.js";
 import { pluginName } from "./plugins.js";
 import { RequesterConfigError } from "./requester-policy.js";
@@ -318,18 +318,6 @@ export function runtimeArgs(req) {
     }
     return result;
 }
-/**
- * The config dir the launched agent will actually use. `launchEnv`'s blocklist
- * is /^(CLAUDECODE|CLAUDE_CODE_|...)/, which does not match CLAUDE_CONFIG_DIR,
- * so the child inherits whatever the caller set and this resolves to the same
- * dir the child will open.
- */
-export function claudeConfigDir(env) {
-    const configured = env.CLAUDE_CONFIG_DIR;
-    if (configured && configured.trim().length > 0)
-        return resolve(configured);
-    return join(env.HOME ?? homedir(), ".claude");
-}
 /**
  * The keys of a profile's own settings.json that name its skill set rather than
  * its policy. `--setting-sources ""` is what keeps `permissions`, `sandbox` and
@@ -358,6 +346,61 @@ function profilePluginSettings(configDir) {
             out[key] = source[key];
     return out;
 }
+/**
+ * Whether the caller typed `--terminal` themselves, read from the raw argv
+ * BEFORE `normalizeOpenFlag` runs. Every `--open <app>` becomes `--terminal
+ * <app>`, so after normalisation the two are indistinguishable and a deprecation
+ * notice would fire on the spelling Muster is steering callers towards.
+ */
+export function usesTerminalFlag(argv) {
+    const end = argv.indexOf("--");
+    return (end === -1 ? argv : argv.slice(0, end)).some((a) => a === "--terminal" || a.startsWith("--terminal="));
+}
+/**
+ * Lifts `--open <app>` and `--open=<app>` onto `--terminal <app>` before
+ * `parseArgs` sees them, so `--open` can carry an optional value at all: in
+ * strict mode a boolean option refuses `=value` and a string option refuses a
+ * bare flag, and there is no third kind. Everything after `--` belongs to the
+ * runtime and is copied through untouched.
+ *
+ * An unrecognised app is lifted too rather than left behind, so the schema names
+ * it in the error instead of it becoming a silent runtime argument.
+ */
+export function normalizeOpenFlag(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--") {
+            out.push(...argv.slice(i));
+            return out;
+        }
+        if (arg.startsWith("--open=")) {
+            out.push("--open", "--terminal", arg.slice("--open=".length));
+            continue;
+        }
+        if (arg === "--open") {
+            const next = argv[i + 1];
+            if (next !== undefined && next !== "--" && !next.startsWith("-")) {
+                out.push("--open", "--terminal", next);
+                i++;
+                continue;
+            }
+        }
+        out.push(arg);
+    }
+    return out;
+}
+/**
+ * Which terminal `--open` uses: the launch's own choice, else config's, and
+ * Terminal.app only when neither names one — it is the one terminal every macOS
+ * is guaranteed to have. `auto` is a request to decide rather than a literal
+ * 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;
+}
 export function launchArgs(req, config, mcp = [], bridgePath, env = process.env) {
     // Before `runtimeArgs`, so this function owns every model error on its own
     // rather than by its caller's discipline: `Muster.launch` happens to resolve
@@ -399,6 +442,12 @@ export function launchArgs(req, config, mcp = [], bridgePath, env = process.env)
         : policy.permissions === "bypass"
             ? "bypassPermissions"
             : "dontAsk";
+    // The dir the launched agent will actually open: `launchEnv`'s blocklist is
+    // /^(CLAUDECODE|CLAUDE_CODE_|...)/, which does not match CLAUDE_CONFIG_DIR, so
+    // the child inherits whatever the caller set. Shared with the trust read and
+    // the sessions dir rather than restated — a second copy here drifted from that
+    // one already (it resolve()d, and read a blank value as unset), which is how a
+    // write root ends up naming a directory nobody is launching in.
     const configDir = claudeConfigDir(env);
     const settings = {
         ...profilePluginSettings(configDir),
@@ -425,8 +474,13 @@ export function launchArgs(req, config, mcp = [], bridgePath, env = process.env)
                 // failed with EPERM while the in-process file tools succeeded (#80).
                 // Granted only under workspace-write: read-only must stay read-only,
                 // and full-access has no sandbox to grant into.
+                // Absolute only here: the sandbox is an OS boundary evaluated against a
+                // path, and a relative CLAUDE_CONFIG_DIR would grant whatever the
+                // launching process's cwd happened to be. The shared resolver stays
+                // as-written so the trust read and the sessions dir keep their
+                // behaviour.
                 ...(policy.sandbox === "workspace-write"
-                    ? { allowWrite: [configDir] }
+                    ? { allowWrite: [resolve(configDir)] }
                     : {}),
             },
         },

package/dist/help.js

@@ -43,8 +43,14 @@ export const COMMANDS = [
             ["--kind KIND", "session (default) or task"],
             ["--host ID", "tmux, pty, or auto (default: tmux, then pty)"],
             ["--identity NAME", "run as a configured identity"],
-            ["--open", "display the tmux session in a terminal (macOS)"],
-            ["--terminal APP", "auto, terminal, iterm2, or ghostty; needs --open"],
+            [
+                "--open [APP]",
+                "display the tmux session in a terminal (macOS); APP is terminal, iterm2 or ghostty, defaulting to the configured terminal",
+            ],
+            [
+                "--terminal APP",
+                "deprecated, removed in v2: pass the app to --open instead",
+            ],
             [
                 "--level LEVEL",
                 "read, work, or open: a legal permissions and sandbox pair",

package/dist/hosts/index.js

@@ -9,9 +9,9 @@ import { MacosTerminalHost } from "./macos-terminal.js";
  * muster` and stay there, since a tmux launch is meant to survive its parent
  * exiting (#57).
  */
-export function hosts(env = process.env) {
+export function hosts(env = process.env, tmuxStatus = "off") {
     return [
-        new TmuxHost(env.MUSTER_TMUX_SERVER || undefined),
+        new TmuxHost(env.MUSTER_TMUX_SERVER || undefined, tmuxStatus),
         new PtyHost(),
         new MacosTerminalHost(),
     ];

package/dist/hosts/tmux.js

@@ -72,9 +72,19 @@ export function tmuxCommand(argv) {
 }
 export class TmuxHost {
     server;
+    status;
     id = "tmux";
-    constructor(server = "muster") {
+    /**
+     * `status` is set explicitly on every session rather than left to tmux's
+     * default, so the bar's state is what Muster asked for whatever version of
+     * tmux is installed. Off by default: Muster's server is its own (`-L`, with
+     * `-f /dev/null`), so the bar here is never the developer's configured one,
+     * and a session is one window running one agent — the bar reports only what
+     * the caller already knows. `tmux_status = "on"` in config.toml restores it.
+     */
+    constructor(server = "muster", status = "off") {
         this.server = server;
+        this.status = status;
         if (!/^[a-zA-Z0-9_-]+$/.test(server))
             throw new Error("Invalid tmux server");
     }
@@ -155,7 +165,23 @@ export class TmuxHost {
         try {
             // Window selection is session-wide: sharing a session makes every
             // attached terminal follow whichever agent was opened most recently.
-            const output = await this.call(["new-session", "-s", `muster-${randomUUID()}`, ...common], opts.deadline);
+            const session = `muster-${randomUUID()}`;
+            // One tmux invocation, not two: a second round trip would leave the bar
+            // visible for as long as it took, and `;` keeps set-option in the same
+            // command list. Targeted by session name rather than relying on "current",
+            // which is not meaningful for a detached session.
+            const output = await this.call([
+                "new-session",
+                "-s",
+                session,
+                ...common,
+                ";",
+                "set-option",
+                "-t",
+                session,
+                "status",
+                this.status,
+            ], opts.deadline);
             return parseWindowRow(output);
         }
         catch (e) {

package/dist/identity/processes.js

@@ -126,6 +126,16 @@ function signal(ref, name) {
  * Reparented descendants are reachable only through the process group, so pass
  * one when the caller has recorded it; the parent chain alone cannot see them.
  */
+/**
+ * Signals a process tree dead: SIGTERM deepest-first, a grace period, a second
+ * pass for anything forked during it, then SIGKILL.
+ *
+ * Resolves once the signals are SENT, not once the processes are gone. SIGKILL
+ * is asynchronous, so a pid may still be in the process table when this returns
+ * — callers that need the stronger guarantee have to poll. Nothing does today:
+ * `stop` marks the entry stopped, and `refreshed` re-probes only entries still
+ * marked running, so the window cannot flip a stopped session back to alive.
+ */
 export async function stopTree(ref, group) {
     if (!(await isSame(ref)))
         return;

package/dist/muster.js

@@ -13,6 +13,7 @@ import { loadConfig, musterHome } from "./config.js";
 import { describeIdentities, interactiveSetup, setupIdentity, } from "./identity-cli.js";
 import { IdentityError } from "./identity-store.js";
 import { MCP_TOOLS } from "./mcp-tools.js";
+import { normalizeOpenFlag, usesTerminalFlag } from "./guard.js";
 import { commandHelp, topLevelHelp } from "./help.js";
 import { promptForMissing, terminalReader } from "./prompt.js";
 const listSchema = z
@@ -147,8 +148,13 @@ async function main() {
     }
     try {
         const command = argv.shift();
+        // Read before normalisation, which turns `--open <app>` into `--terminal
+        // <app>` and would otherwise make the notice fire on the replacement.
+        const typedTerminalFlag = usesTerminalFlag(argv);
         const { values: parsed, positionals } = parseArgs({
-            args: argv,
+            // `--open` carries an optional terminal name, which parseArgs has no kind
+            // for; the value is lifted onto `--terminal` first. See normalizeOpenFlag.
+            args: normalizeOpenFlag(argv),
             allowPositionals: true,
             strict: true,
             options: {
@@ -221,6 +227,8 @@ async function main() {
             ? formatHuman(value, humanColorEnabled(process.stdout.isTTY, process.env))
             : JSON.stringify(value) + "\n");
         if (command === "run") {
+            if (typedTerminalFlag)
+                process.stderr.write("[muster] --terminal is deprecated and will be removed in v2; pass the app to --open instead, or set terminal in config.toml\n");
             const runtime = positionals[0];
             const args = positionals.slice(1);
             const record = await muster.run({