@brutalsystems/muster 0.11.0 → 1.0.0

package/dist/run.js

@@ -1,4 +1,4 @@
-import { stat, readFile, realpath, writeFile, mkdir, rm, } from "node:fs/promises";
+import { stat, readFile, writeFile, mkdir, rm, } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -10,10 +10,13 @@ import { LOCAL } from "./requester.js";
 import { assertEnforcementMeetsMinimum, assertLevelWithinCeiling, assertMayAct, resolveIdentityForRequest, resolveRequesterPolicy, RequesterPolicyRefusal, } from "./requester-policy.js";
 import { IdentityError, readIdentity, } from "./identity-store.js";
 import { resolveCredential } from "./identity-token.js";
-import { copyIdentity, identityEnv, setCodexWorkspaceTrust, setWorkspaceTrust, } from "./identity-copy.js";
+import { copyIdentity, identityEnv } from "./identity-copy.js";
 import { Registry } from "./registry.js";
 import { LaunchLog } from "./log.js";
 import { hosts, selectHost } from "./hosts/index.js";
+import { AGENTS } from "./agents.js";
+import { assertOptionsSupported, screenWorkspace } from "./options.js";
+import { workspaceTrustKey } from "./identity/workspace-key.js";
 import { processRef, isSame, stopTree, delay, descendants, ownedGroup, } from "./identity/processes.js";
 import { resolveCodex } from "./identity/codex.js";
 import { claudeConfigDir, claudeRegistryDiagnostic, claudeWorkspaceTrusted, resolveClaude, } from "./identity/claude.js";
@@ -27,7 +30,7 @@ import { CodexRpc } from "./codex-rpc.js";
 import { allocateLoopbackPort, OpenCodeHttp } from "./opencode-http.js";
 import { assertOpenCodeVersion, openCodeMcpNames, openCodeSessionLaunch, openCodeTaskLaunch, } from "./opencode-policy.js";
 import { assignNames, resolvePeer, runtimeName, suffixOf, } from "./naming.js";
