@sentropic/h2a-runtime 0.85.25 → 0.87.0

package/dist/index.js

@@ -6,6 +6,7 @@ import { homedir } from "node:os";
 import { basename, isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Command } from "commander";
+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";
 import { ensureConnected, stopTunnel } from "./tunnel.js";
@@ -14,7 +15,10 @@ 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, existingLocalSessionSlugs, fanoutLabels, findLocalSession, killLocalSession, localSessionGatewayEnvStatus, listLocalSessions, localSessionIdle, localSessionPanePid, localSessionName, managedSessionCandidates, parseManagedSessionName, readLaunchContext, relaunchInSession, resolveAgentPaneForInstance, resolveLocalSession, runLocalCliForeground, sendKeysLiteral, sessionAttached, sessionAttachedCount, setLocalSessionDisplayName, slugify, cleanupHeadlessPromptFile, startH2aWindow, startH2aWindowVerified, startHeadlessSession, startLocalSession, tmuxAvailable, } from "./tmux.js";
+import { attachLocalSession, attachPodTmux, capturePane, conductorRunning, currentTmuxSessionName, currentTmuxSessionIs, ensureManagedTmuxProfile, existingLocalSessionSlugs, fanoutLabels, findLocalSession, killLocalSession, localSessionGatewayEnvStatus, listLocalSessions, localSessionIdle, localSessionPanePid, localSessionName, installH2aStatusSurface, managedSessionCandidates, parseManagedSessionName, openH2aStatusWindow, persistLaunchContext, readLaunchContext, relaunchInSession, resolveAgentPaneForInstance, resolveLocalSession, runLocalCliForeground, sendKeysLiteral, sessionAttached, sessionAttachedCount, setLocalSessionDisplayName, slugify, cleanupHeadlessPromptFile, startH2aWindow, startH2aWindowVerified, startHeadlessSession, startLocalSession, tmuxAvailable, uninstallH2aStatusSurface, } from "./tmux.js";
+import { buildLaunchContext } from "./launch-context.js";
+import { migrateTmuxNames } from "./tmux-name-migration.js";
+import { projectStatusForH2a } from "./status-projection.js";
 import { buildAgentLaunchArgs, isAgentLaunchEffort, isAgentLaunchProfile, } from "./agent-launch-args.js";
 import { planRelaunch } from "./relaunch.js";
 import { readLastLayout, restore as restoreLayout, } from "./restore.js";
@@ -59,8 +63,8 @@ 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, enrollGeminiAccount, readLlmMeshConfig, startGateway, stopGateway, writeLlmMeshConfig, readGatewayPid, llmMeshLogPath, jwtExpiry, refreshAccountToken, readLlmMeshSessionEnv, acquireLlmMeshSessionEnv, } from "./llm-mesh.js";
+import { CLI_PROFILES, gatewayModeForProfile, profileUsesLlmMeshGateway, } from "./protocol-local.js";
+import { enrollCodexAccount, enrollClaudeAccount, enrollGeminiAccount, readLlmMeshConfig, startGateway, stopGateway, writeLlmMeshConfig, readGatewayPid, llmMeshLogPath, jwtExpiry, refreshAccountToken, replaceAnthropicGatewayEnvironment, readLlmMeshSessionEnv, acquireLlmMeshSessionEnv, } from "./llm-mesh.js";
 const KNOWN_PROFILE_HELP = `${CLI_PROFILES.join(", ")} (aliases: claude-code, antigravity, gemini-cli, mistralcli)`;
 export const packageName = "@sentropic/h2a-runtime";
 export const H2A_RUNTIME_CLI_API_VERSION = 1;
