@brutalsystems/muster 0.7.10 → 0.7.12

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**,
@@ -239,10 +289,22 @@ reader who does not know why they are there:
   session that ended while Muster was not running is reported as ended rather
   than as running.
 
-Process-tree membership is derived from the parent chain, which has a known
-limit: a child reparented after its own parent exits leaves the chain and cannot
-be recovered from it. Tracking that needs a membership signal the chain does not
-carry.
+Process-tree membership uses two signals, because neither is sufficient alone.
+The parent chain is exact while it holds, and stops holding the moment an
+intermediate process exits — its children reparent to launchd and are no longer
+reachable from the root, though they are still doing the session's work. The
+process group survives that, since reparenting changes no process's group.
+
+Muster records the group the launched root leads and takes the union. A stop
+reaches reparented workers, and a session whose root has died but whose group is
+still busy is reported as running rather than ended.
+
+Only a group the root *leads* is used. A process that merely belongs to someone
+else's group shares it with whatever else is there — a shell, a tmux pane, the
+terminal — and treating that as membership would reach far outside the session.
+Both terminal hosts start their root in a new session, so in practice it does
+lead its own group. A process that calls `setsid()` for itself still escapes;
+nothing on macOS prevents that.
 
 ## Configuration and permissions
 

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/identity/processes.js

@@ -16,8 +16,8 @@
  *    on every transaction, so a process that died while Muster was not running
  *    is reported as dead rather than trusted from what was recorded.
  *