-import { selectMcp, prepareMcp, mcpEnvironment } from "./mcp.js";
+import { selectMcp, prepareMcp, mcpEnvironment, } from "./mcp.js";
 import { pollInterval } from "./reap.js";
 import { selectPlugins } from "./plugins.js";
 function taskHandle(entry, pid) {
@@ -58,12 +61,13 @@ function taskHandle(entry, pid) {
  * rather than a configuration path, so relocating its configuration moves
  * nothing Muster reads.
  */
+/**
+ * `undefined` rather than the table's `null`, because every caller treats this
+ * as "there is no such variable" via `?? entry.identityPath` and an absent
+ * value is what that idiom expects.
+ */
 function configHomeVar(runtime) {
-    if (runtime === "codex")
-        return "CODEX_HOME";
-    if (runtime === "claude")
-        return "CLAUDE_CONFIG_DIR";
-    return undefined;
+    return AGENTS[runtime].configHomeVar ?? undefined;
 }
 export class Muster {
     config;
@@ -108,7 +112,14 @@ export class Muster {
         this.active.add(operation);
         return operation.finally(() => this.active.delete(operation));
     }
-    async launch(input, requester) {
+    /**
+     * Phase 1 of a launch: decide whether this caller may ask for this at all,
+     * and settle what "this" is. Everything here refuses BEFORE anything is
+     * reserved, spawned or written, which is why it reads the raw input in places
+     * rather than the parsed request — once defaults have been applied, a value
+     * Muster chose is indistinguishable from one the caller sent.
+     */
+    async authorize(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
@@ -140,7 +151,11 @@ export class Muster {
             // 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"])
+            // `options` joins them for the same reason, and one of its own:
+            // auto-approve-path would have this machine trust a directory a remote
+            // caller named, and trust is what lets that directory configure the
+            // session. Configuration is the grant.
+            for (const key of ["mcp", "plugin", "options"])
                 if (raw[key] !== undefined)
                     throw new RequesterPolicyRefusal("not-expressible-remotely", `a remote request may not select ${key}; this receiver's configured defaults apply`);
         }
@@ -172,6 +187,15 @@ export class Muster {
         const level = req.level ?? policy.level;
         if (level)
             assertLevelWithinCeiling(level, policy);
+        return { req, policy, level };
+    }
+    /**
+     * Phase 2: the read-only half of identity resolution. Validated before
+     * anything is reserved or spawned, so a bad identity leaves no registry entry
+     * behind. The per-launch COPY cannot be made here — it is named after the
+     * launch id, which only `reserve` produces — so that half happens later.
+     */
+    async resolveIdentity(req, 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
@@ -201,6 +225,15 @@ export class Muster {
                         : "has no credential — run `setup-identity --interactive` to log in and store a token");
             }
         }
+        return { identityName, identityMeta, credential };
+    }
+    /**
+     * Phase 3: everything the launch needs decided, and every refusal that can be
+     * made without side effects — host and terminal availability, the runtime's
+     * own preflight, the enforcement floor. Nothing here reserves, spawns or
+     * writes, so a launch refused at this point leaves no trace.
+     */
+    async plan(req, policy, requester, level) {
         /**
          * The one request every permission- and argv-deriving helper is given.
          *
@@ -223,6 +256,9 @@ export class Muster {
         if (req.open &&
             (req.kind !== "session" || !["auto", "tmux"].includes(requestedHost)))
             throw new Error("--open requires a tmux session on macOS");
+        // Refused here, with the other checks that cost nothing to fail: an option
+        // the runtime cannot honour must not leave a registry entry behind.
+        assertOptionsSupported(req.runtime, req.options);
         const permissions = resolvePermissions(effective, this.config);
         const enforcement = enforcementGrade(req.runtime, permissions);
         assertEnforcementMeetsMinimum(req.runtime, enforcement, policy);
@@ -248,7 +284,6 @@ export class Muster {
         if (req.open &&
             (!driver?.open || !(await driver.openAvailable?.(terminal))))
             throw new Error(`--open requires the selected terminal (${terminal}) installed on macOS and tmux`);
-        let codexPolicy = [];
         if (req.runtime === "claude")
             await assertClaudePolicy(this.hostEnv);
         if (req.runtime === "opencode")
@@ -259,6 +294,28 @@ export class Muster {
         // Deciding from `req.host` accepts --idle-timeout under `host = "pty"` in
         // config and then never arms it.
         const lifecycle = resolveLifecycle(effective, this.config, req.kind === "session" && typeof driver?.schedule === "function");
+        return {
+            effective,
+            terminal,
+            permissions,
+            enforcement,
+            agentBase,
+            selectedMcp,
+            selectedPlugins,
+            model,
+            driver,
+            lifecycle,
+            argv,
+        };
+    }
+    /**
+     * Phase 4: claim the slot. The first step with a side effect, and the first
+     * that can answer "this launch already happened" — a repeated `--request-key`
+     * returns the original outcome rather than starting a second agent, so the
+     * caller cannot tell a retry from a duplicate.
+     */
+    async reserveLaunch(c) {
+        const { req, effective, policy, requester, permissions, enforcement, model, lifecycle, selectedMcp, selectedPlugins, identityName, } = c;
         const { entry: reservation, deduped } = await this.registry.reserve({
             runtime: req.runtime,
             kind: req.kind,
@@ -295,9 +352,415 @@ export class Muster {
                 status: reservation.status,
                 requester,
             }, policy.logMode);
-            return this.recordedOutcome(reservation);
+            return { outcome: this.recordedOutcome(reservation) };
         }
         this.owned.add(reservation.launchId);
+        return { entry: reservation };
+    }
+    /**
+     * Phase 5: everything the agent's own environment needs before a process can
+     * be started — MCP servers probed, the per-launch identity copy made (the
+     * launch id exists now, and the copy is named after it), the configuration
+     * home the child will actually open recorded, and Claude's MCP bridge file
+     * written.
+     *
+     * Three of the sixteen per-agent capabilities surface here: workspace trust
+     * is written to a different file and key per agent and does not apply to
+     * OpenCode, the configuration-home variable differs, and the bridge file is
+     * Claude's alone. See AGENT_CAPABILITIES.md.
+     */
+    async prepareEnvironment(c) {
+        const { req, identityName, identityMeta, credential, selectedMcp, agentBase, deadline, } = c;
+        let entry = c.entry;
+        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);
+            // Keyed on the identity's agent, which `resolveIdentity` has already
+            // refused unless it equals req.runtime — so this is the same row either
+            // way, and reading it from the identity keeps the check and the use
+            // agreed. A fresh copy trusts nothing, so without this every identity
+            // launch sat on "Do you trust the contents of this directory?" until the
+            // deadline. `realpath` and the reason for it are documented on the slot.
+            await AGENTS[identityMeta.agent].trustWorkspace?.(copy, await workspaceTrustKey(req.cwd));
+            runtimeEnv = {
+                ...runtimeEnv,
+                ...identityEnv(identityMeta, copy, this.sourceEnv, credential?.token),
+            };
+            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.
+        // `--options auto-approve-path`: record the launch directory as trusted in
+        // the profile the agent will actually use, so the one-time dialog does not
+        // stop the launch. Screened first — a directory that ships hooks or MCP
+        // servers configures the session it is trusted by, and those run without
+        // asking, so it is named and refused rather than waved through.
+        if (req.options.includes("auto-approve-path")) {
+            const findings = await screenWorkspace(req.cwd);
+            if (findings.length)
+                throw new Error(`--options auto-approve-path refused: ${req.cwd} ships ${findings.join(" and ")}; trusting it would let that configure the session. Trust it yourself once, or launch without the option.`);
+        }
+        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 });
+        // Written before the agent starts and into the SAME dir the child will open.
+        // An identity launch has already had its copy trusted above, so this is a
+        // no-op there rather than a second write.
+        if (req.options.includes("auto-approve-path") && configHome)
+            await AGENTS[req.runtime].trustWorkspace?.(configHome, await workspaceTrustKey(req.cwd));
+        const resolveEnv = this.resolutionEnv(req.runtime, configHome);
+        let bridgePath;
+        if (req.runtime === "claude" && prepared.servers.length) {
+            const dir = join(this.home, "mcp");
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+            bridgePath = join(dir, entry.launchId + ".json");
+            entry = await this.registry.update(entry.launchId, {
+                mcpConfigPath: bridgePath,
+            });
+            await writeFile(bridgePath, JSON.stringify(Object.fromEntries(prepared.servers.map((s) => [s.name, s.config]))), { mode: 0o600 });
+        }
+        return { entry, prepared, runtimeEnv, configHome, resolveEnv, bridgePath };
+    }
+    /**
+     * Phase 6: turn the plan into a command line. This is the widest per-agent
+     * split in the launch — Claude and Codex are handed argv and contain
+     * themselves from there, while OpenCode is a server Muster starts on an
+     * allocated loopback port and then talks to over HTTP, so its "argv" comes
+     * back from a builder that also reports the port and an environment patch.
+     *
+     * Codex's policy overrides are spliced in AFTER launchArgs rather than passed
+     * to it, because they are computed from the composed runtime environment that
+     * only exists by this point.
+     */
+    async buildCommand(c) {
+        const { req, effective, prepared, bridgePath, selectedPlugins, deadline } = c;
+        let { argv, codexPolicy, runtimeEnv, entry } = c;
+        if (req.runtime !== "opencode")
+            // `runtimeEnv`, not the host's: an identity launch relocates
+            // CLAUDE_CONFIG_DIR to the per-launch copy, and the sandbox must grant
+            // the dir the child will actually open, not the one Muster runs under.
+            argv = launchArgs(effective, this.config, prepared.servers, bridgePath, runtimeEnv);
+        if (req.runtime === "codex") {
+            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(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, {
+                server_url: launch.serverUrl,
+                opencode_port: launch.port,
+            });
+        }
+        else if (req.runtime === "opencode" && req.kind === "task") {
+            const inheritedMcpNames = await openCodeMcpNames(runtimeEnv, req.cwd, deadline);
+            const launch = await openCodeTaskLaunch(effective, this.config, prepared.servers, inheritedMcpNames, runtimeEnv, req.cwd, deadline, selectedPlugins, this.sourceEnv);
+            argv = launch.argv;
+            runtimeEnv = { ...runtimeEnv, ...launch.envPatch };
+        }
+        return { argv, codexPolicy, runtimeEnv, entry };
+    }
+    /**
+     * Phase 7: start the process. The first point at which a process can exist
+     * without the registry knowing about it, which is why `spawning` is recorded
+     * before the host is asked to launch anything.
+     *
+     * A task ends here — `startTask` owns its whole lifetime — so this returns an
+     * outcome rather than falling through, and only a session carries on to
+     * readiness.
+     */
+    async startProcess(c) {
+        const { req, argv, runtimeEnv, policy, driver, lifecycle, deadline } = c;
+        let entry = c.entry;
+        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 {
+                outcome: await this.startTask(entry, argv, runtimeEnv, policy.logMode),
+            };
+        const launched = await driver.launch({
+            argv,
+            cwd: req.cwd,
+            env: runtimeEnv,
+            label: req.prompt.slice(0, 48),
+            deadline,
+        });
+        const root = await processRef(launched.pid);
+        if (!root) {
+            await driver.stop(launched.hostRef);
+            throw new Error("process exited during launch");
+        }
+        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,
+        });
+        // Armed only once hostRef exists: the job addresses the window, and a job
+        // armed before the window is recorded would poll a target the registry
+        // cannot name. `schedule` is optional on the host interface, so pty and
+        // macos-terminal opt out by not implementing it.
+        if (driver?.schedule && (lifecycle.idleTimeout ?? lifecycle.ttl)) {
+            const armed = await driver
+                .schedule(pollInterval(lifecycle), [
+                process.execPath,
+                // ../dist/muster.js, not ./muster.js: this resolves from src/run.ts
+                // under vitest as well as from dist/run.js in the package, landing
+                // on <root>/dist either way. Same idiom as the tmux bootstrap.
+                fileURLToPath(new URL("../dist/muster.js", import.meta.url)),
+                "reap-check",
+                "--home",
+                this.home,
+                "--socket",
+                driver.socketName?.() ?? "muster",
+                entry.launchId,
+            ])
+                .then(() => true, () => false);
+            // A lifecycle that could not be armed must not fail the launch — the
+            // session is up and usable, and the orphan risk is what we had before.
+            // But it must not be REPORTED either: a record promising an expiry
+            // nothing will honour is worse than one promising none, because there
+            // is no way to tell from the outside.
+            if (!armed) {
+                lifecycle.idleTimeout = null;
+                lifecycle.ttl = null;
+                entry = await this.registry.update(entry.launchId, {
+                    idleTimeout: null,
+                    ttl: null,
+                });
+            }
+        }
+        return { entry, root, launched };
+    }
+    /**
+     * Phase 8: wait until the agent has registered a session Muster can address,
+     * or until the deadline, whichever comes first. The subtlest phase, and the
+     * one where the runtimes differ most: a session record on disk for Claude, a
+     * JSON-RPC thread read for Codex, an HTTP endpoint plus a port-ownership
+     * check for OpenCode. They share a question, not a mechanism.
+     *
+     * `diagnostic` is the reason the launch would fail if the deadline arrived
+     * now. It is overwritten by anything the loop learns, so a timeout reports
+     * the last real explanation rather than "no identity found" — and
+     * `neverRegistered` keeps the original, because only that one can be about a
+     * consent screen nobody answered.
+     *
+     * The RPC connection is created by the caller rather than here: `launch`'s
+     * `finally` has to close it even when this throws.
+     */
+    async awaitReadiness(c) {
+        const { req, root, launched, driver, policy, requester, resolveEnv, rpc, enforcement, prepared, identityName, model, permissions, terminal, lifecycle, startedAt, deadline, } = c;
+        let entry = c.entry;
+        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";
+        // Kept so the throw below can tell "nothing ever registered" from a
+        // diagnosis the loop actually earned. Only the first case can be about a
+        // consent screen; anything later means a session existed.
+        const neverRegistered = diagnostic;
+        // `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.
+        while (Date.now() < deadline) {
+            if (deadline - Date.now() < 25)
+                break;
+            if (await isSame(root)) {
+                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))
+                        refs.push(ref);
+                if (refs.length !== (entry.descendants ?? []).length) {
+                    entry = { ...entry, descendants: refs };
+                    await this.registry.update(entry.launchId, { descendants: refs });
+                }
+            }
+            if (this.closing)
+                throw new Error("Launch cancelled: Muster is closing");
+            if (!(await isSame(root)))
+                throw new Error(`process exited at ${((Date.now() - startedAt) / 1000).toFixed(2)}s`);
+            let openingTerminal = false;
+            try {
+                const identity = req.runtime === "codex"
+                    ? await resolveCodex(root.pid, resolveEnv, deadline, async (id) => {
+                        try {
+                            const { thread } = await rpc.call("thread/read", { threadId: id }, deadline);
+                            return threadRejection(thread, id);
+                        }
+                        catch (e) {
+                            return e.message;
+                        }
+                    })
+                    : req.runtime === "opencode"
+                        ? await resolveOpenCode(root.pid, entry.server_url, req.cwd, startedAt, deadline)
+                        : await resolveClaude(root.pid, resolveEnv, deadline);
+                if (identity) {
+                    diagnostic =
+                        req.runtime === "codex"
+                            ? "thread id reserved but no rollout"
+                            : req.runtime === "opencode"
+                                ? "OpenCode session exists but its endpoint status is not readable"
+                                : "registry exists but inbox socket is not accepting connections";
+                    let metadata;
+                    if (req.runtime === "codex")
+                        metadata = await codexReachable(rpc, identity.id, deadline);
+                    else if (req.runtime === "opencode")
+                        metadata = await openCodeReachable(new OpenCodeHttp(entry.server_url), identity, deadline);
+                    else {
+                        const claude = identity;
+                        if (!(await claudeReachable(claude.socketPath, deadline)))
+                            throw new Error(diagnostic);
+                        metadata = claude;
+                    }
+                    if (Date.now() >= deadline)
+                        throw new Error("readiness completed after launch deadline");
+                    if (!(await isSame(root)) || !(await processRef(identity.pid)))
+                        throw new Error("process exited before readiness completed");
+                    if (req.runtime === "opencode" &&
+                        !(await openCodeEndpointOwnedBy(root.pid, entry.server_url, deadline)))
+                        throw new Error("OpenCode endpoint listener is not owned by the launched process tree");
+                    const runtime = runtimeName(req.runtime);
+                    const named = assignNames([
+                        { runtime, uuid: identity.id, rawName: metadata.rawName },
+                    ])[0];
+                    const peer = {
+                        kind: "session",
+                        ...permissions,
+                        enforcement,
+                        ...prepared.summary,
+                        name: named.display,
+                        canonical_id: named.canonicalId,
+                        runtime,
+                        state: metadata.state,
+                        cwd: req.cwd,
+                        ...(req.runtime === "codex"
+                            ? { thread_id: identity.id }
+                            : req.runtime === "opencode"
+                                ? {
+                                    session_id: identity.id,
+                                    server_url: entry.server_url,
+                                }
+                                : { session_id: identity.id }),
+                        pid: identity.pid,
+                        host: driver.id,
+                        capabilities: driver.capabilities(),
+                        // The RESOLVED name, matching what the entry records and what
+                        // `list` projects: a launch result and a listing must not
+                        // disagree about which account this ran as.
+                        ...(identityName ? { identity: identityName } : {}),
+                        // Same reason, for the same pair of records.
+                        model: model?.model ?? null,
+                        model_source: model?.source ?? null,
+                        ...(lifecycle.idleTimeout
+                            ? { idle_timeout: lifecycle.idleTimeout }
+                            : {}),
+                        ...(lifecycle.ttl ? { ttl: lifecycle.ttl } : {}),
+                        attach_hint: driver.attachHint(launched.hostRef),
+                    };
+                    if (req.open) {
+                        openingTerminal = true;
+                        await driver.open(launched.hostRef, deadline, terminal);
+                        peer.terminal_opened = true;
+                        peer.terminal = terminal;
+                    }
+                    entry = await this.registry.update(entry.launchId, {
+                        id: identity.id,
+                        status: "running",
+                        peer,
+                    });
+                    await this.log.write({ event: "ready", launch_id: entry.launchId, peer }, policy.logMode);
+                    return peer;
+                }
+            }
+            catch (e) {
+                if (openingTerminal)
+                    throw e;
+                // An error arriving after the deadline is dropped, because most of
+                // them are artifacts of the deadline itself — aborted round trips
+                // that would overwrite a real diagnosis with "timed out". The cost is
+                // that a genuine answer landing a moment late is lost too, so raise
+                // one as early as it is known rather than at readiness (#20).
+                if (Date.now() < deadline)
+                    diagnostic = e.message;
+            }
+            await delay(Math.min(250, Math.max(0, deadline - Date.now())));
+        }
+        // Resolved here rather than before the launch: this reads the operator's
+        // live `.claude.json`, and a launch that is going to work should not pay
+        // for it. Failing closed is also wrong before a launch — `--kind task`
+        // runs headless and never sees the dialog, so refusing an untrusted
+        // directory up front would break task launches that work today.
+        if (req.runtime === "claude" && diagnostic === neverRegistered)
+            diagnostic = claudeRegistryDiagnostic(await claudeWorkspaceTrusted(resolveEnv, req.cwd), req.cwd, claudeConfigDir(resolveEnv));
+        throw new Error(`${diagnostic} after ${this.config.launch_timeout_sec}s`);
+    }
+    async launch(input, requester) {
+        const { req, policy, level } = await this.authorize(input, requester);
+        const { identityName, identityMeta, credential } = await this.resolveIdentity(req, policy);
+        const { effective, terminal, permissions, enforcement, agentBase, selectedMcp, selectedPlugins, model, driver, lifecycle, argv: plannedArgv, } = await this.plan(req, policy, requester, level);
+        let argv = plannedArgv;
+        let codexPolicy = [];
+        const reserved = await this.reserveLaunch({
+            req,
+            effective,
+            policy,
+            requester,
+            permissions,
+            enforcement,
+            model,
+            lifecycle,
+            selectedMcp,
+            selectedPlugins,
+            identityName,
+        });
+        if ("outcome" in reserved)
+            return reserved.outcome;
+        const reservation = reserved.entry;
         let entry = reservation;
         const startedAt = Date.now();
         const deadline = startedAt + this.config.launch_timeout_sec * 1000;
@@ -327,315 +790,70 @@ export class Muster {
                 ...permissions,
                 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));
