@brutalsystems/muster 0.11.1 → 1.0.1

package/TINCAN_LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Mike Williams
+Copyright (c) 2026 BrutalSystems
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/agents.js

@@ -0,0 +1,47 @@
+import { abortOpenCodeSession } from "./stop/opencode.js";
+import { refreshClaude, refreshCodex, refreshOpenCode, } from "./refresh/index.js";
+import { setCodexWorkspaceTrust, setWorkspaceTrust } from "./identity-copy.js";
+/**
+ * The model flags Muster resolves itself. Listed as `consumed` for the runtimes
+ * whose model Muster owns, so a caller may NAME a model without it reaching the
+ * 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.
+ */
+export const MODEL_FLAGS = ["--model", "-m"];
+/**
+ * One row per runtime. `Record<Runtime, …>` is the point: a fourth agent is a
+ * compile error until every column is filled, where the scattered
+ * `runtime === ?` checks this replaced would simply have been incomplete.
+ */
+export const AGENTS = {
+    claude: {
+        configHomeVar: "CLAUDE_CONFIG_DIR",
+        enforcement: "kernel",
+        runtimeOptions: { forwarded: ["--effort"], consumed: MODEL_FLAGS },
+        trustWorkspace: setWorkspaceTrust,
+        beforeStop: null,
+        refreshMetadata: refreshClaude,
+    },
+    codex: {
+        configHomeVar: "CODEX_HOME",
+        enforcement: "kernel",
+        runtimeOptions: { forwarded: [], consumed: MODEL_FLAGS },
+        trustWorkspace: setCodexWorkspaceTrust,
+        beforeStop: null,
+        refreshMetadata: refreshCodex,
+    },
+    opencode: {
+        configHomeVar: null,
+        enforcement: "tool-policy",
+        runtimeOptions: {
+            forwarded: ["--model", "-m", "--agent", "--variant"],
+            consumed: [],
+        },
+        trustWorkspace: null,
+        beforeStop: abortOpenCodeSession,
+        refreshMetadata: refreshOpenCode,
+    },
+};

package/dist/claude-policy.js

@@ -3,6 +3,31 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+export function claudeMcpConfig(servers, bridgePath) {
+    if (servers.length && !bridgePath)
+        throw new Error("Missing MCP bridge configuration");
+    return {
+        mcpServers: Object.fromEntries(servers.map(({ name, config }) => [
+            name,
+            {
+                type: "stdio",
+                command: process.execPath,
+                args: [
+                    fileURLToPath(new URL("../dist/mcp-bridge.js", import.meta.url)),
+                    bridgePath,
+                    name,
+                ],
+                env: Object.fromEntries([
+                    ...config.env_vars,
+                    ...(config.bearer_token_env_var
+                        ? [config.bearer_token_env_var]
+                        : []),
+                ].map((key) => [key, "${" + key + "}"])),
+            },
+        ])),
+    };
+}
 /** Claude's CLI cannot report all effective enterprise policy before starting.
  * Refuse detected managed sources rather than pretending inline settings win. */
 export async function assertClaudePolicy(env) {

package/dist/codex-policy.js

@@ -1,8 +1,26 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import TOML from "@iarna/toml";
-import { codexMcpConfig } from "./mcp.js";
 const exec = promisify(execFile);
+export function codexMcpConfig(server) {
+    const c = server.config;
+    return {
+        ...(c.command
+            ? { command: c.command, args: c.args, env: c.env, env_vars: c.env_vars }
+            : {
+                url: c.url,
+                ...(c.bearer_token_env_var
+                    ? { bearer_token_env_var: c.bearer_token_env_var }
+                    : {}),
+            }),
+        enabled: true,
+        required: server.required,
+        enabled_tools: c.tools,
+        disabled_tools: [],
+        startup_timeout_sec: c.startup_timeout_sec,
+        default_tools_approval_mode: "approve",
+    };
+}
 export async function codexPolicyArgs(env, cwd, deadline = Date.now() + 8000, selected = [], 
 /**
  * True when the launch itself will pass `--ignore-user-config`, as task

package/dist/enforcement.js

@@ -1,5 +1,6 @@
+import { AGENTS } from "./agents.js";
 export function enforcementGrade(runtime, resolved) {
     if (resolved.sandbox === "full-access")
         return "none";
-    return runtime === "opencode" ? "tool-policy" : "kernel";
+    return AGENTS[runtime].enforcement;
 }

package/dist/guard.js

@@ -4,8 +4,11 @@ import { readFileSync } from "node:fs";
 import { realpath } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { claudeConfigDir } from "./identity/claude.js";
-import { mcpName, claudeMcpConfig } from "./mcp.js";
+import { mcpName } from "./mcp.js";
+import { claudeMcpConfig } from "./claude-policy.js";
 import { pluginName } from "./plugins.js";
+import { AGENTS, MODEL_FLAGS } from "./agents.js";
+import { LAUNCH_OPTIONS } from "./options.js";
 import { RequesterConfigError } from "./requester-policy.js";
 import { parseDuration } from "./duration.js";
 export const runSchema = z
@@ -41,6 +44,11 @@ export const runSchema = z
         .optional(),
     requestKey: z.string().min(1).max(200).optional(),
     level: z.enum(["read", "work", "open"]).optional(),
+    /**
+     * Named things muster does on the caller's behalf. Closed set, unlike the
+     * pass-through after `--`: see src/options.ts.
+     */
+    options: z.array(z.enum(LAUNCH_OPTIONS)).default([]),
     args: z.array(z.string()).default([]),
 })
     .strict();
