@brutalsystems/muster 0.7.10 → 0.7.11

package/README.md

@@ -208,11 +208,61 @@ What a repeat returns depends on what the first attempt did:
 | 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,6 +1,7 @@
 import { z } from "zod";
 import { createHash } from "node:crypto";
-import { resolve } from "node:path";
+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
@@ -23,6 +24,10 @@ 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([]),
 })
@@ -42,6 +47,40 @@ 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

package/dist/muster.js

@@ -37,6 +37,9 @@ 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.
@@ -129,6 +132,11 @@ 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,
@@ -227,6 +235,7 @@ async function main() {
                 model: { type: "string" },
                 "no-plugin": { type: "boolean" },
                 "request-key": { type: "string" },
+                project: { type: "string" },
             },
         });
         const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, ...values } = parsed;

package/dist/registry.js

@@ -59,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 &&

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, paramsFingerprint, 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";
@@ -69,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)
@@ -177,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({
@@ -347,6 +366,9 @@ export class Muster {
         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}` : "") +

package/package.json

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