@brutalsystems/muster 0.9.2 → 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.
 
@@ -492,6 +508,30 @@ Every launch also records how strongly its containment was imposed:
 | `tool-policy` | OpenCode — rules the agent is asked to respect, with no kernel enforcement. |
 | `none`        | `full-access` — the sandbox is deliberately disabled.                       |
 
+#### What a sandboxed launch may write
+
+Muster names the write roots rather than leaving them to default. Under
+`workspace-write` a launched Claude session may write its cwd, `$TMPDIR`, and
+**its own configuration directory** — the `CLAUDE_CONFIG_DIR` the child will
+actually use, which an identity launch or a requester profile's `env_defaults`
+may relocate. That last root is granted because an agent's memory lives there:
+without it every Bash write to memory failed with `EPERM` while the in-process
+file tools succeeded, which reads from inside the session as a path bug rather
+than a boundary.
+
+Under `read` nothing is writable, including the config dir. Under `full-access`
+there is no sandbox to grant into.
+
+One path stays denied that muster cannot open: **`$CLAUDE_CONFIG_DIR/projects/`**
+(and `shell-snapshots/`). Claude Code refuses writes there in a sandboxed Bash
+regardless of what muster grants — naming those directories explicitly in
+`allowWrite` changes nothing, which is presumably deliberate, since a session's
+own transcripts live there. Project-scoped memory under
+`projects/<cwd-slug>/memory` is therefore reachable only through the file tools,
+which are in-process and not kernel-sandboxed. Note that `work` implies auto
+mode, which asks the model to prefer shell commands for file edits, so a session
+saving project-scoped memory has to be told to use `Write`/`Edit` instead.
+
 ### Requester profiles and enrolments
 
 A non-local caller — one reached through a transport such as Tin Can rather

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

@@ -1,7 +1,9 @@
 import { z } from "zod";
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { realpath } from "node:fs/promises";
-import { isAbsolute, relative, resolve } from "node:path";
+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";
@@ -316,7 +318,90 @@ export function runtimeArgs(req) {
     }
     return result;
 }
-export function launchArgs(req, config, mcp = [], bridgePath) {
+/**
+ * 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
+ * `hooks` muster's alone — forwarding those would let a settings file re-widen
+ * what `assertClaudePolicy` refuses to take on trust — so only these two are
+ * carried across, and muster's keys are spread after them and win regardless.
+ */
+const forwardedSettings = ["enabledPlugins", "extraKnownMarketplaces"];
+function profilePluginSettings(configDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(configDir, "settings.json"), "utf8"));
+    }
+    catch {
+        // No settings file, unreadable, or not JSON: a launch with built-in skills
+        // only is degraded but correct, and failing here would take the sandbox fix
+        // down with it.
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return {};
+    const source = parsed;
+    const out = {};
+    for (const key of forwardedSettings)
+        if (source[key] !== undefined)
+            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
     // first, but `launchArgs` is exported and an input carrying both a model
@@ -357,7 +442,15 @@ export function launchArgs(req, config, mcp = [], bridgePath) {
         : 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),
         disableAllHooks: true,
         permissions: {
             defaultMode: mode,
@@ -374,7 +467,22 @@ export function launchArgs(req, config, mcp = [], bridgePath) {
             autoAllowBashIfSandboxed: true,
             allowUnsandboxedCommands: false,
             excludedCommands: [],
-            filesystem: { denyWrite: readonly ? ["/"] : [] },
+            filesystem: {
+                denyWrite: readonly ? ["/"] : [],
+                // The agent's own memory lives under the config dir, outside the cwd
+                // that Claude Code defaults the write root to, so Bash writes to it
+                // 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: [resolve(configDir)] }
+                    : {}),
+            },
         },
     };
     return [

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)))
@@ -240,7 +241,7 @@ export class Muster {
         if (req.runtime === "opencode")
             runtimeArgs(effective);
         else
-            argv = launchArgs(effective, this.config);
+            argv = launchArgs(effective, this.config, [], undefined, this.sourceEnv);
         const driver = req.kind === "session"
             ? await selectHost(req.open ? "tmux" : requestedHost, this.drivers)
             : undefined;
@@ -389,7 +390,10 @@ export class Muster {
                 await writeFile(bridgePath, JSON.stringify(Object.fromEntries(prepared.servers.map((s) => [s.name, s.config]))), { mode: 0o600 });
             }
             if (req.runtime !== "opencode")
-                argv = launchArgs(effective, this.config, prepared.servers, bridgePath);
+                // `runtimeEnv`, not the host's: an identity launch relocates
+                // CLAUDE_CONFIG_DIR to the per-launch copy, and the sandbox must grant
+                // the dir the child will actually open, not the one Muster runs under.
+                argv = launchArgs(effective, this.config, prepared.servers, bridgePath, runtimeEnv);
             if (req.runtime === "codex") {
                 codexPolicy = await codexPolicyArgs(runtimeEnv, req.cwd, deadline, prepared.servers, req.kind === "task");
                 argv.splice(1, 0, ...codexPolicy);

package/package.json

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