@brutalsystems/muster 0.10.0 → 0.11.1

package/dist/run.js

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { loadConfig } from "./config.js";
-import { runSchema, agentBaseEnv, assertAllowedWorkspace, assertLevelExclusive, resolveLifecycle, resolveModel, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, runtimeArgs, } from "./guard.js";
+import { runSchema, agentBaseEnv, assertAllowedWorkspace, assertLevelExclusive, resolveLifecycle, resolveModel, launchArgs, launchEnv, paramsFingerprint, resolvePermissions, resolveTerminal, 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";
@@ -27,7 +27,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) {
@@ -98,7 +98,8 @@ export class Muster {
     }
     static async create(opts = {}) {
         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), { ...(opts.env ?? process.env) });
+        const config = await loadConfig(home);
+        return new Muster(config, home, env, opts.drivers ?? hosts(opts.env ?? process.env, config.tmux_status), { ...(opts.env ?? process.env) });
     }
     run(input, requester = LOCAL) {
         if (this.closing)
@@ -107,7 +108,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
@@ -171,6 +179,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
@@ -200,6 +217,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.
          *
@@ -217,7 +243,7 @@ export class Muster {
             throw new Error("host applies only to session launches");
         if (req.terminal && !req.open)
             throw new Error("--terminal requires --open");
-        const terminal = !req.terminal || req.terminal === "auto" ? "terminal" : req.terminal;
+        const terminal = resolveTerminal(req, this.config);
         const requestedHost = req.host ?? this.config.host;
         if (req.open &&
             (req.kind !== "session" || !["auto", "tmux"].includes(requestedHost)))
@@ -247,7 +273,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")
@@ -258,6 +283,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,
@@ -294,9 +341,409 @@ 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);
+            // 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 });
+        }
+        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;
@@ -326,315 +773,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(() => { });