@brutalsystems/muster 0.10.0 → 0.11.0

package/README.md

@@ -343,6 +343,8 @@ Missing configuration uses these defaults:
 
 ```toml
 host = "auto"
+tmux_status = "off"
+terminal = "terminal"
 launch_timeout_sec = 30
 max_concurrent = 4
 permissions = "deny"
@@ -472,6 +474,20 @@ 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.
 

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([]),

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/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({

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, resolveLifecycle, resolveModel, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, runtimeArgs, } from "./guard.js";
+import { runSchema, agentBaseEnv, assertAllowedWorkspace, assertLevelExclusive, resolveLifecycle, resolveModel, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, resolveTerminal, 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";
@@ -98,7 +98,8 @@ export class Muster {
     }
     static async create(opts = {}) {
         const env = launchEnv(opts.env ?? process.env), home = opts.home ?? join(env.HOME ?? homedir(), ".muster");
-        return new Muster(await loadConfig(home), home, env, opts.drivers ?? hosts(opts.env ?? process.env), { ...(opts.env ?? process.env) });
+        const config = await loadConfig(home);
+        return new Muster(config, home, env, opts.drivers ?? hosts(opts.env ?? process.env, config.tmux_status), { ...(opts.env ?? process.env) });
     }
     run(input, requester = LOCAL) {
         if (this.closing)
@@ -217,7 +218,7 @@ export class Muster {
             throw new Error("host applies only to session launches");
         if (req.terminal && !req.open)
             throw new Error("--terminal requires --open");
-        const terminal = !req.terminal || req.terminal === "auto" ? "terminal" : req.terminal;
+        const terminal = resolveTerminal(req, this.config);
         const requestedHost = req.host ?? this.config.host;
         if (req.open &&
             (req.kind !== "session" || !["auto", "tmux"].includes(requestedHost)))

package/package.json

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