@sentropic/h2a-runtime 0.96.1 → 0.96.2

package/dist/index.js

@@ -23,9 +23,9 @@ import { attachNativeSession, driveNativeInstruction, killNativeSessionIfIncarna
 import { executeNativeRestart, NativeRestartError, } from "./native-restart.js";
 import { migrateTmuxNames } from "./tmux-name-migration.js";
 import { projectStatusForH2a } from "./status-projection.js";
-import { buildAgentLaunchArgs, isAgentLaunchEffort, isAgentLaunchProfile, } from "./agent-launch-args.js";
+import { buildAgentLaunchArgs, buildAgentLaunchStdin, isAgentLaunchEffort, isAgentLaunchProfile, } from "./agent-launch-args.js";
 import { deriveSessionClass } from "./session-class.js";
-import { isRelaunchKillable, planRelaunch, relaunchContinuationPrompt, wakeRelaunchedSession, } from "./relaunch.js";
+import { isRelaunchKillable, planRelaunch, relaunchContinuationPrompt, tryAcquireResumeLaunchClaim, wakeRelaunchedSession, } from "./relaunch.js";
 import { isHumanFacingSession, legacySessionEvidence, readConversationCustomTitle, readLastLayout, reconcileRunConvIds, restore as restoreLayout, } from "./restore.js";
 import { getLayoutConfig } from "./config.js";
 import { isManagedLocalKind, advanceJob, coerceRegistryTool, enroll, enrollFromRun, isLive, listJobs, listLocalForLs, loadRegistry, loadRegistryWithDiagnostics, probeNativeSession, probeTmuxSession, registryEntriesForNativeTarget, resolveLocalTmuxSessionForName, resolveManagedHost, tryClaimSlot, unreadableRegistryRowsForTarget, withRegistryLock, resolveRegistryPath, } from "./registry.js";
@@ -68,6 +68,7 @@ import { acquireLease, createLineage, handoffLease, isIncarnationSuspended, list
 import { checkReadiness } from "./readiness.js";
 import { createInterface } from "node:readline";
 const H2A_RUN_API_VERSION = "h2a.run/v1";
+const STRUCTURED_LAUNCH_PHASE_PREFIX = "[h2a] h2a.run.phase/v1 ";
 const H2A_RUNTIME_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 import { CLI_PROFILES, gatewayModeForProfile, profileUsesLlmMeshGateway, } from "./protocol-local.js";
 import { enrollViaFacade, formatLlmMeshAccountError, formatLlmMeshAccountList, listAccountsViaFacade, readLlmMeshConfig, startGateway, stopGateway, readGatewayPid, llmMeshLogPath, replaceAnthropicGatewayEnvironment, removeAccountViaFacade, acquireLlmMeshSessionEnv, updateLlmMeshRoutingConfig, } from "./llm-mesh.js";
@@ -77,7 +78,7 @@ export const packageName = "@sentropic/h2a-runtime";
 export const H2A_RUNTIME_CLI_API_VERSION = 1;
 export { run } from "./run.js";
 export { executeNativeRestart, nativeMcpRelaunchInstruction, NativeRestartError, } from "./native-restart.js";
-export { AGENT_LAUNCH_EFFORTS, AGENT_LAUNCH_PROFILES, AGENT_LAUNCH_PROMPT_MAX_BYTES, assertAgentLaunchModel, assertAgentLaunchPrompt, buildAgentLaunchArgs, isAgentLaunchEffort, isAgentLaunchProfile, } from "./agent-launch-args.js";
+export { AGENT_LAUNCH_EFFORTS, AGENT_LAUNCH_PROFILES, AGENT_LAUNCH_PROMPT_MAX_BYTES, assertAgentLaunchModel, assertAgentLaunchPrompt, buildAgentLaunchArgs, buildAgentLaunchStdin, isAgentLaunchEffort, isAgentLaunchProfile, } from "./agent-launch-args.js";
 export { attach, createRemoteSession, getRemoteSession, listRemoteSessions, refreshRemoteSession, renameRemoteSession, stopRemoteSession, } from "./attach.js";
 export { inspectProfileAuth } from "./auth-diagnostics.js";
 export { AuthRefreshError, ensureProfileAuthFresh } from "./auth-refresh.js";
@@ -3883,7 +3884,7 @@ export async function main(argv) {
     });
     program
         .command("run <profile> [path]")
-        .description("Start a LOCAL session in tmux (claude/codex/…) in <path> (default: cwd), then attach this terminal by default. h2a applies its embedded scroll-safe tmux profile at launch; no ~/.tmux.conf is required. Manage it with `h2a ls`, `h2a attach <slug>`, and `h2a stop <slug>`. Detach with Ctrl-b d; the session keeps running.")
+        .description("Start a LOCAL session in tmux (claude/codex/agy/…) in <path> (default: cwd), then attach this terminal by default. h2a applies its embedded scroll-safe tmux profile at launch; no ~/.tmux.conf is required. Manage it with `h2a ls`, `h2a attach <slug>`, and `h2a stop <slug>`. Detach with Ctrl-b d; the session keeps running.")
         .option("--no-attach", "start detached and print the attach command instead (for scripts / fan-out orchestration)")
         .option("--no-attached-terminal", "disable the persistent headless tmux client (legacy compatibility; cannot be used with --prompt-stdin)")
         .option("--tmux", "host the session in tmux instead of the native PTY host (native is the default; H2A_SESSION_HOST=tmux flips the default fleet-wide)")
@@ -3893,10 +3894,11 @@ export async function main(argv) {
         .option("--count <n>", "fan out N parallel agents (named <base>#1…#N) — run more than the per-project layout cap of claude/codex sessions")
         .option("--h2a", 'also start the h2a MCP server in a side tmux window "h2a" (launcher contract: agent reachable/wakeable via ~/h2a-workspace/.h2a); config key `h2a: {enabled, command}` makes it the default')
         .option("--no-h2a", "do not start the h2a MCP side window, overriding config")
-        .option("--prompt-stdin", "read the initial Claude/Codex prompt from stdin (keeps it out of process argv)")
-        .option("--model <model>", "Claude/Codex model override")
-        .option("--effort <level>", "reasoning effort: low|medium|high|xhigh (Claude and Codex)")
-        .option("--headless", "run once and exit (Claude -p / Codex exec), recording output under .h2a/runs/<name>")
+        .option("--prompt-stdin", "read the initial Claude/Codex/AGY prompt from stdin (keeps it out of process argv)")
+        .option("--agent <agent>", "AGY agent override (for example: stp)")
+        .option("--model <model>", "Claude/Codex/AGY model override")
+        .option("--effort <level>", "reasoning effort: low|medium|high|xhigh (AGY supports low|medium|high)")
+        .option("--headless", "run once and exit (Claude -p / Codex exec / AGY --print), recording output under .h2a/runs/<name>")
         .option("--background", "classify this detached session as a background worker excluded from human restore")
         .option("--json", "emit one machine-readable h2a.run.result object")
         .option("--llm-gateway", "launch the CLI through the local llm-mesh gateway")
@@ -3905,13 +3907,14 @@ export async function main(argv) {
         .option("--no-gw", "alias for --no-llm-gateway")
         .action(async (profile, path, opts) => {
         const structuredLaunch = opts.promptStdin === true ||
+            opts.agent !== undefined ||
             opts.model !== undefined ||
             opts.effort !== undefined ||
             opts.headless === true ||
             opts.background === true ||
             opts.json === true;
         if (structuredLaunch && !isAgentLaunchProfile(profile)) {
-            process.stderr.write(`[h2a] structured run supports only claude|codex (got "${profile}")\n`);
+            process.stderr.write(`[h2a] structured run supports only claude|codex|agy (got "${profile}")\n`);
             process.exitCode = 2;
             return;
         }
@@ -3920,6 +3923,16 @@ export async function main(argv) {
             process.exitCode = 2;
             return;
         }
+        if (profile === "agy" && opts.effort === "xhigh") {
+            process.stderr.write("[h2a] AGY --effort must be low|medium|high\n");
+            process.exitCode = 2;
+            return;
+        }
+        if (opts.agent !== undefined && profile !== "agy") {
+            process.stderr.write("[h2a] --agent is supported only for the AGY profile\n");
+            process.exitCode = 2;
+            return;
+        }
         if (opts.json && !opts.background) {
             process.stderr.write("[h2a] --json launch requires --background (MCP launches are detached)\n");
             process.exitCode = 2;
@@ -3945,6 +3958,26 @@ export async function main(argv) {
             process.exitCode = 2;
             return;
         }
+        let gatewayMode;
+        try {
+            gatewayMode = gatewayModeFromOptions(opts);
+        }
+        catch (error) {
+            process.stderr.write(`[h2a] ${error.message}.\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (gatewayMode === "gateway" && !profileUsesLlmMeshGateway(profile)) {
+            process.stderr.write(`[h2a] --llm-gateway/--gw is unsupported for ${profile}; this gateway is Anthropic-compatible and only Claude profiles consume it.\n`);
+            process.exitCode = 2;
+            return;
+        }
+        if (opts.json && opts.name) {
+            process.stderr.write(`${STRUCTURED_LAUNCH_PHASE_PREFIX}${JSON.stringify({
+                launchId: opts.name,
+                phase: "pre-creation",
+            })}\n`);
+        }
         const sessionHost = resolveSessionHostKind(opts);
         if (sessionHost === "local-tmux") {
             if (!tmuxAvailable()) {
@@ -4018,436 +4051,481 @@ export async function main(argv) {
         const labels = count > 1
             ? fanoutLabels(opts.name ?? basename(cwd), count)
             : [opts.name];
-        const existingTmuxSlugs = tmuxAvailable()
-            ? existingLocalSessionSlugs(labels, cwd)
-            : [];
-        // Native existence is THREE-state (the resolver's probe vocabulary):
-        // a probe FAILURE is "unknown", never absence. Treating a thrown
-        // probe as "no session" would let `run --tmux --resume` start a tmux
-        // twin over a live-but-unprovable native writer (sol-F3): the same
-        // fail-closed rule as resolveManagedHost's rule 4 applies — refuse
-        // to launch on an unprovable host state.
-        const nativeExistence = labels
-            .map((label) => slugify(label ?? cwd))
-            .map((slug) => ({
-            slug,
-            probe: probeNativeSession(localSessionName(slug)),
-        }));
-        const unknownNativeSlugs = nativeExistence
-            .filter((probed) => probed.probe === "unknown")
-            .map((probed) => probed.slug);
-        if (unknownNativeSlugs.length > 0) {
-            for (const slug of unknownNativeSlugs) {
-                process.stderr.write(`[h2a] cannot start ${slug}: native host state is unknown (the probe failed) — a probe failure is never proof of absence; refusing to risk a second writer (fail closed).\n`);
-            }
-            process.exitCode = 1;
-            return;
-        }
-        const existingNativeSlugs = nativeExistence
-            .filter((probed) => probed.probe === "live")
-            .map((probed) => probed.slug);
-        const existingLocalSessions = [
-            ...new Set([...existingTmuxSlugs, ...existingNativeSlugs]),
-        ];
-        if (existingLocalSessions.length > 0) {
-            for (const slug of existingLocalSessions) {
-                process.stderr.write(`[h2a] local session ${slug} already exists; no new ${profile} was started.\n`);
-                process.stderr.write(`[h2a] attach: h2a attach ${slug}\n`);
-                process.stderr.write(`[h2a] stop first: h2a stop ${slug} --reason restart\n`);
-            }
-            process.exitCode = 1;
-            return;
-        }
-        if (!existsSync(cwd) || !statSync(cwd).isDirectory()) {
-            process.stderr.write(`[h2a] workspace is not an existing directory: ${cwd}\n`);
-            process.exitCode = 2;
+        const resumeClaim = opts.resume
+            ? tryAcquireResumeLaunchClaim(opts.resume)
+            : undefined;
+        if (opts.resume && !resumeClaim) {
+            process.stderr.write(`[h2a] conversation ${opts.resume} is already being resumed; duplicate launch request skipped.\n`);
             return;
         }
-        let initialPrompt;
-        if (opts.promptStdin) {
-            initialPrompt = readFileSync(0, "utf8");
-        }
-        // Single-writer guard: refuse to resume a conversation another live
-        // session (local registry / remote pod) is already writing.
-        if (opts.resume) {
-            const ok = await guardConvWriters({
-                convId: opts.resume,
-                cwd,
-                ...(opts.force ? { force: true } : {}),
-                fetchRemoteSessions: async () => {
-                    const url = getConfiguredRemoteOptional();
-                    return url ? await listRemoteSessions(url) : [];
-                },
+        try {
+            const reservedTmuxSlugs = tmuxAvailable()
+                ? existingLocalSessionSlugs(labels, cwd)
+                : [];
+            // The inventory and this decision are separate reads: a structured
+            // launch can leave a name visible just before its last tmux process
+            // exits. Re-probe every canonical/legacy spelling and reclaim the slug
+            // only when ALL probes positively report death. A live or unknown
+            // spelling remains reserved, so probe failure can never authorize a
+            // second writer.
+            const tmuxExistence = reservedTmuxSlugs.map((slug) => {
+                const probes = managedSessionCandidates(slug).map((name) => probeTmuxSession(name));
+                const probe = probes.includes("live")
+                    ? "live"
+                    : probes.includes("unknown")
+                        ? "unknown"
+                        : "dead";
+                return { slug, probe };
             });
-            if (!ok) {
+            const unknownTmuxSlugs = tmuxExistence
+                .filter((probed) => probed.probe === "unknown")
+                .map((probed) => probed.slug);
+            if (unknownTmuxSlugs.length > 0) {
+                for (const slug of unknownTmuxSlugs) {
+                    process.stderr.write(`[h2a] cannot start ${slug}: tmux host state is unknown (the probe failed) — refusing to reclaim an unproven session name.\n`);
+                }
                 process.exitCode = 1;
                 return;
             }
-        }
-        // By default launches are direct. --llm-gateway/--gw opts into the
-        // local gateway for any profile that consumes Anthropic-compatible env.
-        let gatewayMode;
-        try {
-            gatewayMode = gatewayModeFromOptions(opts);
-        }
-        catch (error) {
-            process.stderr.write(`[h2a] ${error.message}.\n`);
-            process.exitCode = 1;
-            return;
-        }
-        if (gatewayMode === "gateway" && !profileUsesLlmMeshGateway(profile)) {
-            process.stderr.write(`[h2a] --llm-gateway/--gw is unsupported for ${profile}; this gateway is Anthropic-compatible and only Claude profiles consume it.\n`);
-            process.exitCode = 2;
-            return;
-        }
-        const launchGatewayMode = gatewayModeForProfile(profile, gatewayMode);
-        const command = localCliCommand(profile);
-        // A detached/background or run-once launch is a worker, even when its
-        // agent later emits a Claude SessionStart hook. Stamp this through tmux
-        // so that hook cannot reclassify it as a human session.
-        const sessionClass = deriveSessionClass({
-            background: opts.background === true,
-            headless: opts.headless === true,
-            humanTerminal: opts.attachedTerminal !== false,
-        });
-        let activeGateway;
-        const h2a = getH2aConfig();
-        const h2aSidecar = opts.h2a ?? h2a.enabled;
-        if (opts.headless && h2aSidecar) {
-            process.stderr.write("[h2a] --headless requires --no-h2a (a sidecar would keep the run-once session alive)\n");
-            process.exitCode = 2;
-            return;
-        }
-        if (opts.headless && !opts.name) {
-            process.stderr.write("[h2a] --headless requires --name\n");
-            process.exitCode = 2;
-            return;
-        }
-        const centralMcp = await prepareCentralMcpForLaunch({ root: cwd, profile, cwd });
-        if (centralMcp?.status === "degraded") {
-            process.stderr.write(`[h2a] central MCP unavailable, falling back to per-session sidecar: ${centralMcp.reason}\n`);
-        }
-        const started = [];
-        for (const label of labels) {
-            const clientSessionId = localSessionName(slugify(label ?? cwd));
-            try {
-                if (structuredLaunch) {
-                    activeGateway = await prepareStructuredGateway(launchGatewayMode, (selectedMode) => injectLlmMeshGatewayEnv(selectedMode, selectedMode !== "gateway", clientSessionId));
-                }
-                else {
-                    activeGateway = await injectLlmMeshGatewayEnv(launchGatewayMode, true, clientSessionId);
+            const existingTmuxSlugs = tmuxExistence
+                .filter((probed) => probed.probe === "live")
+                .map((probed) => probed.slug);
+            // Native existence is THREE-state (the resolver's probe vocabulary):
+            // a probe FAILURE is "unknown", never absence. Treating a thrown
+            // probe as "no session" would let `run --tmux --resume` start a tmux
+            // twin over a live-but-unprovable native writer (sol-F3): the same
+            // fail-closed rule as resolveManagedHost's rule 4 applies — refuse
+            // to launch on an unprovable host state.
+            const nativeExistence = labels
+                .map((label) => slugify(label ?? cwd))
+                .map((slug) => ({
+                slug,
+                probe: probeNativeSession(localSessionName(slug)),
+            }));
+            const unknownNativeSlugs = nativeExistence
+                .filter((probed) => probed.probe === "unknown")
+                .map((probed) => probed.slug);
+            if (unknownNativeSlugs.length > 0) {
+                for (const slug of unknownNativeSlugs) {
+                    process.stderr.write(`[h2a] cannot start ${slug}: native host state is unknown (the probe failed) — a probe failure is never proof of absence; refusing to risk a second writer (fail closed).\n`);
                 }
-            }
-            catch (error) {
-                process.stderr.write(`[h2a] ${error.message}\n`);
                 process.exitCode = 1;
                 return;
             }
-            const useBare = shouldUseClaudeBare(profile);
-            let args;
-            try {
-                args =
-                    structuredLaunch && isAgentLaunchProfile(profile)
-                        ? buildAgentLaunchArgs({
-                            profile,
-                            ...(initialPrompt !== undefined
-                                ? { prompt: initialPrompt }
-                                : {}),
-                            ...(opts.model !== undefined ? { model: opts.model } : {}),
-                            ...(opts.effort !== undefined
-                                ? { effort: opts.effort }
-                                : {}),
-                            ...(opts.resume !== undefined
-                                ? { resumeId: opts.resume }
-                                : {}),
-                            ...(opts.headless ? { headless: true } : {}),
-                            ...(useBare ? { bare: true } : {}),
-                        })
-                        : opts.resume
-                            ? localResumeArgs(profile, opts.resume, { bare: useBare })
-                            : localStartArgs(profile, { bare: useBare });
+            const existingNativeSlugs = nativeExistence
+                .filter((probed) => probed.probe === "live")
+                .map((probed) => probed.slug);
+            const existingLocalSessions = [
+                ...new Set([...existingTmuxSlugs, ...existingNativeSlugs]),
+            ];
+            if (existingLocalSessions.length > 0) {
+                for (const slug of existingLocalSessions) {
+                    process.stderr.write(`[h2a] local session ${slug} already exists; no new ${profile} was started.\n`);
+                    process.stderr.write(`[h2a] attach: h2a attach ${slug}\n`);
+                    process.stderr.write(`[h2a] stop first: h2a stop ${slug} --reason restart\n`);
+                }
+                process.exitCode = 1;
+                return;
             }
-            catch (error) {
-                process.stderr.write(`[h2a] ${error.message}\n`);
+            if (!existsSync(cwd) || !statSync(cwd).isDirectory()) {
+                process.stderr.write(`[h2a] workspace is not an existing directory: ${cwd}\n`);
                 process.exitCode = 2;
                 return;
             }
-            if (opts.resume && args.length === 0) {
-                process.stderr.write(`[h2a] profile "${profile}" has no verified local resume argv; start it without -r/--resume\n`);
-                process.exitCode = 1;
-                return;
+            let initialPrompt;
+            if (opts.promptStdin) {
+                initialPrompt = readFileSync(0, "utf8");
             }
-            let name;
-            let slug;
-            let outputLog;
-            let resultJson;
-            let agentPane;
-            let promptFile;
-            let promptDelivery;
-            if (opts.headless) {
-                const runDir = join(cwd, ".h2a", "runs", label);
-                mkdirSync(runDir, { recursive: true });
-                outputLog = join(runDir, "output.log");
-                resultJson = join(runDir, "result.json");
-                if (sessionHost === "native") {
-                    ({ name, slug, promptFile } = startNativeHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, initialPrompt, structuredLaunch, sessionClass));
-                }
-                else {
-                    ({ name, slug, agentPane, promptFile } = startHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, getTmuxProfileConfig().profile, initialPrompt, structuredLaunch, sessionClass));
+            // Single-writer guard: refuse to resume a conversation another live
+            // session (local registry / remote pod) is already writing.
+            if (opts.resume) {
+                const ok = await guardConvWriters({
+                    convId: opts.resume,
+                    cwd,
+                    ...(opts.force ? { force: true } : {}),
+                    fetchRemoteSessions: async () => {
+                        const url = getConfiguredRemoteOptional();
+                        return url ? await listRemoteSessions(url) : [];
+                    },
+                });
+                if (!ok) {
+                    process.exitCode = 1;
+                    return;
                 }
             }
-            else if (sessionHost === "native") {
-                ({ name, slug } = startNativeSession(profile, command, cwd, args, label, {
-                    ...(opts.resume !== undefined ? { resumeId: opts.resume } : {}),
-                    ...(initialPrompt !== undefined
-                        ? { terminateOnAgentExit: true }
-                        : {}),
-                    ...(structuredLaunch ? { refuseExisting: true } : {}),
-                    sessionClass,
-                }));
-            }
-            else {
-                ({ name, slug, agentPane } = startLocalSession(profile, command, cwd, args, label, getTmuxProfileConfig().profile, {
-                    ...(opts.resume !== undefined
-                        ? { resumeId: opts.resume }
-                        : {}),
-                    ...(h2aSidecar ? { h2aCommand: h2a.command } : {}),
-                    ...(initialPrompt !== undefined
-                        ? { terminateOnAgentExit: true }
-                        : {}),
-                    ...(structuredLaunch ? { refuseExisting: true } : {}),
-                    attachedTerminal: opts.attachedTerminal !== false,
-                    sessionClass,
-                }));
+            // By default launches are direct. --llm-gateway/--gw opts into the
+            // local gateway for any profile that consumes Anthropic-compatible env.
+            const launchGatewayMode = gatewayModeForProfile(profile, gatewayMode);
+            const command = localCliCommand(profile);
+            // A detached/background or run-once launch is a worker, even when its
+            // agent later emits a Claude SessionStart hook. Stamp this through tmux
+            // so that hook cannot reclassify it as a human session.
+            const sessionClass = deriveSessionClass({
+                background: opts.background === true,
+                headless: opts.headless === true,
+                humanTerminal: opts.attachedTerminal !== false,
+            });
+            let activeGateway;
+            const h2a = getH2aConfig();
+            const h2aSidecar = opts.h2a ?? h2a.enabled;
+            if (opts.headless && h2aSidecar) {
+                process.stderr.write("[h2a] --headless requires --no-h2a (a sidecar would keep the run-once session alive)\n");
+                process.exitCode = 2;
+                return;
             }
-            if (structuredLaunch && sessionHost !== "native" && !agentPane) {
-                cleanupHeadlessPromptFile(promptFile);
-                // OWN-CLEANUP, deliberately NOT resolver-derived (F1 sorting):
-                // `name` is the session THIS command just created above, on the
-                // host it chose. Re-resolving could return missing/unknown and
-                // refuse — leaking the partial session it exists to remove.
-                killLocalSession(name);
-                process.stderr.write(`[h2a] could not capture the exact agent pane for ${slug}; the partial session was stopped\n`);
-                process.exitCode = 1;
+            if (opts.headless && !opts.name) {
+                process.stderr.write("[h2a] --headless requires --name\n");
+                process.exitCode = 2;
                 return;
             }
-            let h2aSidecarStarted = false;
-            if (h2aSidecar && sessionHost === "native") {
-                h2aSidecarStarted = startNativeH2aSidecar(name, cwd, h2a.command, {
-                    ...(structuredLaunch ? { verified: true } : {}),
-                });
-                if (!h2aSidecarStarted && structuredLaunch) {
-                    cleanupHeadlessPromptFile(promptFile);
-                    // OWN-CLEANUP, deliberately NOT resolver-derived (F1 sorting):
-                    // this kills the session THIS command just created on the host
-                    // it chose; the resolver could refuse and leak the partial.
-                    killNativeSessionTree(name);
-                    process.stderr.write(`[h2a] required h2a sidecar failed for ${slug}; the partial session was stopped\n`);
+            const centralMcp = await prepareCentralMcpForLaunch({ root: cwd, profile, cwd });
+            if (centralMcp?.status === "degraded") {
+                process.stderr.write(`[h2a] central MCP unavailable, falling back to per-session sidecar: ${centralMcp.reason}\n`);
+            }
+            const started = [];
+            for (const label of labels) {
+                const clientSessionId = localSessionName(slugify(label ?? cwd));
+                try {
+                    if (structuredLaunch) {
+                        activeGateway = await prepareStructuredGateway(launchGatewayMode, (selectedMode) => injectLlmMeshGatewayEnv(selectedMode, selectedMode !== "gateway", clientSessionId));
+                    }
+                    else {
+                        activeGateway = await injectLlmMeshGatewayEnv(launchGatewayMode, true, clientSessionId);
+                    }
+                }
+                catch (error) {
+                    process.stderr.write(`[h2a] ${error.message}\n`);
                     process.exitCode = 1;
                     return;
                 }
-                if (h2aSidecarStarted) {
-                    process.stderr.write(`[h2a] h2a sidecar session started for ${slug} (${h2a.command})\n`);
+                const useBare = shouldUseClaudeBare(profile);
+                let args;
+                try {
+                    args =
+                        structuredLaunch && isAgentLaunchProfile(profile)
+                            ? buildAgentLaunchArgs({
+                                profile,
+                                ...(initialPrompt !== undefined
+                                    ? { prompt: initialPrompt }
+                                    : {}),
+                                ...(opts.agent !== undefined ? { agent: opts.agent } : {}),
+                                ...(opts.model !== undefined ? { model: opts.model } : {}),
+                                ...(opts.effort !== undefined
+                                    ? { effort: opts.effort }
+                                    : {}),
+                                ...(opts.resume !== undefined
+                                    ? { resumeId: opts.resume }
+                                    : {}),
+                                ...(opts.headless ? { headless: true } : {}),
+                                ...(useBare ? { bare: true } : {}),
+                            })
+                            : opts.resume
+                                ? localResumeArgs(profile, opts.resume, { bare: useBare })
+                                : localStartArgs(profile, { bare: useBare });
                 }
-            }
-            else if (h2aSidecar) {
-                if (structuredLaunch) {
-                    try {
-                        h2aSidecarStarted = Boolean(await startH2aWindowVerified(name, cwd, h2a.command, agentPane));
+                catch (error) {
+                    process.stderr.write(`[h2a] ${error.message}\n`);
+                    process.exitCode = 2;
+                    return;
+                }
+                if (opts.resume && args.length === 0) {
+                    process.stderr.write(`[h2a] profile "${profile}" has no verified local resume argv; start it without -r/--resume\n`);
+                    process.exitCode = 1;
+                    return;
+                }
+                let name;
+                let slug;
+                let outputLog;
+                let resultJson;
+                let agentPane;
+                let promptFile;
+                let promptDelivery;
+                if (opts.json && opts.name) {
+                    process.stderr.write(`${STRUCTURED_LAUNCH_PHASE_PREFIX}${JSON.stringify({
+                        launchId: opts.name,
+                        phase: "creation-attempted",
+                    })}\n`);
+                }
+                if (opts.headless) {
+                    const runDir = join(cwd, ".h2a", "runs", label);
+                    mkdirSync(runDir, { recursive: true });
+                    outputLog = join(runDir, "output.log");
+                    resultJson = join(runDir, "result.json");
+                    const headlessPromptInput = structuredLaunch && isAgentLaunchProfile(profile)
+                        ? buildAgentLaunchStdin({
+                            profile,
+                            ...(initialPrompt !== undefined
+                                ? { prompt: initialPrompt }
+                                : {}),
+                            headless: true,
+                        })
+                        : initialPrompt;
+                    if (sessionHost === "native") {
+                        ({ name, slug, promptFile } = startNativeHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, headlessPromptInput, structuredLaunch, sessionClass));
                     }
-                    catch (error) {
-                        process.stderr.write(`[h2a] required h2a sidecar verification failed: ${error.message}\n`);
-                        h2aSidecarStarted = false;
+                    else {
+                        ({ name, slug, agentPane, promptFile } = startHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, getTmuxProfileConfig().profile, headlessPromptInput, structuredLaunch, sessionClass));
                     }
                 }
+                else if (sessionHost === "native") {
+                    ({ name, slug } = startNativeSession(profile, command, cwd, args, label, {
+                        ...(opts.resume !== undefined ? { resumeId: opts.resume } : {}),
+                        ...(initialPrompt !== undefined
+                            ? { terminateOnAgentExit: true }
+                            : {}),
+                        ...(structuredLaunch ? { refuseExisting: true } : {}),
+                        sessionClass,
+                    }));
+                }
                 else {
-                    h2aSidecarStarted = startH2aWindow(name, cwd, h2a.command);
+                    ({ name, slug, agentPane } = startLocalSession(profile, command, cwd, args, label, getTmuxProfileConfig().profile, {
+                        ...(opts.resume !== undefined
+                            ? { resumeId: opts.resume }
+                            : {}),
+                        ...(h2aSidecar ? { h2aCommand: h2a.command } : {}),
+                        ...(initialPrompt !== undefined
+                            ? { terminateOnAgentExit: true }
+                            : {}),
+                        ...(structuredLaunch ? { refuseExisting: true } : {}),
+                        attachedTerminal: opts.attachedTerminal !== false,
+                        sessionClass,
+                    }));
                 }
-                if (!h2aSidecarStarted && structuredLaunch) {
+                if (structuredLaunch && sessionHost !== "native" && !agentPane) {
                     cleanupHeadlessPromptFile(promptFile);
                     // OWN-CLEANUP, deliberately NOT resolver-derived (F1 sorting):
-                    // this kills the session THIS command just created on the host
-                    // it chose; the resolver could refuse and leak the partial.
+                    // `name` is the session THIS command just created above, on the
+                    // host it chose. Re-resolving could return missing/unknown and
+                    // refuse — leaking the partial session it exists to remove.
                     killLocalSession(name);
-                    process.stderr.write(`[h2a] required h2a sidecar failed for ${slug}; the partial session was stopped\n`);
+                    process.stderr.write(`[h2a] could not capture the exact agent pane for ${slug}; the partial session was stopped\n`);
                     process.exitCode = 1;
                     return;
                 }
-                if (h2aSidecarStarted) {
-                    process.stderr.write(`[h2a] h2a window started in ${slug} (${h2a.command})\n`);
-                }
-            }
-            if (!opts.headless && initialPrompt !== undefined) {
-                // NEVER paste-and-hope: `tmux new-session -d` returns before the
-                // agent TUI draws anything, and a prompt sent into that window is
-                // echoed by the raw terminal and then discarded. Delivery is
-                // OBSERVED — brief seen in a real composer, then real work — because
-                // reporting "started" over a lost brief is what left a lane inert
-                // for 33 minutes on 2026-07-28.
-                promptDelivery = sessionHost === "native"
-                    ? deliverInitialPrompt(name, initialPrompt, nativePromptDeliveryDeps(sleepSync))
-                    : deliverInitialPrompt(agentPane, initialPrompt, {
-                        capturePane: capturePaneVisible,
-                        clearComposer: clearPaneComposer,
-                        pasteBlock: pasteLiteralBlock,
-                        submit: submitPane,
-                        cpuMs: paneTreeCpuMs,
-                        sleep: sleepSync,
-                        now: () => Date.now(),
+                let h2aSidecarStarted = false;
+                if (h2aSidecar && sessionHost === "native") {
+                    h2aSidecarStarted = startNativeH2aSidecar(name, cwd, h2a.command, {
+                        ...(structuredLaunch ? { verified: true } : {}),
                     });
-                if (promptDelivery.state !== "working") {
+                    if (!h2aSidecarStarted && structuredLaunch) {
+                        cleanupHeadlessPromptFile(promptFile);
+                        // OWN-CLEANUP, deliberately NOT resolver-derived (F1 sorting):
+                        // this kills the session THIS command just created on the host
+                        // it chose; the resolver could refuse and leak the partial.
+                        killNativeSessionTree(name);
+                        process.stderr.write(`[h2a] required h2a sidecar failed for ${slug}; the partial session was stopped\n`);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    if (h2aSidecarStarted) {
+                        process.stderr.write(`[h2a] h2a sidecar session started for ${slug} (${h2a.command})\n`);
+                    }
+                }
+                else if (h2aSidecar) {
+                    if (structuredLaunch) {
+                        try {
+                            h2aSidecarStarted = Boolean(await startH2aWindowVerified(name, cwd, h2a.command, agentPane));
+                        }
+                        catch (error) {
+                            process.stderr.write(`[h2a] required h2a sidecar verification failed: ${error.message}\n`);
+                            h2aSidecarStarted = false;
+                        }
+                    }
+                    else {
+                        h2aSidecarStarted = startH2aWindow(name, cwd, h2a.command);
+                    }
+                    if (!h2aSidecarStarted && structuredLaunch) {
+                        cleanupHeadlessPromptFile(promptFile);
+                        // OWN-CLEANUP, deliberately NOT resolver-derived (F1 sorting):
+                        // this kills the session THIS command just created on the host
+                        // it chose; the resolver could refuse and leak the partial.
+                        killLocalSession(name);
+                        process.stderr.write(`[h2a] required h2a sidecar failed for ${slug}; the partial session was stopped\n`);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    if (h2aSidecarStarted) {
+                        process.stderr.write(`[h2a] h2a window started in ${slug} (${h2a.command})\n`);
+                    }
+                }
+                if (!opts.headless && initialPrompt !== undefined) {
+                    // NEVER paste-and-hope: `tmux new-session -d` returns before the
+                    // agent TUI draws anything, and a prompt sent into that window is
+                    // echoed by the raw terminal and then discarded. Delivery is
+                    // OBSERVED — brief seen in a real composer, then real work — because
+                    // reporting "started" over a lost brief is what left a lane inert
+                    // for 33 minutes on 2026-07-28.
+                    promptDelivery = sessionHost === "native"
+                        ? deliverInitialPrompt(name, initialPrompt, nativePromptDeliveryDeps(sleepSync))
+                        : deliverInitialPrompt(agentPane, initialPrompt, {
+                            capturePane: capturePaneVisible,
+                            clearComposer: clearPaneComposer,
+                            pasteBlock: pasteLiteralBlock,
+                            submit: submitPane,
+                            cpuMs: paneTreeCpuMs,
+                            sleep: sleepSync,
+                            now: () => Date.now(),
+                        });
+                    if (promptDelivery.state !== "working") {
+                        cleanupHeadlessPromptFile(promptFile);
+                        // Only claim the session is gone when the kill actually reported
+                        // success. "nothing is left running" over an unchecked call is the
+                        // same wider-than-its-evidence claim this change exists to remove,
+                        // and a surviving partial session is precisely the idle lane the
+                        // operator was just told could not happen.
+                        // OWN-CLEANUP, deliberately NOT resolver-derived (F1 sorting):
+                        // `name`/`sessionHost` are the session and host THIS command
+                        // just created; re-resolving could refuse and leak the partial.
+                        const stopped = sessionHost === "native"
+                            ? killNativeSessionTree(name)
+                            : killLocalSession(name);
+                        const detail = promptDelivery.state === "submitted-idle"
+                            ? `the brief was submitted but the agent never started working ` +
+                                `(${Math.round(promptDelivery.cpuDeltaMs)}ms of CPU): it is not "started"`
+                            : promptDelivery.reason;
+                        process.stderr.write(`[h2a] the initial prompt did not reach ${slug}: ${detail}\n` +
+                            (promptDelivery.state === "host-modal"
+                                ? `[h2a] fix: ${promptDelivery.hint}\n`
+                                : "") +
+                            (stopped
+                                ? `[h2a] the partial session was stopped, so nothing is left running idle\n`
+                                : `[h2a] WARNING: stopping the partial session FAILED — ${name} may still be alive; ` +
+                                    `list it with h2a ls and stop it with h2a stop ${slug} --reason failed-launch\n`) +
+                            (promptDelivery.state !== "submitted-idle" &&
+                                promptDelivery.capture
+                                ? `[h2a] last screen:\n${promptDelivery.capture}\n`
+                                : ""));
+                        process.exitCode = 1;
+                        return;
+                    }
+                }
+                const pid = sessionHost === "native"
+                    ? nativeSessionPid(name)
+                    : agentPane
+                        ? localSessionPanePid(agentPane)
+                        : undefined;
+                const workerPid = sessionHost === "native"
+                    ? nativeWorkerPid(name)
+                    : agentPane !== undefined
+                        ? paneWorkerPid(agentPane)
+                        : undefined;
+                if (structuredLaunch && pid === undefined) {
                     cleanupHeadlessPromptFile(promptFile);
-                    // Only claim the session is gone when the kill actually reported
-                    // success. "nothing is left running" over an unchecked call is the
-                    // same wider-than-its-evidence claim this change exists to remove,
-                    // and a surviving partial session is precisely the idle lane the
-                    // operator was just told could not happen.
                     // OWN-CLEANUP, deliberately NOT resolver-derived (F1 sorting):
                     // `name`/`sessionHost` are the session and host THIS command
                     // just created; re-resolving could refuse and leak the partial.
-                    const stopped = sessionHost === "native"
-                        ? killNativeSessionTree(name)
-                        : killLocalSession(name);
-                    const detail = promptDelivery.state === "submitted-idle"
-                        ? `the brief was submitted but the agent never started working ` +
-                            `(${Math.round(promptDelivery.cpuDeltaMs)}ms of CPU): it is not "started"`
-                        : promptDelivery.reason;
-                    process.stderr.write(`[h2a] the initial prompt did not reach ${slug}: ${detail}\n` +
-                        (promptDelivery.state === "host-modal"
-                            ? `[h2a] fix: ${promptDelivery.hint}\n`
-                            : "") +
-                        (stopped
-                            ? `[h2a] the partial session was stopped, so nothing is left running idle\n`
-                            : `[h2a] WARNING: stopping the partial session FAILED — ${name} may still be alive; ` +
-                                `list it with h2a ls and stop it with h2a stop ${slug} --reason failed-launch\n`) +
-                        (promptDelivery.state !== "submitted-idle" &&
-                            promptDelivery.capture
-                            ? `[h2a] last screen:\n${promptDelivery.capture}\n`
-                            : ""));
+                    if (sessionHost === "native")
+                        killNativeSessionTree(name);
+                    else
+                        killLocalSession(name);
+                    process.stderr.write(`[h2a] could not verify the agent pane pid for ${slug}; the partial session was stopped\n`);
                     process.exitCode = 1;
                     return;
                 }
+                // Auto-enroll in the live-session registry (feeds `h2a ls`/`restore`).
+                // Pin the gateway posture ONLY when the user was explicit (--gw/--no-gw);
+                // an "auto" launch stays unpinned so restore follows the live default.
+                enrollFromRun({
+                    profile,
+                    slug,
+                    tmuxSession: name,
+                    // The ACTUAL host that just started the terminal — never a default.
+                    hostKind: sessionHost === "native" ? "local-native" : "local-tmux",
+                    ...(pid !== undefined ? { pid } : {}),
+                    ...(workerPid !== undefined ? { workerPid } : {}),
+                    cwd,
+                    sessionClass,
+                    ...(opts.resume !== undefined ? { convId: opts.resume } : {}),
+                    ...(gatewayMode !== "auto" ? { gatewayMode } : {}),
+                });
+                started.push({
+                    name,
+                    slug,
+                    ...(agentPane !== undefined ? { pane: agentPane } : {}),
+                    h2aSidecar: h2aSidecarStarted,
+                    ...(pid !== undefined ? { pid } : {}),
+                    ...(outputLog !== undefined ? { outputLog } : {}),
+                    ...(resultJson !== undefined ? { resultJson } : {}),
+                    ...(promptDelivery !== undefined ? { promptDelivery } : {}),
+                });
+                // The writer is now durable in the registry. End the short critical
+                // section before a foreground attach can keep this command alive.
+                resumeClaim?.release();
             }
-            const pid = sessionHost === "native"
-                ? nativeSessionPid(name)
-                : agentPane
-                    ? localSessionPanePid(agentPane)
-                    : undefined;
-            const workerPid = sessionHost === "native"
-                ? nativeWorkerPid(name)
-                : agentPane !== undefined
-                    ? paneWorkerPid(agentPane)
-                    : undefined;
-            if (structuredLaunch && pid === undefined) {
-                cleanupHeadlessPromptFile(promptFile);
-                // OWN-CLEANUP, deliberately NOT resolver-derived (F1 sorting):
-                // `name`/`sessionHost` are the session and host THIS command
-                // just created; re-resolving could refuse and leak the partial.
-                if (sessionHost === "native")
-                    killNativeSessionTree(name);
-                else
-                    killLocalSession(name);
-                process.stderr.write(`[h2a] could not verify the agent pane pid for ${slug}; the partial session was stopped\n`);
-                process.exitCode = 1;
-                return;
+            if (count > 1) {
+                process.stderr.write(`[h2a] ${started.length} ${profile} agents started in ${cwd}: ${started.map((s) => s.slug).join(", ")}\n` +
+                    `[h2a] attach one with: h2a attach <slug>\n`);
+                return; // never auto-attach a fleet
             }
-            // Auto-enroll in the live-session registry (feeds `h2a ls`/`restore`).
-            // Pin the gateway posture ONLY when the user was explicit (--gw/--no-gw);
-            // an "auto" launch stays unpinned so restore follows the live default.
-            enrollFromRun({
-                profile,
-                slug,
-                tmuxSession: name,
-                // The ACTUAL host that just started the terminal — never a default.
-                hostKind: sessionHost === "native" ? "local-native" : "local-tmux",
-                ...(pid !== undefined ? { pid } : {}),
-                ...(workerPid !== undefined ? { workerPid } : {}),
-                cwd,
-                sessionClass,
-                ...(opts.resume !== undefined ? { convId: opts.resume } : {}),
-                ...(gatewayMode !== "auto" ? { gatewayMode } : {}),
-            });
-            started.push({
-                name,
-                slug,
-                ...(agentPane !== undefined ? { pane: agentPane } : {}),
-                h2aSidecar: h2aSidecarStarted,
-                ...(pid !== undefined ? { pid } : {}),
-                ...(outputLog !== undefined ? { outputLog } : {}),
-                ...(resultJson !== undefined ? { resultJson } : {}),
-                ...(promptDelivery !== undefined ? { promptDelivery } : {}),
-            });
-        }
-        if (count > 1) {
-            process.stderr.write(`[h2a] ${started.length} ${profile} agents started in ${cwd}: ${started.map((s) => s.slug).join(", ")}\n` +
-                `[h2a] attach one with: h2a attach <slug>\n`);
-            return; // never auto-attach a fleet
-        }
-        const only = started[0];
-        if (opts.json) {
-            process.stdout.write(`${JSON.stringify({
-                kind: "h2a.run.result",
-                version: 1,
-                apiVersion: H2A_RUN_API_VERSION,
-                runtimeVersion: H2A_RUNTIME_VERSION,
-                ok: true,
-                state: "started",
-                session: {
-                    id: only.slug,
-                    tmuxSession: only.name,
-                    host: sessionHost === "native" ? "native" : "tmux",
-                    profile,
-                    workspace: cwd,
-                    mode: opts.headless ? "headless" : "interactive",
-                    background: opts.background === true,
-                    gateway: activeGateway ? "gateway" : "direct",
-                    h2aSidecar: only.h2aSidecar,
-                    ...(only.pane !== undefined ? { pane: only.pane } : {}),
-                    ...(only.pid !== undefined ? { pid: only.pid } : {}),
-                    // `pid` is the launch WRAPPER. Measured 2026-07-29: it showed 0s
-                    // of CPU after 37s while its codex child had burned 13s, so a
-                    // liveness check on `pid` alone reports a working agent as dead.
-                    // Name the process that actually works, and say it is distinct.
-                    ...(only.workerPid !== undefined
-                        ? { workerPid: only.workerPid }
+            const only = started[0];
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify({
+                    kind: "h2a.run.result",
+                    version: 1,
+                    apiVersion: H2A_RUN_API_VERSION,
+                    runtimeVersion: H2A_RUNTIME_VERSION,
+                    ok: true,
+                    state: "started",
+                    session: {
+                        id: only.slug,
+                        tmuxSession: only.name,
+                        host: sessionHost === "native" ? "native" : "tmux",
+                        profile,
+                        workspace: cwd,
+                        mode: opts.headless ? "headless" : "interactive",
+                        background: opts.background === true,
+                        gateway: activeGateway ? "gateway" : "direct",
+                        h2aSidecar: only.h2aSidecar,
+                        ...(only.pane !== undefined ? { pane: only.pane } : {}),
+                        ...(only.pid !== undefined ? { pid: only.pid } : {}),
+                        // `pid` is the launch WRAPPER. Measured 2026-07-29: it showed 0s
+                        // of CPU after 37s while its codex child had burned 13s, so a
+                        // liveness check on `pid` alone reports a working agent as dead.
+                        // Name the process that actually works, and say it is distinct.
+                        ...(only.workerPid !== undefined
+                            ? { workerPid: only.workerPid }
+                            : {}),
+                    },
+                    attach: opts.headless
+                        ? null
+                        : { command: "h2a", args: ["attach", only.slug] },
+                    // What was OBSERVED, not what was attempted: the brief was seen in
+                    // a real composer, submitted, and the agent's CPU then moved.
+                    ...(only.promptDelivery?.state === "working"
+                        ? {
+                            prompt: {
+                                delivered: true,
+                                waitedMs: only.promptDelivery.waitedMs,
+                                cpuDeltaMs: Math.round(only.promptDelivery.cpuDeltaMs),
+                            },
+                        }
                         : {}),
-                },
-                attach: opts.headless
-                    ? null
-                    : { command: "h2a", args: ["attach", only.slug] },
-                // What was OBSERVED, not what was attempted: the brief was seen in
-                // a real composer, submitted, and the agent's CPU then moved.
-                ...(only.promptDelivery?.state === "working"
-                    ? {
-                        prompt: {
-                            delivered: true,
-                            waitedMs: only.promptDelivery.waitedMs,
-                            cpuDeltaMs: Math.round(only.promptDelivery.cpuDeltaMs),
-                        },
-                    }
-                    : {}),
-                ...(only.outputLog !== undefined
-                    ? {
-                        logs: { path: only.outputLog },
-                        result: { path: only.resultJson },
-                    }
-                    : {}),
-            })}\n`);
+                    ...(only.outputLog !== undefined
+                        ? {
+                            logs: { path: only.outputLog },
+                            result: { path: only.resultJson },
+                        }
+                        : {}),
+                })}\n`);
+                return;
+            }
+            process.stderr.write(`[h2a] local session ${only.slug} started (${profile}${opts.resume ? ` --resume ${opts.resume}` : ""} in ${cwd})\n`);
+            // Single local runs hand off the terminal by default: there is no value
+            // in making users type a second `h2a attach <slug>` command. Commander
+            // sets opts.attach=false only for --no-attach.
+            if (opts.attach === false) {
+                process.stderr.write(`[h2a] attach with: h2a attach ${only.slug}\n`);
+                return;
+            }
+            process.exitCode =
+                sessionHost === "native"
+                    ? attachNativeSession(only.name)
+                    : attachLocalSession(only.name);
             return;
         }
-        process.stderr.write(`[h2a] local session ${only.slug} started (${profile}${opts.resume ? ` --resume ${opts.resume}` : ""} in ${cwd})\n`);
-        // Single local runs hand off the terminal by default: there is no value
-        // in making users type a second `h2a attach <slug>` command. Commander
-        // sets opts.attach=false only for --no-attach.
-        if (opts.attach === false) {
-            process.stderr.write(`[h2a] attach with: h2a attach ${only.slug}\n`);
-            return;
+        finally {
+            resumeClaim?.release();
         }
-        process.exitCode =
-            sessionHost === "native"
-                ? attachNativeSession(only.name)
-                : attachLocalSession(only.name);
-        return;
     });
     // ---------------------------------------------------------------------------
     // delegate — spawn a cross-type agent (claude/codex/agy) as a LOCAL job (P1)