@sentropic/h2a-runtime 0.98.7-rc.1 → 0.98.7-rc.10

package/dist/index.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Command, Help } from "commander";
+import { resolveSeatEnrollmentProvider } from "./cli-seat-codecs.js";
+import { agyClaudeQuotaError, assertAgyClaudeBuildAllowed, detectAgyClaudeQuotaExhaustion, isAgyClaudeModel, normalizeAgyEffort, readAgyClaudeQuotaStatus, resolveAgyModel, writeAgyClaudeQuotaStatus } from "./agy-claude.js";
 import { applyRuntimeHelpGroups, groupRuntimeHelpItems, } from "./cli-help-groups.js";
 import { attach, createRemoteSession, getRemoteSession, listRemoteSessions, refreshRemoteSession, renameRemoteSession, sessionTerminalHealth, stopRemoteSession, } from "./attach.js";
 import { authHeaders, clearDefaultRemote, getDefaultRemote, getDefaultTarget, getDefaultTools, getH2aConfig, getJobMaxAgeHours, getMaxConcurrent, getLlmMeshRuntimeConfig, getTmuxProfileConfig, getTunnel, resolveConfigPath, setDefaultRemote, setDefaultTarget, migrateConfigHomeIfNeeded, setDefaultTools, setLlmMeshRuntimeConfig, setTmuxProfileConfig, setToken, setTunnel, } from "./config.js";
@@ -22,13 +24,14 @@ import { attachLocalSession, attachPodTmux, capturePane, capturePaneVisible, cle
 import { deliverInitialPrompt, sleepSync, } from "./prompt-delivery.js";
 import { startLaunchGuard } from "./launch-guard.js";
 import { buildLaunchContext } from "./launch-context.js";
-import { attachNativeSession, driveNativeInstruction, killNativeSessionIfIncarnation, killNativeSessionTree, nativeHostAvailable, nativePromptDeliveryDeps, nativeSessionLiveness, nativeSessionPid, nativeSessionState, nativeTreeCpuMs, nativeWorkerPid, preflightNativeLaunch, resolveSessionHostKind, startNativeH2aSidecar, startNativeHeadlessSession, startNativeSession, NativeHostCapabilityMismatchError, NativeLaunchAdmissionError, } from "./native-host.js";
+import { attachNativeSession, driveNativeInstruction, killNativeSessionIfIncarnation, killNativeSessionTree, nativeHostAvailable, nativePromptDeliveryDeps, nativeSessionLiveness, nativeSessionPid, nativeSessionState, nativeSessionStateAsync, nativeTreeCpuMs, nativeWorkerPid, preflightNativeLaunch, resolveSessionHostKind, startNativeH2aSidecar, startNativeHeadlessSession, startNativeSession, startNativeSessionSingleShot, NativeHostCapabilityMismatchError, NativeLaunchAdmissionError, } from "./native-host.js";
 import { executeNativeRestart, NativeRestartError, } from "./native-restart.js";
 import { migrateTmuxNames } from "./tmux-name-migration.js";
 import { projectStatusForH2a } from "./status-projection.js";
 import { buildAgentLaunchArgs, buildAgentLaunchStdin, isAgentLaunchEffort, isAgentLaunchProfile, } from "./agent-launch-args.js";
+import { resolveGatewayModelAlias } from "./gateway-model-catalog/model-catalog.js";
 import { deriveSessionClass } from "./session-class.js";
-import { isRelaunchKillable, planRelaunch, relaunchContinuationPrompt, tryAcquireResumeLaunchClaim, wakeRelaunchedSession, } from "./relaunch.js";
+import { isRelaunchKillable, planRelaunch, relaunchContinuationPrompt, scrubbedRetypeCommand, prepareGatewayRetypeCommand, tryAcquireResumeLaunchClaim, wakeRelaunchedSession, } from "./relaunch.js";
 import { isHumanFacingSession, legacySessionEvidence, readConversationCustomTitle, readLastLayout, reconcileRunConvIds, restore as restoreLayout, } from "./restore.js";
 import { getLayoutConfig } from "./config.js";
 import { resolvePinnedLaunchEntries } from "./resume-launch-options.js";
@@ -42,7 +45,11 @@ import { DEFAULT_FANOUT_MAX, mapWithConcurrency, planRemoteFanout, } from "./fan
 import { authenticateJobEnvelopes, buildDecisionReply, dropEnvelope, emitJobDone, envelopeFileName, isAwaitingDecision, jobInstance, parentInstance, pendingDecisions, readInboxEnvelopes, renderPendingDecisions, repliedDecisionJobIds, } from "./h2a-jobs.js";
 import { buildConductorTask, computeDurableWorkspaceId, normalizeRootCommits, detectAvailableHosts, freshestLaunchEnvelope, h2aReportsLiveConductor, markLaunchEnvelopeProcessed, readLastLaunchAt, readLaunchEnvelopes, recordLaunchAt, selectHost, shouldLaunch, } from "./conductor-launch.js";
 import { defaultLocalH2aRoot } from "./h2a-bridge.js";
-import { refuseCullExecution, runIdentityCullDryRun } from "./identity-cull/cull.js";
+import { operatorBreak as operatorBreakToCore } from "./identity-operator-break.js";
+// identity-cull is imported lazily at its verb below: cull.js needs the
+// core identity fence (`@sentropic/h2a`), which must never become a
+// load-time edge of this barrel — isolated installs of this package have
+// no core beside them.
 import { guardConvWriters } from "./conv-guard.js";
 import { handleClaudeHook, installClaudeHooks, manualEnroll, readStdin, } from "./enroll.js";
 import { probePodCredHealth, softRefreshSession } from "./soft-refresh.js";
@@ -74,8 +81,7 @@ 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, removeAccountViaFacade, } from "./llm-mesh-accounts.js";
+import { CLI_PROFILES, gatewayModeForProfile, profileUsesLlmMeshGateway, resolveResumedGatewayMode, } from "./protocol-local.js";
 import { readLlmMeshConfig, updateLlmMeshRoutingConfig, } from "./gateway-host/config-file.js";
 import { startGateway, stopGateway, readGatewayPid, llmMeshLogPath, replaceAnthropicGatewayEnvironment, acquireLlmMeshSessionEnv, } from "./gateway-host/daemon.js";
 import { describeLlmMeshRoutingConfig, parseLlmMeshRoutingConfig, preferredRoutingConfig, strategyRoutingConfig, } from "./routing-preferences.js";
@@ -135,6 +141,7 @@ async function startRemoteFanout(remote, profileName, members, spec) {
                 ? { startupArgs: spec.startupArgs }
                 : {}),
             ...(spec.credentials ? { credentials: spec.credentials } : {}),
+            ...(spec.llmGateway === true ? { llmGateway: true } : {}),
         });
         return { name: member.name, sessionId: session.id, workspaceId: ws.id };
     });