- * Membership is derived from the parent chain and inherits its one real limit:
- * a reparented child is unreachable from the root. See issue #24.
+ * Membership is the union of the parent chain and the process group the root
+ * leads, because a reparented child leaves the chain but keeps its group.
  */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -41,8 +41,41 @@ export async function processRef(pid) {
 export async function isSame(ref) {
     return (await processRef(ref.pid))?.start === ref.start;
 }
-export async function descendants(root, deadline = Date.now() + 1000) {
-    const rows = (await command("ps", ["-axo", "pid=,ppid="], Math.max(1, Math.min(1000, deadline - Date.now()))))
+/**
+ * The process group a pid leads, or undefined if it leads none.
+ *
+ * Only a leader's group is safe to treat as membership: the group then exists
+ * because this process was started, so everything in it descends from that
+ * start. A process that merely belongs to someone else's group shares it with
+ * whatever else is there — a shell, a tmux pane, the terminal — and sweeping
+ * that would reach far outside the session.
+ *
+ * Both terminal hosts start their root in a new session, so in practice the
+ * launched root does lead its own group.
+ */
+export async function ownedGroup(pid) {
+    try {
+        const pgid = Number((await command("ps", ["-p", String(pid), "-o", "pgid="])).trim());
+        return pgid === pid ? pgid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Membership by two signals, because neither is sufficient alone.
+ *
+ * The parent chain is exact while it holds, and it stops holding the moment an
+ * intermediate process exits: the children reparent to launchd and are no
+ * longer reachable from the root, though they are still running the session's
+ * work. The process group survives that — reparenting changes no pid's group —
+ * but is only meaningful for a group the root leads, and is escapable by a
+ * process that calls setsid() for itself.
+ *
+ * So: union them. What the chain loses to reparenting, the group usually keeps.
+ */
+export async function descendants(root, deadline = Date.now() + 1000, group) {
+    const rows = (await command("ps", ["-axo", "pid=,ppid=,pgid="], Math.max(1, Math.min(1000, deadline - Date.now()))))
         .split("\n")
         .map((l) => l.trim().split(/\s+/).map(Number));
     const found = new Set([root]);
@@ -54,10 +87,26 @@ export async function descendants(root, deadline = Date.now() + 1000) {
                 changed = true;
             }
     }
+    if (group)
+        for (const [pid, , pgid] of rows)
+            if (pid && pid > 1 && pgid === group)
+                found.add(pid);
     return [...found];
 }
-async function liveTree(root) {
-    return (await Promise.all((await descendants(root)).map(processRef))).filter((r) => !!r);
+/** Whether anything still runs in a group we started. */
+export async function groupAlive(group, deadline = Date.now() + 1000) {
+    try {
+        const rows = (await command("ps", ["-axo", "pid=,pgid="], Math.max(1, Math.min(1000, deadline - Date.now()))))
+            .split("\n")
+            .map((l) => l.trim().split(/\s+/).map(Number));
+        return rows.some(([pid, pgid]) => pid && pid > 1 && pgid === group);
+    }
+    catch {
+        return false;
+    }
+}
+async function liveTree(root, group) {
+    return (await Promise.all((await descendants(root, Date.now() + 1000, group)).map(processRef))).filter((r) => !!r);
 }
 function signal(ref, name) {
     try {
@@ -74,11 +123,10 @@ function signal(ref, name) {
  * every signal, because a pid that exits between discovery and the signal may
  * already belong to something else.
  *
- * Reparented descendants are a separate gap: once an intermediate process dies,
- * its children leave the parent chain entirely and no re-read will find them.
- * That needs a membership signal the chain does not provide (see issue #24).
+ * Reparented descendants are reachable only through the process group, so pass
+ * one when the caller has recorded it; the parent chain alone cannot see them.
  */
-export async function stopTree(ref) {
+export async function stopTree(ref, group) {
     if (!(await isSame(ref)))
         return;
     const known = new Map();
@@ -94,12 +142,12 @@ export async function stopTree(ref) {
         return added;
     };
     const deepestFirst = () => [...known.values()].reverse();
-    remember(await liveTree(ref.pid));
+    remember(await liveTree(ref.pid, group));
     for (const r of deepestFirst())
         if (await isSame(r))
             signal(r, "SIGTERM");
     await delay(150);
-    const late = (await isSame(ref)) ? remember(await liveTree(ref.pid)) : [];
+    const late = remember((await isSame(ref)) || group ? await liveTree(ref.pid, group) : []);
     if (late.length) {
         for (const r of late.reverse())
             if (await isSame(r))

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

@@ -1,7 +1,7 @@
 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";
+import { processRef, isSame, delay, groupAlive, } 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
@@ -59,13 +59,32 @@ 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 &&
                     !(await isSame(entry.root))) {
-                    if (!(await Promise.all((entry.descendants ?? []).map(isSame))).some(Boolean))
+                    // The recorded descendants are only those seen during launch, and a
+                    // reparented one is not among them at all. Ask the group before
+                    // concluding the session ended: it is the signal that survives both.
+                    if (!(await Promise.all((entry.descendants ?? []).map(isSame))).some(Boolean) &&
+                        !(entry.group && (await groupAlive(entry.group))))
                         entry.status = "exited";
                 }
             }

package/dist/run.js

@@ -1,14 +1,14 @@
 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";
-import { processRef, isSame, stopTree, delay, descendants, } from "./identity/processes.js";
+import { processRef, isSame, stopTree, delay, descendants, ownedGroup, } from "./identity/processes.js";
 import { resolveCodex } from "./identity/codex.js";
 import { resolveClaude } from "./identity/claude.js";
 import { openCodeEndpointOwnedBy, resolveOpenCode, } from "./identity/opencode.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({
@@ -191,7 +210,14 @@ export class Muster {
                 await driver.stop(launched.hostRef);
                 throw new Error("process exited during launch");
             }
-            entry = { ...entry, root, host: driver.id, hostRef: launched.hostRef };
+            const group = await ownedGroup(launched.pid);
+            entry = {
+                ...entry,
+                root,
+                ...(group ? { group } : {}),
+                host: driver.id,
+                hostRef: launched.hostRef,
+            };
             await this.registry.update(entry.launchId, entry);
             let diagnostic = req.runtime === "claude"
                 ? "no Claude session registry found (check terminal for workspace trust or login prompts)"
@@ -204,7 +230,7 @@ export class Muster {
                 if (deadline - Date.now() < 25)
                     break;
                 if (await isSame(root)) {
-                    const tracked = (await Promise.all((await descendants(root.pid)).map(processRef))).filter((p) => !!p);
+                    const tracked = (await Promise.all((await descendants(root.pid, Date.now() + 1000, entry.group)).map(processRef))).filter((p) => !!p);
                     const refs = [...(entry.descendants ?? [])];
                     for (const ref of tracked)
                         if (!refs.some((r) => r.pid === ref.pid && r.start === ref.start))
@@ -347,6 +373,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}` : "") +
@@ -388,9 +417,11 @@ export class Muster {
             child.kill();
             throw new Error("task owner exited during launch");
         }
+        const group = await ownedGroup(child.pid);
         try {
             await this.registry.update(entry.launchId, {
                 root,
+                ...(group ? { group } : {}),
                 outputPath,
                 exitPath,
                 status: "running",
@@ -406,7 +437,7 @@ export class Muster {
             return handle;
         }
         catch (e) {
-            await stopTree(root);
+            await stopTree(root, group);
             await rm(specPath, { force: true });
             throw e;
         }
@@ -436,7 +467,7 @@ export class Muster {
             return;
         if (!(await isSame(entry.root))) {
             for (const ref of entry.descendants ?? [])
-                await stopTree(ref);
+                await stopTree(ref, entry.group);
             return;
         }
         // Validate the persisted process identity before ever using a window reference.
@@ -446,9 +477,9 @@ export class Muster {
             (await driver.list()).some((s) => s.hostRef === entry.hostRef && s.pid === entry.root.pid))
             await driver.stop(entry.hostRef);
         else
-            await stopTree(entry.root);
+            await stopTree(entry.root, entry.group);
         for (const ref of entry.descendants ?? [])
-            await stopTree(ref);
+            await stopTree(ref, entry.group);
     }
     async find(id) {
         const all = await this.registry.all();

package/package.json

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