@brutalsystems/muster 1.1.1 → 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/config.js

@@ -58,6 +58,12 @@ const sessionSectionSchema = z
     .object({
     idle_timeout: z.string().min(1).optional(),
     ttl: z.string().min(1).optional(),
+    /**
+     * Show the agent's own terminal title instead of muster's. Off by default:
+     * Claude Code retitles constantly with a status glyph and topic, which
+     * replaces the name `list` and `stop` accept.
+     */
+    title_from_agent: z.boolean().default(false),
 })
     .strict()
     .default({});

package/dist/format.js

@@ -38,6 +38,9 @@ function recordHuman(record, color) {
     const id = record.id ?? record.thread_id ?? record.session_id;
     if (record.stopped === true)
         return `${paint("Stopped", 90)} ${clean(id)}.`;
+    // `muster title` answers with the id and the title alone, no kind.
+    if (record.kind === undefined && record.title !== undefined)
+        return `Titled ${clean(id)}: ${clean(record.title)}.`;
     const lines = [
         `${clean(record.runtime)} · ${clean(record.kind)} · ${paint(clean(record.state), stateColor)}`,
         field("ID", clean(id)),
@@ -46,6 +49,8 @@ function recordHuman(record, color) {
         lines.push(field("Address", clean(record.canonical_id)));
     if (record.runtime === "opencode" && record.server_url)
         lines.push(field("Control URL", clean(record.server_url)));
+    if (record.title)
+        lines.push(field("Title", clean(record.title)));
     lines.push(field("Directory", clean(record.cwd)));
     if (record.identity)
         lines.push(field("Identity", clean(record.identity)));

package/dist/guard.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+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"]),
@@ -33,6 +36,8 @@ export const runSchema = z
     model: z.string().min(1).optional(),
     idleTimeout: z.string().min(1).optional(),
     ttl: z.string().min(1).optional(),
+    /** The terminal title of a tmux session. See `resolveTitle`. */
+    title: z.string().optional(),
     project: z
         .string()
         .regex(/^[a-zA-Z0-9_-]+$/)
@@ -132,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
@@ -220,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.`);
@@ -241,11 +331,8 @@ export function resolveModel(req, config) {
         ? null
         : { model: configured, source: "config", origin: "config" };
 }
-/** 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;
 /**
- * Flag, then config, then the built-in default; `off` disables at any level.
+ * Flag, then config; `off` disables at any level. Defaults to off.
  *
  * Only a tmux session can honour a lifecycle: pty and macos-terminal die with
  * their parent and a task is not a session at all. An explicit request there is
@@ -280,10 +367,41 @@ export function resolveLifecycle(req, config, reapable) {
         return chosen === "off" ? null : chosen;
     };
     return {
-        idleTimeout: one(req.idleTimeout, config.session.idle_timeout, "--idle-timeout", "[session] idle_timeout", DEFAULT_IDLE_TIMEOUT),
+        idleTimeout: one(req.idleTimeout, config.session.idle_timeout, "--idle-timeout", "[session] idle_timeout", null),
         ttl: one(req.ttl, config.session.ttl, "--ttl", "[session] ttl", null),
     };
 }
+/** Longer than any tab shows, short enough that a pasted prompt is not a title. */
+const TITLE_MAX = 100;
+/**
+ * A title reaches the outer terminal inside an OSC escape that tmux writes, so a
+ * control character in it is not cosmetic: ESC or BEL ends that sequence and
+ * whatever follows is read by the terminal as a command of its own. C0, DEL and
+ * C1 all go, and what is left must still say something.
+ */
+export function sanitiseTitle(raw) {
+    const text = raw
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, "")
+        .trim()
+        .slice(0, TITLE_MAX)
+        .trim();
+    if (!text)
+        throw new Error("--title must contain printable text");
+    return text;
+}
+/**
+ * The launch's explicit title, or undefined when the launch should be titled by
+ * default once its name is known. Refused where nothing will carry it, on the
+ * same terms as `resolveLifecycle`: only a tmux session has a window muster
+ * owns, and `titleable` comes from the selected driver, not from `req.host`.
+ */
+export function resolveTitle(req, titleable) {
+    if (req.title === undefined)
+        return undefined;
+    if (!titleable)
+        throw new Error(`--title applies to tmux sessions; this launch is ${req.kind === "task" ? "a task" : `hosted on ${req.host ?? "the configured host"}`}`);
+    return sanitiseTitle(req.title);
+}
 export function runtimeArgs(req) {
     const result = [];
     const { forwarded, consumed } = AGENTS[req.runtime].runtimeOptions;
@@ -392,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
@@ -414,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"
@@ -456,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: [],
@@ -467,7 +605,16 @@ export function launchArgs(req, config, mcp = [], bridgePath, env = process.env)
             allowUnsandboxedCommands: false,
             excludedCommands: [],
             filesystem: {
-                denyWrite: readonly ? ["/"] : [],
+                // The cwd is the sandbox's only default write root, so denying it
+                // is the whole of read-only. Not "/": that also denies Claude Code's
+                // own temp dir, which it writes after every Bash call, so every
+                // 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.
+                // 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).
@@ -504,6 +651,17 @@ export function launchArgs(req, config, mcp = [], bridgePath, env = process.env)
         req.prompt,
     ];
 }
+/** A path as given and as resolved, once each. An unresolvable path (it does
+ *  not exist yet) is denied as given — nothing can be written through a
+ *  missing directory anyway. */
+function writeRootSpellings(path) {
+    let real = path;
+    try {
+        real = realpathSync(path);
+    }
+    catch { }
+    return [...new Set([path, real])];
+}
 export function launchEnv(env) {
     const blocked = /^(CLAUDECODE|CLAUDE_CODE_|CODEX_THREAD_ID$|TMUX$|TMUX_PANE$|MCP_)/;
     return Object.fromEntries(Object.entries(env).filter(([k, v]) => typeof v === "string" && !blocked.test(k)));

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"],
@@ -71,12 +71,16 @@ export const COMMANDS = [
             ],
             [
                 "--idle-timeout DURATION",
-                "stop a tmux session after this much inactivity; 30m by default, off to disable",
+                "stop a tmux session after this much inactivity (off by default)",
             ],
             [
                 "--ttl DURATION",
                 "stop a tmux session this long after launch, whatever its state",
             ],
+            [
+                "--title TEXT",
+                "the terminal title of a tmux session; defaults to its name and runtime",
+            ],
             [
                 "--request-key KEY",
                 "name the request; sending it again returns the same launch",
@@ -121,6 +125,16 @@ export const COMMANDS = [
         notes: ["Prints raw text; --format does not apply."],
         examples: ["muster output 6fae755b-8f5d-4425-8ed7-69e84bfac8c5"],
     },
+    {
+        name: "title",
+        summary: "retitle a running tmux session",
+        synopsis: "muster title <id> TEXT [--format json|human]",
+        options: [["--format FORMAT", "json (default) or human"]],
+        notes: [
+            "Sets the title any attached terminal shows, without involving the agent. Refused for tasks, pty sessions and ended sessions.",
+        ],
+        examples: ["muster title simple-cms-46 'reviewing #48'"],
+    },
     {
         name: "identities",
         summary: "show configured identities",

package/dist/hosts/tmux.js

@@ -57,6 +57,68 @@ export function parseWindowList(output) {
         label: label.join(FIELD),
     }));
 }
+/**
+ * Where muster keeps a session's title. A user option, not the pane title
+ * (`#T`): an agent's OSC 0/2 rewrites `#T` whatever `allow-rename` says — that
+ * option governs only the window name — so a title muster set there would last
+ * until Claude Code's first status update. The pane title is left to the agent,
+ * which is what `fromAgent` shows instead.
+ */
+export const TITLE_OPTION = "@muster_title";
+/** `;`-joined `set-option` commands for `new-session`'s command list, so the
+ *  title is in place before any client can attach and see a blank one. */
+export function titleOptions(session, title) {
+    const set = (name, value) => [
+        ";",
+        "set-option",
+        "-t",
+        session,
+        name,
+        value,
+    ];
+    return [
+        ...set(TITLE_OPTION, title.text),
+        ...set("set-titles-string", title.fromAgent ? "#T" : `#{${TITLE_OPTION}}`),
+        ...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`.
  *
@@ -171,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,
@@ -181,6 +244,7 @@ export class TmuxHost {
                 session,
                 "status",
                 this.status,
+                ...(opts.title ? titleOptions(session, opts.title) : []),
             ], opts.deadline);
             return parseWindowRow(output);
         }
@@ -202,6 +266,12 @@ export class TmuxHost {
             throw e;
         }
     }
+    /** Session options accept a window id as their target, so the hostRef the
+     *  registry already holds is enough. The value is passed as one argv element
+     *  and tmux stores it verbatim: a leading `-` or a `#{...}` stays text. */
+    async setTitle(hostRef, text) {
+        await this.call(["set-option", "-t", hostRef, TITLE_OPTION, text]);
+    }
     async list() {
         try {
             return parseWindowList(await this.call(["list-windows", "-a", "-F", LIST_FORMAT]));

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/mcp-tools.js

@@ -1,5 +1,5 @@
 /**
- * The `run`, `list`, `stop` and `output` tools exactly as the MCP server
+ * The `run`, `list`, `stop`, `output` and `title` tools exactly as the MCP server
  * advertises them.
  *
  * Extracted from `src/muster.ts` so it can be ASSERTED against `runSchema`
@@ -92,12 +92,16 @@ export const MCP_TOOLS = [
                 },
                 idleTimeout: {
                     type: "string",
-                    description: "Stop this tmux session after the given inactivity, as 90s/30m/4h, or 'off'. Defaults to 30m. Refused for tasks and for pty or macos-terminal hosts, which do not outlive their parent.",
+                    description: "Stop this tmux session after the given inactivity, as 90s/30m/4h, or 'off'. Off by default. Refused for tasks and for pty or macos-terminal hosts, which do not outlive their parent.",
                 },
                 ttl: {
                     type: "string",
                     description: "Stop this tmux session the given duration after launch regardless of activity, as 90s/30m/4h, or 'off'. Off by default.",
                 },
+                title: {
+                    type: "string",
+                    description: "Terminal title for this tmux session, shown by any terminal attached to it. Defaults to the session's name and runtime once it is reachable; the agent's own title is shown instead only with [session] title_from_agent. Control characters are stripped and it is capped at 100 characters. Refused for tasks and for pty or macos-terminal hosts.",
+                },
                 identity: {
                     type: "string",
                     pattern: "^[a-zA-Z0-9_-]+$",
@@ -138,6 +142,19 @@ export const MCP_TOOLS = [
             additionalProperties: false,
         },
     },
+    {
+        name: "title",
+        description: "Retitle a running tmux session by durable id or unambiguous peer name, from outside its agent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", minLength: 1 },
+                title: { type: "string", minLength: 1 },
+            },
+            required: ["id", "title"],
+            additionalProperties: false,
+        },
+    },
 ];
 /**
  * runSchema keys deliberately absent from the advertised `run` inputSchema.

package/dist/muster.js

@@ -20,6 +20,9 @@ const listSchema = z
     .object({ kind: z.enum(["session", "task"]).optional() })
     .strict();
 const idSchema = z.object({ id: z.string().min(1) }).strict();
+const titleSchema = z
+    .object({ id: z.string().min(1), title: z.string().min(1) })
+    .strict();
 const { version } = createRequire(import.meta.url)("../package.json");
 const text = (value) => ({
     content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
@@ -125,6 +128,10 @@ async function main() {
                         return text(await muster.stop(idSchema.parse(args).id));
                     case "output":
                         return text(await muster.output(idSchema.parse(args).id));
+                    case "title": {
+                        const { id, title } = titleSchema.parse(args);
+                        return text(await muster.title(id, title));
+                    }
                     default:
                         throw new Error(`Unknown tool ${params.name}`);
                 }
@@ -175,6 +182,7 @@ async function main() {
                 model: { type: "string" },
                 "idle-timeout": { type: "string" },
                 ttl: { type: "string" },
+                title: { type: "string" },
                 socket: { type: "string" },
                 home: { type: "string" },
                 "stop-now": { type: "boolean" },
@@ -194,6 +202,7 @@ async function main() {
         for (const [name, value] of [
             ["--idle-timeout", idleTimeout],
             ["--ttl", values.ttl],
+            ["--title", values.title],
         ])
             if (value !== undefined && command !== "run")
                 throw new Error(`${name} applies only to run`);
@@ -336,6 +345,14 @@ async function main() {
             else
                 process.stdout.write(await muster.output(id));
         }
+        else if (command === "title") {
+            // Positional rather than --title: the flag names a launch's title, and
+            // reusing it here would make `muster title --title x <id>` a spelling.
+            if (positionals.length !== 2 || Object.keys(values).length)
+                throw new Error("title requires an id and the title text");
+            const { id } = idSchema.parse({ id: positionals[0] });
+            print(await muster.title(id, positionals[1]));
+        }
         else if (command === "reap-check") {
             // Hidden: armed by muster itself as a tmux job, never typed by a person.
             // NOTE: `Muster.create()` above already ran against the REAL home before

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

@@ -1,10 +1,10 @@
 import { stat, readFile, writeFile, mkdir, rm, } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 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, 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";
@@ -69,6 +69,10 @@ function taskHandle(entry, pid) {
 function configHomeVar(runtime) {
     return AGENTS[runtime].configHomeVar ?? undefined;
 }
+/** What a window shows before readiness names the session: never the prompt. */
+function provisionalTitle(req) {
+    return sanitiseTitle(`${basename(req.cwd)} · ${req.runtime}`);
+}
 export class Muster {
     config;
     home;
@@ -260,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
@@ -277,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;
@@ -294,6 +302,9 @@ export class Muster {
         // Deciding from `req.host` accepts --idle-timeout under `host = "pty"` in
         // config and then never arms it.
         const lifecycle = resolveLifecycle(effective, this.config, req.kind === "session" && typeof driver?.schedule === "function");
+        // Beside the lifecycle and for the same reason: only the selected driver
+        // knows whether there will be a window to title.
+        const title = resolveTitle(effective, req.kind === "session" && typeof driver?.setTitle === "function");
         return {
             effective,
             terminal,
@@ -305,6 +316,7 @@ export class Muster {
             model,
             driver,
             lifecycle,
+            title,
             argv,
         };
     }
@@ -467,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);
@@ -501,7 +516,7 @@ export class Muster {
      * readiness.
      */
     async startProcess(c) {
-        const { req, argv, runtimeEnv, policy, driver, lifecycle, deadline } = c;
+        const { req, argv, runtimeEnv, policy, driver, lifecycle, title, deadline, } = c;
         let entry = c.entry;
         if (this.closing)
             throw new Error("Launch cancelled: Muster is closing");
@@ -517,6 +532,16 @@ export class Muster {
             cwd: req.cwd,
             env: runtimeEnv,
             label: req.prompt.slice(0, 48),
+            // Provisional until readiness names the session, unless the caller named
+            // it: the window must never show a prompt fragment as its title.
+            ...(driver.setTitle
+                ? {
+                    title: {
+                        text: title ?? provisionalTitle(req),
+                        fromAgent: this.config.session.title_from_agent,
+                    },
+                }
+                : {}),
             deadline,
         });
         const root = await processRef(launched.pid);
@@ -594,7 +619,7 @@ export class Muster {
      * `finally` has to close it even when this throws.
      */
     async awaitReadiness(c) {
-        const { req, root, launched, driver, policy, requester, resolveEnv, rpc, enforcement, prepared, identityName, model, permissions, terminal, lifecycle, startedAt, deadline, } = c;
+        const { req, root, launched, driver, policy, requester, resolveEnv, rpc, enforcement, prepared, identityName, model, permissions, terminal, lifecycle, title, startedAt, deadline, } = c;
         let entry = c.entry;
         let diagnostic = req.runtime === "claude"
             ? "no Claude session registry found (check terminal for workspace trust or login prompts)"
@@ -644,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 =
@@ -675,6 +700,7 @@ export class Muster {
                     const named = assignNames([
                         { runtime, uuid: identity.id, rawName: metadata.rawName },
                     ])[0];
+                    const shownTitle = await this.nameTitle(driver, launched.hostRef, title, `${named.display} · ${req.runtime}`, provisionalTitle(req));
                     const peer = {
                         kind: "session",
                         ...permissions,
@@ -707,6 +733,7 @@ export class Muster {
                             ? { idle_timeout: lifecycle.idleTimeout }
                             : {}),
                         ...(lifecycle.ttl ? { ttl: lifecycle.ttl } : {}),
+                        ...(shownTitle ? { title: shownTitle } : {}),
                         attach_hint: driver.attachHint(launched.hostRef),
                     };
                     if (req.open) {
@@ -753,7 +780,7 @@ export class Muster {
     async launch(input, requester) {
         const { req, policy, level } = await this.authorize(input, requester);
         const { identityName, identityMeta, credential } = await this.resolveIdentity(req, policy);
-        const { effective, terminal, permissions, enforcement, agentBase, selectedMcp, selectedPlugins, model, driver, lifecycle, argv: plannedArgv, } = await this.plan(req, policy, requester, level);
+        const { effective, terminal, permissions, enforcement, agentBase, selectedMcp, selectedPlugins, model, driver, lifecycle, title, argv: plannedArgv, } = await this.plan(req, policy, requester, level);
         let argv = plannedArgv;
         let codexPolicy = [];
         const reserved = await this.reserveLaunch({
@@ -837,6 +864,7 @@ export class Muster {
                 policy,
                 driver,
                 lifecycle,
+                title,
                 deadline,
             });
             if ("outcome" in started)
@@ -862,6 +890,7 @@ export class Muster {
                 permissions,
                 terminal,
                 lifecycle,
+                title,
                 startedAt,
                 deadline,
             });
@@ -920,6 +949,7 @@ export class Muster {
             exitPath,
             startPath,
             logHome: this.home,
+            logMode,
             launchId: entry.launchId,
             mcpConfigPath: entry.mcpConfigPath,
         }), { mode: 0o600 });
@@ -1021,6 +1051,42 @@ export class Muster {
             throw new Error(`${result.reason}: ${result.candidates.join(", ")}`);
         return peers[named.indexOf(result.peer)];
     }
+    /**
+     * The title a ready session ends up showing. A caller's own title was set at
+     * launch and stays; otherwise the provisional one is replaced with the name
+     * `list` and `stop` accept, which only exists once the agent has registered.
+     * A retitle that fails does not fail the launch — the session is up — but the
+     * record then reports the provisional title, because that is what is shown.
+     */
+    async nameTitle(driver, hostRef, explicit, named, provisional) {
+        if (!driver?.setTitle)
+            return undefined;
+        if (explicit !== undefined)
+            return explicit;
+        const text = sanitiseTitle(named);
+        return driver.setTitle(hostRef, text).then(() => text, () => provisional);
+    }
+    /** Retitle a running tmux session from outside its agent. */
+    async title(id, raw, requester = LOCAL) {
+        const entry = await this.find(id);
+        assertMayAct(entry, requester);
+        const driver = this.drivers.find((d) => d.id === entry.host);
+        const refusal = entry.kind !== "session"
+            ? "this is a task"
+            : entry.status !== "running"
+                ? `this session is ${entry.status}`
+                : !driver?.setTitle || !entry.hostRef || !entry.peer
+                    ? `this session is hosted on ${entry.host ?? "no host"}`
+                    : undefined;
+        if (refusal)
+            throw new Error(`title applies to a running tmux session; ${refusal}`);
+        const text = sanitiseTitle(raw);
+        await driver.setTitle(entry.hostRef, text);
+        await this.registry.update(entry.launchId, {
+            peer: { ...entry.peer, title: text },
+        });
+        return { id: entry.id, title: text };
+    }
     async stop(id, requester = LOCAL) {
         const entry = await this.find(id);
         assertMayAct(entry, requester);

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.1.1",
+  "version": "1.2.1",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {