@brutalsystems/muster 0.7.9 → 0.7.11

package/README.md

@@ -180,6 +180,89 @@ OpenCode sessions otherwise use the same tmux/pty, viewer, list, stop, and human
 output behavior described above; OpenCode tasks use the same detached output
 and exit-status lifecycle as other tasks.
 
+## Repeating a launch request
+
+`--request-key KEY` (MCP: `requestKey`) names the launch *request*, not the
+session it produces. Sending the same key again returns the launch it already
+produced instead of starting a second agent:
+
+```sh
+muster run codex --prompt "Review the auth flow" --request-key review-auth-7f3a
+```
+
+A key is bound to the parameters it was first seen with — runtime, kind,
+resolved working directory, the instruction, the effective permissions, the
+selected MCP servers and plugins, and the model. Sending the same key with any
+of those changed is **refused**, rather than answered with a session that does
+something other than what was asked. Launching something genuinely different
+means using a different key.
+
+The fingerprint is computed here, after validation, rather than accepted from
+the caller: two machines canonicalize a path differently, and a fingerprint
+computed before validation would disagree with itself.
+
+What a repeat returns depends on what the first attempt did:
+
+| First attempt | A repeat gets |
+| --- | --- |
+| Reachable session or running task | That session or task, unchanged |
+| Still launching | Refused — ask for its status instead |
+| Failed, exited or stopped | Refused, naming the recorded outcome |
+| Outcome unknown | Refused, and told to inspect first (below) |
+
+A repeat never consumes launch capacity, including when the concurrency cap is
+full of the very launch being asked about. Omitting the key leaves behaviour
+exactly as it was: every request is its own launch.
+
+## When an outcome is unknown
+
+If Muster dies between starting a process and recording it, the entry says
+`unknown` rather than `failed`, and `muster list` reports it that way.
+
+The distinction is not cosmetic. `failed` means nothing is running and retrying
+is safe; `unknown` means a session may be running that Muster never got to
+record, and relaunching would be how a second agent appears in the same
+directory. A repeat under the same request key is refused for exactly that
+reason.
+
+Only the half of the window that provably never reached a spawn is still called
+`failed` — an owner that died before Muster marked itself about to start a
+process. Resolving an `unknown` entry is manual today: look for the session,
+stop it if it is there, and launch again under a new key.
+
+## Where a launch may run
+
+By default any directory the account can read is a legal target, which is the
+behaviour Muster has always had. Two config settings narrow it:
+
+```toml
+allowed_roots = ["/Users/you/Source"]
+
+[projects]
+muster = "/Users/you/Source/brutalsystems/muster"
+```
+
+With either configured, a launch outside all of them is refused. A configured
+project is a grant in its own right — naming a directory there permits it
+without also permitting its parent.
+
+```sh
+muster run codex --project muster --prompt "Review the auth flow"
+```
+
+`--project NAME` (MCP: `project`) is used instead of `--cwd`; naming both is an
+error rather than a precedence rule. A project name is also portable in a way an
+absolute path is not, since the same name can point somewhere different on
+another machine.
+
+The check resolves symlinks before comparing, so a link inside an allowed root
+that points elsewhere does not escape it, and compares path-relatively, so
+`/work/project-other` is not treated as part of `/work/project`.
+
+This constrains **where a session starts, not what it can then reach**. It is
+not a sandbox: a launched agent still has whatever access the OS account has.
+Permission modes and the sandbox settings below are the controls for that.
+
 ## Process ownership
 
 Muster identifies a launched process by its **pid paired with its start time**,

package/dist/config.js

@@ -11,6 +11,9 @@ export const configSchema = z
     host: z.enum(["auto", "tmux", "pty", "macos-terminal"]).default("auto"),
     launch_timeout_sec: z.number().finite().positive().max(600).default(30),
     max_concurrent: z.number().int().positive().max(1000).default(4),