@@ -200,6 +207,20 @@ async function runProfile(profileName, opts, commandArgs = []) {
         if (opts.resume !== undefined && resumeArgs.length === 0) {
             throw new Error(`profile "${profileName}" has no verified resume argv; start it without -r/--resume`);
         }
+        // Remote sessions are direct unless the gateway is explicitly asked for.
+        // Only an explicit --gw/--llm-gateway transmits the opt-in; the server
+        // ignores a globally configured gateway URL without it.
+        let remoteGatewayMode;
+        try {
+            remoteGatewayMode = gatewayModeFromOptions(opts);
+        }
+        catch (error) {
+            throw new Error(`[h2a] ${error.message}.`);
+        }
+        if (remoteGatewayMode === "gateway" && !profileUsesLlmMeshGateway(profileName)) {
+            throw new Error(`[h2a] --llm-gateway/--gw is unsupported for ${profileName}; this gateway is Anthropic-compatible and only Claude profiles consume it.`);
+        }
+        const remoteGatewayChoice = remoteGatewayMode === "gateway" ? { llmGateway: true } : {};
         const startupArgs = [...resumeArgs, ...commandArgs];
         // WP6 — REMOTE fan-out: --count N spawns N concurrent remote sessions, each
         // on its OWN workspace subPath of the shared RWX volume. count<=1 falls
@@ -229,6 +250,7 @@ async function runProfile(profileName, opts, commandArgs = []) {
                 target: opts.target,
                 startupArgs,
                 ...(credentials ? { credentials } : {}),
+                ...remoteGatewayChoice,
             });
             return;
         }