@@ -754,10 +758,20 @@ export async function startJob(job) {
                 kind: "remote",
                 cwd: ws.id,
                 source: "remote",
+                sessionClass: "background",
                 label: job.id,
                 remoteId: session.id,
                 role: "job",
                 jobState: "running",
+                ...(job.delegationOrigin !== undefined
+                    ? { delegationOrigin: job.delegationOrigin }
+                    : {}),
+                ...(job.delegatorInstance !== undefined
+                    ? { delegatorInstance: job.delegatorInstance }
+                    : {}),
+                ...(job.delegatorTmuxSession !== undefined
+                    ? { delegatorTmuxSession: job.delegatorTmuxSession }
+                    : {}),
                 // Persist originCwd so reconcile reads result.json under the right dir
                 // (H2) regardless of the conductor's cwd.
                 ...(job.originCwd !== undefined ? { originCwd: job.originCwd } : {}),
@@ -860,23 +874,52 @@ export async function startJob(job) {
     // 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 meshEnv = getLlmMeshRuntimeConfig().enabled
-        ? readLlmMeshSessionEnv()
-        : null;
-    if (meshEnv) {
-        for (const [k, v] of Object.entries(meshEnv)) {
-            prevAccountEnvs[k] = process.env[k];
-            process.env[k] = v;
+    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) {
+        for (const [key, previous] of Object.entries(prevAccountEnvs)) {
+            if (previous === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = previous;
         }
+        return {
+            started: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
     }
+    const restoreGatewayEnvironment = replaceAnthropicGatewayEnvironment(process.env, meshEnv ?? undefined);
     let tmuxSession;
+    let workerPid;
     try {
         if (headless) {
             const dir = jobDir(originCwd, job.id);
-            ({ name: tmuxSession } = startHeadlessSession(job.tool, argv.command, runCwd, argv.args, join(dir, "result.json"), join(dir, "output.log"), job.id));
+            const launched = startHeadlessSession(job.tool, argv.command, runCwd, argv.args, join(dir, "result.json"), join(dir, "output.log"), job.id, undefined, undefined, false, "background");
+            tmuxSession = launched.name;
+            workerPid = launched.agentPane
+                ? localSessionPanePid(launched.agentPane)
+                : undefined;
         }
         else {
-            ({ name: tmuxSession } = startLocalSession(job.tool, argv.command, runCwd, argv.args, job.id));
+            const launched = startLocalSession(job.tool, argv.command, runCwd, argv.args, job.id, undefined, { sessionClass: "background" });
+            tmuxSession = launched.name;
+            workerPid = launched.agentPane
+                ? localSessionPanePid(launched.agentPane)
+                : undefined;
             const h2a = getH2aConfig();
             startH2aWindow(tmuxSession, runCwd, h2a.command);
         }
@@ -885,6 +928,7 @@ export async function startJob(job) {
         return { started: false, error: err.message };
     }
     finally {
+        restoreGatewayEnvironment();
         if (prevDepth === undefined)
             delete process.env[DEPTH_ENV];
         else
@@ -906,8 +950,10 @@ export async function startJob(job) {
         kind: "local-tmux",
         cwd: runCwd,
         source: "run",
+        sessionClass: "background",
         label: job.id,
         tmuxSession,
+        ...(workerPid !== undefined ? { pid: workerPid } : {}),
         role: "job",
         jobState: "running",
         // Persist originCwd (H2): result.json/output.log live under originCwd, read
@@ -915,6 +961,15 @@ export async function startJob(job) {
         originCwd,
         ...(job.task !== undefined ? { task: job.task } : {}),
         ...(job.callbackTo !== undefined ? { callbackTo: job.callbackTo } : {}),
+        ...(job.delegationOrigin !== undefined
+            ? { delegationOrigin: job.delegationOrigin }
+            : {}),
+        ...(job.delegatorInstance !== undefined
+            ? { delegatorInstance: job.delegatorInstance }
+            : {}),
+        ...(job.delegatorTmuxSession !== undefined
+            ? { delegatorTmuxSession: job.delegatorTmuxSession }
+            : {}),
     });
     mirrorNew();
     return {
@@ -1000,9 +1055,14 @@ export function resumeThrottledJob(job) {
     process.env[DEPTH_ENV] = childDepthEnvValue(job.depthBudget ?? clampDepth(undefined));
     process.env[JOB_ID_ENV] = job.id;
     let tmuxSession;
+    let workerPid;
     try {
         const dir = jobDir(originCwd, job.id);
-        ({ name: tmuxSession } = startHeadlessSession(job.tool, argv.command, runCwd, argv.args, join(dir, "result.json"), join(dir, "output.log"), job.id));
+        const launched = startHeadlessSession(job.tool, argv.command, runCwd, argv.args, join(dir, "result.json"), join(dir, "output.log"), job.id, undefined, undefined, false, "background");
+        tmuxSession = launched.name;
+        workerPid = launched.agentPane
+            ? localSessionPanePid(launched.agentPane)
+            : undefined;
     }
     catch (err) {
         return { started: false, error: err.message };
@@ -1038,13 +1098,24 @@ export function resumeThrottledJob(job) {
         kind: "local-tmux",
         cwd: runCwd,
         source: "run",
+        sessionClass: "background",
         label: job.id,
         tmuxSession,
+        ...(workerPid !== undefined ? { pid: workerPid } : {}),
         role: "job",
         jobState: "running",
         originCwd,
         ...(job.task !== undefined ? { task: job.task } : {}),
         ...(job.callbackTo !== undefined ? { callbackTo: job.callbackTo } : {}),
+        ...(job.delegationOrigin !== undefined
+            ? { delegationOrigin: job.delegationOrigin }
+            : {}),
+        ...(job.delegatorInstance !== undefined
+            ? { delegatorInstance: job.delegatorInstance }
+            : {}),
+        ...(job.delegatorTmuxSession !== undefined
+            ? { delegatorTmuxSession: job.delegatorTmuxSession }
+            : {}),
         ...(job.throttle !== undefined ? { throttle: job.throttle } : {}),
     });
     return { started: true, target: "local", detail: `${runCwd} [resume]` };
@@ -1161,7 +1232,7 @@ function gatewayModeFromOptions(opts) {
     return "auto";
 }
 function shouldUseClaudeBare(profile) {
-    return ((profile === "claude" || profile === "claude-code") &&
+    return (profileUsesLlmMeshGateway(profile) &&
         Boolean(process.env.ANTHROPIC_BASE_URL && process.env.ANTHROPIC_AUTH_TOKEN));
 }
 async function injectLlmMeshGatewayEnv(mode = "auto", allowDirectFallback = true, clientSessionId) {
@@ -1256,7 +1327,12 @@ function registryEntryForResumeTarget(target, local) {
             ? [target]
             : managedSessionCandidates(canonicalSlug);
     const matches = loadRegistry().filter((e) => {
-        if (e.role !== undefined || e.kind !== "local-tmux")
+        // Resume is a human-facing operation, not a promotion path.  Keep the
+        // durable class intact by accepting only explicitly human rows; legacy and
+        // background entries fail closed instead of becoming restorable here.
+        if (e.role !== undefined ||
+            e.kind !== "local-tmux" ||
+            e.sessionClass !== "human")
             return false;
         // Full managed names are exact targets; never reinterpret one as an id
         // or label that happens to share a prefix-shaped string.
@@ -1368,8 +1444,112 @@ export async function main(argv) {
     const program = new Command();
     program
         .name("h2a")
-        .description("Wrap a local agent CLI (codex/claude/agy/gemini/mistral) and expose its session for h2a attach.")
+        // The previous wording ("Wrap a local agent CLI … and expose its session for
+        // h2a attach.") described h2a before the consolidation: it named only the
+        // session-wrapper role and taught nothing about track, harness, focus or the
+        // h2a protocol. See docs/TRANSITION.md § 1. Deliberately NOT claimed here:
+        // that h2a is a native agent.
+        //
+        // An earlier version of this comment justified that omission by calling the
+        // change "owner-approved but unshipped", citing an unpublished internal
+        // study. Review was right to strike it: there is no reachable warrant for
+        // the approval — no committed decision record, and the study is on no git
+        // ref — so the claim could not be checked by anyone reading this file. An
+        // uncheckable appeal to the owner's approval is the same defect as an
+        // uncheckable citation to a study. The omission needs no warrant anyway:
+        // h2a is not a native agent today, which is a fact about this binary.
+        .description("The unified sentropic CLI and core: start and return to agent work sessions " +
+        "(local tmux or cluster), coordinate agents over the h2a protocol, and read " +
+        "or record the work — one entry point for the surfaces that used to live in " +
+        "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");
+    const tmuxCommand = program
+        .command("tmux")
+        .description("Manage h2a's local tmux naming and status surface");
+    tmuxCommand
+        .command("migrate-names")
+        .description("Plan, apply, or roll back legacy remote-* to h2a-* session names")
+        .option("--dry-run", "show the exact rename plan (default)")
+        .option("--apply", "rename collision-free sessions and update the registry")
+        .option("--rollback", "reverse the journalled migration")
+        .action((opts) => {
+        const selected = [opts.dryRun, opts.apply, opts.rollback].filter(Boolean);
+        if (selected.length > 1) {
+            process.stderr.write("[h2a] choose exactly one of --dry-run, --apply, or --rollback\n");
+            process.exitCode = 2;
+            return;
+        }
+        const mode = opts.apply
+            ? "apply"
+            : opts.rollback
+                ? "rollback"
+                : "dry-run";
+        const result = migrateTmuxNames(mode);
+        for (const entry of result.entries) {
+            process.stdout.write(`${entry.tmuxSessionId.padEnd(5)} ${entry.state.padEnd(11)} ${entry.oldName} -> ${entry.newName}` +
+                `${entry.registryEntriesUpdated ? `  registry:${entry.registryEntriesUpdated}` : ""}\n`);
+        }
+        for (const collision of result.collisions) {
+            process.stderr.write(`[h2a] collision: ${collision.oldName} cannot become ${collision.newName}\n`);
+        }
+        for (const warning of result.warnings) {
+            process.stderr.write(`[h2a] ${warning}\n`);
+        }
+        process.stderr.write(`[h2a] tmux name migration ${mode}: ${result.changed} session(s) changed\n`);
+        if (result.collisions.length > 0 || result.warnings.length > 0) {
+            process.exitCode = 2;
+        }
+    });
+    const tmuxStatusCommand = tmuxCommand
+        .command("status")
+        .description("Install or restore the h2a tmux status surface");
+    tmuxStatusCommand
+        .command("install [session]")
+        .option("--all", "install on every currently managed h2a/legacy session")
+        .action((session, opts) => {
+        const targets = opts.all
+            ? listLocalSessions().map((item) => item.name)
+            : session
+                ? [session]
+                : [];
+        if (targets.length === 0) {
+            process.stderr.write("[h2a] tmux status install requires an exact session or --all\n");
+            process.exitCode = 2;
+            return;
+        }
+        let installed = 0;
+        for (const target of targets) {
+            if (installH2aStatusSurface(target))
+                installed += 1;
+        }
+        process.stderr.write(`[h2a] installed status surface on ${installed} session(s)\n`);
+        if (installed !== targets.length)
+            process.exitCode = 2;
+    });
+    tmuxStatusCommand
+        .command("uninstall [session]")
+        .option("--all", "restore captured options on every managed session")
+        .action((session, opts) => {
+        const targets = opts.all
+            ? listLocalSessions().map((item) => item.name)
+            : session
+                ? [session]
+                : [];
+        if (targets.length === 0) {
+            process.stderr.write("[h2a] tmux status uninstall requires an exact session or --all\n");
+            process.exitCode = 2;
+            return;
+        }
+        let restored = 0;
+        for (const target of targets) {
+            if (uninstallH2aStatusSurface(target))
+                restored += 1;
+        }
+        process.stderr.write(`[h2a] restored prior status options on ${restored} session(s)\n`);
+        if (restored !== targets.length)
+            process.exitCode = 2;
+    });
     for (const [profileName, alias] of [
         ["codex", undefined],
         ["claude", "claude-code"],
@@ -3106,7 +3286,13 @@ export async function main(argv) {
             process.exitCode = 1;
             return;
         }
-        const gateway = await injectLlmMeshGatewayEnv(gatewayMode, true, entry.convId ?? localSessionName(resumeSlug));
+        if (gatewayMode === "gateway" && !profileUsesLlmMeshGateway(profile)) {
+            process.stderr.write(`[h2a] --llm-gateway/--gw is unsupported for ${profile}; this gateway is Anthropic-compatible and only Claude profiles consume it.\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const effectiveGatewayMode = gatewayModeForProfile(profile, gatewayMode);
+        let gateway;
         const useBare = shouldUseClaudeBare(profile);
         const command = localCliCommand(profile);
         const args = localResumeArgs(profile, entry.convId, {
@@ -3135,6 +3321,13 @@ export async function main(argv) {
             process.stderr.write(`[h2a] local session ${displaySlug} already exists and does not look idle; no new ${profile} was started.\n`);
             if (opts.attach || explicitProfile) {
                 if (explicitProfile && currentTmuxSessionIs(local.name)) {
+                    gateway = await injectLlmMeshGatewayEnv(effectiveGatewayMode, true, local.name);
+                    persistLaunchContext(local.name, buildLaunchContext({
+                        profile,
+                        cwd: entry.cwd,
+                        label: displaySlug,
+                        ...(entry.convId ? { resumeId: entry.convId } : {}),
+                    }));
                     process.stderr.write(`[h2a] already inside ${displaySlug}; running ${profile} resume in this pane\n`);
                     process.exitCode = runLocalCliForeground(command, args);
                     return;
@@ -3214,12 +3407,14 @@ export async function main(argv) {
                 }
             }
         }
-        const { name } = startLocalSession(profile, command, entry.cwd, args, resumeSlug);
+        gateway = await injectLlmMeshGatewayEnv(effectiveGatewayMode, true, localSessionName(resumeSlug));
+        const { name } = startLocalSession(profile, command, entry.cwd, args, resumeSlug, undefined, { sessionClass: "human" });
         enrollFromRun({
             profile,
             slug: resumeSlug,
             tmuxSession: name,
             cwd: entry.cwd,
+            sessionClass: "human",
             ...(entry.convId ? { convId: entry.convId } : {}),
             ...(gatewayMode !== "auto" ? { gatewayMode } : {}),
         });
@@ -3398,15 +3593,17 @@ export async function main(argv) {
             process.exitCode = 1;
             return;
         }
-        if (structuredLaunch &&
-            profile === "codex" &&
-            gatewayMode === "gateway") {
-            process.stderr.write("[h2a] --gw is unsupported for structured codex launches (llm-mesh is Anthropic-compatible)\n");
+        if (gatewayMode === "gateway" && !profileUsesLlmMeshGateway(profile)) {
+            process.stderr.write(`[h2a] --llm-gateway/--gw is unsupported for ${profile}; this gateway is Anthropic-compatible and only Claude profiles consume it.\n`);
             process.exitCode = 2;
             return;
         }
-        const launchGatewayMode = structuredLaunch && profile === "codex" ? "direct" : gatewayMode;
+        const launchGatewayMode = gatewayModeForProfile(profile, gatewayMode);
         const command = localCliCommand(profile);
+        // A detached/background or run-once launch is a worker, even when its
+        // agent later emits a Claude SessionStart hook. Stamp this through tmux
+        // so that hook cannot reclassify it as a human session.
+        const sessionClass = opts.background || opts.headless ? "background" : "human";
         let activeGateway;
         const h2a = getH2aConfig();
         const h2aSidecar = opts.h2a ?? h2a.enabled;
@@ -3422,13 +3619,13 @@ export async function main(argv) {
         }
         const started = [];
         for (const label of labels) {
-            const clientSessionId = opts.resume ?? localSessionName(slugify(label ?? cwd));
+            const clientSessionId = localSessionName(slugify(label ?? cwd));
             try {
                 if (structuredLaunch) {
                     activeGateway = await prepareStructuredGateway(launchGatewayMode, (selectedMode) => injectLlmMeshGatewayEnv(selectedMode, selectedMode !== "gateway", clientSessionId));
                 }
                 else {
-                    activeGateway = await injectLlmMeshGatewayEnv(gatewayMode, true, clientSessionId);
+                    activeGateway = await injectLlmMeshGatewayEnv(launchGatewayMode, true, clientSessionId);
                 }
             }
             catch (error) {
@@ -3481,7 +3678,7 @@ export async function main(argv) {
                 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));
+                ({ name, slug, agentPane, promptFile } = startHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, getTmuxProfileConfig().profile, initialPrompt, structuredLaunch, sessionClass));
             }
             else {
                 ({ name, slug, agentPane } = startLocalSession(profile, command, cwd, args, label, getTmuxProfileConfig().profile, {
@@ -3493,6 +3690,7 @@ export async function main(argv) {
                         ? { terminateOnAgentExit: true }
                         : {}),
                     ...(structuredLaunch ? { refuseExisting: true } : {}),
+                    sessionClass,
                 }));
             }
             if (structuredLaunch && !agentPane) {
@@ -3553,10 +3751,11 @@ export async function main(argv) {
                 profile,
                 slug,
                 tmuxSession: name,
+                ...(pid !== undefined ? { pid } : {}),
                 cwd,
+                sessionClass,
                 ...(opts.resume !== undefined ? { convId: opts.resume } : {}),
                 ...(gatewayMode !== "auto" ? { gatewayMode } : {}),
-                ...(opts.background ? { sessionClass: "background" } : {}),
             });
             started.push({
                 name,
@@ -3653,6 +3852,12 @@ export async function main(argv) {
         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;
+        // A CLI delegation is attributable only when the caller explicitly
+        // names its callback owner AND tmux can identify the exact delegating
+        // session.  Do not infer either value from a job name or cwd.
+        const delegatorTmuxSession = callbackTo
+            ? currentTmuxSessionName()
+            : undefined;
         try {
             assertSafeName(jobId);
         }
@@ -3716,6 +3921,7 @@ export async function main(argv) {
                 kind: isRemote ? "remote" : "local-tmux",
                 cwd: isRemote ? `job-${jobId}` : process.cwd(),
                 source: isRemote ? "remote" : "run",
+                sessionClass: "background",
                 label: jobId,
                 role: "job",
                 jobState: "pending",
@@ -3726,6 +3932,13 @@ export async function main(argv) {
                 ...(remoteTarget !== undefined ? { remoteTarget } : {}),
                 ...(explicitCwd !== undefined ? { explicitCwd } : {}),
                 ...(callbackTo !== undefined ? { callbackTo } : {}),
+                ...(callbackTo !== undefined && delegatorTmuxSession !== undefined
+                    ? {
+                        delegationOrigin: "cli:h2a-delegate",
+                        delegatorInstance: callbackTo,
+                        delegatorTmuxSession,
+                    }
+                    : {}),
                 ...(opts.track !== undefined ? { trackWp: opts.track } : {}),
                 ...(opts.model !== undefined ? { model: opts.model } : {}),
                 ...(opts.effort !== undefined ? { effort: opts.effort } : {}),
@@ -3745,6 +3958,7 @@ export async function main(argv) {
             kind: (isRemote ? "remote" : "local-tmux"),
             cwd: isRemote ? `job-${jobId}` : process.cwd(),
             source: (isRemote ? "remote" : "run"),
+            sessionClass: "background",
             label: jobId,
             role: "job",
             task,
@@ -3754,6 +3968,13 @@ export async function main(argv) {
             ...(remoteTarget !== undefined ? { remoteTarget } : {}),
             ...(explicitCwd !== undefined ? { explicitCwd } : {}),
             ...(callbackTo !== undefined ? { callbackTo } : {}),
+            ...(callbackTo !== undefined && delegatorTmuxSession !== undefined
+                ? {
+                    delegationOrigin: "cli:h2a-delegate",
+                    delegatorInstance: callbackTo,
+                    delegatorTmuxSession,
+                }
+                : {}),
             ...(opts.track !== undefined ? { trackWp: opts.track } : {}),
             ...(opts.model !== undefined ? { model: opts.model } : {}),
             ...(opts.effort !== undefined ? { effort: opts.effort } : {}),
@@ -3797,6 +4018,13 @@ export async function main(argv) {
                 ...(remoteTarget !== undefined ? { remoteTarget } : {}),
                 ...(explicitCwd !== undefined ? { explicitCwd } : {}),
                 ...(callbackTo !== undefined ? { callbackTo } : {}),
+                ...(callbackTo !== undefined && delegatorTmuxSession !== undefined
+                    ? {
+                        delegationOrigin: "cli:h2a-delegate",
+                        delegatorInstance: callbackTo,
+                        delegatorTmuxSession,
+                    }
+                    : {}),
                 ...(opts.track !== undefined ? { trackWp: opts.track } : {}),
                 ...(opts.model !== undefined ? { model: opts.model } : {}),
                 ...(opts.effort !== undefined ? { effort: opts.effort } : {}),
@@ -4591,6 +4819,7 @@ export async function main(argv) {
             enrolledAt: new Date().toISOString(),
             lastSeenAt: new Date().toISOString(),
             source: "run",
+            sessionClass: "background",
             label: slug,
             role: "job",
             jobState: "running",
@@ -4605,6 +4834,7 @@ export async function main(argv) {
             kind: "local-tmux",
             cwd: process.cwd(),
             source: "run",
+            sessionClass: "background",
             label: slug,
             role: "job",
             jobState: "pending",
@@ -6271,6 +6501,57 @@ export async function main(argv) {
             ? `[h2a] lineage ${id} resumed\n`
             : `[h2a] lineage ${id} was not suspended (no-op)\n`);
     });
+    // Help layout only — assign every top-level command an intention group and
+    // render the groups in the declared order instead of registration order.
+    // Presentational for every PRE-EXISTING RECOGNIZED COMMAND: `helpGroup()` and
+    // the `groupItems` override touch nothing but the heading a command is listed
+    // under, so dispatch, argv parsing, exit codes and `--json` payloads are
+    // unchanged for all 46 of them. The top-level help layout and the root
+    // description DO change here — that is the point of the change, not an
+    // exception to it. Stating the narrow property rather than "zero behaviour
+    // change", which was wider than the evidence.
+    //
+    // ┌── TWO ORDER-DEPENDENCIES, both recorded because neither is guarded.
+    // │   Keep both calls after the last `program.command(...)` registration.
+    // │
+    // │   A COMMENT IS NOT A SAFETY MECHANISM. Neither (a) nor (b) below is
+    // │   enforced by any test. If you move these calls, the suite will not tell
+    // │   you — it will stay green, because both dependencies are currently inert
+    // │   for the reasons given. They are written down so the next person can see
+    // │   the latch, not because the latch is held shut.
+    // │
+    // │ (a) `configureHelp` writes `program._helpConfiguration`, which Commander
+    // │     copies to each subcommand in `copyInheritedSettings` — invoked from
+    // │     `.command()` AT REGISTRATION TIME (commander/lib/command.js:104). So
+    // │     placing this after all registration means no subcommand inherits
+    // │     `groupItems`.
+    // │
+    // │     MEASURED, not assumed: hoisting this call to before registration was
+    // │     tried, and `--help`, `run --help`, `account --help`, `jobs --help` and
+    // │     `relay --help` all came back BYTE-IDENTICAL. The inheritance is real
+    // │     but INERT, because `groupRuntimeHelpItems` re-emits any heading it does
+    // │     not own (`Commands:`, `Options:`) unchanged — and a subcommand's own
+    // │     children never carry one of our headings. So placement is currently a
+    // │     preference, NOT a correctness requirement, and no test claims
+    // │     otherwise. What IS pinned is the pass-through property that makes it
+    // │     inert: "the group override passes through headings it does not own"
+    // │     in packages/h2a/test/cli-command-map.test.js. It would stop being inert
+    // │     if a subcommand's child were ever given one of our group headings.
+    // │
+    // │ (b) `visibleCommands()` forces Commander to create its implicit `help`
+    // │     command NOW (`_addImplicitHelpCommand`), so that it gets a group too —
+    // │     otherwise it is the lone survivor of the default `Commands:` heading.
+    // │     Side effect: a command registered AFTER this point would inherit the
+    // │     parent's already-created help-command instance
+    // │     (commander/lib/command.js:103) instead of getting its own. An
+    // │     adversarial A/B confirmed that inheritance does happen. It is inert
+    // │     today only because nothing is registered after this line, it is
+    // │     harmless in the output even then, and NOTHING GUARDS IT — a property
+    // │     of statement order, not an invariant. Recorded, not relied upon.
+    // └──
+    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]);
     const code = process.exitCode;
     return typeof code === "number" ? code : 0;
@@ -6311,6 +6592,12 @@ export { main as dispatch };
 export function projectAgentsForH2a() {
     return projectRemoteAgents({ jobs: listJobs(), localRows: listLocalForLs() });
 }
+export { projectStatusForH2a };
+/** Open the detailed watcher only for an exact, currently managed session. */
+export function openStatusWindowForH2a(session) {
+    const exact = listLocalSessions().find((item) => item.name === session);
+    return exact ? openH2aStatusWindow(exact.name, exact.path) : false;
+}
 /**
  * h2a-facing surface: read-only tmux pane snapshot for the canevas ③ session
  * view, consumed by `@sentropic/h2a`'s canevas adapter via lazy `import()`.