@brutalsystems/muster 3.2.1 → 3.3.1

package/dist/agents.js

@@ -10,6 +10,13 @@ import { setCodexWorkspaceTrust, setWorkspaceTrust } from "./identity-copy.js";
  * neither list and is refused rather than quietly dropped.
  */
 export const MODEL_FLAGS = ["--model", "-m"];
+/**
+ * Claude's resume flags, consumed for the same reason as the model's: Muster
+ * validates them and delivers them once (`resolveResume`). `--fork-session` is
+ * the one consumed flag that takes no value.
+ */
+export const RESUME_FLAGS = ["--resume", "-r"];
+export const FORK_FLAG = "--fork-session";
 /**
  * One row per runtime. `Record<Runtime, …>` is the point: a fourth agent is a
  * compile error until every column is filled, where the scattered
@@ -21,7 +28,7 @@ export const AGENTS = {
         enforcement: "kernel",
         runtimeOptions: {
             forwarded: ["--effort", "--name"],
-            consumed: MODEL_FLAGS,
+            consumed: [...MODEL_FLAGS, ...RESUME_FLAGS, FORK_FLAG],
         },
         trustWorkspace: setWorkspaceTrust,
         beforeStop: null,

package/dist/cli-options.js

@@ -22,6 +22,8 @@ export const CLI_OPTIONS = {
     "no-mcp": { type: "boolean" },
     plugin: { type: "string", multiple: true },
     model: { type: "string" },
+    resume: { type: "string" },
+    "fork-session": { type: "boolean" },
     "idle-timeout": { type: "string" },
     ttl: { type: "string" },
     title: { type: "string" },

package/dist/guard.js

@@ -1,16 +1,16 @@
 import { z } from "zod";
 import { createHash } from "node:crypto";
-import { readFileSync, realpathSync } from "node:fs";
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, 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 { claudeConfigDir, claudeSessionsDir } from "./identity/claude.js";
 import { builtinTerminals } from "./hosts/types.js";
 import { mcpName } from "./mcp.js";
 import { claudeMcpConfig } from "./claude-policy.js";
 import { pluginName } from "./plugins.js";
-import { AGENTS, MODEL_FLAGS } from "./agents.js";
+import { AGENTS, FORK_FLAG, MODEL_FLAGS, RESUME_FLAGS } from "./agents.js";
 import { LAUNCH_OPTIONS } from "./options.js";
 import { RequesterConfigError } from "./requester-policy.js";
 import { parseDuration } from "./duration.js";
@@ -38,6 +38,10 @@ export const runSchema = z
     mcp: z.array(mcpName).optional(),
     plugin: z.array(pluginName).optional(),
     model: z.string().min(1).optional(),
+    /** A Claude session id to reopen instead of starting a new one. See `resolveResume`. */
+    resume: z.string().min(1).optional(),
+    /** With `resume`: continue it under a new session id, leaving the original untouched. */
+    forkSession: z.boolean().optional(),
     idleTimeout: z.string().min(1).optional(),
     ttl: z.string().min(1).optional(),
     /** The terminal title of a tmux session. See `resolveTitle`. */
@@ -364,6 +368,151 @@ function nameModel(req, config) {
         ? null
         : { model: configured, source: "config", origin: "config" };
 }