@@ -247,6 +269,7 @@ async function runProfile(profileName, opts, commandArgs = []) {
             ...(opts.workspaceId ? { workspaceId: opts.workspaceId } : {}),
             ...(opts.browser ? { metadata: { browser: true } } : {}),
             ...(opts.agentImage ? { agentImage: opts.agentImage } : {}),
+            ...remoteGatewayChoice,
         });
         if (archive) {
             await uploadWorkspaceArchive(opts.remote, session.id, archive);
@@ -270,7 +293,21 @@ async function runProfile(profileName, opts, commandArgs = []) {
         ...(opts.port !== undefined ? { port: opts.port } : {}),
         ...(commandArgs.length > 0 ? { startupArgs: commandArgs } : {}),
     };
-    const result = await run(runOptions);
+    const gatewayMode = gatewayModeFromOptions(opts);
+    if (gatewayMode === "gateway" && !profileUsesLlmMeshGateway(profileName)) {
+        throw new Error(`--llm-gateway/--gw is unsupported for ${profileName}`);
+    }
+    // Resolve local PTY routing before spawning, just as for managed sessions.
+    // Restore the caller's native auth even if acquisition or spawning fails.
+    const restoreEnv = replaceAnthropicGatewayEnvironment(process.env, captureAnthropicGatewayEnvironment());
+    let result;
+    try {
+        await injectLlmMeshGatewayEnv(gatewayMode, false);
+        result = await run({ ...runOptions, gatewayMode: gatewayMode === "gateway" ? "gateway" : "direct" });
+    }
+    finally {
+        restoreEnv();
+    }
     process.stderr.write(`[h2a] session ${result.sessionId} attach at http://127.0.0.1:${result.port}\n`);
     const { exitCode } = await result.exit;
     process.exitCode = exitCode;
@@ -852,32 +889,12 @@ export async function startJob(job) {
     const prevJobId = process.env[JOB_ID_ENV];
     process.env[DEPTH_ENV] = childDepthEnvValue(job.depthBudget ?? clampDepth(undefined));
     process.env[JOB_ID_ENV] = job.id;
-    // Inject llm-mesh gateway env if running. Do not trust a parent env that may
-    // contain an old gateway token from a previous restart.
-    // tmux inherits process.env, so claude + its subagents all get the gateway automatically.
-    const jobSessionSlug = slugify(job.id);
-    const jobSessionResolution = resolveLocalSession(jobSessionSlug);
-    const gatewayClientSessionId = jobSessionResolution.kind === "found"
-        ? jobSessionResolution.session.name
-        : jobSessionResolution.kind === "missing"
-            ? localSessionName(jobSessionSlug)
-            : undefined;
-    let meshEnv;
-    try {
-        meshEnv =
-            profileUsesLlmMeshGateway(job.tool) &&
-                getLlmMeshRuntimeConfig().enabled &&
-                gatewayClientSessionId
-                ? await acquireLlmMeshSessionEnv(undefined, gatewayClientSessionId)
-                : null;
-    }
-    catch (error) {
-        return {
-            started: false,
-            error: error instanceof Error ? error.message : String(error),
-        };
-    }
-    const restoreGatewayEnvironment = replaceAnthropicGatewayEnvironment(process.env, meshEnv ?? undefined);
+    // Gateway off unless explicitly asked: jobs never acquire the gateway.
+    // A legacy llmMesh.enabled=true, a running service, enrolled accounts or a
+    // parent env never select gateway routing for immediate or deferred jobs.
+    // Strip any stale h2a routing vars so the child starts direct; a user-owned
+    // ANTHROPIC_API_KEY survives for native authentication.
+    const restoreGatewayEnvironment = replaceAnthropicGatewayEnvironment(process.env, undefined);
     let tmuxSession;
     let workerPid;
     let agentPane;
@@ -1399,13 +1416,12 @@ export function bareChoiceFromOptions(opts) {
         return false;
     return undefined;
 }
-async function injectLlmMeshGatewayEnv(mode = "auto", allowDirectFallback = true, clientSessionId) {
-    if (mode === "direct") {
-        delete process.env.ANTHROPIC_BASE_URL;
-        delete process.env.ANTHROPIC_AUTH_TOKEN;
-        return undefined;
-    }
-    if (mode !== "gateway" && !getLlmMeshRuntimeConfig().enabled) {
+export async function injectLlmMeshGatewayEnv(mode = "auto", allowDirectFallback = true, clientSessionId) {
+    if (mode !== "gateway") {
+        // Gateway off unless explicitly asked: auto resolves to direct BEFORE any
+        // acquire/start. A legacy llmMesh.enabled=true, a running service, enrolled
+        // accounts or a parent env never select gateway routing. A user-owned
+        // ANTHROPIC_API_KEY is preserved for native authentication.
         delete process.env.ANTHROPIC_BASE_URL;
         delete process.env.ANTHROPIC_AUTH_TOKEN;
         return undefined;
@@ -1436,7 +1452,7 @@ async function injectLlmMeshGatewayEnv(mode = "auto", allowDirectFallback = true
         delete process.env.ANTHROPIC_BASE_URL;
         delete process.env.ANTHROPIC_AUTH_TOKEN;
         if (mode === "gateway") {
-            throw new Error("llm-mesh gateway is required but unavailable; no agent was started. Run `h2a llm-mesh start` or `h2a llm-mesh account enroll codex|cloud-code|muse` first");
+            throw new Error("llm-mesh gateway is required but unavailable; no agent was started. Run `h2a llm-mesh start` or `h2a llm-mesh account enroll codex|cloud-code|muse|claude-code` first");
         }
         if (allowDirectFallback) {
             process.stderr.write("[h2a] llm-mesh: gateway unavailable; continuing with native authentication.\n");
@@ -1518,7 +1534,7 @@ function renderNativeRestartResult(result, json) {
 export async function prepareStructuredGateway(mode, inject = (selectedMode) => injectLlmMeshGatewayEnv(selectedMode, selectedMode !== "gateway")) {
     const gateway = await inject(mode);
     if (mode === "gateway" && !gateway) {
-        throw new Error("llm-mesh gateway is required but unavailable; no agent was started. Run `h2a llm-mesh start` or `h2a llm-mesh account enroll codex|cloud-code|muse` first");
+        throw new Error("llm-mesh gateway is required but unavailable; no agent was started. Run `h2a llm-mesh start` or `h2a llm-mesh account enroll codex|cloud-code|muse|claude-code` first");
     }
     return gateway;
 }
@@ -1529,7 +1545,9 @@ export async function prepareLlmMeshForRestore(opts = {}, context = {
     injectGateway: (mode) => injectLlmMeshGatewayEnv(mode, mode !== "gateway"),
 }) {
     const mode = opts.mode ?? "auto";
-    if (mode !== "gateway" && !context.runtimeEnabled)
+    // Global enablement is not restore consent. Pinned sessions request --gw
+    // individually through their launch command; only --gw prewarms globally.
+    if (mode !== "gateway")
         return;
     const config = context.config ?? {};
     const port = config.port ?? 3002;
@@ -1720,6 +1738,40 @@ function setAndReportDefaultRemote(url) {
     ensureManagedTmuxProfile(getTmuxProfileConfig().profile);
     process.stderr.write(`[h2a] default remote set to ${configured}\n`);
 }
+// Root commander error boundary (DEC-119): commander never prints its own
+// error text. `outputError` is a no-op so the commander-built message (which
+// echoes argv, possibly multi-line) is dropped; `exitOverride` writes a
+// static message chosen ONLY from `err.code` — never `err.message`, never
+// user-typed text. Registered on the ROOT program before any `.command()`
+// so the whole tree inherits it via `copyInheritedSettings`.
+function staticCommanderErrorForCode(code) {
+    switch (code) {
+        case "commander.unknownOption":
+            return "error: unknown option\n";
+        case "commander.unknownCommand":
+            return "error: unknown command\n";
+        case "commander.excessArguments":
+            return "error: too many arguments\n";
+        case "commander.missingArgument":
+            return "error: missing required argument\n";
+        case "commander.optionMissingArgument":
+            return "error: option argument missing\n";
+        case "commander.missingMandatoryOptionValue":
+            return "error: required option not specified\n";
+        case "commander.conflictingOption":
+            return "error: conflicting option\n";
+        case "commander.invalidArgument":
+            return "error: invalid argument\n";
+        default:
+            return "error: command error\n";
+    }
+}
+function isCommanderNonErrorCode(code) {
+    return (code === "commander.help" ||
+        code === "commander.helpDisplayed" ||
+        code === "commander.version" ||
+        code === "commander.executeSubCommandAsync");
+}
 export async function main(argv) {
     // Passive fatal-path witness on the real entry path (see
     // installCliWitnessOnce): observes via uncaughtExceptionMonitor, so the
@@ -1773,22 +1825,34 @@ export async function main(argv) {
         "the separate remote and track CLIs. The heavy session runtime loads on " +
         "demand. h2a runs and coordinates agents; it is not itself an agent.")
         .version("0.0.0");
+    // Root error boundary (DEC-119): commander never prints its own error
+    // text. `outputError` is a no-op (commander message dropped);
+    // `exitOverride` writes the static per-code message. Registered here —
+    // before any `.command()` — so the whole tree inherits it through
+    // `copyInheritedSettings`.
+    program.configureOutput({
+        writeErr: (str) => {
+            process.stderr.write(str);
+        },
+        outputError: () => { },
+    });
+    program.showHelpAfterError(false);
+    program.showSuggestionAfterError(false);
+    program.exitOverride((err) => {
+        if (isCommanderNonErrorCode(err.code))
+            throw err;
+        process.stderr.write(staticCommanderErrorForCode(err.code));
+        throw err;
+    });
     const identityCommand = program
         .command("identity")
         .description("Inspect identity bindings or unlock a token-fenced identity lock");
-    const operatorBreak = async (lockPath, token, assertDead) => {
-        const { breakLockAsOperator, breakIdentityLockAsOperator } = await import("@sentropic/h2a");
-        const identityLock = basename(lockPath) === '.lock' && basename(dirname(lockPath)) === 'identity';
-        const breaker = identityLock ? breakIdentityLockAsOperator : breakLockAsOperator;
-        const result = breaker(lockPath, { expectToken: token, assertDead });
-        process.stdout.write(`${JSON.stringify({ path: identityLock ? 'identity/.lock' : lockPath, ...result })}\n`);
-        if (!result.broken) {
-            process.stderr.write(`[h2a] lock break refused: ${result.reason}${result.pid !== undefined ? ` (pid ${result.pid})` : ""}\n`);
-            if (result.reason === "assert-dead-required") {
-                process.stderr.write("[h2a] verify the holder has stopped, then explicitly pass --assert-dead; no PID is killed\n");
-            }
-            process.exitCode = 1;
-        }
+    // Operator break delegates to the core CLI's hidden `__operator-break`
+    // plumbing (same `h2a`-binary spawn pattern as central-mcp): this package
+    // must not import `@sentropic/h2a`, and the relay keeps stdio/exit codes
+    // byte-for-byte identical where core is installed.
+    const operatorBreak = (lockPath, token, assertDead) => {
+        operatorBreakToCore(lockPath, token, assertDead, (code) => { process.exitCode = code; });
     };
     identityCommand
         .command("unlock")
@@ -1818,9 +1882,18 @@ export async function main(argv) {
         .option("--execute", "refuse destructive execution; no bypass exists")
         .option("--root <path>", "DEF h2a root (default: H2A_ROOT or ~/h2a-workspace/.h2a)")
         .option("--output <path>", "new external directory for the proof packet")
-        .action((opts) => {
+        .action(async (opts) => {
+        let cull;
+        try {
+            cull = await import("./identity-cull/cull.js");
+        }
+        catch (error) {
+            process.stderr.write(`[h2a] identity cull unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+            return;
+        }
         if (opts.execute) {
-            const refusal = refuseCullExecution();
+            const refusal = cull.refuseCullExecution();
             process.stderr.write(`[h2a] identity cull refused: ${refusal.refusalCodes.join(", ")}\n`);
             process.exitCode = 2;
             return;
@@ -1828,7 +1901,7 @@ export async function main(argv) {
         const defRoot = opts.root ?? process.env.H2A_ROOT ?? defaultLocalH2aRoot();
         const outputDir = opts.output ?? join(tmpdir(), `h2a-identity-cull-${randomUUID()}`);
         try {
-            const result = runIdentityCullDryRun({
+            const result = cull.runIdentityCullDryRun({
                 defRoot,
                 pinRoot: join(homedir(), "src", "a2a-cli"),
                 outputDir,
@@ -1955,6 +2028,10 @@ export async function main(argv) {
             .option("--name <label>", "base label for the --count fan-out fleet names (default: cwd basename)")
             .option("--browser", "add the headful-browser noVNC sidecar (WP7) — enables 2FA / authenticated-site flows from inside the pod")
             .option("--image <ref>", "override the session-agent container image (fully-qualified registry ref, e.g. rg.fr-par.scw.cloud/sentropic-geo/geo-acquisition:0.1.0)")
+            .option("--llm-gateway", "route this remote session through the llm-mesh gateway (explicit opt-in; default is direct)")
+            .option("--gw", "alias for --llm-gateway")
+            .option("--no-llm-gateway", "run this remote session without llm-mesh gateway env")
+            .option("--no-gw", "alias for --no-llm-gateway")
             .action(async (commandArgs, opts) => {
             const { remote: remoteOverride, local, workspace, ...rest } = opts;
             if (local) {
@@ -3640,6 +3717,8 @@ export async function main(argv) {
             process.exitCode = 1;
             return;
         }
+        const sameResumeIdentity = resolvedConvId !== undefined && registryEntry?.convId === resolvedConvId &&
+            registryEntry?.cwd === process.cwd() && registryEntry?.tool === explicitProfile;
         const entry = explicitProfile
             ? {
                 id: displaySlug,
@@ -3654,8 +3733,9 @@ export async function main(argv) {
                 enrolledAt: new Date().toISOString(),
                 lastSeenAt: new Date().toISOString(),
                 source: "run",
-                bare: registryEntry?.convId === resolvedConvId ? registryEntry?.bare : undefined,
-                gatewayMode: registryEntry?.convId === resolvedConvId ? registryEntry?.gatewayMode : undefined,
+                bare: sameResumeIdentity ? registryEntry?.bare : undefined,
+                gatewayMode: sameResumeIdentity ? registryEntry?.gatewayMode : undefined,
+                gatewayProvenance: sameResumeIdentity ? registryEntry?.gatewayProvenance : undefined,
             }
             : registryEntry;
         // WHICH host serves this resume — resolved BEFORE ANY act (F1): every
@@ -3753,7 +3833,7 @@ export async function main(argv) {
             process.exitCode = 2;
             return;
         }
-        const effectiveGatewayMode = gatewayModeForProfile(profile, gatewayMode === "auto" ? entry.gatewayMode ?? "auto" : gatewayMode);
+        const effectiveGatewayMode = resolveResumedGatewayMode(profile, gatewayMode, entry.gatewayMode, entry.gatewayProvenance);
         let gateway;
         // Resolve against the selected mode, not the parent's environment:
         // required gateway injection below must succeed before either launch.
@@ -3966,7 +4046,11 @@ export async function main(argv) {
             cwd: entry.cwd,
             sessionClass,
             ...(entry.convId ? { convId: entry.convId } : {}),
-            gatewayMode: effectiveGatewayMode,
+            // Only an explicit CLI choice becomes a new proven pin; otherwise
+            // the previous pin (if any) is preserved untouched by the merge.
+            ...(gatewayMode !== "auto"
+                ? { gatewayMode, gatewayProvenance: "explicit" }
+                : {}),
             bare: useBare,
         });
         process.stderr.write(`[h2a] resumed local session ${resumeSlug} (${profile} resume${entry.convId ? ` ${entry.convId}` : ""} in ${entry.cwd})\n`);
@@ -3997,8 +4081,11 @@ export async function main(argv) {
         .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("--role <role>", "launch purpose: review|challenge|build; AGY Claude builds require explicit opt-in")
+        .option("--allow-claude-build", "explicitly spend the reserved AGY Claude pool on a build")
+        .option("--output-file <path>", "expected AGY Claude headless artifact; report missing or unchanged output at exit")
+        .option("--effort <level>", "reasoning effort: low|medium|high|xhigh (AGY: low|medium|high, max maps to high)")
+        .option("--headless", "run once and exit (Claude -p / Codex exec / AGY stream-json), 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")
@@ -4020,13 +4107,30 @@ export async function main(argv) {
             process.exitCode = 2;
             return;
         }
-        if (opts.effort !== undefined && !isAgentLaunchEffort(opts.effort)) {
-            process.stderr.write(`[h2a] --effort must be low|medium|high|xhigh\n`);
+        try {
+            if (profile === "agy") {
+                const effort = normalizeAgyEffort(opts.effort);
+                if (effort !== undefined)
+                    opts.effort = effort;
+                const model = resolveAgyModel(opts.model, effort);
+                if (model !== undefined)
+                    opts.model = model;
+            }
+            assertAgyClaudeBuildAllowed({ profile, model: opts.model, role: opts.role, allowClaudeBuild: opts.allowClaudeBuild });
+            if (opts.outputFile && !(profile === "agy" && isAgyClaudeModel(opts.model) && opts.headless)) {
+                throw new Error("--output-file requires an AGY Claude headless run");
+            }
+        }
+        catch (error) {
+            process.stderr.write(`[h2a] ${error.message}\n`);
+            if (opts.json)
+                process.stdout.write(`${JSON.stringify({ kind: "h2a.run.failure", version: 1, state: "not-started",
+                    code: error.code ?? "invalid-agy-launch", error: error.message, retrySafe: false })}\n`);
             process.exitCode = 2;
             return;
         }
-        if (profile === "agy" && opts.effort === "xhigh") {
-            process.stderr.write("[h2a] AGY --effort must be low|medium|high\n");
+        if (opts.effort !== undefined && !isAgentLaunchEffort(opts.effort)) {
+            process.stderr.write(`[h2a] --effort must be low|medium|high|xhigh\n`);
             process.exitCode = 2;
             return;
         }
@@ -4172,13 +4276,11 @@ export async function main(argv) {
             }
         };
         try {
-            if (structuredLaunch && sessionHost === "native") {
-                for (const label of labels)
-                    preflightNativeLaunch(localSessionName(slugify(label ?? cwd)));
-            }
-            const reservedTmuxSlugs = tmuxAvailable()
-                ? existingLocalSessionSlugs(labels, cwd)
-                : [];
+            // No separate preflight fork: the in-process name probe below prepares
+            // the host for a native run. The single-shot launch still performs its
+            // fenced admission with a fresh inventory before creating any session.
+            void preflightNativeLaunch;
+            const reservedTmuxSlugs = 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
@@ -4213,14 +4315,16 @@ export async function main(argv) {
             // 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
+            const nativeExistence = await Promise.all(labels
                 .map((label) => slugify(label ?? cwd))
-                .map((slug) => {
-                const detail = nativeSessionState(localSessionName(slug));
+                .map(async (slug) => {
+                const detail = sessionHost === "native"
+                    ? await nativeSessionStateAsync(localSessionName(slug), true)
+                    : nativeSessionState(localSessionName(slug));
                 const probe = detail.state === "unknown" ? "unknown"
                     : detail.state === "found" && detail.session.status === "running" ? "live" : "dead";
                 return { slug, probe, reason: detail.state === "unknown" ? detail.reason : undefined };
-            });
+            }));
             const unknownNativeSlugs = nativeExistence
                 .filter((probed) => probed.probe === "unknown");
             if (unknownNativeSlugs.length > 0) {
@@ -4265,9 +4369,15 @@ export async function main(argv) {
             // Single-writer guard: refuse to resume a conversation another live
             // session (local registry / remote pod) is already writing.
             if (opts.resume) {
+                // Reuse this operation's certified name verdict for that SAME
+                // session. Other conversation owners still require their own probe.
+                // Creation rechecks the complete inventory and name admission at
+                // the host, so this snapshot never authorizes a colliding create.
+                const nativeLivenessByName = new Map(nativeExistence.map(({ slug, probe }) => [localSessionName(slug), probe === "dead" ? false : probe === "live" ? true : "unknown"]));
                 const ok = await guardConvWriters({
                     convId: opts.resume,
                     cwd,
+                    nativeSessionLiveness: name => nativeLivenessByName.get(name) ?? nativeSessionLiveness(name),
                     ...(opts.force ? { force: true } : {}),
                     fetchRemoteSessions: async () => {
                         const url = getConfiguredRemoteOptional();
@@ -4296,8 +4406,11 @@ export async function main(argv) {
             for (const prunedId of resumeResolution.prunedIds) {
                 process.stderr.write(`[h2a] pruned dead registry row ${prunedId} that pinned conflicting launch options for this resume\n`);
             }
-            const pinnedLaunch = resumeResolution.entries[0];
-            const launchGatewayMode = gatewayModeForProfile(profile, gatewayMode === "auto" ? pinnedLaunch?.gatewayMode ?? "auto" : gatewayMode);
+            // Conflicting pins have already failed closed above. For agreeing
+            // pins, prefer the proven choice over an equivalent legacy row.
+            const pinnedLaunch = resumeResolution.entries.find(entry => entry.gatewayProvenance === "explicit")
+                ?? resumeResolution.entries[0];
+            const launchGatewayMode = resolveResumedGatewayMode(profile, gatewayMode, pinnedLaunch?.gatewayMode, pinnedLaunch?.gatewayProvenance);
             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
@@ -4341,6 +4454,17 @@ export async function main(argv) {
                     return;
                 }
                 const useBare = resolveClaudeBare(profile, bareChoiceFromOptions(opts) ?? pinnedLaunch?.bare);
+                // Preserve the conversation's bare pin, including absence on a
+                // legacy row: materializing it only on the new row creates a conflict.
+                const enrollmentBare = pinnedLaunch && bareChoiceFromOptions(opts) === undefined
+                    ? pinnedLaunch.bare
+                    : useBare;
+                // H0 (#662): normalize readable gateway aliases (argon-high, wonder,
+                // wonder-full, spark) to their exact canonical model id. Unknown
+                // names pass through unchanged for exact-model validation downstream.
+                const runModel = opts.model !== undefined
+                    ? (resolveGatewayModelAlias(opts.model) ?? opts.model)
+                    : undefined;
                 let args;
                 try {
                     args =
@@ -4351,7 +4475,7 @@ export async function main(argv) {
                                     ? { prompt: initialPrompt }
                                     : {}),
                                 ...(opts.agent !== undefined ? { agent: opts.agent } : {}),
-                                ...(opts.model !== undefined ? { model: opts.model } : {}),
+                                ...(runModel !== undefined ? { model: runModel } : {}),
                                 ...(opts.effort !== undefined
                                     ? { effort: opts.effort }
                                     : {}),
@@ -4377,6 +4501,10 @@ export async function main(argv) {
                 }
                 let name;
                 let slug;
+                // R3 P1: pid/identity returned by the single-shot launch; the
+                // re-probes below prefer these and skip their forks.
+                let launchedPid;
+                let launchedWorkerPid;
                 let outputLog;
                 let resultJson;
                 let agentPane;
@@ -4389,6 +4517,10 @@ export async function main(argv) {
                     mkdirSync(runDir, { recursive: true });
                     outputLog = join(runDir, "output.log");
                     resultJson = join(runDir, "result.json");
+                    // Name admission above has completed. Retire the previous result
+                    // before returning a path or starting the new run-once supervisor.
+                    if (profile === "agy" && isAgyClaudeModel(opts.model))
+                        rmSync(resultJson, { force: true });
                     const headlessPromptInput = structuredLaunch && isAgentLaunchProfile(profile)
                         ? buildAgentLaunchStdin({
                             profile,
@@ -4402,14 +4534,16 @@ export async function main(argv) {
                         ({ name, slug, promptFile } = startNativeHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, headlessPromptInput, structuredLaunch, sessionClass, onCreateAttempt, structuredLaunch ? (owned) => {
                             launchOwnership = { host: "native", sessions: [owned] };
                             launchGuard = startLaunchGuard(runDir, launchOwnership);
-                        } : undefined));
+                        } : undefined, opts.outputFile ? resolve(cwd, opts.outputFile) : undefined));
                     }
                     else {
-                        ({ name, slug, agentPane, promptFile } = startHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, getTmuxProfileConfig().profile, headlessPromptInput, structuredLaunch, sessionClass, onCreateAttempt));
+                        ({ name, slug, agentPane, promptFile } = startHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, getTmuxProfileConfig().profile, headlessPromptInput, structuredLaunch, sessionClass, onCreateAttempt, opts.outputFile ? resolve(cwd, opts.outputFile) : undefined));
                     }
                 }
                 else if (sessionHost === "native") {
-                    ({ name, slug } = startNativeSession(profile, command, cwd, args, label, {
+                    // One in-process async operation, with a fresh admission inventory;
+                    // returns pid/identity so the re-probes below are skipped.
+                    ({ name, slug, pid: launchedPid, workerPid: launchedWorkerPid } = await startNativeSessionSingleShot(profile, command, cwd, args, label, {
                         onCreateAttempt,
                         ...(opts.resume !== undefined ? { resumeId: opts.resume } : {}),
                         ...(initialPrompt !== undefined
@@ -4538,6 +4672,18 @@ export async function main(argv) {
                             now: () => Date.now(),
                         }, { profile });
                     if (promptDelivery.state !== "working") {
+                        const quotaDiagnostic = promptDelivery.state === "submitted-idle" ? "" : `${promptDelivery.reason}\n${promptDelivery.capture ?? ""}`;
+                        const quotaVerdict = profile === "agy" && isAgyClaudeModel(opts.model)
+                            ? detectAgyClaudeQuotaExhaustion(quotaDiagnostic) : { exhausted: false };
+                        const quotaFailure = profile === "agy" && isAgyClaudeModel(opts.model) &&
+                            promptDelivery.state === "provider-blocked" && promptDelivery.providerError
+                            ? promptDelivery.providerError : quotaVerdict.exhausted
+                            ? agyClaudeQuotaError(quotaVerdict.signature, quotaDiagnostic) : undefined;
+                        if (quotaFailure)
+                            try {
+                                writeAgyClaudeQuotaStatus(quotaFailure.quota);
+                            }
+                            catch { /* Response still carries the observation. */ }
                         cleanupHeadlessPromptFile(promptFile);
                         // Only claim the session is gone when the kill actually reported
                         // success. "nothing is left running" over an unchecked call is the
@@ -4567,26 +4713,64 @@ export async function main(argv) {
                                 ? `[h2a] last screen:\n${promptDelivery.capture}\n`
                                 : ""));
                         process.exitCode = 1;
-                        if (opts.json && promptDelivery.state === "provider-blocked") {
+                        if (opts.json && (promptDelivery.state === "provider-blocked" || quotaFailure)) {
                             process.stdout.write(`${JSON.stringify({ kind: "h2a.run.failure", version: 1,
-                                state: "provider-blocked", launchId: slug, error: promptDelivery.reason,
-                                stopped, retrySafe: false, prompt: { delivered: true, waitedMs: promptDelivery.waitedMs },
+                                state: "provider-blocked", launchId: slug, error: quotaFailure?.message ?? (promptDelivery.state === "submitted-idle" ? "agent idle after submission" : promptDelivery.reason),
+                                stopped, retrySafe: false, prompt: { delivered: promptDelivery.state === "provider-blocked", ...("waitedMs" in promptDelivery ? { waitedMs: promptDelivery.waitedMs } : {}) },
+                                ...(quotaFailure ? { code: quotaFailure.code, error: quotaFailure.message, quota: quotaFailure.quota,
+                                    resetsAt: quotaFailure.resetsAt, retryable: false, model: opts.model } : {}),
                             })}\n`);
                         }
                         return;
                     }
                 }
+                const reportAgyCompletion = () => {
+                    if (!(profile === "agy" && isAgyClaudeModel(opts.model) && opts.headless && resultJson))
+                        return false;
+                    try {
+                        const completed = JSON.parse(readFileSync(resultJson, "utf8"));
+                        // The previous result was removed before this supervisor started.
+                        // Filesystem and wall-clock timestamps cannot prove generation.
+                        if (!["h2a.run.failure", "h2a.run.completion"].includes(completed.kind))
+                            return false;
+                        launchGuard?.complete();
+                        if (opts.json)
+                            process.stdout.write(`${JSON.stringify({ ...completed, launchId: slug, result: { path: resultJson }, logs: { path: outputLog } })}\n`);
+                        else
+                            process.stderr.write(`[h2a] ${completed.error ?? "AGY run completed"}\n`);
+                        process.exitCode = completed.state === "done" ? 0 : 1;
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    } // Still running; the durable result may appear later.
+                };
+                if (profile === "agy" && isAgyClaudeModel(opts.model) && opts.headless && resultJson) {
+                    // A fast provider refusal may finish before the host PID probe.
+                    // Return that typed completion rather than a misleading PID error.
+                    for (let attempt = 0; attempt < 5; attempt++) {
+                        if (reportAgyCompletion())
+                            return;
+                        sleepSync(50);
+                    }
+                }
+                // R3 P1: prefer the pid/identity returned by the single-shot
+                // launch (no fork); fall back to probes only when absent (e.g.
+                // tmux path or adopted pre-existing session without a fresh pid).
                 const pid = sessionHost === "native"
-                    ? nativeSessionPid(name)
+                    ? (launchedPid ?? nativeSessionPid(name))
                     : agentPane
                         ? localSessionPanePid(agentPane)
                         : undefined;
                 const workerPid = sessionHost === "native"
-                    ? nativeWorkerPid(name)
+                    ? (launchedWorkerPid ?? nativeWorkerPid(name))
                     : agentPane !== undefined
                         ? paneWorkerPid(agentPane)
                         : undefined;
                 if (structuredLaunch && pid === undefined) {
+                    // The supervisor can publish and exit DURING the PID probe.
+                    if (reportAgyCompletion())
+                        return;
                     cleanupHeadlessPromptFile(promptFile);
                     // OWN-CLEANUP, deliberately NOT resolver-derived (F1 sorting):
                     // `name`/`sessionHost` are the session and host THIS command
@@ -4602,8 +4786,8 @@ export async function main(argv) {
                     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.
+                // A CLI choice or a proven pin for this exact convId/cwd/tool
+                // survives enrollment under a new name. Legacy/auto stays unpinned.
                 enrollFromRun({
                     profile,
                     slug,
@@ -4615,8 +4799,10 @@ export async function main(argv) {
                     cwd,
                     sessionClass,
                     ...(opts.resume !== undefined ? { convId: opts.resume } : {}),
-                    gatewayMode: launchGatewayMode,
-                    bare: useBare,
+                    ...(gatewayMode !== "auto" || pinnedLaunch?.gatewayProvenance === "explicit"
+                        ? { gatewayMode: launchGatewayMode, gatewayProvenance: "explicit" }
+                        : {}),
+                    ...(enrollmentBare !== undefined ? { bare: enrollmentBare } : {}),
                 });
                 const nativeOwnerSocket = launchOwnership?.host === "native"
                     ? launchOwnership.sessions.find(owned => owned.name === name)?.socketPath : undefined;
@@ -4656,6 +4842,8 @@ export async function main(argv) {
                         tmuxSession: only.name,
                         host: sessionHost === "native" ? "native" : "tmux",
                         profile,
+                        ...(opts.model ? { model: opts.model, modelSource: "launch-argument", effectiveModel: "unknown" } : {}),
+                        ...(profile === "agy" && isAgyClaudeModel(opts.model) ? { quota: readAgyClaudeQuotaStatus() } : {}),
                         workspace: cwd,
                         mode: opts.headless ? "headless" : "interactive",
                         background: opts.background === true,
@@ -6140,6 +6328,9 @@ export async function main(argv) {
                 ...(entry.gatewayMode !== undefined
                     ? { gatewayMode: entry.gatewayMode }
                     : {}),
+                ...(entry.gatewayProvenance !== undefined
+                    ? { gatewayProvenance: entry.gatewayProvenance }
+                    : {}),
                 ...(entry.bare !== undefined ? { bare: entry.bare } : {}),
             }));
             const result = await executeNativeRestart({
@@ -6194,7 +6385,9 @@ export async function main(argv) {
                             ...(candidate.convId !== undefined
                                 ? { convId: candidate.convId }
                                 : {}),
-                            ...(mode !== "auto" ? { gatewayMode: mode } : {}),
+                            ...(mode !== "auto"
+                                ? { gatewayMode: mode, gatewayProvenance: "explicit" }
+                                : {}),
                             ...(candidate.bare !== undefined ? { bare: candidate.bare } : {}),
                         });
                     }
@@ -6307,7 +6500,7 @@ export async function main(argv) {
                     process.exitCode = 1;
                     return;
                 }
-                const relaunchMode = gatewayModeForProfile(nativeEntry.tool, nativeEntry.gatewayMode ?? "auto");
+                const relaunchMode = resolveResumedGatewayMode(nativeEntry.tool, "auto", nativeEntry.gatewayMode, nativeEntry.gatewayProvenance);
                 await injectLlmMeshGatewayEnv(relaunchMode, relaunchMode !== "gateway", actName);
                 if (!killNativeSessionTree(actName)) {
                     process.stderr.write(`[h2a] native session ${slug} could not be killed; nothing was relaunched.\n`);
@@ -6334,7 +6527,15 @@ export async function main(argv) {
                     ...(relaunched.pid !== undefined ? { pid: relaunched.pid } : {}),
                     cwd: nativeEntry.cwd,
                     sessionClass: nativeEntry.sessionClass ?? "human",
-                    gatewayMode: relaunchMode,
+                    // No new CLI choice here: preserve the recorded pin verbatim so a
+                    // proven choice survives the relaunch and a legacy row keeps its
+                    // (unproven) data without gaining authority.
+                    ...(nativeEntry.gatewayMode !== undefined
+                        ? { gatewayMode: nativeEntry.gatewayMode }
+                        : {}),
+                    ...(nativeEntry.gatewayProvenance !== undefined
+                        ? { gatewayProvenance: nativeEntry.gatewayProvenance }
+                        : {}),
                     bare: useBare,
                     ...(nativeEntry.convId ? { convId: nativeEntry.convId } : {}),
                 });
@@ -6464,14 +6665,55 @@ export async function main(argv) {
         if (!forced) {
             let ok = 0;
             for (const action of plan.actions) {
-                const sessionId = entryByTmuxSession.get(action.name)?.id;
-                const relaunched = sessionId !== undefined
-                    ? relaunchSessionWithLease({
-                        sessionId,
-                        tmuxSession: action.name,
-                        command: action.cmd,
-                    })
-                    : relaunchInSession(action.name, action.cmd);
+                // The pane is NOT recreated, so apply the routing policy to the
+                // retyped command itself: resolve the session's consent, scrub the
+                // routing vars for direct, or pass the freshly acquired gateway
+                // route: the idle shell may carry an expired bearer or no route.
+                const retypeEntry = entryByTmuxSession.get(action.name);
+                const retypeMode = resolveResumedGatewayMode(action.profile, "auto", retypeEntry?.gatewayMode, retypeEntry?.gatewayProvenance);
+                let retypeCmd = action.cmd;
+                let cleanupRetypeEnv = () => { };
+                if (retypeMode === "gateway") {
+                    // Validate the explicit choice before retyping: fail closed when
+                    // the gateway is unavailable instead of typing a doomed command.
+                    // Hand off privately before restoring this process's environment.
+                    const restoreRetypeEnv = replaceAnthropicGatewayEnvironment(process.env, captureAnthropicGatewayEnvironment());
+                    try {
+                        await injectLlmMeshGatewayEnv("gateway", false, localSessionName(action.slug));
+                        const prepared = prepareGatewayRetypeCommand(action.cmd, {
+                            ANTHROPIC_BASE_URL: process.env.ANTHROPIC_BASE_URL,
+                            ANTHROPIC_AUTH_TOKEN: process.env.ANTHROPIC_AUTH_TOKEN,
+                        });
+                        retypeCmd = prepared.command;
+                        cleanupRetypeEnv = prepared.cleanup;
+                    }
+                    catch (error) {
+                        process.stderr.write(`[h2a] FAILED to relaunch ${action.slug}: ${error.message}\n`);
+                        continue;
+                    }
+                    finally {
+                        restoreRetypeEnv();
+                    }
+                }
+                else {
+                    retypeCmd = scrubbedRetypeCommand(action.cmd);
+                }
+                const sessionId = retypeEntry?.id;
+                let relaunched = false;
+                try {
+                    relaunched = sessionId !== undefined
+                        ? relaunchSessionWithLease({
+                            sessionId,
+                            tmuxSession: action.name,
+                            command: retypeCmd,
+                        })
+                        : relaunchInSession(action.name, retypeCmd);
+                }
+                finally {
+                    // A successful retype transfers cleanup to the private reader.
+                    if (!relaunched)
+                        cleanupRetypeEnv();
+                }
                 if (relaunched) {
                     ok += 1;
                     process.stderr.write(`[h2a] relaunched ${action.slug}: ${action.cmd}\n`);
@@ -6547,6 +6789,11 @@ export async function main(argv) {
             }
             finalReady.push(item);
         }
+        // Isolate the routing env per session: a gateway relaunch deletes the
+        // native ANTHROPIC_API_KEY from the shared process env, so without a
+        // per-iteration restore the next (direct) session would lose native
+        // auth. Every iteration starts from the loop-entry environment.
+        const loopEntryGatewayEnv = captureAnthropicGatewayEnvironment();
         let ok = 0;
         for (const { action, entry, sessionClass } of finalReady) {
             const safety = sessionRelaunchSafety(action.name);
@@ -6573,8 +6820,9 @@ export async function main(argv) {
                 process.stderr.write(`[h2a] skipped ${action.slug}: tmux session ${action.name} changed or was no longer proven dead immediately before kill.\n`);
                 continue;
             }
+            const restoreLoopEnv = replaceAnthropicGatewayEnvironment(process.env, loopEntryGatewayEnv);
             try {
-                const gatewayMode = gatewayModeForProfile(action.profile, entry.gatewayMode ?? "auto");
+                const gatewayMode = resolveResumedGatewayMode(action.profile, "auto", entry.gatewayMode, entry.gatewayProvenance);
                 await injectLlmMeshGatewayEnv(gatewayMode, true, localSessionName(action.slug));
                 const { name, agentPane } = startLocalSession(action.profile, action.command, entry.cwd, localResumeArgs(action.profile, action.convId, {
                     bare: resolveClaudeBare(action.profile, entry.bare),
@@ -6596,6 +6844,9 @@ export async function main(argv) {
                     ...(entry.gatewayMode !== undefined
                         ? { gatewayMode: entry.gatewayMode }
                         : {}),
+                    ...(entry.gatewayProvenance !== undefined
+                        ? { gatewayProvenance: entry.gatewayProvenance }
+                        : {}),
                     ...(entry.bare !== undefined ? { bare: entry.bare } : {}),
                 });
                 const wake = wakeRelaunchedSession(relaunchContinuationPrompt(entry.task), {
@@ -6628,6 +6879,9 @@ export async function main(argv) {
             catch (error) {
                 process.stderr.write(`[h2a] FAILED to force-restart ${action.slug} after killing ${action.name}: ${error.message}\n`);
             }
+            finally {
+                restoreLoopEnv();
+            }
         }
         process.stderr.write(`[h2a] force-restarted ${ok}/${plan.actions.length}${plan.skipped.length ? `, ${plan.skipped.length} skipped` : ""}\n`);
         if (ok !== plan.actions.length)
@@ -6991,13 +7245,13 @@ export async function main(argv) {
         }
         if (opts.reattach)
             restoreOpts.reattach = true;
-        // Forced-direct restore must NOT spin up the gateway; otherwise prepare
-        // it as before (no-op when the gateway is disabled).
-        if (forceGateway !== "direct") {
+        // Only explicit --gw prewarms globally. In auto mode, any pinned
+        // gateway session acquires its gateway through its own launch.
+        if (forceGateway === "gateway") {
             try {
                 await prepareLlmMeshForRestore({
                     dryRun: Boolean(opts.dryRun),
-                    mode: forceGateway ?? "auto",
+                    mode: forceGateway,
                 });
             }
             catch (error) {
@@ -7531,13 +7785,29 @@ export async function main(argv) {
     llmMeshAccountCommand
         .command("enroll <provider>")
         .description("Enroll through the sentropic-owned OAuth state machine " +
-        "(cloud-code, codex, muse OAuth device flow, or mistral-vibe browser sign-in — alias: vibe). " +
-        "--cli imports credentials from the provider's local CLI store instead (muse only)")
+        "(cloud-code, codex, muse OAuth device flow, mistral-vibe browser sign-in — alias: vibe, or claude-code). " +
+        "--from oauth|cli|token selects the source (default oauth): cli reads a private L1 parser profile selected by --seat-profile; " +
+        "token reads a consumer SeatBundle via bounded stdin or masked input for all five CLIs. " +
+        "--cli / --token are the same modes as booleans. Seat aliases: agy/cloud-code, claude/claude-code, vibe/mistral-vibe")
         .option("--config-ref <ref>", "sentropic configuration reference for OAuth")
-        .option("--cli", "import credentials from the provider's local CLI store (muse only) instead of the OAuth flow")
-        .action(async (provider, opts) => {
-        // "vibe" is the CLI-friendly alias of the mistral-vibe transport.
-        const normalized = provider === "vibe" ? "mistral-vibe" : provider;
+        .option("--from <mode>", "enrollment source: oauth (default), cli (private L1 seat profile) or token (consumer SeatBundle on stdin)")
+        .option("--cli", "import a consumer seat from the explicitly selected --seat-profile. Takes no value")
+        .option("--token", "import a consumer SeatBundle for any of the five CLIs via bounded stdin or masked input; never argv")
+        .option("--seat-profile <path>", "private L1 CliSeatProfileInput file for --from cli; no ambient store fallback")
+        .allowExcessArguments(true)
+        .action(async (provider, opts, command) => {
+        // Static excess-argument refusal (m1): commander would otherwise echo
+        // every positional value (including a secret) on stderr before the
+        // action runs. Excess positionals are refused here without echoing
+        // any value. Token material travels on stdin only, never argv.
+        const positionalCount = Array.isArray(command?.args) ? command.args.length : 1;
+        if (positionalCount > 1) {
+            process.stderr.write("[h2a] llm-mesh account: too many arguments (expected provider only; never pass secrets in argv)\n");
+            process.exitCode = 1;
+            return;
+        }
+        // Seat names and enrollment providers share the five-CLI codec map.
+        const normalized = ["agy", "claude", "vibe"].includes(provider) ? resolveSeatEnrollmentProvider(provider) : provider;
         if (normalized === "muse-code") {
             // Owner decision 2026-10-10: muse-code is no longer a user entry —
             // muse enrolls via the OAuth device flow by default, --cli selects
@@ -7547,20 +7817,37 @@ export async function main(argv) {
             process.exitCode = 1;
             return;
         }
+        if (opts.from !== undefined && opts.from !== "oauth" && opts.from !== "cli" && opts.from !== "token") {
+            process.stderr.write("[h2a] llm-mesh account: --from must be one of oauth, cli, token\n");
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.from !== undefined && (opts.cli || opts.token)) {
+            process.stderr.write("[h2a] llm-mesh account: --from cannot be combined with --cli or --token\n");
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.cli && opts.token) {
+            process.stderr.write("[h2a] llm-mesh account: --cli and --token cannot be combined\n");
+            process.exitCode = 1;
+            return;
+        }
         if (normalized !== "cloud-code" &&
             normalized !== "codex" &&
             normalized !== "muse" &&
-            normalized !== "mistral-vibe") {
-            process.stderr.write(`[h2a] llm-mesh account: unsupported provider "${provider}". ` +
-                "Supported: cloud-code, codex, muse (OAuth; --cli imports the CLI store), mistral-vibe (alias: vibe)\n");
+            normalized !== "mistral-vibe" &&
+            normalized !== "claude-code") {
+            process.stderr.write("[h2a] llm-mesh account: unsupported provider. " +
+                "Supported: cloud-code (agy), codex, muse, mistral-vibe (vibe), claude-code (claude); oauth is the default, cli/token import consumer seats\n");
             process.exitCode = 1;
             return;
         }
         try {
-            const account = await enrollViaFacade(normalized, {
-                ...(opts.configRef ? { configRef: opts.configRef } : {}),
-                ...(opts.cli ? { cliImport: true } : {}),
-            });
+            const source = opts.from ?? (opts.cli ? "cli" : opts.token ? "token" : "oauth");
+            const { enrollViaFacade } = await import("./llm-mesh-accounts.js");
+            const account = source === "oauth"
+                ? await enrollViaFacade(normalized, { ...(opts.configRef ? { configRef: opts.configRef } : {}), from: "oauth" })
+                : await enrollSeatConsumerViaFacade(normalized, { from: source, ...(opts.seatProfile ? { seatProfile: opts.seatProfile } : {}) });
             process.stdout.write(`[h2a] llm-mesh account: enrolled ${account.provider}; ` +
                 "account inventory remains in Sentropic\n");
             // The gateway loads the account inventory at boot only: an account
@@ -7582,6 +7869,7 @@ export async function main(argv) {
         .description("List public accounts owned by this local llm-mesh scope")
         .option("--json", "emit public account metadata as JSON")
         .action(async (opts) => {
+        const { listAccountsViaFacade, formatLlmMeshAccountList, formatLlmMeshAccountError } = await import("./llm-mesh-accounts.js");
         try {
             const accounts = await listAccountsViaFacade();
             process.stdout.write(`${formatLlmMeshAccountList(accounts, opts.json === true)}\n`);
@@ -7596,6 +7884,7 @@ export async function main(argv) {
         .aliases(["rm", "unenroll"])
         .description("Remove one account owned by this local llm-mesh scope")
         .action(async (accountId) => {
+        const { removeAccountViaFacade, formatLlmMeshAccountError } = await import("./llm-mesh-accounts.js");
         try {
             const result = await removeAccountViaFacade(accountId);
             process.stdout.write(`[h2a] llm-mesh account: removed ${result.accountId}\n`);
@@ -7661,17 +7950,15 @@ export async function main(argv) {
         const config = readLlmMeshConfig() ?? {};
         const existing = readGatewayPid();
         if (existing) {
-            setLlmMeshRuntimeConfig({ enabled: true });
+            // Starting the service is not routing consent: launches stay direct
+            // unless --gw is passed, so the durable flag is left untouched.
             process.stdout.write(`[h2a] llm-mesh: already running (pid ${existing})\n`);
-            process.stdout.write(`[h2a] llm-mesh: restore config enabled\n`);
             return;
         }
         process.stdout.write(`[h2a] llm-mesh: starting gateway…\n`);
         const result = await startGateway(config, { verbose: opts.verbose });
-        setLlmMeshRuntimeConfig({ enabled: true });
         const port = result.port;
         process.stdout.write(`[h2a] llm-mesh: gateway started (pid ${result.pid}, port ${port})\n`);
-        process.stdout.write(`[h2a] llm-mesh: restore config enabled\n`);
         process.stdout.write("[h2a] llm-mesh: use `h2a run claude --gw`; the opaque bearer is not printed\n");
     });
     llmMeshCommand
@@ -7699,6 +7986,9 @@ export async function main(argv) {
         else {
             process.stdout.write(`[h2a] llm-mesh: not running\n`);
         }
+        // A previous start must not keep authorizing reactivation: stopping the
+        // service clears the durable flag so a later restore stays direct.
+        setLlmMeshRuntimeConfig({ enabled: false });
     });
     llmMeshCommand
         .command("restart")
@@ -7715,9 +8005,9 @@ export async function main(argv) {
         }
         process.stdout.write(`[h2a] llm-mesh: starting gateway…\n`);
         const result = await startGateway(config, { verbose: opts.verbose });
-        setLlmMeshRuntimeConfig({ enabled: true });
+        // Restarting the service is not routing consent: the durable flag is
+        // left untouched so a later restore stays direct unless --gw is passed.
         process.stdout.write(`[h2a] llm-mesh: gateway restarted (pid ${result.pid}, port ${result.port})\n`);
-        process.stdout.write(`[h2a] llm-mesh: restore config enabled\n`);
         process.stdout.write(`[h2a] llm-mesh: no tmux/Claude session was restarted; active sessions may keep their old gateway token until explicitly relaunched.\n`);
         process.stdout.write("[h2a] llm-mesh: use `h2a run claude --gw`; the opaque bearer is not printed\n");
     });
@@ -7897,7 +8187,25 @@ export async function main(argv) {
     applyRuntimeHelpGroups(program.createHelp().visibleCommands(program));
     program.configureHelp({ groupItems: groupRuntimeHelpItems });
     program.addHelpText("after", "\nGrouped map of every h2a command (core + runtime): h2a explain\n");
-    await program.parseAsync([...argv]);
+    try {
+        await program.parseAsync([...argv]);
+    }
+    catch (err) {
+        // Commander errors already wrote their static per-code message in
+        // `exitOverride`; only set the exit code here, never `err.message`.
+        if (err !== null &&
+            typeof err === "object" &&
+            "code" in err &&
+            typeof err.code === "string") {
+            const code = err.code;
+            if (code.startsWith("commander.")) {
+                const exitCode = err.exitCode;
+                process.exitCode = typeof exitCode === "number" ? exitCode : 1;
+                return process.exitCode;
+            }
+        }
+        throw err;
+    }
     const code = process.exitCode;
     return typeof code === "number" ? code : 0;
 }
@@ -7931,6 +8239,13 @@ export { main as dispatchH2a };
 /** @deprecated Compatibility for older h2a cores; new cores require dispatchH2a. */
 export { main as dispatch };
 export { ensureCentralMcp } from "./central-mcp.js";
+/** Offline five-CLI seat contract and run-scoped materialization. */
+export * from "./cli-seat-fixtures.js";
+export * from "./cli-seat-codecs.js";
+export * from "./cli-seat-materialization.js";
+// Keep the public async consumer contract without loading account providers in
+// every local crash-recovery launcher before it can elect its native host.
+export const enrollSeatConsumerViaFacade = async (...args) => (await import("./llm-mesh-accounts.js")).enrollSeatConsumerViaFacade(...args);
 /**
  * h2a-facing surface: the read-only remote-agents projection consumed by the
  * objective-loop tick's *agents adapter* in `@sentropic/h2a` (via lazy