@sentropic/h2a-runtime 0.85.16 → 0.85.17

package/dist/index.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join, resolve } from "node:path";
+import { basename, isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Command } from "commander";
 import { attach, createRemoteSession, getRemoteSession, listRemoteSessions, refreshRemoteSession, renameRemoteSession, sessionTerminalHealth, stopRemoteSession, } from "./attach.js";
@@ -14,12 +14,13 @@ import { transmittedSecrets, secretsSummary } from "./secrets.js";
 import { localConvStat, remoteConvStat, alignment } from "./convsync.js";
 import { gitAlignment, localAncestry, localGitStat, remoteGitStat, } from "./gitdiff.js";
 import { syncConversation } from "./sync.js";
-import { attachLocalSession, attachPodTmux, capturePane, conductorRunning, currentTmuxSessionIs, ensureManagedTmuxProfile, fanoutLabels, findLocalSession, killLocalSession, localSessionGatewayEnvStatus, listLocalSessions, localSessionIdle, localSessionName, readLaunchContext, relaunchInSession, resolveAgentPaneForInstance, runLocalCliForeground, sendKeysLiteral, sessionAttached, sessionAttachedCount, setLocalSessionDisplayName, slugify, startH2aWindow, startHeadlessSession, startLocalSession, tmuxAvailable, } from "./tmux.js";
+import { attachLocalSession, attachPodTmux, capturePane, conductorRunning, currentTmuxSessionIs, ensureManagedTmuxProfile, existingLocalSessionSlugs, fanoutLabels, findLocalSession, killLocalSession, localSessionGatewayEnvStatus, listLocalSessions, localSessionIdle, localSessionPanePid, localSessionName, readLaunchContext, relaunchInSession, resolveAgentPaneForInstance, runLocalCliForeground, sendKeysLiteral, sessionAttached, sessionAttachedCount, setLocalSessionDisplayName, slugify, cleanupHeadlessPromptFile, startH2aWindow, startH2aWindowVerified, startHeadlessSession, startLocalSession, tmuxAvailable, } from "./tmux.js";
+import { buildAgentLaunchArgs, isAgentLaunchEffort, isAgentLaunchProfile, } from "./agent-launch-args.js";
 import { planRelaunch } from "./relaunch.js";
 import { readLastLayout, restore as restoreLayout, } from "./restore.js";
 import { getLayoutConfig } from "./config.js";
 import { advanceJob, coerceRegistryTool, enroll, enrollFromRun, isLive, listJobs, listLocalForLs, loadRegistry, localTmuxSessionForName, tryClaimSlot, withRegistryLock, resolveRegistryPath, } from "./registry.js";
-import { aimdEffectiveCap, assertSafeName, buildDelegateArgs, buildJobRows, buildRemoteDelegate, buildThrottleResumeArgs, canDelegateAtDepth, childDepthEnvValue, clampDepth, clampRemoteDepthBudget, conductorAdvisory, DEFAULT_MAX_CONCURRENT, DEPTH_ENV, inheritedDepthBudget, isDelegateType, isThrottleResumeDue, jitteredBackoffMs, JOB_ID_ENV, jobDir, planNextStarts, planThrottleStep, readJobResult, THROTTLE_MAX_ATTEMPTS, reconcileRemoteJobs, renderJobsTable, resolveJobCwd, runTrackMirror, sweepStaleJobs, trackItemNewArgs, trackItemRealizeArgs, } from "./delegate.js";
+import { aimdEffectiveCap, assertDelegateEffort, assertSafeName, buildDelegateArgs, buildJobRows, buildRemoteDelegate, buildThrottleResumeArgs, canDelegateAtDepth, childDepthEnvValue, clampDepth, clampRemoteDepthBudget, conductorAdvisory, DEFAULT_MAX_CONCURRENT, DEPTH_ENV, inheritedDepthBudget, isDelegateType, isThrottleResumeDue, jitteredBackoffMs, JOB_ID_ENV, jobDir, planNextStarts, planThrottleStep, readJobResult, THROTTLE_MAX_ATTEMPTS, reconcileRemoteJobs, renderJobsTable, resolveJobCwd, runTrackMirror, sweepStaleJobs, trackItemNewArgs, trackItemRealizeArgs, } from "./delegate.js";
 import { detectThrottle, THROTTLE_TAIL_LINES } from "./throttle-signatures.js";
 import { interactiveResumeNudge, planInteractiveResume, } from "./interactive-throttle.js";
 import { promptProfileMenu, shouldShowProfileMenu } from "./profile-menu.js";