@@ -166,7 +174,6 @@ 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
@@ -234,22 +241,6 @@ export function resolveModel(req, config) {
         ? 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: [],
-    },
-};
 /** 30 minutes. Long enough that a trust prompt or a coffee does not cost a
  *  session; short enough that an orphan dies within the hour. */
 export const DEFAULT_IDLE_TIMEOUT = 1800;
@@ -295,7 +286,7 @@ export function resolveLifecycle(req, config, reapable) {
 }
 export function runtimeArgs(req) {
     const result = [];
-    const { forwarded, consumed } = RUNTIME_OPTIONS[req.runtime];
+    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);

package/dist/help.js

@@ -58,6 +58,10 @@ export const COMMANDS = [
             ["--permissions MODE", "auto, deny, or bypass"],
             ["--sandbox MODE", "read-only, workspace-write, or full-access"],
             ["--mcp NAME", "repeatable; replaces configured defaults"],
+            [
+                "--options NAME",
+                "repeatable; muster-side launch options — auto-approve-path records the launch directory as trusted so its one-time dialog does not block the launch (claude and codex only, and refused if the directory ships hooks or MCP servers)",
+            ],
             ["--no-mcp", "launch with no MCP servers"],
             ["--plugin NAME", "repeatable; replaces configured defaults (OpenCode)"],
             ["--no-plugin", "launch with no plugins"],

package/dist/identity/workspace-key.js

@@ -0,0 +1,59 @@
+import { realpath } from "node:fs/promises";
+import { command } from "./processes.js";
+/**
+ * The key a workspace's trust is recorded under.
+ *
+ * NOT the launch directory. Claude Code 2.1.274 has two gates and they disagree
+ * about how far they will look, so only one key satisfies both:
+ *
+ * - The **dialog** gate walks up from the launch directory looking for any
+ *   trusted ancestor, but stops AT the git repo root — a trusted `/` does not
+ *   reach inside a repo.
+ * - The **settings** gate, which decides whether `.claude/settings.json` is
+ *   honoured, tests one exact key with no walking at all, and that key is the
+ *   repo root.
+ *
+ * So writing the launch directory silences the dialog and still leaves the
+ * workspace untrusted for settings. Claude says so itself, from a subdirectory
+ * of an untrusted repo:
+ *
+ *   Ignoring 1 permissions.allow entry from .claude/settings.json: this
+ *   workspace has not been trusted ... set projects["<repo root>"]
+ *
+ * Writing the repo root satisfies both: the settings gate matches it exactly,
+ * and the dialog gate's walk reaches it before hitting its ceiling.
+ *
+ * A linked worktree keys on its MAIN checkout, which is why this asks git for
+ * the common directory rather than the top level — verified against a real
+ * linked worktree, whose `.git` is a file rather than a directory.
+ *
+ * Outside a repository, or with no usable git, the answer is the directory
+ * itself: the dialog gate then walks freely and the settings gate wants exactly
+ * this path.
+ */
+export async function workspaceTrustKey(cwd) {
+    const resolved = await realpath(cwd).catch(() => cwd);
+    try {
+        // `--git-common-dir`, not `--show-toplevel`: a linked worktree's top level
+        // is the worktree, while Claude keys on the checkout that owns the repo.
+        const common = (await command("git", [
+            "-C",
+            resolved,
+            "rev-parse",
+            "--path-format=absolute",
+            "--git-common-dir",
+        ], 2000)).trim();
+        if (!common)
+            return resolved;
+        // <main checkout>/.git for a normal repo and for a linked worktree alike.
+        // A bare repo has no checkout to trust, so it falls through to the cwd.
+        const base = common.replace(/\/\.git\/?$/, "");
+        if (base === common)
+            return resolved;
+        return await realpath(base).catch(() => base);
+    }
+    catch {
+        // Not a repository, or git unavailable: the directory is its own key.
+        return resolved;
+    }
+}

package/dist/mcp-tools.js

@@ -61,6 +61,11 @@ export const MCP_TOOLS = [
                     items: { type: "string", pattern: "^[a-zA-Z0-9_-]+$" },
                     description: "Configured MCP server names. Omit for session defaults; [] disables all. Tasks have no defaults.",
                 },
+                options: {
+                    type: "array",
+                    items: { type: "string", enum: ["auto-approve-path"] },
+                    description: "Muster-side launch options. auto-approve-path records the launch directory as trusted in the profile the agent will use, so its one-time dialog does not block the launch; refused for a runtime with no trust gate, and refused if the directory ships hooks or MCP servers. Not expressible remotely.",
+                },
                 project: {
                     type: "string",
                     pattern: "^[a-zA-Z0-9_-]+$",

package/dist/mcp.js

@@ -1,4 +1,3 @@
-import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -162,46 +161,3 @@ export async function prepareMcp(selected, env, cwd, deadline) {
         },
     };
 }
