@brutalsystems/muster 1.2.0 → 1.2.1

package/README.md

@@ -76,14 +76,14 @@ muster stop <id>
 ```
 
 `--level` names a containment pair. `read` can look but not change; `work` can
-edit its working directory; `open` removes the sandbox and needs
-`allow_dangerous_flags` in config.
-
-| Level  | The agent asks before acting | What it may touch |
-| ------ | ---------------------------- | ----------------- |
-| `read` | always                       | nothing on disk   |
-| `work` | no                           | its cwd           |
-| `open` | no                           | everything        |
+edit its working directory, except muster's own home (`~/.muster`); `open`
+removes the sandbox and needs `allow_dangerous_flags` in config.
+
+| Level  | The agent asks before acting | What it may touch           |
+| ------ | ---------------------------- | --------------------------- |
+| `read` | always                       | nothing on disk             |
+| `work` | no                           | its cwd, except `~/.muster` |
+| `open` | no                           | everything                  |
 
 Claude asks to trust a directory the first time. That is a one-time review you
 do yourself — or `--options auto-approve-path`, which records it for you after

package/dist/guard.js

@@ -2,7 +2,9 @@ import { z } from "zod";
 import { createHash } from "node:crypto";
 import { readFileSync, realpathSync } from "node:fs";
 import { realpath } from "node:fs/promises";
+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 { mcpName } from "./mcp.js";
 import { claudeMcpConfig } from "./claude-policy.js";
@@ -11,6 +13,7 @@ import { AGENTS, MODEL_FLAGS } from "./agents.js";
 import { LAUNCH_OPTIONS } from "./options.js";
 import { RequesterConfigError } from "./requester-policy.js";
 import { parseDuration } from "./duration.js";
+import { assertModelDeclared } from "./providers.js";
 export const runSchema = z
     .object({
     runtime: z.enum(["codex", "claude", "opencode"]),
@@ -134,6 +137,82 @@ export async function assertAllowedWorkspace(cwd, config) {
     throw new Error(`cwd is outside every configured allowed root: ${cwd}. ` +
         `Add a root or a project to config.toml, or launch somewhere already permitted.`);
 }
+/**
+ * Where muster keeps its own state when a caller does not say: the same
+ * default `Muster.create` uses, so `launchArgs` called on its own protects the
+ * home a real launch would.
+ */
+export function defaultMusterHome(env) {
+    return join(env.HOME ?? homedir(), ".muster");
+}
+/**
+ * True when a launch at this pair can write under its cwd: every
+ * workspace-write launch. Read-only writes nothing, and full-access (`open`)
+ * is unrestricted by definition and gated by `allow_dangerous_flags` instead.
+ */
+function writesWorkspace(policy) {
+    return policy.sandbox === "workspace-write";
+}
+/**
+ * Refuses a launch that would hand a runtime write access to muster's own home
+ * when that runtime cannot be told to leave the home alone (#44).
+ *
+ * The home holds the machine's policy: `allow_dangerous_flags`, the requester
+ * grants, and the MCP server commands muster runs for every later launch. An
+ * agent that can write it can widen the policy that constrains it.
+ *
+ * Claude and Codex take a path deny in what muster generates for them, so they
+ * are protected there and never refused here. OpenCode's permissions are tool
+ * policy: an `edit` rule can name a path, but a shell command cannot be
+ * confined to one, and `bash` is what `work` grants it. So for OpenCode the
+ * one guarantee is a cwd that does not contain the home — the home is then an
+ * external directory, which `work` already denies. "Overlaps" means the cwd is
+ * the home, inside it, or an ancestor of it (such as `~`), compared as real
+ * paths so a symlink on either side cannot hide it.
+ */
+export function assertMusterHomeProtectable(runtime, cwd, policy, home) {
+    if (runtime !== "opencode" || !writesWorkspace(policy))
+        return;
+    // `deny` with workspace-write already denies OpenCode's edit and shell
+    // tools, so it can write nothing anywhere.
+    if (policy.permissions === "deny")
+        return;
+    // Both spellings of each side. Real paths alone miss a home reached through
+    // a symlink: `~/.muster` linking elsewhere is not inside `~` once resolved,
+    // yet writing through `~/.muster` lands in it.
+    const cwds = writeRootSpellings(resolve(cwd));
+    const homes = writeRootSpellings(resolve(home));
+    if (cwds.some((c) => homes.some((h) => contains(h, c) || contains(c, h))))
+        throw new Error(`refusing an opencode ${policy.sandbox} launch in ${cwd}: it contains or ` +
+            `is inside muster's own home (${home}), which holds the config every ` +
+            `later launch obeys. OpenCode's permissions are tool policy and cannot ` +
+            `keep its shell out of one folder, so launch it in a folder that does ` +
+            `not contain muster's home, or at --level read.`);
+}
+/** Whether `inner` is `outer` or below it, by path segments, not characters. */
+function contains(outer, inner) {
+    const rel = relative(outer, inner);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * The Codex arguments that make muster's home read-only inside a writable
+ * workspace. A permissions profile is the only Codex config that can carve a
+ * read-only path out of a writable root, and a `--sandbox` flag overrides a
+ * profile, so a workspace-write launch selects this profile instead of passing
+ * `--sandbox workspace-write`. `:workspace` is the built-in profile that flag
+ * names, so everything else about the sandbox is the same.
+ */
+function codexWorkspaceProfile(home) {
+    const filesystem = Object.fromEntries(writeRootSpellings(home).map((p) => [p, "read"]));
+    return [
+        "-c",
+        'default_permissions="muster_work"',
+        "-c",
+        'permissions.muster_work.extends=":workspace"',
+        "-c",
+        `permissions.muster_work.filesystem=${TOML.stringify.value(filesystem)}`,
+    ];
+}
 /**
  * What a request key is bound to, so the same key arriving with different
  * parameters can be refused rather than silently answered with the wrong
@@ -222,6 +301,15 @@ function modelInArgs(args) {
  * by luck — which is the whole point of recording it at all.
  */
 export function resolveModel(req, config) {
+    const resolved = nameModel(req, config);
+    // Every route to a model — --model, args, [opencode] model — passes here,
+    // and this runs before anything is reserved, so an undeclared one leaves no
+    // record behind.
+    if (resolved !== null && req.runtime === "opencode")
+        assertModelDeclared(resolved.model, config);
+    return resolved;
+}
+function nameModel(req, config) {
     const inArgs = modelInArgs(req.args);
     if (req.model !== undefined && inArgs !== undefined)
         throw new Error(`Model named twice: --model ${req.model} and ${inArgs} in runtime options. Name it once.`);
@@ -422,7 +510,9 @@ export function resolveTerminal(req, config) {
         return req.terminal;
     return config.terminal === "auto" ? "terminal" : config.terminal;
 }
-export function launchArgs(req, config, mcp = [], bridgePath, env = process.env) {
+export function launchArgs(req, config, mcp = [], bridgePath, env = process.env, 
+/** Muster's own home, write-protected at workspace-write (#44). */
+musterHome = defaultMusterHome(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
@@ -444,20 +534,32 @@ export function launchArgs(req, config, mcp = [], bridgePath, env = process.env)
                 : policy.permissions === "bypass"
                     ? ["--dangerously-bypass-approvals-and-sandbox"]
                     : [
-                        "--sandbox",
-                        policy.sandbox === "full-access"
-                            ? "danger-full-access"
-                            : policy.sandbox,
+                        // Workspace-write is spelled as the profile below instead: the
+                        // flag would override it.
+                        ...(writesWorkspace(policy)
+                            ? []
+                            : [
+                                "--sandbox",
+                                policy.sandbox === "full-access"
+                                    ? "danger-full-access"
+                                    : policy.sandbox,
+                            ]),
                         ...(req.kind === "session"
                             ? ["--ask-for-approval", "never"]
                             : ["-c", 'approval_policy="never"']),
                     ]),
+            ...(writesWorkspace(policy) ? codexWorkspaceProfile(musterHome) : []),
             ...model,
             ...extra,
             "--",
             req.prompt,
         ];
     const readonly = policy.sandbox === "read-only";
+    // Muster's own home, under both spellings, wherever the launch can write its
+    // cwd: the cwd write grant covers the home when the cwd contains it (#44).
+    const protectedHome = writesWorkspace(policy)
+        ? writeRootSpellings(musterHome)
+        : [];
     const mode = policy.permissions === "auto"
         ? "auto"
         : policy.permissions === "bypass"
@@ -486,6 +588,12 @@ export function launchArgs(req, config, mcp = [], bridgePath, env = process.env)
             allow: mcp.flatMap((s) => s.config.tools.map((t) => `mcp__${s.name}__${t}`)),
             deny: [
                 ...(readonly ? ["Edit", "Write", "NotebookEdit"] : []),
+                // The in-process file tools run outside the OS sandbox, so the
+                // denyWrite below does not reach them. `//` is Claude's spelling of
+                // an absolute path, and an `Edit(path)` rule covers every
+                // file-editing tool: Claude 2.1.293 warns that `Write(path)` is never
+                // matched by its file permission checks.
+                ...protectedHome.map((dir) => `Edit(/${dir}/**)`),
                 ...mcp.flatMap((s) => s.excludedTools.map((t) => `mcp__${s.name}__${t}`)),
             ],
             additionalDirectories: [],
@@ -503,7 +611,10 @@ export function launchArgs(req, config, mcp = [], bridgePath, env = process.env)
                 // command exited 1 (#41) — and a deny beats an allow, so the temp dir
                 // cannot be allowed back. Both spellings of a symlinked cwd, so this
                 // does not rest on Claude normalising the path.
-                denyWrite: readonly ? writeRootSpellings(req.cwd) : [],
+                // At workspace-write, muster's own home is denied instead (#44): it
+                // holds the policy every later launch obeys, and a cwd that contains
+                // it (such as `~`) would otherwise make it writable.
+                denyWrite: readonly ? writeRootSpellings(req.cwd) : protectedHome,
                 // 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).

package/dist/help.js

@@ -53,7 +53,7 @@ export const COMMANDS = [
             ],
             [
                 "--level LEVEL",
-                "read, work, or open: a legal permissions and sandbox pair",
+                "read, work, or open: a legal permissions and sandbox pair; work writes the launch folder except muster's own home",
             ],
             ["--permissions MODE", "auto, deny, or bypass"],
             ["--sandbox MODE", "read-only, workspace-write, or full-access"],

package/dist/hosts/tmux.js

@@ -82,6 +82,43 @@ export function titleOptions(session, title) {
         ...set("set-titles", "on"),
     ];
 }
+/**
+ * What muster's server needs in place of a config file. It runs with `-f
+ * /dev/null` so a developer's ~/.tmux.conf cannot change how muster's sessions
+ * behave, which leaves tmux's own defaults: the scroll wheel never reaches the
+ * pane's history, the history is 2000 lines, and Shift+Enter arrives as plain
+ * Enter, so it submits Claude Code's prompt instead of starting a new line
+ * (#57).
+ *
+ * These go at the front of `new-session`'s command list, not after it:
+ * `history-limit` is read when a pane is created, so a value set once the
+ * window exists never reaches it. Every launch sets them again, which is what
+ * brings a server started by an older muster up to date.
+ *
+ * `extkeys` tells tmux the outer terminal understands extended keys, so it
+ * asks the terminal for them; without it `extended-keys` has nothing to pass
+ * on. It is set at a fixed index rather than appended (`-a`), so a long-lived
+ * server does not gain another copy with every launch. `xterm*` matches the
+ * TERM Ghostty, iTerm2 and Terminal.app report; a terminal that does not
+ * support the request ignores it.
+ *
+ * `-q` because these name options newer than some tmux still installed
+ * (`extended-keys-format` arrived in 3.5, `terminal-features` in 3.2), and an
+ * unknown option is an error that would abort the whole command list and with
+ * it the launch. An older tmux launches as before, without the option.
+ */
+export const SERVER_OPTIONS = [
+    ["-g", "mouse", "on"],
+    ["-g", "history-limit", "50000"],
+    ["-s", "extended-keys", "always"],
+    ["-s", "extended-keys-format", "csi-u"],
+    ["-s", "terminal-features[90]", "xterm*:extkeys"],
+];
+/** `SERVER_OPTIONS` as `;`-terminated `set-option` commands, to lead a
+ *  command list. */
+export function serverOptions() {
+    return SERVER_OPTIONS.flatMap((o) => ["set-option", "-q", ...o, ";"]);
+}
 /**
  * One shell command line for `run-shell`.
  *
@@ -196,6 +233,7 @@ export class TmuxHost {
             // command list. Targeted by session name rather than relying on "current",
             // which is not meaningful for a detached session.
             const output = await this.call([
+                ...serverOptions(),
                 "new-session",
                 "-s",
                 session,

package/dist/identity/opencode.js

@@ -29,7 +29,48 @@ export async function openCodeEndpointOwnedBy(rootPid, serverUrl, deadline) {
         return false;
     }
 }
-export async function resolveOpenCode(rootPid, serverUrl, cwd, createdAfter, deadline) {
+/** The text of the session's first user message, or undefined before it has one. */
+function firstUserText(messages) {
+    const first = messages.find((message) => message.info.role === "user");
+    if (!first)
+        return undefined;
+    return first.parts
+        .filter((part) => part.type === "text" && part.text !== undefined)
+        .map((part) => part.text)
+        .join("");
+}
+async function carriesPrompt(client, id, prompt, deadline) {
+    try {
+        const text = firstUserText(await client.messages(id, deadline));
+        return text !== undefined && text.trim() === prompt.trim();
+    }
+    catch (error) {
+        // One unreadable candidate — deleted, or another process's half-written
+        // session — is not a match, and must not stall discovery of the rest.
+        if (error instanceof OpenCodeProtocolError)
+            return false;
+        throw error;
+    }
+}
+/**
+ * Finds the session this launch's OpenCode created.
+ *
+ * `/session` reads the project database every OpenCode process on the machine
+ * shares, so directory and creation window alone can match a stranger's
+ * session. Two signals tie a candidate to this launch:
+ *
+ * - presence in `/session/status`, which is the endpoint process's in-memory
+ *   map of its own non-idle sessions; or
+ * - for a candidate absent from that map, a first user message equal to the
+ *   prompt this launch submitted.
+ *
+ * The second exists because OpenCode deletes a session from the status map the
+ * moment it goes idle (#2): a first turn that finishes before discovery left
+ * the session invisible, and the launch timed out. Without `prompt`, an absent
+ * candidate is never claimed. Every candidate that passes either signal counts
+ * toward the ambiguity check.
+ */
+export async function resolveOpenCode(rootPid, serverUrl, cwd, createdAfter, deadline, prompt) {
     const resolvedCwd = await realpath(cwd);
     const client = new OpenCodeHttp(serverUrl);
     let ownershipProven = false;
@@ -55,13 +96,18 @@ export async function resolveOpenCode(rootPid, serverUrl, cwd, createdAfter, dea
                 const statuses = candidates.length
                     ? await client.statuses(deadline)
                     : {};
+                const matches = [];
+                for (const session of candidates)
+                    if (Object.prototype.hasOwnProperty.call(statuses, session.id) ||
+                        (prompt !== undefined &&
+                            (await carriesPrompt(client, session.id, prompt, deadline))))
+                        matches.push(session);
                 if (!(await processRef(rootPid)))
                     return;
                 if (!(await openCodeEndpointOwnedBy(rootPid, serverUrl, deadline))) {
                     ownershipProven = false;
                     continue;
                 }
-                const matches = candidates.filter((session) => Object.prototype.hasOwnProperty.call(statuses, session.id));
                 if (matches.length > 1)
                     throw new Error("Multiple OpenCode sessions matched the launch endpoint, cwd, and creation window");
                 const match = matches[0];

package/dist/log.js

@@ -38,6 +38,16 @@ export const METADATA_RECORD_KEEP = [
     "mcp_warnings",
     "plugins",
 ];
+/**
+ * What an `error` becomes in metadata mode. An error is free text, and some of
+ * it is prompt-derived: a tmux error quotes the host's own output, and the
+ * window name is a slice of the prompt (#26). Free text cannot be allowlisted
+ * field by field the way a record is, so the only safe projection of the
+ * string is a constant. The key is kept rather than dropped so a metadata line
+ * still says a launch failed with an error, which an absent key would not;
+ * the text stays in the registry entry, which is not this log.
+ */
+export const ERROR_WITHHELD = "withheld (metadata-only log)";
 /**
  * `requester` is the one nested object passed through whole: the spec keeps the
  * tuple and its label, and a label is supplied by the receiver's own config,
@@ -79,12 +89,14 @@ export class LaunchLog {
             ? data
             : Object.fromEntries(Object.entries(data)
                 .filter(([k]) => !METADATA_DROP.includes(k))
-                .map(([k, v]) => isRecord(v) && !PASS_THROUGH.includes(k)
-                ? [
-                    k,
-                    Object.fromEntries(Object.entries(v).filter(([field]) => METADATA_RECORD_KEEP.includes(field))),
-                ]
-                : [k, v]));
+                .map(([k, v]) => k === "error" && v !== undefined
+                ? [k, ERROR_WITHHELD]
+                : isRecord(v) && !PASS_THROUGH.includes(k)
+                    ? [
+                        k,
+                        Object.fromEntries(Object.entries(v).filter(([field]) => METADATA_RECORD_KEEP.includes(field))),
+                    ]
+                    : [k, v]));
         const file = await open(path, "a", 0o600);
         try {
             await file.writeFile(JSON.stringify({ at: new Date().toISOString(), ...body }) + "\n");

package/dist/opencode-http.js

@@ -14,6 +14,12 @@ const sessionSchema = z.object({
         updated: z.number(),
     }),
 });
+// Only what identity needs: who wrote each message and its text parts. Every
+// other field, and every non-text part, passes through unread.
+const messageSchema = z.object({
+    info: z.object({ role: z.string() }).passthrough(),
+    parts: z.array(z.object({ type: z.string(), text: z.string().optional() }).passthrough()),
+});
 const statusSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("idle") }),
     z.object({ type: z.literal("busy") }),
@@ -125,6 +131,9 @@ export class OpenCodeHttp {
     session(id, deadline) {
         return this.requestJson("GET", `/session/${encodeURIComponent(id)}`, deadline, sessionSchema);
     }
+    messages(id, deadline) {
+        return this.requestJson("GET", `/session/${encodeURIComponent(id)}/message`, deadline, z.array(messageSchema));
+    }
     statuses(deadline) {
         return this.requestJson("GET", "/session/status", deadline, z.record(statusSchema));
     }

package/dist/providers.js

@@ -37,6 +37,30 @@ function models(definition) {
         ? Object.fromEntries(definition.models.map((id) => [id, {}]))
         : definition.models;
 }
+/**
+ * Refuses an OpenCode model whose provider muster declares but whose id that
+ * provider does not list (#52). OpenCode answers that launch with a bare
+ * "Unexpected server error", and nothing in it points at the missing entry.
+ *
+ * Only providers muster itself declares are checked. A built-in provider
+ * (anthropic, openai) or one from the user's own OpenCode configuration never
+ * appears here, and is OpenCode's to resolve: refusing it would break launches
+ * that work today. A model with no slash is likewise left for OpenCode.
+ */
+export function assertModelDeclared(model, config) {
+    const slash = model.indexOf("/");
+    if (slash <= 0)
+        return;
+    const provider = model.slice(0, slash);
+    const id = model.slice(slash + 1);
+    const definition = Object.hasOwn(config.opencode.provider, provider)
+        ? config.opencode.provider[provider]
+        : undefined;
+    if (definition === undefined || Object.hasOwn(models(definition), id))
+        return;
+    throw new Error(`model ${id} is not declared under [opencode.provider.${provider}.models]; ` +
+        `add [opencode.provider.${provider}.models.${JSON.stringify(id)}] to ~/.muster/config.toml`);
+}
 function apiKey(name, definition, source) {
     if (definition.api_key !== undefined)
         return definition.api_key;

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, resolveTitle, sanitiseTitle, resolveModel, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, resolveTerminal, runtimeArgs, } from "./guard.js";
+import { runSchema, agentBaseEnv, assertAllowedWorkspace, assertLevelExclusive, resolveLifecycle, resolveTitle, sanitiseTitle, resolveModel, assertMusterHomeProtectable, 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";
@@ -264,6 +264,10 @@ export class Muster {
         // Refused here, with the other checks that cost nothing to fail: an option
         // the runtime cannot honour must not leave a registry entry behind.
         assertOptionsSupported(req.runtime, req.options, permissions);
+        // A runtime that cannot be told to leave muster's home alone is not
+        // handed a cwd that contains it (#44). Refused here, before anything is
+        // reserved, like the other checks that cost nothing to fail.
+        assertMusterHomeProtectable(req.runtime, req.cwd, permissions, this.home);
         const enforcement = enforcementGrade(req.runtime, permissions);
         assertEnforcementMeetsMinimum(req.runtime, enforcement, policy);
         // Composed here, before any process of any kind is started — the version
@@ -281,7 +285,7 @@ export class Muster {
         if (req.runtime === "opencode")
             runtimeArgs(effective);
         else
-            argv = launchArgs(effective, this.config, [], undefined, this.sourceEnv);
+            argv = launchArgs(effective, this.config, [], undefined, this.sourceEnv, this.home);
         const driver = req.kind === "session"
             ? await selectHost(req.open ? "tmux" : requestedHost, this.drivers)
             : undefined;
@@ -475,7 +479,10 @@ export class Muster {
             // `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);
+            argv = launchArgs(effective, this.config, prepared.servers, bridgePath, runtimeEnv, 
+            // Muster's own home, not one derived from `runtimeEnv`: an identity
+            // launch may relocate the agent's HOME, but not where muster lives.
+            this.home);
         if (req.runtime === "codex") {
             codexPolicy = await codexPolicyArgs(runtimeEnv, req.cwd, deadline, prepared.servers, req.kind === "task");
             argv.splice(1, 0, ...codexPolicy);
@@ -662,7 +669,7 @@ export class Muster {
                         }
                     })
                     : req.runtime === "opencode"
-                        ? await resolveOpenCode(root.pid, entry.server_url, req.cwd, startedAt, deadline)
+                        ? await resolveOpenCode(root.pid, entry.server_url, req.cwd, startedAt, deadline, req.prompt)
                         : await resolveClaude(root.pid, resolveEnv, deadline);
                 if (identity) {
                     diagnostic =
@@ -942,6 +949,7 @@ export class Muster {
             exitPath,
             startPath,
             logHome: this.home,
+            logMode,
             launchId: entry.launchId,
             mcpConfigPath: entry.mcpConfigPath,
         }), { mode: 0o600 });

package/dist/task-worker.js

@@ -41,7 +41,7 @@ async function finish(code, signal, error) {
             exit_code: code,
             signal,
             error,
-        });
+        }, spec.logMode);
     }
     finally {
         try {

package/package.json

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