@@ -56,11 +57,15 @@ import { acquireLease, createLineage, handoffLease, isIncarnationSuspended, list
 import { checkReadiness } from "./readiness.js";
 import { createInterface } from "node:readline";
 import { appendSessionLogEntry, clearBinding, clearExhaustion, enrollAccount, listAccounts, listAccountsWithTokens, listAccountsWithStatus, listBindings, lookupBinding, markExhausted, readClaudeCredential, readCodexCredential, removeAccount, selectAccount, selectAccountWithFallback, stickyBind, loadCandidates, sessionLogPath, exportSessionLogToS3, QUOTA_WINDOW_5H_MS, QUOTA_WINDOW_WEEK_MS, } from "./account-pool.js";
+const H2A_RUN_API_VERSION = "h2a.run/v1";
+const H2A_RUNTIME_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 import { CLI_PROFILES } from "./protocol-local.js";
 import { enrollCodexAccount, enrollClaudeAccount, readLlmMeshConfig, startGateway, stopGateway, writeLlmMeshConfig, readGatewayPid, llmMeshLogPath, jwtExpiry, readLlmMeshSessionEnv, acquireLlmMeshSessionEnv, } from "./llm-mesh.js";
 const KNOWN_PROFILE_HELP = `${CLI_PROFILES.join(", ")} (aliases: claude-code, antigravity, gemini-cli, mistralcli)`;
-export const packageName = "@sentropic/remote-cli";
+export const packageName = "@sentropic/h2a-runtime";
+export const H2A_RUNTIME_CLI_API_VERSION = 1;
 export { run } from "./run.js";
+export { AGENT_LAUNCH_EFFORTS, AGENT_LAUNCH_PROFILES, AGENT_LAUNCH_PROMPT_MAX_BYTES, assertAgentLaunchModel, assertAgentLaunchPrompt, buildAgentLaunchArgs, 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";
@@ -87,8 +92,8 @@ function resumeStartupArgs(profileName, resume) {
  * fleet (one auth). Creation is bounded-concurrent (cap = the fleet size,
  * itself <= DEFAULT_FANOUT_MAX). NEVER auto-attaches — a fleet has no single
  * terminal to take over; prints a summary table and the per-session attach
- * hints, mirroring the LOCAL `remote run --count` contract. Reconcile/cleanup
- * of dead members reuses the existing `remote ls`/`jobs` reconciliation against
+ * hints, mirroring the LOCAL `h2a run --count` contract. Reconcile/cleanup
+ * of dead members reuses the existing `h2a ls`/`jobs` reconciliation against
  * `listRemoteSessions` (a dead Pod simply drops off the live list). Returns the
  * created (id,name) pairs; throws only on a setup error before fan-out.
  */
@@ -721,7 +726,7 @@ export async function startJob(job) {
             // Bundle local CLI credentials (e.g. ~/.claude/.credentials.json for
             // "claude", ~/.codex/auth.json for "codex") so the pod has them at start.
             // Best-effort: a missing bundle is not fatal — the session starts without
-            // credentials (user can `remote refresh` the job later if needed).
+            // credentials (user can `h2a refresh` the job later if needed).
             let jobCredentials;
             if (isCliProfile(remoteArgs.profile)) {
                 try {
@@ -838,7 +843,7 @@ export async function startJob(job) {
         // allExhausted: proceed with existing env (fail gracefully at the CLI level)
     }
     // Propagate the child's remaining spawn-depth budget through the env so a job
-    // that itself runs `remote delegate` inherits a DECREMENTED budget (depth=0 →
+    // that itself runs `h2a delegate` inherits a DECREMENTED budget (depth=0 →
     // refuse). tmux inherits the spawning process's env, so set it around spawn.
     // ALSO stamp REMOTE_JOB_ID (H1): the spawned agent's claude SessionStart/End
     // hooks read it to resolve THIS job (they only get claude's conversation uuid,
@@ -949,7 +954,7 @@ export function resumeThrottledJob(job) {
     const runCwd = job.cwd;
     let argv;
     try {
-        argv = buildThrottleResumeArgs(job.tool, task);
+        argv = buildThrottleResumeArgs(job.tool, task, job.model, job.effort);
     }
     catch (err) {
         return { started: false, error: err.message };
@@ -1064,7 +1069,7 @@ function looksLikeUrl(value) {
 }
 /**
  * Resolve the tool list to bundle: `--with a,b` overrides the configured
- * default (`remote config tools …`). Unknown tools are dropped with a warning.
+ * default (`h2a config tools …`). Unknown tools are dropped with a warning.
  */
 function resolveTools(withOpt) {
     const raw = withOpt
@@ -1091,7 +1096,7 @@ function projectName(s) {
     }
     return s.id;
 }
-/** Local CLI binary for a profile (used by `remote run`). */
+/** Local CLI binary for a profile (used by `h2a run`). */
 const LOCAL_CLI = {
     claude: "claude",
     "claude-code": "claude",
@@ -1159,7 +1164,7 @@ function shouldUseClaudeBare(profile) {
     return ((profile === "claude" || profile === "claude-code") &&
         Boolean(process.env.ANTHROPIC_BASE_URL && process.env.ANTHROPIC_AUTH_TOKEN));
 }
-async function injectLlmMeshGatewayEnv(mode = "auto") {
+async function injectLlmMeshGatewayEnv(mode = "auto", allowDirectFallback = true) {
     if (mode === "direct") {
         delete process.env.ANTHROPIC_BASE_URL;
         delete process.env.ANTHROPIC_AUTH_TOKEN;
@@ -1186,12 +1191,14 @@ async function injectLlmMeshGatewayEnv(mode = "auto") {
                 process.stderr.write(`[h2a] llm-mesh: gateway was stopped; started on ${meshEnv.ANTHROPIC_BASE_URL}\n`);
             }
             catch (err) {
-                process.stderr.write(`[h2a] llm-mesh: gateway env unavailable (${String(err)}); Claude may ask for login.\n`);
+                if (allowDirectFallback) {
+                    process.stderr.write(`[h2a] llm-mesh: gateway env unavailable (${String(err)}); Claude may ask for login.\n`);
+                }
             }
         }
     }
     if (!meshEnv) {
-        if (mode === "gateway") {
+        if (mode === "gateway" && allowDirectFallback) {
             process.stderr.write("[h2a] llm-mesh: --gw requested but no gateway env is available; continuing direct. Run `h2a llm-mesh start` or enroll an account first.\n");
         }
         return undefined;
@@ -1206,6 +1213,13 @@ async function injectLlmMeshGatewayEnv(mode = "auto") {
     }
     return meshEnv.ANTHROPIC_BASE_URL;
 }
+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");
+    }
+    return gateway;
+}
 async function prepareLlmMeshForRestore(opts = {}) {
     if (!getLlmMeshRuntimeConfig().enabled)
         return;
@@ -1268,7 +1282,7 @@ function resolveUrlAndSessionId(first, second) {
         return { url: getConfiguredRemote(first), sessionId: second };
     }
     if (looksLikeUrl(first)) {
-        throw new Error(`Missing session id. Usage: remote <command> [url] <sessionId> (received URL "${first}" without session id).`);
+        throw new Error(`Missing session id. Usage: h2a <command> [url] <sessionId> (received URL "${first}" without session id).`);
     }
     return { url: getConfiguredRemote(), sessionId: first };
 }
@@ -1297,7 +1311,7 @@ export async function main(argv) {
         }
         return main([
             argv[0] ?? "node",
-            argv[1] ?? "remote",
+            argv[1] ?? "h2a",
             "run",
             profile,
             process.cwd(),
@@ -1305,7 +1319,7 @@ export async function main(argv) {
     }
     const program = new Command();
     program
-        .name("remote")
+        .name("h2a")
         .description("Wrap a local agent CLI (codex/claude/agy/gemini/mistral) and expose its session for h2a attach.")
         .version("0.0.0");
     for (const [profileName, alias] of [
@@ -1319,11 +1333,11 @@ export async function main(argv) {
     ]) {
         const cmd = program
             .command(profileName)
-            .description(`Run ${profileName} via remote-cli`)
+            .description(`Run ${profileName} via h2a`)
             .argument("[commandArgs...]", "Arguments passed to the wrapped CLI")
             .option("-r, --resume [convId]", "resume the wrapped CLI's last conversation (or a specific one by id) using its native --continue/--resume flag")
             .option("-p, --port <port>", "expose the in-process control-plane on this port", (value) => Number(value))
-            .option("--remote <url>", "override the control-plane URL (defaults to the configured remote; `remote` is remote-first)")
+            .option("--remote <url>", "override the control-plane URL (h2a defaults to the configured remote)")
             .option("--local", "run the CLI in-process via a local PTY instead of a remote session")
             .option("--sync", "seed the remote /workspace with the current directory (honors .gitignore)")
             .option("--no-workspace", "ignore the .remote/ mapping and use a throwaway workspace")
@@ -1374,7 +1388,7 @@ export async function main(argv) {
     }
     program
         .command("install <url>")
-        .description("Set default remote URL and apply remote's managed local tmux profile")
+        .description("Set default remote URL and apply h2a's managed local tmux profile")
         .action((url) => {
         setAndReportDefaultRemote(url);
     });
@@ -1655,7 +1669,7 @@ export async function main(argv) {
     });
     const authCommand = program
         .command("auth")
-        .description("Inspect and manage the local CLI credentials remote sends to sessions");
+        .description("Inspect and manage the local CLI credentials h2a sends to sessions");
     const printAuthStatus = async (profile, opts) => {
         const result = await inspectProfileAuth(profile, {
             ...(opts.authRefresh !== undefined
@@ -1818,7 +1832,7 @@ export async function main(argv) {
     });
     configCommand
         .command("tmux-profile <name>")
-        .description("Set the marker name for remote's embedded tmux profile applied to local sessions")
+        .description("Set the marker name for h2a's embedded tmux profile applied to local sessions")
         .action((name) => {
         setTmuxProfileConfig({ profile: name });
         const profile = getTmuxProfileConfig().profile;
@@ -2461,7 +2475,7 @@ export async function main(argv) {
         await ensureConnected(remoteUrl);
         // Single-writer guard: the conversation must not stay open locally (or
         // in another pod) while we deport it — stop the local session first
-        // (`remote stop <slug>`), or --force to take over anyway. A BARE -r
+        // (`h2a stop <slug>`), or --force to take over anyway. A BARE -r
         // resumes "the most recent conversation", resolved inside
         // migrateForward AFTER this point — so resolve the same newest local
         // conversation HERE (localConvStat on the cwd; claude-family only,
@@ -3165,18 +3179,61 @@ 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. Remote applies its embedded scroll-safe tmux profile at launch; no ~/.tmux.conf is required. Manage it like a remote one: `h2a ls`, `h2a attach <slug>`, `h2a stop <slug>`. Detach with Ctrl-b d; the session keeps running.")
+        .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.")
         .option("--no-attach", "start detached and print the attach command instead (for scripts / fan-out orchestration)")
         .option("-r, --resume <convId>", "resume a specific conversation in the CLI")
         .option("--force", "start even if the conversation already has a live writer (risk: conversation .jsonl corruption)")
         .option("--name <label>", "tmux session slug + tab label (default: workdir basename); use to keep multiple sessions of one project distinct")
         .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("--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")
         .option("--gw", "alias for --llm-gateway")
         .option("--no-llm-gateway", "launch without llm-mesh gateway env")
         .option("--no-gw", "alias for --no-llm-gateway")
         .action(async (profile, path, opts) => {
+        const structuredLaunch = opts.promptStdin === true ||
+            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.exitCode = 2;
+            return;
+        }
+        if (opts.effort !== undefined && !isAgentLaunchEffort(opts.effort)) {
+            process.stderr.write(`[h2a] --effort must be low|medium|high|xhigh\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;
+            return;
+        }
+        if (opts.background && opts.attach !== false) {
+            process.stderr.write("[h2a] --background requires --no-attach\n");
+            process.exitCode = 2;
+            return;
+        }
+        if (opts.headless && opts.h2a === true) {
+            process.stderr.write("[h2a] --headless cannot combine with --h2a (the sidecar would keep a run-once session alive)\n");
+            process.exitCode = 2;
+            return;
+        }
+        if (opts.promptStdin && process.stdin.isTTY) {
+            process.stderr.write("[h2a] --prompt-stdin requires piped stdin\n");
+            process.exitCode = 2;
+            return;
+        }
         if (!tmuxAvailable()) {
             process.stderr.write("[h2a] tmux is not installed locally — `h2a run` needs it (e.g. `sudo apt install tmux`).\n");
             process.exitCode = 1;
@@ -3198,6 +3255,39 @@ export async function main(argv) {
                 return;
             }
         }
+        if (structuredLaunch && count !== 1) {
+            process.stderr.write("[h2a] structured prompt/model launch supports exactly one session\n");
+            process.exitCode = 2;
+            return;
+        }
+        if (opts.json && !opts.promptStdin) {
+            process.stderr.write("[h2a] --json launch requires --prompt-stdin\n");
+            process.exitCode = 2;
+            return;
+        }
+        if (opts.json && (!path || !isAbsolute(path))) {
+            process.stderr.write("[h2a] --json launch requires an explicit absolute workspace path\n");
+            process.exitCode = 2;
+            return;
+        }
+        if (opts.json && !opts.name) {
+            process.stderr.write("[h2a] --json launch requires --name\n");
+            process.exitCode = 2;
+            return;
+        }
+        if (opts.name) {
+            try {
+                assertSafeName(opts.name);
+                if (opts.name.length > 64) {
+                    throw new Error("job/session name must be at most 64 characters");
+                }
+            }
+            catch (error) {
+                process.stderr.write(`[h2a] ${error.message}\n`);
+                process.exitCode = 2;
+                return;
+            }
+        }
         const cwd = path ? resolve(path) : process.cwd();
         // count==1 keeps the exact prior behaviour (label = opts.name, which may
         // be undefined -> slug derives from cwd). count>1 fans out distinct
@@ -3205,12 +3295,7 @@ export async function main(argv) {
         const labels = count > 1
             ? fanoutLabels(opts.name ?? basename(cwd), count)
             : [opts.name];
-        const existingLocalSessions = labels
-            .map((label) => {
-            const slug = slugify(label ?? cwd);
-            return findLocalSession(slug) ? slug : undefined;
-        })
-            .filter((slug) => slug !== undefined);
+        const existingLocalSessions = existingLocalSessionSlugs(labels, cwd);
         if (existingLocalSessions.length > 0) {
             for (const slug of existingLocalSessions) {
                 process.stderr.write(`[h2a] local session ${slug} already exists; no new ${profile} was started.\n`);
@@ -3220,6 +3305,15 @@ export async function main(argv) {
             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;
+            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) {
@@ -3248,22 +3342,154 @@ export async function main(argv) {
             process.exitCode = 1;
             return;
         }
-        await injectLlmMeshGatewayEnv(gatewayMode);
+        if (structuredLaunch &&
+            profile === "codex" &&
+            gatewayMode === "gateway") {
+            process.stderr.write("[h2a] --gw is unsupported for structured codex launches (llm-mesh is Anthropic-compatible)\n");
+            process.exitCode = 2;
+            return;
+        }
+        const launchGatewayMode = structuredLaunch && profile === "codex" ? "direct" : gatewayMode;
+        let activeGateway;
+        try {
+            if (structuredLaunch) {
+                activeGateway = await prepareStructuredGateway(launchGatewayMode);
+            }
+            else {
+                activeGateway = await injectLlmMeshGatewayEnv(gatewayMode);
+            }
+        }
+        catch (error) {
+            process.stderr.write(`[h2a] ${error.message}\n`);
+            process.exitCode = 1;
+            return;
+        }
         const useBare = shouldUseClaudeBare(profile);
         const command = localCliCommand(profile);
-        const args = opts.resume
-            ? localResumeArgs(profile, opts.resume, { bare: useBare })
-            : localStartArgs(profile, { bare: useBare });
+        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 });
+        }
+        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;
         }
         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 started = [];
         for (const label of labels) {
-            const { name, slug } = startLocalSession(profile, command, cwd, args, label);
-            // Auto-enroll in the live-session registry (feeds `remote ls`/`restore`).
+            let name;
+            let slug;
+            let outputLog;
+            let resultJson;
+            let agentPane;
+            let promptFile;
+            if (opts.headless) {
+                const runDir = join(cwd, ".h2a", "runs", label);
+                mkdirSync(runDir, { recursive: true });
+                outputLog = join(runDir, "output.log");
+                resultJson = join(runDir, "result.json");
+                ({ name, slug, agentPane, promptFile } = startHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, getTmuxProfileConfig().profile, initialPrompt, structuredLaunch));
+            }
+            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 } : {}),
+                }));
+            }
+            if (structuredLaunch && !agentPane) {
+                cleanupHeadlessPromptFile(promptFile);
+                killLocalSession(name);
+                process.stderr.write(`[h2a] could not capture the exact agent pane for ${slug}; the partial session was stopped\n`);
+                process.exitCode = 1;
+                return;
+            }
+            let h2aSidecarStarted = false;
+            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);
+                    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 &&
+                !sendKeysLiteral(agentPane, initialPrompt)) {
+                cleanupHeadlessPromptFile(promptFile);
+                killLocalSession(name);
+                process.stderr.write(`[h2a] failed to deliver the initial prompt to ${slug}; the partial session was stopped\n`);
+                process.exitCode = 1;
+                return;
+            }
+            const pid = agentPane
+                ? localSessionPanePid(agentPane)
+                : undefined;
+            if (structuredLaunch && pid === undefined) {
+                cleanupHeadlessPromptFile(promptFile);
+                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({
@@ -3273,15 +3499,17 @@ export async function main(argv) {
                 cwd,
                 ...(opts.resume !== undefined ? { convId: opts.resume } : {}),
                 ...(gatewayMode !== "auto" ? { gatewayMode } : {}),
+                ...(opts.background ? { sessionClass: "background" } : {}),
+            });
+            started.push({
+                name,
+                slug,
+                ...(agentPane !== undefined ? { pane: agentPane } : {}),
+                h2aSidecar: h2aSidecarStarted,
+                ...(pid !== undefined ? { pid } : {}),
+                ...(outputLog !== undefined ? { outputLog } : {}),
+                ...(resultJson !== undefined ? { resultJson } : {}),
             });
-            started.push({ name, slug });
-            // h2a launcher contract (opt-in): --h2a forces it; `h2a.enabled` makes
-            // it the default. Never fails the run.
-            if (opts.h2a || h2a.enabled) {
-                if (startH2aWindow(name, cwd, h2a.command)) {
-                    process.stderr.write(`[h2a] h2a window started in ${slug} (${h2a.command})\n`);
-                }
-            }
         }
         if (count > 1) {
             process.stderr.write(`[h2a] ${started.length} ${profile} agents started in ${cwd}: ${started.map((s) => s.slug).join(", ")}\n` +
@@ -3289,9 +3517,41 @@ export async function main(argv) {
             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,
+                    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 } : {}),
+                },
+                attach: opts.headless
+                    ? null
+                    : { command: "h2a", args: ["attach", only.slug] },
+                ...(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 `remote attach <slug>` command. Commander
+        // 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`);
@@ -3305,9 +3565,9 @@ export async function main(argv) {
     // ---------------------------------------------------------------------------
     program
         .command("delegate <type> <task>")
-        .description("Delegate a task to a LIVE agent (claude/codex/agy) in a detached tmux session, primed with <task> (passed as a single argv — never shell-concatenated) and with the h2a side-window so the parent/master dialogue works. Returns a job id. Supervise with `remote jobs`; drain the queue with `remote jobs conduct`. `--remote` runs the job CONCURRENTLY in a SCW Pod on the shared RWX volume (subPath per job). Beyond the concurrency cap (default 16) the job is QUEUED (pending) and started by the conductor as slots free.")
+        .description("Delegate a task to a LIVE agent (claude/codex/agy) in a detached tmux session, primed with <task> (passed as a single argv — never shell-concatenated) and with the h2a side-window so the parent/master dialogue works. Returns a job id. Supervise with `h2a jobs`; drain the queue with `h2a jobs conduct`. `--remote` runs the job CONCURRENTLY in a SCW Pod on the shared RWX volume (subPath per job). Beyond the concurrency cap (default 16) the job is QUEUED (pending) and started by the conductor as slots free.")
         .option("--remote [url]", "run the job in a SCW Pod (concurrent; isolated by a per-job workspace subPath on the shared RWX volume) instead of a local tmux session; optional control-plane URL (default: the configured remote)")
-        .option("--cwd <path>", "run the agent in this directory as-is (default: a dedicated git worktree under .remote/jobs/<id>/wt when cwd is a repo, else cwd). Local only.")
+        .option("--cwd <path>", "run the agent in this directory as-is (default: a dedicated git worktree under .h2a/jobs/<id>/wt when cwd is a repo, else cwd). Local only.")
         .option("--name <label>", "job id / tmux slug (letters/digits/_/-; default: <type>-<random>)")
         .option("--headless", "run-once-exit batch mode: claude -p / codex exec, stdout→output.log, write result.json, then END the session (no live agent; agy has no headless mode)")
         .option("--on-done <h2a-instance>", "h2a instance to notify with a `job.done` envelope when the job ends, and the parent for the decision channel (e.g. claude:remote:abc / claude:job:foo). Alias: --parent.")
@@ -3316,7 +3576,7 @@ export async function main(argv) {
         .option("--max-depth <d>", "spawn-depth budget granted to this job (clamp 1–3, default 1, à la Hermes). A LOCAL job inherits a DECREMENTED budget via REMOTE_DELEGATE_DEPTH; at 0 a nested `delegate` refuses. With --remote the budget is clamped to 1 (no env channel reaches the Pod yet → a job-in-a-Pod does not re-delegate).")
         .option("--track <wpId>", "mirror this job as a track item under workpackage <wpId> (`track item new --parent`, realized on done/failed). Best-effort: skipped silently if track is absent.")
         .option("--model <model>", "model override for the spawned agent (claude: --model; codex: -m). E.g. claude-sonnet-4-6, claude-opus-4-8, o3.")
-        .option("--effort <level>", "reasoning-effort override (claude only: --effort low|medium|high|xhigh|max). Silently ignored for non-claude types.")
+        .option("--effort <level>", "reasoning-effort override (claude: --effort low|medium|high|xhigh|max; codex: model_reasoning_effort low|medium|high|xhigh).")
         .option("--account <id>", "force a specific account from the pool (bypass selectAccountWithFallback). E.g. claude-code-1234567890.")
         .action(async (type, task, opts) => {
         if (!isDelegateType(type)) {
@@ -3325,6 +3585,14 @@ export async function main(argv) {
             return;
         }
         const jobType = type;
+        try {
+            assertDelegateEffort(jobType, opts.effort);
+        }
+        catch (err) {
+            process.stderr.write(`[h2a] ${err.message}\n`);
+            process.exitCode = 1;
+            return;
+        }
         const jobId = opts.name ?? `${jobType}-${Math.random().toString(36).slice(2, 8)}`;
         // Parent h2a instance to notify on done + answer decisions (best-effort).
         const callbackTo = opts.onDone ?? opts.parent;
@@ -3352,7 +3620,7 @@ export async function main(argv) {
         // --- Concurrency cap (P4). The cap applies to BOTH local and remote
         // (shared RWX is multi-node; no CSI packing limit). Beyond `running`
         // jobs at the cap, ENQUEUE the job (jobState:"pending") instead of
-        // launching it; the conductor (`remote jobs conduct`) starts it later.
+        // launching it; the conductor (`h2a jobs conduct`) starts it later.
         const cap = opts.maxConcurrent !== undefined
             ? Number.parseInt(opts.maxConcurrent, 10)
             : (getMaxConcurrent() ?? DEFAULT_MAX_CONCURRENT);
@@ -3445,7 +3713,7 @@ export async function main(argv) {
         if (!claimed && listJobs().some((e) => e.id === jobId)) {
             // The entry exists but the cap is full → stay queued.
             process.stderr.write(`[h2a] queued job ${jobId} (${jobType}${opts.headless ? " headless" : ""}${isRemote ? " remote" : ""}) — ` +
-                `${effectiveCap} concurrent slot(s) busy. Start it with: remote jobs conduct\n`);
+                `${effectiveCap} concurrent slot(s) busy. Start it with: h2a jobs conduct\n`);
             process.stdout.write(`${jobId}\n`);
             return;
         }
@@ -3489,8 +3757,8 @@ export async function main(argv) {
             return;
         }
         process.stderr.write(`[h2a] delegated ${result.target === "remote" ? "REMOTE " : ""}job ${jobId} (${jobType}${opts.headless ? " headless" : ""}) ${result.target === "remote" ? "→ " : "in "}${result.detail}\n` +
-            `[h2a] supervise: remote jobs status ${jobId}` +
-            (opts.headless ? "" : `   attach: remote jobs attach ${jobId}`) +
+            `[h2a] supervise: h2a jobs status ${jobId}` +
+            (opts.headless ? "" : `   attach: h2a jobs attach ${jobId}`) +
             "\n");
         process.stdout.write(`${jobId}\n`);
     });
@@ -3812,7 +4080,7 @@ export async function main(argv) {
         await reconcileJobs();
         const job = listJobs().find((e) => e.id === id);
         if (!job) {
-            process.stderr.write(`[h2a] no job "${id}" (see: remote jobs ls)\n`);
+            process.stderr.write(`[h2a] no job "${id}" (see: h2a jobs ls)\n`);
             process.exitCode = 1;
             return;
         }
@@ -3865,11 +4133,11 @@ export async function main(argv) {
         .action(async (id) => {
         const job = listJobs().find((e) => e.id === id);
         // REMOTE job (P2): exec into the Pod's tmux over the configured tunnel,
-        // reusing the same path as `remote attach <id> --exec`.
+        // reusing the same path as `h2a attach <id> --exec`.
         if (job?.kind === "remote") {
             const remoteId = job.remoteId;
             if (!remoteId) {
-                process.stderr.write(`[h2a] remote job "${id}" has no session id recorded (see: remote jobs status ${id})\n`);
+                process.stderr.write(`[h2a] remote job "${id}" has no session id recorded (see: h2a jobs status ${id})\n`);
                 process.exitCode = 1;
                 return;
             }
@@ -3892,7 +4160,7 @@ export async function main(argv) {
         // LOCAL job (P1): attach into the detached tmux session.
         const name = job?.tmuxSession ?? localSessionName(id);
         if (!findLocalSession(name)) {
-            process.stderr.write(`[h2a] no live tmux session for job "${id}" (it may have ended; see: remote jobs status ${id})\n`);
+            process.stderr.write(`[h2a] no live tmux session for job "${id}" (it may have ended; see: h2a jobs status ${id})\n`);
             process.exitCode = 1;
             return;
         }
@@ -3904,7 +4172,7 @@ export async function main(argv) {
         .action((id) => {
         const job = listJobs().find((e) => e.id === id);
         if (!job) {
-            process.stderr.write(`[h2a] no job "${id}" (see: remote jobs ls)\n`);
+            process.stderr.write(`[h2a] no job "${id}" (see: h2a jobs ls)\n`);
             process.exitCode = 1;
             return;
         }
@@ -3916,7 +4184,7 @@ export async function main(argv) {
         }
         // REMOTE job: the output lives in the Pod's tmux, not a local pane.
         if (job.kind === "remote") {
-            process.stderr.write(`[h2a] remote job "${id}" runs in a Pod — view it live with: remote jobs attach ${id}\n`);
+            process.stderr.write(`[h2a] remote job "${id}" runs in a Pod — view it live with: h2a jobs attach ${id}\n`);
             process.exitCode = 1;
             return;
         }
@@ -3931,7 +4199,7 @@ export async function main(argv) {
     });
     // P3 — the decision channel (h2a). A delegated INTERACTIVE job can emit a
     // `decision.requested` envelope; the parent lists them here and answers with
-    // `decide`. Both ride the local h2a inbox + `remote h2a bridge` to the Pod.
+    // `decide`. Both ride the local h2a inbox + `h2a relay bridge` to the Pod.
     jobsCommand
         .command("decisions")
         .description("List unanswered `decision.requested` envelopes from delegated jobs (read from the local h2a inbox), with the asking job id and its question.")
@@ -3954,7 +4222,7 @@ export async function main(argv) {
     });
     jobsCommand
         .command("decide <jobId> <answer>")
-        .description("Answer a job's `decision.requested`: write a `decision.reply` envelope into the job's h2a inbox (carried to its Pod by `remote h2a bridge`). <answer> is a single argv — never shell-concatenated.")
+        .description("Answer a job's `decision.requested`: write a `decision.reply` envelope into the job's h2a inbox (carried to its Pod by `h2a relay bridge`). <answer> is a single argv — never shell-concatenated.")
         .option("--from <h2a-instance>", "parent/master h2a instance to attribute the reply to (default: the job's recorded parent, else `remote:cli`)")
         .action((jobId, answer, opts) => {
         try {
@@ -3967,7 +4235,7 @@ export async function main(argv) {
         }
         const job = listJobs().find((e) => e.id === jobId);
         if (!job) {
-            process.stderr.write(`[h2a] no job "${jobId}" (see: remote jobs ls)\n`);
+            process.stderr.write(`[h2a] no job "${jobId}" (see: h2a jobs ls)\n`);
             process.exitCode = 1;
             return;
         }
@@ -3982,7 +4250,7 @@ export async function main(argv) {
             process.stderr.write(`[h2a] decision.reply for ${jobId} → ${envelope.to}` +
                 `${written ? "" : " (already present, not overwritten)"}\n` +
                 `[h2a] envelope: ${path}\n` +
-                `[h2a] delivered to the job's Pod on the next: remote h2a bridge\n`);
+                `[h2a] delivered to the job's Pod on the next: h2a relay bridge\n`);
         }
         catch (error) {
             process.stderr.write(`[h2a] failed to write decision.reply: ${(error instanceof Error ? error.message : String(error)).slice(0, 160)}\n`);
@@ -4269,7 +4537,7 @@ export async function main(argv) {
             return { launched: false, detail: result.error };
         }
         process.stderr.write(`[h2a] conductor-launch: launched ${host} conductor ${slug} for ${request.workspaceId} in ${result.detail}\n` +
-            `[h2a] supervise: remote jobs status ${slug}   attach: remote jobs attach ${slug}\n`);
+            `[h2a] supervise: h2a jobs status ${slug}   attach: h2a jobs attach ${slug}\n`);
         return { launched: true, detail: `${host} ${slug}` };
     };
     /** One pass: handle the freshest unprocessed launch envelope (or report none). */
@@ -4429,7 +4697,7 @@ export async function main(argv) {
             }
             const pane = resolveAgentPaneForInstance(target);
             if (!pane) {
-                process.stderr.write(`[h2a] wake-request: no agent pane for ${target} — not launched by remote, skipping (reason: ${reason || "none"})\n`);
+                process.stderr.write(`[h2a] wake-request: no agent pane for ${target} — not launched by h2a, skipping (reason: ${reason || "none"})\n`);
                 continue;
             }
             // Guard (h2a 0.74.0 parity): defer send-keys if a human was active in the
@@ -4481,7 +4749,7 @@ export async function main(argv) {
         .command("wake-request")
         .description("Handle an h2a `wake-request` envelope: read the local h2a inbox for a wake-request, " +
         "resolve the target agent pane from launch records, and send tmux send-keys to wake it. " +
-        "No-op if no pane is known for the target (agent not launched by remote). " +
+        "No-op if no pane is known for the target (agent not launched by h2a). " +
         "Idempotent: ignores duplicate wake-requests received within 60s. " +
         "--watch loops in the foreground.")
         .option("--root <path>", "h2a root (default: ~/h2a-workspace/.h2a)")
@@ -4588,7 +4856,7 @@ export async function main(argv) {
     // Reliability slice 2 (throttle phase 2) — auto-resume RATE-LIMITED INTERACTIVE
     // local tmux sessions, staggered + hands-off.
     //
-    // INTERACTIVE `remote run` sessions (claude/codex/agy in a live pane) do NOT
+    // INTERACTIVE `h2a run` sessions (claude/codex/agy in a live pane) do NOT
     // exit on a transient provider rate-limit — they STALL until a human pokes them.
     // This passes the pure `planInteractiveResume` the per-session pane tail
     // (detectThrottle source), `#{session_attached}` (the HARD detached-only guard),
@@ -4743,18 +5011,19 @@ export async function main(argv) {
         process.exitCode = await watchRefreshLoop(minutes, async () => runOnce());
     });
     // ---------------------------------------------------------------------------
-    // h2a — bridge the local agent network (~/h2a-workspace/.h2a) with session Pods
+    // relay — bridge the local agent network (~/h2a-workspace/.h2a) with session Pods
     // ---------------------------------------------------------------------------
-    const h2aCommand = program
-        .command("h2a")
+    const relayCommand = program
+        .command("relay")
+        .alias("h2a")
         .description("h2a agent-network helpers (local file store: ~/h2a-workspace/.h2a)");
-    h2aCommand
+    relayCommand
         .command("ping <instance>")
         .description("Drop an `h2a.ping` envelope into the local h2a inbox for <instance> (e.g. codex:remote:sess-1). Use --bridge to push it to a remote session immediately.")
         .option("--from <instance>", "sender h2a instance", "remote:cli")
         .option("-m, --message <text>", "ping message body", "ping")
         .option("--root <path>", "local h2a root (default: ~/h2a-workspace/.h2a)")
-        .option("--bridge [sessionId]", "after queuing the ping, run one h2a bridge pass for this remote session (defaults from <instance> when it is <tool>:remote:<sessionId>)")
+        .option("--bridge [sessionId]", "after queuing the ping, run one relay bridge pass for this remote session (defaults from <instance> when it is <tool>:remote:<sessionId>)")
         .action(async (instance, opts) => {
         const ping = sendH2aPing({
             to: instance,
@@ -4763,7 +5032,7 @@ export async function main(argv) {
             cwd: process.cwd(),
             ...(opts.root !== undefined ? { localRoot: opts.root } : {}),
         });
-        process.stderr.write(`[h2a] h2a ping ${ping.written ? "queued" : "already queued"} for ${instance}: ${ping.path}\n`);
+        process.stderr.write(`[h2a] relay ping ${ping.written ? "queued" : "already queued"} for ${instance}: ${ping.path}\n`);
         if (opts.bridge === undefined)
             return;
         const sessionId = typeof opts.bridge === "string"
@@ -4781,28 +5050,28 @@ export async function main(argv) {
         const { bridgeSession } = await import("./h2a-bridge.js");
         try {
             const r = await bridgeSession(sessionId, { profile });
-            process.stderr.write(`[h2a] h2a bridge ${sessionId} (${profile}) pulled=${r.pulled} pushed=${r.pushed} skipped=${r.skipped}` +
+            process.stderr.write(`[h2a] relay bridge ${sessionId} (${profile}) pulled=${r.pulled} pushed=${r.pushed} skipped=${r.skipped}` +
                 `${r.failed > 0 ? ` failed=${r.failed}` : ""}\n`);
             if (r.failed > 0)
                 process.exitCode = 1;
         }
         catch (error) {
-            process.stderr.write(`[h2a] h2a bridge ${sessionId} failed: ${(error instanceof Error ? error.message : String(error)).slice(0, 200)}\n`);
+            process.stderr.write(`[h2a] relay bridge ${sessionId} failed: ${(error instanceof Error ? error.message : String(error)).slice(0, 200)}\n`);
             process.exitCode = 1;
         }
     });
-    h2aCommand
+    relayCommand
         .command("bridge [sessionId]")
         .description("Bridge h2a envelopes with session Pod(s) over kubectl exec: PULL envelopes the Pod's agent emitted (Pod inbox/* minus the Pod's own instances) into the local inboxes, PUSH local envelopes addressed to the Pod's instances (<tool>:remote:<sessionId> + the Pod's registry) into the Pod. Idempotent by file name (existing files are skipped, never overwritten), NEVER deletes (acks/cleanup belong to h2a). A Pod without ~/h2a-workspace/.h2a gets the skeleton + README. Without sessionId: every live session.")
         .option("--watch <minutes>", "repeat the bridge every N minutes in the FOREGROUND; Ctrl-C to stop")
         .addHelpText("after", [
         "",
         "Examples:",
-        "  $ remote h2a bridge sess-abc         one pass for one session",
-        "  $ remote h2a bridge                  one pass for every live session",
-        "  $ remote h2a bridge --watch 5        foreground loop, every 5 min",
+        "  $ h2a relay bridge sess-abc           one pass for one session",
+        "  $ h2a relay bridge                    one pass for every live session",
+        "  $ h2a relay bridge --watch 5          foreground loop, every 5 min",
         "  Run the watch in a dedicated tmux window, e.g.:",
-        "    tmux new-window -n h2a-bridge 'remote h2a bridge --watch 5'",
+        "    tmux new-window -n h2a-bridge 'h2a relay bridge --watch 5'",
         "",
     ].join("\n"))
         .action(async (sessionId, opts) => {
@@ -4848,13 +5117,13 @@ export async function main(argv) {
                     const r = await bridgeSession(s.id, { profile: s.profile });
                     if (r.failed > 0)
                         failed += 1;
-                    process.stderr.write(`[h2a] h2a bridge ${s.id} (${s.profile}) pulled=${r.pulled} pushed=${r.pushed} skipped=${r.skipped}` +
+                    process.stderr.write(`[h2a] relay bridge ${s.id} (${s.profile}) pulled=${r.pulled} pushed=${r.pushed} skipped=${r.skipped}` +
                         `${r.failed > 0 ? ` failed=${r.failed}` : ""}` +
                         `${r.scaffolded ? " (pod .h2a scaffolded)" : ""}\n`);
                 }
                 catch (error) {
                     failed += 1;
-                    process.stderr.write(`[h2a] h2a bridge ${s.id} failed: ${(error instanceof Error ? error.message : String(error)).slice(0, 200)}\n`);
+                    process.stderr.write(`[h2a] relay bridge ${s.id} failed: ${(error instanceof Error ? error.message : String(error)).slice(0, 200)}\n`);
                 }
             }
             return { failed };
@@ -4966,7 +5235,16 @@ export async function main(argv) {
             if (result.backupPath) {
                 process.stderr.write(`[h2a] backup: ${result.backupPath}\n`);
             }
-            process.stderr.write(`[h2a] installed ${result.installed.join(" + ")} enroll hooks in ${result.settingsPath}\n`);
+            process.stderr.write(`[h2a] ${[
+                result.installed.length > 0
+                    ? `installed ${result.installed.join(" + ")}`
+                    : undefined,
+                result.migrated.length > 0
+                    ? `migrated ${result.migrated.join(" + ")}`
+                    : undefined,
+            ]
+                .filter((part) => part !== undefined)
+                .join("; ")} enroll hooks in ${result.settingsPath}\n`);
             return;
         }
         if (opts.hook) {
@@ -5030,12 +5308,12 @@ export async function main(argv) {
         // Local tmux session? (unless an explicit URL/sessionId pair is given).
         if (second === undefined && !looksLikeUrl(first)) {
             const local = findLocalSession(first);
-            // A session started by `remote run` is enrolled in the registry as
+            // A session started by `h2a run` is enrolled in the registry as
             // kind:"local-tmux". Trust that durable record even when a transient
             // `tmux list-sessions` miss hides the live session — otherwise a purely
             // LOCAL session is mis-routed to a k8s Pod (kubectl exec session-<name>
             // → NotFound → reconnect loop) as soon as a tunnel is configured.
-            // `remote ls` already merges registry + tmux; attach must not be less
+            // `h2a ls` already merges registry + tmux; attach must not be less
             // reliable. When the registry says local but tmux can't reach it,
             // attachLocalSession fails with a clear LOCAL error (never a Pod).
             const localName = local?.name ?? localTmuxSessionForName(first, loadRegistry());
@@ -5908,6 +6186,8 @@ if (isEntryPoint()) {
         process.exitCode = 1;
     });
 }
+export { main as dispatchH2a };
+/** @deprecated Compatibility for older h2a cores; new cores require dispatchH2a. */
 export { main as dispatch };
 /**
  * h2a-facing surface: the read-only remote-agents projection consumed by the