-                // Codex gates the same way behind a different file and a different key,
-                // and a fresh copy trusts nothing — so every Codex identity launch sat
-                // on "Do you trust the contents of this directory?" until the deadline.
-                // Resolved for the same reason: Codex keys `projects` by its own cwd.
-                else if (identityMeta.agent === "codex")
-                    await setCodexWorkspaceTrust(copy, await realpath(req.cwd));
-                runtimeEnv = {
-                    ...runtimeEnv,
-                    ...identityEnv(identityMeta, copy, this.sourceEnv, credential?.token),
-                };
-                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");
-                await mkdir(dir, { recursive: true, mode: 0o700 });
-                bridgePath = join(dir, entry.launchId + ".json");
-                entry = await this.registry.update(entry.launchId, {
-                    mcpConfigPath: bridgePath,
-                });
-                await writeFile(bridgePath, JSON.stringify(Object.fromEntries(prepared.servers.map((s) => [s.name, s.config]))), { mode: 0o600 });
-            }
-            if (req.runtime !== "opencode")
-                // `runtimeEnv`, not the host's: an identity launch relocates
-                // CLAUDE_CONFIG_DIR to the per-launch copy, and the sandbox must grant
-                // the dir the child will actually open, not the one Muster runs under.
-                argv = launchArgs(effective, this.config, prepared.servers, bridgePath, runtimeEnv);
-            if (req.runtime === "codex") {
-                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(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, {
-                    server_url: launch.serverUrl,
-                    opencode_port: launch.port,
-                });
-            }
-            else if (req.runtime === "opencode" && req.kind === "task") {
-                const inheritedMcpNames = await openCodeMcpNames(runtimeEnv, req.cwd, deadline);
-                const launch = await openCodeTaskLaunch(effective, this.config, prepared.servers, inheritedMcpNames, runtimeEnv, req.cwd, deadline, selectedPlugins, this.sourceEnv);
-                argv = launch.argv;
-                runtimeEnv = { ...runtimeEnv, ...launch.envPatch };
-            }
-            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, policy.logMode);
-            const launched = await driver.launch({
-                argv,
-                cwd: req.cwd,
-                env: runtimeEnv,
-                label: req.prompt.slice(0, 48),
+            const environment = await this.prepareEnvironment({
+                req,
+                entry,
+                identityName,
+                identityMeta,
+                credential,
+                selectedMcp,
+                agentBase,
                 deadline,
             });
-            const root = await processRef(launched.pid);
-            if (!root) {
-                await driver.stop(launched.hostRef);
-                throw new Error("process exited during launch");
-            }
-            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,
+            entry = environment.entry;
+            // `runtimeEnv` is still reassigned below — an OpenCode launch patches it
+            // with the port its server ended up on — so it stays a `let` here rather
+            // than being destructured as a const.
+            let runtimeEnv = environment.runtimeEnv;
+            const { prepared, configHome, resolveEnv, bridgePath } = environment;
+            ({ argv, codexPolicy, runtimeEnv, entry } = await this.buildCommand({
+                req,
+                effective,
+                entry,
+                argv,
+                codexPolicy,
+                runtimeEnv,
+                prepared,
+                bridgePath,
+                selectedPlugins,
+                deadline,
+            }));
+            const started = await this.startProcess({
+                req,
+                entry,
+                argv,
+                runtimeEnv,
+                policy,
+                driver,
+                lifecycle,
+                deadline,
             });
-            // Armed only once hostRef exists: the job addresses the window, and a job
-            // armed before the window is recorded would poll a target the registry
-            // cannot name. `schedule` is optional on the host interface, so pty and
-            // macos-terminal opt out by not implementing it.
-            if (driver?.schedule && (lifecycle.idleTimeout ?? lifecycle.ttl)) {
-                const armed = await driver
-                    .schedule(pollInterval(lifecycle), [
-                    process.execPath,
-                    // ../dist/muster.js, not ./muster.js: this resolves from src/run.ts
-                    // under vitest as well as from dist/run.js in the package, landing
-                    // on <root>/dist either way. Same idiom as the tmux bootstrap.
-                    fileURLToPath(new URL("../dist/muster.js", import.meta.url)),
-                    "reap-check",
-                    "--home",
-                    this.home,
-                    "--socket",
-                    driver.socketName?.() ?? "muster",
-                    entry.launchId,
-                ])
-                    .then(() => true, () => false);
-                // A lifecycle that could not be armed must not fail the launch — the
-                // session is up and usable, and the orphan risk is what we had before.
-                // But it must not be REPORTED either: a record promising an expiry
-                // nothing will honour is worse than one promising none, because there
-                // is no way to tell from the outside.
-                if (!armed) {
-                    lifecycle.idleTimeout = null;
-                    lifecycle.ttl = null;
-                    entry = await this.registry.update(entry.launchId, {
-                        idleTimeout: null,
-                        ttl: null,
-                    });
-                }
-            }
-            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";
-            // Kept so the throw below can tell "nothing ever registered" from a
-            // diagnosis the loop actually earned. Only the first case can be about a
-            // consent screen; anything later means a session existed.
-            const neverRegistered = diagnostic;
-            // `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 ("outcome" in started)
+                return started.outcome;
+            entry = started.entry;
+            const { root, launched } = started;
             if (req.runtime === "codex")
                 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, 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))
