@brutalsystems/muster 0.7.11 → 0.7.14

package/dist/run.js

@@ -1,14 +1,19 @@
-import { stat, readFile, writeFile, mkdir, rm } from "node:fs/promises";
+import { stat, readFile, realpath, writeFile, mkdir, rm, } from "node:fs/promises";
 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, assertAllowedWorkspace, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, runtimeArgs, } from "./guard.js";
+import { runSchema, agentBaseEnv, assertAllowedWorkspace, assertLevelExclusive, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, 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";
+import { IdentityError, readIdentity, } from "./identity-store.js";
+import { copyIdentity, identityEnv, setWorkspaceTrust, } from "./identity-copy.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";
@@ -30,6 +35,7 @@ function taskHandle(entry, pid) {
         sandbox: entry.sandbox,
         mcp: entry.mcp ?? [],
         ...(entry.mcp_warnings ? { mcp_warnings: entry.mcp_warnings } : {}),
+        ...(entry.enforcement ? { enforcement: entry.enforcement } : {}),
         id: entry.id,
         runtime: entry.runtime,
         state: "running",
@@ -37,10 +43,24 @@ function taskHandle(entry, pid) {
         pid,
     };
 }
+/**
+ * The variable that relocates an agent's configuration home — the one place the
+ * agent records its session, and therefore the one place resolution may look.
+ * OpenCode has none: its resolver uses the per-launch loopback HTTP endpoint
+ * rather than a configuration path, so relocating its configuration moves
+ * nothing Muster reads.
+ */
+function configHomeVar(runtime) {
+    if (runtime === "codex")
+        return "CODEX_HOME";
+    if (runtime === "claude")
+        return "CLAUDE_CONFIG_DIR";
+    return undefined;
+}
 export class Muster {
     config;
     home;
-    env;
+    hostEnv;
     drivers;
     sourceEnv;
     registry;
@@ -48,10 +68,21 @@ export class Muster {
     owned = new Set();
     closing = false;
     active = new Set();
-    constructor(config, home, env, drivers, sourceEnv) {
+    constructor(config, home, 
+    /**
+     * Muster's own subprocesses: the version and policy probes. Denylist-filtered
+     * from the parent and never handed to an agent — the agent's base comes from
+     * `agentBaseEnv` per launch, which a remote requester composes rather than
+     * inherits.
+     *
+     * Not what locates or reads an agent's session: that follows the agent's own
+     * configuration directory, which a launch under an identity relocates. See
+     * `resolutionEnv`, which is this environment plus that one override.
+     */
+    hostEnv, drivers, sourceEnv) {
         this.config = config;
         this.home = home;
-        this.env = env;
+        this.hostEnv = hostEnv;
         this.drivers = drivers;
         this.sourceEnv = sourceEnv;
         this.registry = new Registry(home);
@@ -61,7 +92,7 @@ export class Muster {
         const env = launchEnv(opts.env ?? process.env), home = opts.home ?? join(env.HOME ?? homedir(), ".muster");
         return new Muster(await loadConfig(home), home, env, opts.drivers ?? hosts(), { ...(opts.env ?? process.env) });
     }
-    run(input, requester = "cli") {
+    run(input, requester = LOCAL) {
         if (this.closing)
             return Promise.reject(new Error("Muster is closing"));
         const operation = this.launch(input, requester);
@@ -78,6 +109,32 @@ export class Muster {
             "project" in input &&
             input.cwd !== undefined)
             throw new Error("use project or cwd, not both");
+        assertLevelExclusive(input);
+        // Resolved before the request is parsed, so an unenrolled requester is
+        // refused without Muster having interpreted anything it sent.
+        const policy = resolveRequesterPolicy(requester, this.config);
+        if (requester.kind === "remote" &&
+            typeof input === "object" &&
+            input !== null) {
+            const raw = input;
+            if (raw.permissions !== undefined || raw.sandbox !== undefined)
+                throw new RequesterPolicyRefusal("not-expressible-remotely", "a remote request may name a level, not permissions or sandbox");
+            // `env_allow` is not the whole allowlist while a request may choose its
+            // own MCP servers: `mcpEnvironment` copies each selected server's
+            // declared `env_vars` and `bearer_token_env_var` out of the unfiltered
+            // source environment, so naming a server is how a remote request would
+            // pull that server's credentials into its agent despite `env_allow = []`.
+            // A plugin is the same shape, and an OpenCode launch that selects any
+            // plugin additionally admits whatever the target repository ships under
+            // .opencode/plugin. The spec's mitigation is to withhold the server
+            // rather than the variable, and no profile key can — so the selection
+            // itself is not expressible remotely, and a remote launch gets the
+            // receiver's configured `default_mcp` / `default_plugins`. Configuration
+            // is the grant.
+            for (const key of ["mcp", "plugin"])
+                if (raw[key] !== undefined)
+                    throw new RequesterPolicyRefusal("not-expressible-remotely", `a remote request may not select ${key}; this receiver's configured defaults apply`);
+        }
         const req = runSchema.parse(input);
         if (req.project) {
             const configured = this.config.projects[req.project];
@@ -88,6 +145,65 @@ export class Muster {
         if (!(await stat(req.cwd)).isDirectory())
             throw new Error("cwd is not a directory");
         await assertAllowedWorkspace(req.cwd, this.config);
+        if (policy.profile)
+            // Intersection by two independent checks. `projects: {}` matters: a
+            // configured project path is a root in its own right, and a remote
+            // profile must not inherit those grants.
+            await assertAllowedWorkspace(req.cwd, {
+                allowed_roots: policy.profile.allowed_roots,
+                projects: {},
+            });
+        // The effective level, and the reason this is not `?? "read"`: a remote
+        // request usually names no level, and `resolvePermissions` with no level
+        // falls through to `req.permissions ?? config.permissions` and
+        // `req.sandbox ?? config.sandbox` — the *receiving machine's* global
+        // defaults. So the profile is the floor here as well as the ceiling. A
+        // local requester has no `policy.level`, which leaves this undefined and
+        // local behaviour untouched.
+        const level = req.level ?? policy.level;
+        if (level)
+            assertLevelWithinCeiling(level, policy);
+        // Validated here, before anything is reserved or spawned: a bad identity
+        // must leave no registry entry behind. The copy cannot be made yet — it is
+        // named after the launch id, which only `reserve` produces — so this is the
+        // read-only half, and the copy happens below once that id exists.
+        const identityName = resolveIdentityForRequest(req.identity, policy);
+        let identityMeta;
+        if (identityName) {
+            identityMeta = await readIdentity(this.home, identityName);
+            if (identityMeta.agent !== req.runtime)
+                throw new IdentityError(identityName, `belongs to agent ${identityMeta.agent}, not ${req.runtime}`);
+            // Claude is the one runtime whose credential cannot survive the copy. It
+            // is keyed by the configuration directory's PATH, and a launch points
+            // Claude at the per-launch copy, which hashes to a service name that does
+            // not exist — the unsuffixed item is not a fallback. So `token_env` is the
+            // only route a Claude identity can launch under. Without this, such an
+            // identity would pass validation, copy, spawn a real agent and die at the
+            // deadline with "no Claude session registry found".
+            if (identityMeta.agent === "claude" && !identityMeta.token_env)
+                throw new IdentityError(identityName, "a Claude identity needs a token: run `claude setup-token`, export the " +
+                    "token, and name the variable with --token-env. The keychain credential " +
+                    "is keyed to the template's own path and cannot be used from the " +
+                    "per-launch copy a launch actually runs from");
+            // Reported now rather than by an agent that starts unauthenticated: the
+            // variable is read from the unfiltered source environment because that is
+            // where the operator set it, and `hostEnv` filters CLAUDE_CODE_* away.
+            if (identityMeta.token_env && !this.sourceEnv[identityMeta.token_env])
+                throw new IdentityError(identityName, `needs ${identityMeta.token_env} set in the environment`);
+        }
+        /**
+         * The one request every permission- and argv-deriving helper is given.
+         *
+         * `launchArgs`, `openCodeSessionLaunch` and `openCodeTaskLaunch` each call
+         * `resolvePermissions` again internally, so resolving the pair here and
+         * handing them the raw `req` would put the effective level in the record
+         * and the machine's global defaults in the argv — a remote `read` launch
+         * whose registry entry says `read-only` while the spawned process was
+         * given `--approve-for-me`. Two values where there should be one is how
+         * that happens, so there is one: nothing below derives containment from
+         * `req`.
+         */
+        const effective = level ? { ...req, level } : req;
         if (req.kind === "task" && req.host)
             throw new Error("host applies only to session launches");
         if (req.terminal && !req.open)
@@ -97,31 +213,51 @@ export class Muster {
         if (req.open &&
             (req.kind !== "session" || !["auto", "tmux"].includes(requestedHost)))
             throw new Error("--open requires a tmux session on macOS");
-        const permissions = resolvePermissions(req, this.config);
-        const selectedMcp = selectMcp(req, this.config);
-        const selectedPlugins = req.runtime === "opencode" ? selectPlugins(req, this.config) : [];
+        const permissions = resolvePermissions(effective, this.config);
+        const enforcement = enforcementGrade(req.runtime, permissions);
+        assertEnforcementMeetsMinimum(req.runtime, enforcement, policy);
+        // Composed here, before any process of any kind is started — the version
+        // probes and host availability checks below all spawn. A profile whose
+        // composed environment has no PATH or LANG must refuse the launch rather
+        // than leave a half-started one behind.
+        const agentBase = agentBaseEnv(requester, policy.profile, this.sourceEnv);
+        const selectedMcp = selectMcp(effective, this.config);
+        const selectedPlugins = req.runtime === "opencode" ? selectPlugins(effective, this.config) : [];
         let argv = [];
         if (req.runtime === "opencode")
-            runtimeArgs(req);
+            runtimeArgs(effective);
         else
-            argv = launchArgs(req, this.config);
+            argv = launchArgs(effective, this.config);
         const driver = req.kind === "session"
             ? await selectHost(req.open ? "tmux" : requestedHost, this.drivers)
             : undefined;
         if (req.open &&
             (!driver?.open || !(await driver.openAvailable?.(terminal))))
             throw new Error(`--open requires the selected terminal (${terminal}) installed on macOS and tmux`);
-        let policy = [];
+        let codexPolicy = [];
         if (req.runtime === "claude")
-            await assertClaudePolicy(this.env);
+            await assertClaudePolicy(this.hostEnv);
         if (req.runtime === "opencode")
-            await assertOpenCodeVersion(this.env, "1.18.31", Date.now() + 4000);
-        const { entry: reservation, deduped } = await this.registry.reserve({ runtime: req.runtime, kind: req.kind, cwd: req.cwd, ...permissions }, this.config.max_concurrent, req.requestKey
+            await assertOpenCodeVersion(this.hostEnv, "1.18.31", Date.now() + 4000);
+        const { entry: reservation, deduped } = await this.registry.reserve({
+            runtime: req.runtime,
+            kind: req.kind,
+            cwd: req.cwd,
+            ...permissions,
+            enforcement,
+        }, this.config.max_concurrent, req.requestKey
             ? {
                 requestKey: req.requestKey,
-                paramsFingerprint: paramsFingerprint(req, permissions, selectedMcp.map((s) => s.name), selectedPlugins.map((p) => p.name)),
+                paramsFingerprint: paramsFingerprint(
+                // The identity that actually determined the account, not the one
+                // named in the request: a remote requester granted exactly one
+                // identity names none and gets it anyway, and that launch must
+                // not share a fingerprint with a request that named something
+                // else. `effective` is left alone — nothing else derives from
+                // identity.
+                { ...effective, identity: identityName }, permissions, selectedMcp.map((s) => s.name), selectedPlugins.map((p) => p.name)),
             }
-            : undefined);
+            : undefined, requester);
         if (deduped) {
             await this.log.write({
                 event: "deduped",
@@ -129,7 +265,7 @@ export class Muster {
                 request_key: req.requestKey,
                 status: reservation.status,
                 requester,
-            });
+            }, policy.logMode);
             return this.recordedOutcome(reservation);
         }
         this.owned.add(reservation.launchId);
@@ -149,15 +285,65 @@ export class Muster {
                 requester,
                 ...(req.open ? { open: true, terminal } : {}),
                 args: req.args,
+                // The RESOLVED name, not req.identity: a remote requester granted
+                // exactly one identity names none and gets it anyway, and the audit
+                // trail must state the account that was actually used. Not in
+                // METADATA_DROP — a receiver needs this in a metadata-only record
+                // more than anywhere else, since it is the account it lent out.
+                ...(identityName ? { identity: identityName } : {}),
                 mcp: selectedMcp.map((s) => s.name),
                 ...(selectedPlugins.length
                     ? { plugins: selectedPlugins.map((p) => p.name) }
                     : {}),
                 ...permissions,
-            });
-            const prepared = await prepareMcp(selectedMcp, mcpEnvironment(selectedMcp, this.env, this.sourceEnv), req.cwd, deadline);
-            let runtimeEnv = mcpEnvironment(prepared.servers, this.env, this.sourceEnv);
+                enforcement,
+            }, policy.logMode);
+            const prepared = await prepareMcp(selectedMcp, mcpEnvironment(selectedMcp, agentBase, this.sourceEnv), req.cwd, deadline);
+            let runtimeEnv = mcpEnvironment(prepared.servers, agentBase, this.sourceEnv);
             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.
+                const copy = await copyIdentity(this.home, identityName, identityMeta, entry.launchId);
+                // Written into the copy, never the live ~/.claude.json: a running
+                // session rewrites that file continuously and Muster cannot coordinate.
+                if (identityMeta.agent === "claude")
+                    // RESOLVED, not as written: Claude keys projects[] by what its own
+                    // getcwd(2) returns, which has every symlink resolved. On macOS a
+                    // launch into /tmp/... is really /private/tmp/..., so the un-resolved
+                    // key is one Claude never looks up — the trust dialog appears, the
+                    // session never registers, and the launch burns its whole deadline.
+                    // `assertAllowedWorkspace` already realpaths for containment.
+                    await setWorkspaceTrust(copy, await realpath(req.cwd));
+                runtimeEnv = {
+                    ...runtimeEnv,
+                    ...identityEnv(identityMeta, copy, this.sourceEnv),
+                };
+                entry = await this.registry.update(entry.launchId, {
+                    identityPath: copy,
+                    // Recorded alongside the path, because the path outlives the directory
+                    // it names and never named the account.
+                    identity: identityName,
+                });
+            }
+            // Where the agent will record its session. Distinct from `hostEnv`, which
+            // keeps spawning Muster's own helpers — see `resolutionEnv`.
+            //
+            // Derived from the COMPOSED agent environment, not from `identityPath`
+            // alone: a requester profile's `env_defaults` delivers any key by design,
+            // so a profile setting CLAUDE_CONFIG_DIR or CODEX_HOME hands the agent one
+            // configuration home while resolution searched the host's — reserve, spawn,
+            // dead at the deadline. The identity copy still wins where there is one,
+            // because `identityEnv` is merged into `runtimeEnv` above.
+            const configVar = configHomeVar(req.runtime);
+            const configHome = configVar
+                ? (runtimeEnv[configVar] ?? entry.identityPath)
+                : undefined;
+            // Persisted only when it differs from the host's, so a launch with neither
+            // an identity nor an override writes nothing new and reads exactly as
+            // before. `refreshed()` has only the entry in scope and must agree.
+            if (configVar && configHome && configHome !== this.hostEnv[configVar])
+                entry = await this.registry.update(entry.launchId, { configHome });
+            const resolveEnv = this.resolutionEnv(req.runtime, configHome);
             let bridgePath;
             if (req.runtime === "claude" && prepared.servers.length) {
                 const dir = join(this.home, "mcp");
@@ -169,15 +355,15 @@ export class Muster {
                 await writeFile(bridgePath, JSON.stringify(Object.fromEntries(prepared.servers.map((s) => [s.name, s.config]))), { mode: 0o600 });
             }
             if (req.runtime !== "opencode")
-                argv = launchArgs(req, this.config, prepared.servers, bridgePath);
+                argv = launchArgs(effective, this.config, prepared.servers, bridgePath);
             if (req.runtime === "codex") {
-                policy = await codexPolicyArgs(runtimeEnv, req.cwd, deadline, prepared.servers, req.kind === "task");
-                argv.splice(1, 0, ...policy);
+                codexPolicy = await codexPolicyArgs(runtimeEnv, req.cwd, deadline, prepared.servers, req.kind === "task");
+                argv.splice(1, 0, ...codexPolicy);
             }
             else if (req.runtime === "opencode" && req.kind === "session") {
                 const port = await allocateLoopbackPort();
                 const inheritedMcpNames = await openCodeMcpNames(runtimeEnv, req.cwd, deadline);
-                const launch = await openCodeSessionLaunch(req, this.config, prepared.servers, inheritedMcpNames, port, runtimeEnv, req.cwd, deadline, selectedPlugins, this.sourceEnv);
+                const launch = await openCodeSessionLaunch(effective, this.config, prepared.servers, inheritedMcpNames, port, runtimeEnv, req.cwd, deadline, selectedPlugins, this.sourceEnv);
                 argv = launch.argv;
                 runtimeEnv = { ...runtimeEnv, ...launch.envPatch };
                 entry = await this.registry.update(entry.launchId, {
@@ -187,7 +373,7 @@ export class Muster {
             }
             else if (req.runtime === "opencode" && req.kind === "task") {
                 const inheritedMcpNames = await openCodeMcpNames(runtimeEnv, req.cwd, deadline);
-                const launch = await openCodeTaskLaunch(req, this.config, prepared.servers, inheritedMcpNames, runtimeEnv, req.cwd, deadline, selectedPlugins, this.sourceEnv);
+                const launch = await openCodeTaskLaunch(effective, this.config, prepared.servers, inheritedMcpNames, runtimeEnv, req.cwd, deadline, selectedPlugins, this.sourceEnv);
                 argv = launch.argv;
                 runtimeEnv = { ...runtimeEnv, ...launch.envPatch };
             }
@@ -197,7 +383,7 @@ export class Muster {
             // 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);
+                return await this.startTask(entry, argv, runtimeEnv, policy.logMode);
             const launched = await driver.launch({
                 argv,
                 cwd: req.cwd,
@@ -210,20 +396,43 @@ export class Muster {
                 await driver.stop(launched.hostRef);
                 throw new Error("process exited during launch");
             }
-            entry = { ...entry, root, host: driver.id, hostRef: launched.hostRef };
-            await this.registry.update(entry.launchId, entry);
+            const group = await ownedGroup(launched.pid);
+            entry = {
+                ...entry,
+                root,
+                ...(group ? { group } : {}),
+                host: driver.id,
+                hostRef: launched.hostRef,
+            };
+            // Only the fields that changed, not the whole entry: `entry` still
+            // carries its recorded `requester`, and update() refuses a patch that
+            // mentions that field at all, changed or not.
+            await this.registry.update(entry.launchId, {
+                root,
+                ...(group ? { group } : {}),
+                host: driver.id,
+                hostRef: launched.hostRef,
+            });
             let diagnostic = req.runtime === "claude"
                 ? "no Claude session registry found (check terminal for workspace trust or login prompts)"
                 : req.runtime === "opencode"
                     ? "no OpenCode session matched the launch endpoint, cwd, and creation window"
                     : "no descendant runtime identity found";
+            // `resolveEnv`, not `hostEnv`: this connection is how the thread
+            // `resolveCodex` found gets READ — both its `rejectionOf` screen, where a
+            // non-null answer is fatal, and `codexReachable` at readiness. An
+            // app-server reading the operator's CODEX_HOME has no rollout for a thread
+            // created under the copy, so it answers "no rollout found", every
+            // candidate is rejected, and the launch burns its deadline. Pointing
+            // discovery at the copy while its reads stay on the host is the same bug
+            // one call downstream.
             if (req.runtime === "codex")
-                rpc = new CodexRpc(this.env, req.cwd);
+                rpc = new CodexRpc(resolveEnv, req.cwd);
             while (Date.now() < deadline) {
                 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))
@@ -240,7 +449,7 @@ export class Muster {
                 let openingTerminal = false;
                 try {
                     const identity = req.runtime === "codex"
-                        ? await resolveCodex(root.pid, this.env, deadline, async (id) => {
+                        ? await resolveCodex(root.pid, resolveEnv, deadline, async (id) => {
                             try {
                                 const { thread } = await rpc.call("thread/read", { threadId: id }, deadline);
                                 return threadRejection(thread, id);
@@ -251,7 +460,7 @@ export class Muster {
                         })
                         : req.runtime === "opencode"
                             ? await resolveOpenCode(root.pid, entry.server_url, req.cwd, startedAt, deadline)
-                            : await resolveClaude(root.pid, this.env, deadline);
+                            : await resolveClaude(root.pid, resolveEnv, deadline);
                     if (identity) {
                         diagnostic =
                             req.runtime === "codex"
@@ -284,6 +493,7 @@ export class Muster {
                         const peer = {
                             kind: "session",
                             ...permissions,
+                            enforcement,
                             ...prepared.summary,
                             name: named.display,
                             canonical_id: named.canonicalId,
@@ -314,11 +524,7 @@ export class Muster {
                             status: "running",
                             peer,
                         });
-                        await this.log.write({
-                            event: "ready",
-                            launch_id: entry.launchId,
-                            peer,
-                        });
+                        await this.log.write({ event: "ready", launch_id: entry.launchId, peer }, policy.logMode);
                         return peer;
                     }
                 }
@@ -345,7 +551,7 @@ export class Muster {
                 error: message,
             });
             await this.log
-                .write({ event: "failure", launch_id: entry.launchId, error: message })
+                .write({ event: "failure", launch_id: entry.launchId, error: message }, policy.logMode)
                 .catch(() => { });
             throw e;
         }
@@ -382,7 +588,7 @@ export class Muster {
             throw new Error(`Request key ${key} has no recorded session`);
         return entry.peer;
     }
-    async startTask(entry, argv, env) {
+    async startTask(entry, argv, env, logMode) {
         const dir = join(this.home, "tasks", entry.id);
         await mkdir(dir, { recursive: true, mode: 0o700 });
         const outputPath = join(dir, "output.txt"), exitPath = join(dir, "exit.json"), startPath = join(dir, "start"), specPath = join(dir, "launch.json");
@@ -410,9 +616,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",
@@ -420,15 +628,11 @@ export class Muster {
             await writeFile(startPath, "start", { mode: 0o600 });
             child.unref();
             const handle = taskHandle(entry, root.pid);
-            await this.log.write({
-                event: "started",
-                launch_id: entry.launchId,
-                run: handle,
-            });
+            await this.log.write({ event: "started", launch_id: entry.launchId, run: handle }, logMode);
             return handle;
         }
         catch (e) {
-            await stopTree(root);
+            await stopTree(root, group);
             await rm(specPath, { force: true });
             throw e;
         }
@@ -451,6 +655,8 @@ export class Muster {
         finally {
             if (entry.mcpConfigPath)
                 await rm(entry.mcpConfigPath, { force: true });
+            if (entry.identityPath)
+                await rm(entry.identityPath, { recursive: true, force: true });
         }
     }
     async stopEntryProcesses(entry) {
@@ -458,7 +664,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.
@@ -468,9 +674,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();
@@ -496,13 +702,37 @@ export class Muster {
             throw new Error(`${result.reason}: ${result.candidates.join(", ")}`);
         return peers[named.indexOf(result.peer)];
     }
-    async stop(id) {
+    async stop(id, requester = LOCAL) {
         const entry = await this.find(id);
+        assertMayAct(entry, requester);
         await this.stopEntry(entry);
         await this.registry.update(entry.launchId, { status: "stopped" });
         await this.log.write({ event: "stopped", launch_id: entry.launchId });
         return { stopped: true, id: entry.id };
     }
+    /**
+     * Where to look for the agent's own session registry. Two different uses of an
+     * environment meet here, and conflating them is the bug this exists to avoid:
+     *
+     * - *Spawning* Muster's own helpers — the version probes, `assertClaudePolicy`
+     *   and the Codex RPC connection — keeps `hostEnv`. They need a working PATH
+     *   and they are Muster's machinery, not the agent's.
+     * - *Locating* what the agent wrote must follow the agent's configuration
+     *   directory. A launch under an identity relocates that directory to the
+     *   per-launch copy, so the session record is inside the copy; resolving
+     *   against `hostEnv` would search the operator's own directory, find nothing,
+     *   and fail the whole launch deadline with a useless diagnostic.
+     *
+     * The identity's token is deliberately absent: the resolvers read paths.
+     * OpenCode needs no entry — its resolver uses the per-launch loopback HTTP
+     * endpoint rather than a configuration path.
+     */
+    resolutionEnv(runtime, configHome) {
+        const key = configHomeVar(runtime);
+        if (!configHome || !key)
+            return this.hostEnv;
+        return { ...this.hostEnv, [key]: configHome };
+    }
     async refreshed(entry) {
         if (entry.kind !== "session" ||
             entry.status !== "running" ||
@@ -514,7 +744,11 @@ export class Muster {
         try {
             let metadata;
             if (entry.runtime === "codex") {
-                rpc = new CodexRpc(this.env, entry.cwd);
+                // Derived from the entry for the same reason as the claude branch
+                // below: this reads the session's own thread, and a session launched
+                // under an identity recorded it inside the copy. On `hostEnv` a healthy
+                // codex identity session reads as `unreachable` in every listing.
+                rpc = new CodexRpc(this.resolutionEnv("codex", entry.configHome ?? entry.identityPath), entry.cwd);
                 metadata = await codexReachable(rpc, entry.id, deadline);
             }
             else if (entry.runtime === "opencode") {
@@ -535,7 +769,12 @@ export class Muster {
                     throw new Error("session endpoint ownership changed during refresh");
             }
             else {
-                const identity = await resolveClaude(entry.root.pid, this.env, deadline);
+                // Derived from the entry, not from a launch-time value: this runs long
+                // after the launch returned and has only the recorded entry in scope. A
+                // running session launched under an identity recorded itself inside the
+                // copy, so re-resolution must look there or `list` reports every such
+                // session as unreachable.
+                const identity = await resolveClaude(entry.root.pid, this.resolutionEnv(entry.runtime, entry.configHome ?? entry.identityPath), deadline);
                 if (!identity ||
                     identity.id !== entry.id ||
                     !(await claudeReachable(identity.socketPath, deadline)))
@@ -570,6 +809,12 @@ export class Muster {
             await rpc?.close();
         }
     }
+    /**
+     * Unscoped by requester, unlike stop and output. Filtering the listing is a
+     * contract change and nothing can call this remotely yet; the decision belongs
+     * with the supported entry point (#44), which is also what would need to
+     * choose between hiding other requesters' entries and redacting them.
+     */
     async list(kind) {
         const entries = await this.registry.all();
         const result = [];
@@ -579,6 +824,8 @@ export class Muster {
             const e = await this.refreshed(original);
             if (e.mcpConfigPath && !["starting", "running"].includes(e.status))
                 await rm(e.mcpConfigPath, { force: true });
+            if (e.identityPath && !["starting", "running"].includes(e.status))
+                await rm(e.identityPath, { recursive: true, force: true });
             if (e.kind === "session")
                 result.push({
                     ...e.peer,
@@ -586,6 +833,9 @@ export class Muster {
                     ...(e.permissions
                         ? { permissions: e.permissions, sandbox: e.sandbox }
                         : {}),
+                    // From the entry, not the peer: a listing must report the same fact a
+                    // launch result does, and an entry predating the field has none.
+                    ...(e.enforcement ? { enforcement: e.enforcement } : {}),
                     id: e.id,
                     runtime: e.peer?.runtime ?? e.runtime,
                     state: e.status === "running" ? (e.peer?.state ?? "idle") : e.status,
@@ -605,6 +855,7 @@ export class Muster {
                     ...(e.permissions
                         ? { permissions: e.permissions, sandbox: e.sandbox }
                         : {}),
+                    ...(e.enforcement ? { enforcement: e.enforcement } : {}),
                     id: e.id,
                     runtime: e.runtime,
                     cwd: e.cwd,
@@ -617,8 +868,9 @@ export class Muster {
         }
         return result;
     }
-    async output(id) {
+    async output(id, requester = LOCAL) {
         const entry = await this.find(id);
+        assertMayAct(entry, requester);
         if (entry.kind !== "task")
             throw new Error("output is available only for task runs");
         if (!entry.outputPath)

package/package.json

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