+/** What Claude prints as a session id, and the only thing `--resume` is given:
+ *  a bare `--resume` or a search term opens Claude's picker, which no muster
+ *  launch can answer. */
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * The session a launch reopens, from `--resume`/`--fork-session` or the same
+ * flags after `--` — consumed like a model, so the child's argv carries them
+ * once, from here. Claude only: Codex and OpenCode resume through different
+ * commands, which muster does not drive.
+ */
+export function resolveResume(req) {
+    const named = [];
+    let fork = req.forkSession === true;
+    for (let i = 0; i < req.args.length; i++) {
+        const arg = req.args[i], flag = normaliseFlag(arg);
+        if (flag === FORK_FLAG && !arg.includes("="))
+            fork = true;
+        if (!RESUME_FLAGS.includes(flag))
+            continue;
+        // Case-sensitive like the rest of the pass-through: `-R` is not `-r`.
+        if (!arg.startsWith("--") && arg.split("=")[0] !== flag)
+            continue;
+        const value = arg.includes("=")
+            ? arg.slice(arg.indexOf("=") + 1)
+            : req.args[i + 1];
+        if (!value || value.startsWith("-"))
+            throw new Error(`Missing value for ${arg}`);
+        named.push(value);
+    }
+    if (req.resume !== undefined)
+        named.unshift(req.resume);
+    if (named.length > 1)
+        throw new Error(`Session to resume named twice: ${named.join(" and ")}. Name it once.`);
+    const id = named[0];
+    if (id === undefined) {
+        if (fork)
+            throw new Error("--fork-session applies only with --resume");
+        return null;
+    }
+    if (req.runtime !== "claude")
+        throw new Error(`--resume is supported for claude only, not ${req.runtime}`);
+    if (!SESSION_ID.test(id))
+        throw new Error(`--resume takes a Claude session id (a UUID), not ${JSON.stringify(id)}`);
+    return { id: id.toLowerCase(), fork };
+}
+/**
+ * Refuses a resume Claude would fail on, or one that would put two processes
+ * on one conversation. Checked before anything is reserved or spawned.
+ *
+ * - The transcript must exist in the config dir the launch opens. Claude
+ *   reports a missing one only inside its terminal, where a muster launch
+ *   would wait out its whole identity deadline before saying so.
+ * - The session must not be running. Two Claude processes appending to one
+ *   transcript interleave it, and both would register the same session id, so
+ *   tincan and the ledger could not say which one a message reaches. A fork
+ *   only reads the original, so it may resume a live one.
+ */
+export function assertResumable(resume, env, cwd, alive = pidAlive) {
+    const configDir = claudeConfigDir(env);
+    const projects = join(configDir, "projects");
+    let transcript;
+    try {
+        transcript = readdirSync(projects)
+            .map((dir) => join(projects, dir, resume.id + ".jsonl"))
+            .find((file) => existsSync(file));
+    }
+    catch { }
+    if (!transcript)
+        throw new Error(`No Claude conversation ${resume.id} in ${configDir}; --resume reopens a session recorded in the profile this launch runs in`);
+    // Claude 2.1.302 resumes a conversation from any directory, so this is
+    // muster's to refuse (#10): the history would describe one tree while the
+    // agent works in another. Unknown when the transcript names no cwd.
+    const recorded = transcriptCwd(transcript);
+    if (recorded !== undefined && realPath(recorded) !== realPath(cwd))
+        throw new Error(`Claude session ${resume.id} was recorded in ${recorded}, not ${cwd}; resume it with --cwd ${recorded}`);
+    if (resume.fork)
+        return;
+    const sessions = claudeSessionsDir(env);
+    let files = [];
+    try {
+        files = readdirSync(sessions).filter((f) => /^\d+\.json$/.test(f));
+    }
+    catch { }
+    for (const file of files) {
+        let rec;
+        try {
+            rec = JSON.parse(readFileSync(join(sessions, file), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const pid = Number(file.slice(0, -5));
+        if (typeof rec.sessionId === "string" &&
+            rec.sessionId.toLowerCase() === resume.id &&
+            alive(pid))
+            throw new Error(`Claude session ${resume.id} is running (pid ${pid}); stop it before resuming it, or pass --fork-session to continue it under a new id`);
+    }
+}
+/** The first `cwd` a transcript records, read from its head: a transcript can
+ *  run to many megabytes, and the cwd is on its first message. */
+function transcriptCwd(file) {
+    let head = "";
+    try {
+        const fd = openSync(file, "r");
+        try {
+            const buf = Buffer.alloc(1 << 20);
+            head = buf.toString("utf8", 0, readSync(fd, buf, 0, buf.length, 0));
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    for (const line of head.split("\n")) {
+        if (!line.includes('"cwd"'))
+            continue;
+        try {
+            const { cwd } = JSON.parse(line);
+            if (typeof cwd === "string" && cwd)
+                return cwd;
+        }
+        catch { }
+    }
+    return undefined;
+}
+function realPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM: it exists and belongs to someone else, which is still running.
+        return e.code === "EPERM";
+    }
+}
 /**
  * Flag, then config; `off` disables at any level. Defaults to off.
  *
@@ -457,6 +606,12 @@ export function runtimeArgs(req) {
         const keep = !caseChanged && forwarded.includes(flag);
         if (caseChanged || (!keep && !consumed.includes(flag)))
             throw new Error(`Runtime option refused: ${arg}`);
+        // The one consumed switch: it takes no value, so there is none to step over.
+        if (flag === FORK_FLAG) {
+            if (arg.includes("="))
+                throw new Error(`${FORK_FLAG} takes no value`);
+            continue;
+        }
         if (arg.includes("=")) {
             if (keep) {
                 refuseWidening(flag, arg.slice(arg.indexOf("=") + 1));
@@ -582,7 +737,13 @@ musterHome = defaultMusterHome(env)) {
     // first, but `launchArgs` is exported and an input carrying both a model
     // conflict and a refused option must report the model conflict.
     const resolved = resolveModel(req, config);
-    const extra = runtimeArgs(req);
+    const resume = resolveResume(req);
+    const extra = [
+        ...runtimeArgs(req),
+        ...(resume
+            ? ["--resume", resume.id, ...(resume.fork ? [FORK_FLAG] : [])]
+            : []),
+    ];
     // OpenCode never reaches here — `run.ts` branches it to the OpenCode launch
     // builders, which carry the model in their config overlay.
     const model = resolved ? ["--model", resolved.model] : [];

package/dist/help.js

@@ -81,6 +81,14 @@ export const COMMANDS = [
                 "--model MODEL",
                 "model for the launch: a bare id for claude and codex, PROVIDER/MODEL for opencode",
             ],
+            [
+                "--resume SESSION_ID",
+                "claude only: reopen that session instead of starting a new one; the prompt is its next message (also accepted after --)",
+            ],
+            [
+                "--fork-session",
+                "with --resume: continue it under a new session id, leaving the original untouched",
+            ],
             [
                 "--idle-timeout DURATION",
                 "stop a tmux session after this much inactivity (off by default)",

package/dist/mcp-tools.js

@@ -89,6 +89,14 @@ export const MCP_TOOLS = [
                     minLength: 1,
                     description: "Model for the launch. A bare model id for claude and codex; PROVIDER/MODEL for opencode, where it overrides the configured [opencode] model. Recorded on the run and reported by `list`.",
                 },
+                resume: {
+                    type: "string",
+                    description: "Claude only: reopen this existing session (its UUID) instead of starting a new one; the prompt is its next message, and the run reports the same session id. Refused while that session is running, for a remote requester, and with an identity.",
+                },
+                forkSession: {
+                    type: "boolean",
+                    description: "With resume: continue the conversation under a new session id, leaving the original as it was. Allowed while the original is running.",
+                },
                 idleTimeout: {
                     type: "string",
                     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.",

package/dist/muster.js

@@ -206,7 +206,7 @@ async function main() {
             strict: true,
             options: CLI_OPTIONS,
         });
-        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, "idle-timeout": idleTimeout, socket, home: homeFlag, "stop-now": stopNow, "read-only": readOnly, "write-here": writeHere, unrestricted, "on-exit": onExit, timeout, ...values } = parsed;
+        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, "idle-timeout": idleTimeout, socket, home: homeFlag, "stop-now": stopNow, "read-only": readOnly, "write-here": writeHere, unrestricted, "on-exit": onExit, "fork-session": forkSession, timeout, ...values } = parsed;
         if (onExit !== undefined && command !== "run")
             throw new Error("--on-exit applies only to run");
         if (timeout !== undefined && command !== "wait")
@@ -234,6 +234,8 @@ async function main() {
             ["--idle-timeout", idleTimeout],
             ["--ttl", values.ttl],
             ["--title", values.title],
+            ["--resume", values.resume],
+            ["--fork-session", forkSession],
         ])
             if (value !== undefined && command !== "run")
                 throw new Error(`${name} applies only to run`);
@@ -281,6 +283,7 @@ async function main() {
                     ...values,
                     ...(requestKey === undefined ? {} : { requestKey }),
                     ...(idleTimeout === undefined ? {} : { idleTimeout }),
+                    ...(forkSession === undefined ? {} : { forkSession }),
                     args,
                 });
             }

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, assertMusterHomeProtectable, 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, resolveResume, assertResumable, } from "./guard.js";
 import { enforcementGrade } from "./enforcement.js";
 import { LOCAL } from "./requester.js";
 import { assertEnforcementMeetsMinimum, assertLevelWithinCeiling, assertMayAct, resolveIdentityForRequest, resolveRequesterPolicy, RequesterPolicyRefusal, } from "./requester-policy.js";
@@ -802,6 +802,15 @@ export class Muster {
                         ? await resolveOpenCode(root.pid, entry.server_url, req.cwd, startedAt, deadline, req.prompt)
                         : await resolveClaude(root.pid, resolveEnv, deadline);
                 if (identity) {
+                    // The answer #10 asks for: a resume that registered some other
+                    // session is a launch that failed, never a new session reported as
+                    // the old one. Not fatal at once, like every other diagnosis here,
+                    // in case the registry is read mid-write.
+                    const resume = req.runtime === "claude" ? resolveResume(req) : null;
+                    if (resume && (identity.id === resume.id) === resume.fork)
+                        throw new Error(resume.fork
+                            ? `--fork-session registered the original session ${resume.id} instead of a new one`
+                            : `Claude registered session ${identity.id} instead of resuming ${resume.id}`);
                     diagnostic =
                         req.runtime === "codex"
                             ? "thread id reserved but no rollout"
@@ -911,6 +920,20 @@ export class Muster {
         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, title, argv: plannedArgv, } = await this.plan(req, policy, requester, level);
+        // Before anything is reserved, like the refusals in `plan`. A remote
+        // requester is refused because a resumed session carries the whole of
+        // that conversation, and the profile holds every conversation its owner
+        // has had: being allowed to launch is not being allowed to read those.
+        // An identity launch runs in a fresh copy of the config dir, which holds
+        // none of them, so it could only fail.
+        const resume = resolveResume(effective);
+        if (resume) {
+            if (requester.kind !== "local")
+                throw new Error("--resume is available to a local requester only");
+            if (identityName)
+                throw new Error("--resume cannot be combined with an identity: the identity's config dir holds none of this profile's conversations");
+            assertResumable(resume, agentBase, effective.cwd);
+        }
         let argv = plannedArgv;
         let codexPolicy = [];
         const reserved = await this.reserveLaunch({

package/package.json

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