+    allowed_roots: z.array(z.string().min(1)).default([]),
+    projects: z.record(z.string().regex(/^[a-zA-Z0-9_-]+$/), z.string().min(1))
+        .default({}),
     permissions: z.enum(["auto", "deny", "bypass"]).default("deny"),
     sandbox: z
         .enum([

package/dist/format.js

@@ -19,7 +19,7 @@ function recordHuman(record, color) {
     const paint = (value, code) => color ? `\u001b[${code}m${value}\u001b[0m` : value;
     const field = (label, value) => `  ${paint(label + ":", 90)} ${value}`;
     const badExit = typeof record.exit_code === "number" && record.exit_code !== 0;
-    const stateColor = record.state === "failed" || badExit
+    const stateColor = record.state === "failed" || record.state === "unknown" || badExit
         ? 31
         : ["idle", "running"].includes(record.state ?? "")
             ? 32

package/dist/guard.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
-import { resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
 import { mcpName, claudeMcpConfig } from "./mcp.js";
 import { pluginName } from "./plugins.js";
 export const runSchema = z
@@ -22,6 +24,11 @@ export const runSchema = z
     mcp: z.array(mcpName).optional(),
     plugin: z.array(pluginName).optional(),
     model: z.string().min(1).optional(),
+    project: z
+        .string()
+        .regex(/^[a-zA-Z0-9_-]+$/)
+        .optional(),
+    requestKey: z.string().min(1).max(200).optional(),
     args: z.array(z.string()).default([]),
 })
     .strict();
@@ -40,6 +47,71 @@ export function resolvePermissions(req, config) {
         throw new Error("--permissions bypass requires --sandbox full-access");
     return { permissions, sandbox };
 }
+/**
+ * Where a launch is allowed to run.
+ *
+ * Two properties do the work, and a prefix comparison has neither:
+ *
+ * - **Symlinks are resolved first.** A link inside an allowed root pointing
+ *   anywhere else would otherwise be a way out of the root, and the path as
+ *   written says nothing about where it lands.
+ * - **Containment is path-relative.** `/work/project-other` is not inside
+ *   `/work/project`, though it shares every character of it.
+ *
+ * Configured project paths are roots in their own right: naming a directory as
+ * a project is the grant.
+ *
+ * With nothing configured this permits anything the account can reach, which is
+ * the behaviour Muster has always had. That is a choice, and the README says so
+ * — it is not a safe default inherited by accident.
+ */
+export async function assertAllowedWorkspace(cwd, config) {
+    const roots = [...config.allowed_roots, ...Object.values(config.projects)];
+    if (!roots.length)
+        return;
+    const real = await realpath(cwd);
+    for (const root of roots) {
+        const resolved = await realpath(resolve(root)).catch(() => null);
+        if (!resolved)
+            continue;
+        const rel = relative(resolved, real);
+        if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+            return;
+    }
+    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.`);
+}
+/**
+ * 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
+ * session.
+ *
+ * Computed here, after validation and after defaults are resolved, rather than
+ * accepted from the caller: a sender and a receiver canonicalize a path
+ * differently (symlinks, /private, a different home directory), and a
+ * fingerprint computed before validation would disagree with itself across
+ * machines.
+ *
+ * Covers what changes *what gets launched*. Excludes anything cosmetic or
+ * derived at launch — timestamps, the key itself, pids, ports, tmux targets —
+ * because changing those should not make this a different request.
+ */
+export function paramsFingerprint(req, permissions, mcp, plugins) {
+    return createHash("sha256")
+        .update(JSON.stringify([
+        req.runtime,
+        req.kind,
+        req.cwd,
+        createHash("sha256").update(req.prompt).digest("hex"),
+        permissions.permissions,
+        permissions.sandbox,
+        [...mcp].sort(),
+        [...plugins].sort(),
+        req.model ?? null,
+        req.args,
+    ]))
+        .digest("hex");
+}
 export function runtimeArgs(req) {
     const result = [];
     const allowed = req.runtime === "claude"

package/dist/muster.js

@@ -17,7 +17,7 @@ const listSchema = z
 const idSchema = z.object({ id: z.string().min(1) }).strict();
 const { version } = createRequire(import.meta.url)("../package.json");
 const help = `Usage:
-  muster run <codex|claude|opencode> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [--terminal APP] [-- RUNTIME_OPTIONS]
+  muster run <codex|claude|opencode> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [--terminal APP] [--request-key KEY] [-- RUNTIME_OPTIONS]
   muster list [--kind session|task] [--format json|human]
   muster stop <id> [--format json|human]
   muster output <id>
@@ -37,6 +37,12 @@ which also admits any plugin the target repository ships.
 --model PROVIDER/MODEL selects the OpenCode model, overriding the configured
 [opencode] model. Providers defined under [opencode.provider] are supplied to
 the child, so launches do not depend on the user's own OpenCode config.
+--project NAME launches in a directory named under [projects] in config.toml,
+instead of --cwd; naming both is an error. When allowed_roots or [projects] are
+configured, a launch outside all of them is refused.
+--request-key KEY names the launch request itself. Sending the same key again
+returns the launch it already produced rather than starting a second one, and
+sending it with different parameters is refused rather than answered.
 run, list and stop default to JSON. output prints raw task text.
 
 doctor checks path-configured plugins against the packages they came from: a
@@ -126,6 +132,17 @@ async function main() {
                                 items: { type: "string", pattern: "^[a-zA-Z0-9_-]+$" },
                                 description: "Configured MCP server names. Omit for session defaults; [] disables all. Tasks have no defaults.",
                             },
+                            project: {
+                                type: "string",
+                                pattern: "^[a-zA-Z0-9_-]+$",
+                                description: "A project named in config.toml, used instead of cwd. Naming both is an error.",
+                            },
+                            requestKey: {
+                                type: "string",
+                                minLength: 1,
+                                maxLength: 200,
+                                description: "Caller-owned identity for this launch. Repeating it returns the launch it already produced instead of starting another; repeating it with different parameters is refused.",
+                            },
                             args: { type: "array", items: { type: "string" } },
                         },
                         required: ["runtime", "prompt"],
@@ -217,9 +234,13 @@ async function main() {
                 plugin: { type: "string", multiple: true },
                 model: { type: "string" },
                 "no-plugin": { type: "boolean" },
+                "request-key": { type: "string" },
+                project: { type: "string" },
             },
         });
