@brutalsystems/muster 1.1.0 → 1.2.0

package/README.md

@@ -59,7 +59,9 @@ models; behaviour against real ones is verified by hand and recorded in
 ## Quick start
 
 ```sh
-npm install -g @brutalsystems/muster
+# Allow the install scripts: muster's postinstall builds node-pty, and npm
+# skips install scripts by default — silently, so the pty host fails later.
+npm install -g --allow-scripts=@brutalsystems/muster,node-pty @brutalsystems/muster
 
 # A session: an agent you can reach, addressed once it is genuinely alive.
 muster run claude --prompt 'Review this project' --cwd . --level work

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,6 +1,6 @@
 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 { isAbsolute, join, relative, resolve } from "node:path";
 import { claudeConfigDir } from "./identity/claude.js";
@@ -33,6 +33,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_-]+$/)
@@ -241,11 +243,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 +279,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;
@@ -467,7 +497,13 @@ 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.
+                denyWrite: readonly ? writeRootSpellings(req.cwd) : [],
                 // 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 +540,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

@@ -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,31 @@ 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"),
+    ];
+}
 /**
  * One shell command line for `run-shell`.
  *
@@ -181,6 +206,7 @@ export class TmuxHost {
                 session,
                 "status",
                 this.status,
+                ...(opts.title ? titleOptions(session, opts.title) : []),
             ], opts.deadline);
             return parseWindowRow(output);
         }
@@ -202,6 +228,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/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/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, 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;
@@ -294,6 +298,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 +312,7 @@ export class Muster {
             model,
             driver,
             lifecycle,
+            title,
             argv,
         };
     }
@@ -373,7 +381,14 @@ export class Muster {
         const { req, identityName, identityMeta, credential, selectedMcp, agentBase, deadline, } = c;
         let entry = c.entry;
         const prepared = await prepareMcp(selectedMcp, mcpEnvironment(selectedMcp, agentBase, this.sourceEnv), req.cwd, deadline);
-        let runtimeEnv = mcpEnvironment(prepared.servers, agentBase, this.sourceEnv);
+        // PWD names the launch directory, not the caller's. The child is spawned
+        // in req.cwd, but an inherited PWD still names wherever muster was run
+        // from, and `opencode run` prefers PWD over its real cwd: its model's
+        // shell then ran in the caller's directory instead of --cwd.
+        let runtimeEnv = {
+            ...mcpEnvironment(prepared.servers, agentBase, this.sourceEnv),
+            PWD: req.cwd,
+        };
         entry = await this.registry.update(entry.launchId, prepared.summary);
         if (identityName && identityMeta) {
             // The launch id exists now, so the copy can be made and named after it.
@@ -494,7 +509,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");
@@ -510,6 +525,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);
@@ -587,7 +612,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)"
@@ -668,6 +693,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,
@@ -700,6 +726,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) {
@@ -746,7 +773,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({
@@ -830,6 +857,7 @@ export class Muster {
                 policy,
                 driver,
                 lifecycle,
+                title,
                 deadline,
             });
             if ("outcome" in started)
@@ -855,6 +883,7 @@ export class Muster {
                 permissions,
                 terminal,
                 lifecycle,
+                title,
                 startedAt,
                 deadline,
             });
@@ -1014,6 +1043,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/package.json

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