-export function codexMcpConfig(server) {
-    const c = server.config;
-    return {
-        ...(c.command
-            ? { command: c.command, args: c.args, env: c.env, env_vars: c.env_vars }
-            : {
-                url: c.url,
-                ...(c.bearer_token_env_var
-                    ? { bearer_token_env_var: c.bearer_token_env_var }
-                    : {}),
-            }),
-        enabled: true,
-        required: server.required,
-        enabled_tools: c.tools,
-        disabled_tools: [],
-        startup_timeout_sec: c.startup_timeout_sec,
-        default_tools_approval_mode: "approve",
-    };
-}
-export function claudeMcpConfig(servers, bridgePath) {
-    if (servers.length && !bridgePath)
-        throw new Error("Missing MCP bridge configuration");
-    return {
-        mcpServers: Object.fromEntries(servers.map(({ name, config }) => [
-            name,
-            {
-                type: "stdio",
-                command: process.execPath,
-                args: [
-                    fileURLToPath(new URL("../dist/mcp-bridge.js", import.meta.url)),
-                    bridgePath,
-                    name,
-                ],
-                env: Object.fromEntries([
-                    ...config.env_vars,
-                    ...(config.bearer_token_env_var
-                        ? [config.bearer_token_env_var]
-                        : []),
-                ].map((key) => [key, "${" + key + "}"])),
-            },
-        ])),
-    };
-}

package/dist/muster.js

@@ -169,6 +169,7 @@ async function main() {
                 sandbox: { type: "string" },
                 level: { type: "string" },
                 mcp: { type: "string", multiple: true },
+                options: { type: "string", multiple: true },
                 "no-mcp": { type: "boolean" },
                 plugin: { type: "string", multiple: true },
                 model: { type: "string" },

package/dist/options.js

@@ -0,0 +1,63 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { AGENTS } from "./agents.js";
+/**
+ * Options are things MUSTER does on the caller's behalf, which is what
+ * separates them from the pass-through after `--`.
+ *
+ * A pass-through reaches the runtime verbatim and is refused unless the agent's
+ * row allow-lists it. An option is a muster concept that each agent expresses
+ * in its own way, or cannot express at all — so the set is closed, and naming
+ * one an agent has no answer for is an error rather than a silent no-op.
+ */
+export const LAUNCH_OPTIONS = ["auto-approve-path"];
+/**
+ * Refuses an option the runtime cannot honour, before anything is reserved or
+ * spawned. `auto-approve-path` records that the launch directory is trusted, so
+ * it needs an agent with a trust gate to record it in; OpenCode has none, and
+ * accepting the flag there would promise something muster cannot deliver.
+ */
+export function assertOptionsSupported(runtime, options) {
+    for (const option of options)
+        if (option === "auto-approve-path" && !AGENTS[runtime].trustWorkspace)
+            throw new Error(`--options auto-approve-path is not supported for ${runtime}: it has no workspace-trust gate`);
+}
+/**
+ * What a directory ships that would configure a session it is trusted by.
+ *
+ * Trusting a folder lets its own `.claude/settings.json` configure the session,
+ * hooks included, and hooks run without asking — which is the reason the trust
+ * dialog exists at all. Auto-approving without looking would be answering a
+ * question nobody read, so a directory carrying either of these is reported and
+ * the launch refuses rather than trusting it quietly.
+ *
+ * A `settings.json` WITHOUT hooks is not a finding: it configures the editor,
+ * not the session's ability to run commands.
+ *
+ * Any read failure is silence rather than a finding. This decides whether to
+ * refuse a launch, and refusing because a file could not be parsed would stop
+ * work for a reason that is not about risk.
+ */
+export async function screenWorkspace(cwd) {
+    const findings = [];
+    try {
+        const raw = await readFile(join(cwd, ".claude", "settings.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            "hooks" in parsed &&
+            Object.keys(parsed.hooks ?? {}).length)
+            findings.push("hooks in .claude/settings.json");
+    }
+    catch {
+        // No file, unreadable, or not JSON: nothing established either way.
+    }
+    try {
+        if ((await stat(join(cwd, ".mcp.json"))).isFile())
+            findings.push("MCP servers in .mcp.json");
+    }
+    catch {
+        // Absent is the common case and not a finding.
+    }
+    return findings;
+}

package/dist/refresh/index.js

@@ -0,0 +1,66 @@
+import { CodexRpc } from "../codex-rpc.js";
+import { OpenCodeHttp } from "../opencode-http.js";
+import { codexReachable } from "../reach/codex.js";
+import { openCodeReachable } from "../reach/opencode.js";
+import { claudeReachable } from "../reach/claude.js";
+import { resolveClaude } from "../identity/claude.js";
+import { openCodeEndpointOwnedBy } from "../identity/opencode.js";
+import { isSame } from "../identity/processes.js";
+/**
+ * Live metadata for a running session, one implementation per agent.
+ *
+ * These pass the same test `trustWorkspace` and `beforeStop` passed: the inputs
+ * match. Each takes the entry, the environment the agent's own configuration
+ * lives in, and a deadline, and each reads from the entry whatever it needs —
+ * a server URL, a configuration home, nothing at all. Readiness could not be a
+ * slot for the opposite reason: it needs a socket path, a live RPC handle and a
+ * server URL, which is three different inputs wearing one name.
+ *
+ * Throwing is how "unreachable" is reported; the caller turns it into that
+ * state. Each implementation owns any connection it opens.
+ */
+export async function refreshCodex(entry, env, deadline) {
+    // The connection is opened and closed here rather than by the caller, so a
+    // refresh cannot leak one by taking an early path out.
+    const rpc = new CodexRpc(env, entry.cwd);
+    try {
+        return await codexReachable(rpc, entry.id, deadline);
+    }
+    finally {
+        await rpc.close();
+    }
+}
+export async function refreshOpenCode(entry, _env, deadline) {
+    if (!entry.server_url)
+        throw new Error("session endpoint missing");
+    if (!entry.root)
+        throw new Error("session has no root process");
+    // Checked BEFORE and AFTER the read, which is not belt-and-braces: a loopback
+    // port is a shared resource and a pid can be reused, so an endpoint that was
+    // ours when the read started may belong to something else by the time it
+    // finishes, and metadata from a stranger is worse than none.
+    const owned = async () => (await isSame(entry.root)) &&
+        (await openCodeEndpointOwnedBy(entry.root.pid, entry.server_url, deadline));
+    if (!(await owned()))
+        throw new Error("session endpoint is not owned by the launch");
+    const metadata = await openCodeReachable(new OpenCodeHttp(entry.server_url), {
+        id: entry.id,
+        pid: entry.root.pid,
+        rawName: null,
+        cwd: entry.cwd,
+        serverUrl: entry.server_url,
+    }, deadline);
+    if (!(await owned()))
+        throw new Error("session endpoint ownership changed during refresh");
+    return metadata;
+}
+export async function refreshClaude(entry, env, deadline) {
+    if (!entry.root)
+        throw new Error("session has no root process");
+    const identity = await resolveClaude(entry.root.pid, env, deadline);
+    if (!identity ||
+        identity.id !== entry.id ||
+        !(await claudeReachable(identity.socketPath, deadline)))
+        throw new Error("session unreachable");
+    return identity;
+}