-        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, ...values } = parsed;
+        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, ...values } = parsed;
+        if (requestKey !== undefined && command !== "run")
+            throw new Error("--request-key applies only to run");
         if (noMcp !== undefined && command !== "run")
             throw new Error("--no-mcp applies only to run");
         if (noMcp && values.mcp)
@@ -242,7 +263,12 @@ async function main() {
         if (command === "run") {
             const runtime = positionals[0];
             const args = positionals.slice(1);
-            const record = await muster.run({ runtime, ...values, args });
+            const record = await muster.run({
+                runtime,
+                ...values,
+                ...(requestKey === undefined ? {} : { requestKey }),
+                args,
+            });
             print(record);
             if (record.kind === "session" && record.host === "pty") {
                 process.stderr.write("[muster] pty: not watchable or attachable; this process owns the session. Ctrl-C stops it.\n");

package/dist/registry.js

@@ -2,6 +2,25 @@ import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { processRef, isSame, delay, } from "./identity/processes.js";
+/**
+ * A request key arrived again with different parameters. Distinct from a launch
+ * failure: nothing was attempted, and the caller reused a key it should have
+ * rotated.
+ */
+export class IdempotencyKeyReuse extends Error {
+    requestKey;
+    recorded;
+    offered;
+    constructor(requestKey, recorded, offered) {
+        super(`Request key ${requestKey} was recorded with different parameters ` +
+            `(recorded ${recorded.slice(0, 12)}, offered ${offered.slice(0, 12)}). ` +
+            `Use a new key to launch something different.`);
+        this.requestKey = requestKey;
+        this.recorded = recorded;
+        this.offered = offered;
+        this.name = "IdempotencyKeyReuse";
+    }
+}
 export class Registry {
     home;
     constructor(home) {
@@ -40,8 +59,23 @@ export class Registry {
                 if (entry.status === "starting" &&
                     !(await isSame(entry.owner)) &&
                     !entry.root) {
-                    entry.status = "failed";
-                    entry.error = "launch owner exited before recording process";
+                    // The owner died between reserving and recording a process. Whether
+                    // one exists depends on how far it got, and the entry cannot say —
+                    // so only the half that provably never reached a spawn is called
+                    // failed. The other half is unknown, which is not the same claim:
+                    // failed reads as safe to retry, and retrying a launch that did
+                    // happen is how a second agent appears in the same directory.
+                    if (entry.spawning) {
+                        entry.status = "unknown";
+                        entry.unknownSince ??= new Date().toISOString();
+                        entry.error =
+                            "launch owner exited after starting a process but before recording it; " +
+                                "a session may be running untracked";
+                    }
+                    else {
+                        entry.status = "failed";
+                        entry.error = "launch owner exited before recording process";
+                    }
                 }
                 if (["starting", "running"].includes(entry.status) &&
                     entry.root &&
@@ -65,11 +99,28 @@ export class Registry {
     async all() {
         return this.transaction(async (entries) => structuredClone(entries));
     }
-    async reserve(req, cap) {
+    /**
+     * The lookup runs inside the same transaction as the write, so the mkdir lock
+     * that already serializes reservations serializes deduplication too.
+     *
+     * Order is load-bearing: a match returns before the cap is consulted, because
+     * the entry it returns is already counted against the cap. Checking capacity
+     * first would reject a retry of a launch that succeeded, which reads as a
+     * failure and invites a third attempt.
+     */
+    async reserve(req, cap, idem) {
         const owner = await processRef(process.pid);
         if (!owner)
             throw new Error("Cannot identify Muster owner process");
         return this.transaction(async (entries) => {
+            if (idem) {
+                const prior = entries.find((e) => e.requestKey === idem.requestKey);
+                if (prior) {
+                    if (prior.paramsFingerprint !== idem.paramsFingerprint)
+                        throw new IdempotencyKeyReuse(idem.requestKey, prior.paramsFingerprint ?? "none", idem.paramsFingerprint);
+                    return { entry: structuredClone(prior), deduped: true };
+                }
+            }
             if (entries.filter((e) => e.status === "starting" || e.status === "running")
                 .length >= cap)
                 throw new Error(`Concurrency cap reached (${cap})`);
@@ -78,12 +129,13 @@ export class Registry {
                 ...req,
                 id,
                 launchId: id,
+                ...(idem ?? {}),
                 status: "starting",
                 createdAt: new Date().toISOString(),
                 owner,
             };
             entries.push(entry);
-            return { ...entry };
+            return { entry: { ...entry }, deduped: false };
         });
     }
     async update(id, patch) {

package/dist/run.js

@@ -1,10 +1,10 @@
 import { stat, readFile, writeFile, mkdir, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { 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, launchArgs, launchEnv, resolvePermissions, runtimeArgs, } from "./guard.js";
+import { runSchema, assertAllowedWorkspace, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, runtimeArgs, } from "./guard.js";
 import { Registry } from "./registry.js";
 import { LaunchLog } from "./log.js";
 import { hosts, selectHost } from "./hosts/index.js";
@@ -23,6 +23,20 @@ import { assertOpenCodeVersion, openCodeMcpNames, openCodeSessionLaunch, openCod
 import { assignNames, resolvePeer, runtimeName, } from "./naming.js";
 import { selectMcp, prepareMcp, mcpEnvironment } from "./mcp.js";
 import { selectPlugins } from "./plugins.js";
+function taskHandle(entry, pid) {
+    return {
+        kind: "task",
+        permissions: entry.permissions,
+        sandbox: entry.sandbox,
+        mcp: entry.mcp ?? [],
+        ...(entry.mcp_warnings ? { mcp_warnings: entry.mcp_warnings } : {}),
+        id: entry.id,
+        runtime: entry.runtime,
+        state: "running",
+        cwd: entry.cwd,
+        pid,
+    };
+}
 export class Muster {
     config;
     home;
@@ -55,9 +69,25 @@ export class Muster {
         return operation.finally(() => this.active.delete(operation));
     }
     async launch(input, requester) {
+        // Read before parsing, because cwd defaults during it and a default is then
+        // indistinguishable from a directory the caller asked for. Naming both a
+        // project and a directory is a contradiction worth reporting rather than
+        // resolving by precedence.
+        if (typeof input === "object" &&
+            input !== null &&
+            "project" in input &&
+            input.cwd !== undefined)
+            throw new Error("use project or cwd, not both");
         const req = runSchema.parse(input);
+        if (req.project) {
+            const configured = this.config.projects[req.project];
+            if (!configured)
+                throw new Error(`Unknown project ${req.project}. Configured: ${Object.keys(this.config.projects).join(", ") || "none"}`);
+            req.cwd = resolve(configured);
+        }
         if (!(await stat(req.cwd)).isDirectory())
             throw new Error("cwd is not a directory");
+        await assertAllowedWorkspace(req.cwd, this.config);
         if (req.kind === "task" && req.host)
             throw new Error("host applies only to session launches");
         if (req.terminal && !req.open)
@@ -86,7 +116,22 @@ export class Muster {
             await assertClaudePolicy(this.env);
         if (req.runtime === "opencode")
             await assertOpenCodeVersion(this.env, "1.18.31", Date.now() + 4000);
-        const reservation = await this.registry.reserve({ runtime: req.runtime, kind: req.kind, cwd: req.cwd, ...permissions }, this.config.max_concurrent);
+        const { entry: reservation, deduped } = await this.registry.reserve({ runtime: req.runtime, kind: req.kind, cwd: req.cwd, ...permissions }, this.config.max_concurrent, req.requestKey
+            ? {
+                requestKey: req.requestKey,
+                paramsFingerprint: paramsFingerprint(req, permissions, selectedMcp.map((s) => s.name), selectedPlugins.map((p) => p.name)),
+            }
+            : undefined);
+        if (deduped) {
+            await this.log.write({
+                event: "deduped",
+                launch_id: reservation.launchId,
+                request_key: req.requestKey,
+                status: reservation.status,
+                requester,
+            });
+            return this.recordedOutcome(reservation);
+        }
         this.owned.add(reservation.launchId);
         let entry = reservation;
         const startedAt = Date.now();
@@ -148,6 +193,9 @@ export class Muster {
             }
             if (this.closing)
                 throw new Error("Launch cancelled: Muster is closing");
+            // From here a process may exist without the registry knowing it. See the
+            // recovery branch in Registry.transaction.
+            entry = await this.registry.update(entry.launchId, { spawning: true });
             if (req.kind === "task")
                 return await this.startTask(entry, argv, runtimeEnv);
             const launched = await driver.launch({
@@ -305,6 +353,35 @@ export class Muster {
             await rpc?.close();
         }
     }
+    /**
+     * The answer to a request we have already seen. Never a new launch: a repeat
+     * of a request that succeeded must return what it produced, and a repeat of
+     * one that did not must report that rather than quietly trying again.
+     *
+     * A launch still in flight is refused rather than answered, because there is
+     * nothing yet to return and inventing a pending result would let a caller
+     * treat it as a session.
+     */
+    recordedOutcome(entry) {
+        const key = entry.requestKey;
+        if (entry.status === "starting")
+            throw new Error(`Request key ${key} is already launching (${entry.launchId}); ask for its status rather than launching again`);
+        if (entry.status === "unknown")
+            throw new Error(`Request key ${key} has an unknown outcome (${entry.launchId}): ${entry.error}. ` +
+                `Inspect before launching again — this is not a failure, and retrying it may leave two sessions`);
+        if (entry.status !== "running")
+            throw new Error(`Request key ${key} already resolved as ${entry.status}` +
+                (entry.error ? `: ${entry.error}` : "") +
+                `; use a different key to launch again`);
+        if (entry.kind === "task") {
+            if (!entry.root)
+                throw new Error(`Request key ${key} has no recorded task process`);
+            return taskHandle(entry, entry.root.pid);
+        }
+        if (!entry.peer)
+            throw new Error(`Request key ${key} has no recorded session`);
+        return entry.peer;
+    }
     async startTask(entry, argv, env) {
         const dir = join(this.home, "tasks", entry.id);
         await mkdir(dir, { recursive: true, mode: 0o700 });
@@ -342,18 +419,7 @@ export class Muster {
             });
             await writeFile(startPath, "start", { mode: 0o600 });
             child.unref();
-            const handle = {
-                kind: "task",
-                permissions: entry.permissions,
-                sandbox: entry.sandbox,
-                mcp: entry.mcp ?? [],
-                ...(entry.mcp_warnings ? { mcp_warnings: entry.mcp_warnings } : {}),
-                id: entry.id,
-                runtime: entry.runtime,
-                state: "running",
-                cwd: entry.cwd,
-                pid: root.pid,
-            };
+            const handle = taskHandle(entry, root.pid);
             await this.log.write({
                 event: "started",
                 launch_id: entry.launchId,

package/package.json

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