-                            refs.push(ref);
-                    if (refs.length !== (entry.descendants ?? []).length) {
-                        entry = { ...entry, descendants: refs };
-                        await this.registry.update(entry.launchId, { descendants: refs });
-                    }
-                }
-                if (this.closing)
-                    throw new Error("Launch cancelled: Muster is closing");
-                if (!(await isSame(root)))
-                    throw new Error(`process exited at ${((Date.now() - startedAt) / 1000).toFixed(2)}s`);
-                let openingTerminal = false;
-                try {
-                    const identity = req.runtime === "codex"
-                        ? await resolveCodex(root.pid, resolveEnv, deadline, async (id) => {
-                            try {
-                                const { thread } = await rpc.call("thread/read", { threadId: id }, deadline);
-                                return threadRejection(thread, id);
-                            }
-                            catch (e) {
-                                return e.message;
-                            }
-                        })
-                        : req.runtime === "opencode"
-                            ? await resolveOpenCode(root.pid, entry.server_url, req.cwd, startedAt, deadline)
-                            : await resolveClaude(root.pid, resolveEnv, deadline);
-                    if (identity) {
-                        diagnostic =
-                            req.runtime === "codex"
-                                ? "thread id reserved but no rollout"
-                                : req.runtime === "opencode"
-                                    ? "OpenCode session exists but its endpoint status is not readable"
-                                    : "registry exists but inbox socket is not accepting connections";
-                        let metadata;
-                        if (req.runtime === "codex")
-                            metadata = await codexReachable(rpc, identity.id, deadline);
-                        else if (req.runtime === "opencode")
-                            metadata = await openCodeReachable(new OpenCodeHttp(entry.server_url), identity, deadline);
-                        else {
-                            const claude = identity;
-                            if (!(await claudeReachable(claude.socketPath, deadline)))
-                                throw new Error(diagnostic);
-                            metadata = claude;
-                        }
-                        if (Date.now() >= deadline)
-                            throw new Error("readiness completed after launch deadline");
-                        if (!(await isSame(root)) || !(await processRef(identity.pid)))
-                            throw new Error("process exited before readiness completed");
-                        if (req.runtime === "opencode" &&
-                            !(await openCodeEndpointOwnedBy(root.pid, entry.server_url, deadline)))
-                            throw new Error("OpenCode endpoint listener is not owned by the launched process tree");
-                        const runtime = runtimeName(req.runtime);
-                        const named = assignNames([
-                            { runtime, uuid: identity.id, rawName: metadata.rawName },
-                        ])[0];
-                        const peer = {
-                            kind: "session",
-                            ...permissions,
-                            enforcement,
-                            ...prepared.summary,
-                            name: named.display,
-                            canonical_id: named.canonicalId,
-                            runtime,
-                            state: metadata.state,
-                            cwd: req.cwd,
-                            ...(req.runtime === "codex"
-                                ? { thread_id: identity.id }
-                                : req.runtime === "opencode"
-                                    ? {
-                                        session_id: identity.id,
-                                        server_url: entry.server_url,
-                                    }
-                                    : { session_id: identity.id }),
-                            pid: identity.pid,
-                            host: driver.id,
-                            capabilities: driver.capabilities(),
-                            // The RESOLVED name, matching what the entry records and what
-                            // `list` projects: a launch result and a listing must not
-                            // disagree about which account this ran as.
-                            ...(identityName ? { identity: identityName } : {}),
-                            // Same reason, for the same pair of records.
-                            model: model?.model ?? null,
-                            model_source: model?.source ?? null,
-                            ...(lifecycle.idleTimeout
-                                ? { idle_timeout: lifecycle.idleTimeout }
-                                : {}),
-                            ...(lifecycle.ttl ? { ttl: lifecycle.ttl } : {}),
-                            attach_hint: driver.attachHint(launched.hostRef),
-                        };
-                        if (req.open) {
-                            openingTerminal = true;
-                            await driver.open(launched.hostRef, deadline, terminal);
-                            peer.terminal_opened = true;
-                            peer.terminal = terminal;
-                        }
-                        entry = await this.registry.update(entry.launchId, {
-                            id: identity.id,
-                            status: "running",
-                            peer,
-                        });
-                        await this.log.write({ event: "ready", launch_id: entry.launchId, peer }, policy.logMode);
-                        return peer;
-                    }
-                }
-                catch (e) {
-                    if (openingTerminal)
-                        throw e;
-                    // An error arriving after the deadline is dropped, because most of
-                    // them are artifacts of the deadline itself — aborted round trips
-                    // that would overwrite a real diagnosis with "timed out". The cost is
-                    // that a genuine answer landing a moment late is lost too, so raise
-                    // one as early as it is known rather than at readiness (#20).
-                    if (Date.now() < deadline)
-                        diagnostic = e.message;
-                }
-                await delay(Math.min(250, Math.max(0, deadline - Date.now())));
-            }
-            // Resolved here rather than before the launch: this reads the operator's
-            // live `.claude.json`, and a launch that is going to work should not pay
-            // for it. Failing closed is also wrong before a launch — `--kind task`
-            // runs headless and never sees the dialog, so refusing an untrusted
-            // directory up front would break task launches that work today.
-            if (req.runtime === "claude" && diagnostic === neverRegistered)
-                diagnostic = claudeRegistryDiagnostic(await claudeWorkspaceTrusted(resolveEnv, req.cwd), req.cwd, claudeConfigDir(resolveEnv));
-            throw new Error(`${diagnostic} after ${this.config.launch_timeout_sec}s`);
+            return await this.awaitReadiness({
+                req,
+                entry,
+                root,
+                launched,
+                driver,
+                policy,
+                requester,
+                resolveEnv,
+                rpc,
+                enforcement,
+                prepared,
+                identityName,
+                model,
+                permissions,
+                terminal,
+                lifecycle,
+                startedAt,
+                deadline,
+            });
         }
         catch (e) {
             await this.stopEntry(entry).catch(() => { });
@@ -649,9 +867,6 @@ export class Muster {
                 .catch(() => { });
             throw e;
         }
-        finally {
-            await rpc?.close();
-        }
     }
     /**
      * The answer to a request we have already seen. Never a new launch: a repeat
@@ -733,17 +948,11 @@ export class Muster {
     }
     async stopEntry(entry) {
         try {
-            const openCodeSessionId = entry.peer?.session_id;
-            const abortDeadline = Date.now() + 1000;
-            if (entry.runtime === "opencode" &&
-                entry.root &&
-                entry.server_url &&
-                typeof openCodeSessionId === "string" &&
-                (await isSame(entry.root)) &&
-                (await openCodeEndpointOwnedBy(entry.root.pid, entry.server_url, abortDeadline)))
-                await new OpenCodeHttp(entry.server_url)
-                    .abort(openCodeSessionId, abortDeadline)
-                    .catch(() => { });
+            // One second, and best effort: the kill below is what guarantees the
+            // stop, so an agent that will not answer must not delay it. Which agents
+            // have anything to say, and every precondition on saying it, lives on
+            // the row rather than here.
+            await AGENTS[entry.runtime].beforeStop?.(entry, Date.now() + 1000);
             await this.stopEntryProcesses(entry);
         }
         finally {
@@ -839,47 +1048,11 @@ export class Muster {
             !entry.peer)
             return entry;
         const deadline = Date.now() + 1500;
-        let rpc;
         try {
-            let metadata;
-            if (entry.runtime === "codex") {
-                // 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") {
-                if (!entry.server_url)
-                    throw new Error("session endpoint missing");
-                if (!(await isSame(entry.root)) ||
-                    !(await openCodeEndpointOwnedBy(entry.root.pid, entry.server_url, deadline)))
-                    throw new Error("session endpoint is not owned by the launch");
-                metadata = await openCodeReachable(new OpenCodeHttp(entry.server_url), {
-                    id: entry.id,
-                    pid: entry.root.pid,
-                    rawName: null,
-                    cwd: entry.cwd,
-                    serverUrl: entry.server_url,
-                }, deadline);
-                if (!(await isSame(entry.root)) ||
-                    !(await openCodeEndpointOwnedBy(entry.root.pid, entry.server_url, deadline)))
-                    throw new Error("session endpoint ownership changed during refresh");
-            }
-            else {
-                // 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)))
-                    throw new Error("session unreachable");
-                metadata = identity;
-            }
+            // The agent's own configuration home, which an identity launch relocates
+            // to a per-launch copy — composed here because only Muster knows where
+            // that copy went, and handed to the row that knows what to do with it.
+            const metadata = await AGENTS[entry.runtime].refreshMetadata(entry, this.resolutionEnv(entry.runtime, entry.configHome ?? entry.identityPath), deadline);
             const named = assignNames([
                 {
                     runtime: runtimeName(entry.runtime),
@@ -900,13 +1073,13 @@ export class Muster {
             });
         }
         catch {
+            // Any failure is "unreachable", including a connection this refresh never
+            // managed to open. Each implementation owns whatever it opened, so there
+            // is nothing left for this to close.
             return await this.registry.update(entry.launchId, {
                 peer: { ...entry.peer, state: "unreachable" },
             });
         }
-        finally {
-            await rpc?.close();
-        }
     }
     /**
      * Unscoped by requester, unlike stop and output. Filtering the listing is a