@sentropic/h2a-runtime 0.88.0 → 0.89.0

package/dist/index.js

@@ -15,15 +15,17 @@ 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, 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 { attachLocalSession, attachPodTmux, capturePane, capturePaneVisible, clearPaneComposer, conductorRunning, currentTmuxSessionName, currentTmuxSessionIs, ensureManagedTmuxProfile, ensureHeadlessTerminal, existingLocalSessionSlugs, fanoutLabels, findLocalSession, killLocalSession, localSessionGatewayEnvStatus, listLocalSessions, localSessionIdle, localSessionPanePid, localSessionName, paneTreeCpuMs, paneWorkerPid, pasteLiteralBlock, submitPane, installH2aStatusSurface, managedSessionCandidates, parseManagedSessionName, openH2aStatusWindow, persistLaunchContext, readLaunchContext, relaunchInSession, resolveAgentPane, resolveAgentPaneForInstance, resolveLocalSession, runLocalCliForeground, sendKeysLiteral, sessionAttached, sessionAttachedCount, setLocalSessionDisplayName, slugify, cleanupHeadlessPromptFile, startH2aWindow, startH2aWindowVerified, startHeadlessSession, startLocalSession, tmuxAvailable, uninstallH2aStatusSurface, } from "./tmux.js";
+import { deliverInitialPrompt, sleepSync, } from "./prompt-delivery.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";
+import { isHumanFacingSession, readLastLayout, restore as restoreLayout, } from "./restore.js";
 import { getLayoutConfig } from "./config.js";
 import { advanceJob, coerceRegistryTool, enroll, enrollFromRun, isLive, listJobs, listLocalForLs, loadRegistry, resolveLocalTmuxSessionForName, tryClaimSlot, withRegistryLock, resolveRegistryPath, } from "./registry.js";
+import { SessionLeaseStore, decideSessionBeat, isSessionLeaseAbandoned, planLeaseSupervision, reclaimProposals, resolveSessionLeasePath, } from "./session-lease.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";
@@ -905,18 +907,21 @@ export async function startJob(job) {
     const restoreGatewayEnvironment = replaceAnthropicGatewayEnvironment(process.env, meshEnv ?? undefined);
     let tmuxSession;
     let workerPid;
+    let agentPane;
     try {
         if (headless) {
             const dir = jobDir(originCwd, 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;
+            agentPane = launched.agentPane;
             workerPid = launched.agentPane
                 ? localSessionPanePid(launched.agentPane)
                 : undefined;
         }
         else {
-            const launched = startLocalSession(job.tool, argv.command, runCwd, argv.args, job.id, undefined, { sessionClass: "background" });
+            const launched = startLocalSession(job.tool, argv.command, runCwd, argv.args, job.id, undefined, { sessionClass: "background", attachedTerminal: true });
             tmuxSession = launched.name;
+            agentPane = launched.agentPane;
             workerPid = launched.agentPane
                 ? localSessionPanePid(launched.agentPane)
                 : undefined;
@@ -971,6 +976,21 @@ export async function startJob(job) {
             ? { delegatorTmuxSession: job.delegatorTmuxSession }
             : {}),
     });
+    // Take the SLOT lease for this session (machine-scoped). From here on the slot
+    // is held only as long as something keeps beating it — a session that finishes
+    // without dying stops beating and its slot is reported reclaimable after one
+    // TTL, instead of the 994 minutes measured on the worst hoarder. Best-effort:
+    // a lease hiccup must never break a launch that already happened.
+    try {
+        acquireSessionLease(job.id, {
+            holder: job.delegatorInstance ?? "h2a:startJob",
+            workspace: runCwd,
+            ...(agentPane !== undefined ? { agentPane } : {}),
+        });
+    }
+    catch {
+        // the store is advisory — the job is running either way
+    }
     mirrorNew();
     return {
         started: true,
@@ -978,6 +998,91 @@ export async function startJob(job) {
         detail: `${runCwd}${isolated ? " [worktree]" : ""}`,
     };
 }
+/**
+ * Open the machine-scoped session-lease store. The clock is injected HERE, at
+ * the call site, and never read inside the store: abandonment stays a reader's
+ * computation against an instant the caller names.
+ */
+function sessionLeaseStore() {
+    return new SessionLeaseStore(resolveSessionLeasePath(), {
+        now: () => new Date().toISOString(),
+    });
+}
+/**
+ * Take the slot lease for a freshly launched session, seeding it with the pane's
+ * current process-tree CPU so the FIRST supervising pass already has a baseline
+ * to compute a rate against.
+ */
+export function acquireSessionLease(sessionId, opts) {
+    const cpuMs = opts.agentPane ? paneTreeCpuMs(opts.agentPane) : undefined;
+    return sessionLeaseStore().acquire({
+        sessionId,
+        holder: opts.holder,
+        ...(opts.workspace !== undefined ? { workspace: opts.workspace } : {}),
+        ...(cpuMs !== undefined ? { cpuMs } : {}),
+    });
+}
+/**
+ * One supervising pass: for every recorded lease, decide from the REGISTRY what
+ * to do, then — for sessions still running — probe the pane's process tree and
+ * beat only what is actually working. Everything else merely records its CPU
+ * reading, so the abandonment clock keeps running.
+ *
+ * This pass NEVER kills, never sends a key, and never frees a slot on its own.
+ * Its only output beyond the store is a list of PROPOSALS.
+ */
+export function superviseSessionLeases(sessions, now = new Date().toISOString()) {
+    const store = sessionLeaseStore();
+    const result = {
+        beaten: [],
+        observed: [],
+        released: [],
+        unreadable: [],
+        proposals: [],
+    };
+    const leases = store.readAll();
+    const byId = new Map(leases.map((lease) => [lease.sessionId, lease]));
+    for (const step of planLeaseSupervision(leases, sessions)) {
+        const lease = byId.get(step.sessionId);
+        if (lease === undefined)
+            continue;
+        try {
+            if (step.action === "release") {
+                store.release({ sessionId: lease.sessionId, token: lease.token });
+                result.released.push(lease.sessionId);
+                continue;
+            }
+            if (step.action === "leave")
+                continue;
+            const pane = step.tmuxSession ? resolveAgentPane(step.tmuxSession) : undefined;
+            const cpuMsNow = pane ? paneTreeCpuMs(pane) : undefined;
+            const decision = decideSessionBeat({ lease, cpuMsNow, now });
+            if (decision.action === "beat" && cpuMsNow !== undefined) {
+                store.heartbeat({ sessionId: lease.sessionId, token: lease.token, cpuMs: cpuMsNow });
+                result.beaten.push(lease.sessionId);
+            }
+            else if (decision.action === "observe" && cpuMsNow !== undefined) {
+                store.observe({ sessionId: lease.sessionId, token: lease.token, cpuMs: cpuMsNow });
+                result.observed.push(lease.sessionId);
+            }
+            else {
+                result.unreadable.push(lease.sessionId);
+            }
+        }
+        catch {
+            // a rejected write (raced re-acquisition, torn store) must not stop the pass
+        }
+    }
+    result.proposals = reclaimProposals(store.readAll(), now);
+    return result;
+}
+/** Human-readable duration for lease reporting ("41m", "2h13m"). */
+function formatIdle(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes}m`;
+    return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
+}
 /**
  * Reliability slice 1 — RESUME a throttled HEADLESS LOCAL job. Relaunch the SAME
  * job in the SAME `runCwd` it already ran in (its recorded `cwd` — NOT a fresh
@@ -1327,12 +1432,18 @@ function registryEntryForResumeTarget(target, local) {
             ? [target]
             : managedSessionCandidates(canonicalSlug);
     const matches = loadRegistry().filter((e) => {
-        // 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")
+        // Resume is a human-facing operation, not a promotion path: a delegated job
+        // or an explicit background launch must never become resumable here.
+        //
+        // The class test is SHARED with restore rather than written inline, because
+        // written inline it was an opt-in on an explicit class and every record
+        // enrolled before the class existed failed closed — measured as "cannot
+        // resume <slug>: registry has no human session" on entries that are plainly
+        // human sessions. Two gates judging the same question in two ways is how one
+        // of them ends up wrong on its own.
+        if (e.role !== undefined || e.kind !== "local-tmux")
+            return false;
+        if (!isHumanFacingSession(e))
             return false;
         // Full managed names are exact targets; never reinterpret one as an id
         // or label that happens to share a prefix-shaped string.
@@ -3408,7 +3519,7 @@ export async function main(argv) {
             }
         }
         gateway = await injectLlmMeshGatewayEnv(effectiveGatewayMode, true, localSessionName(resumeSlug));
-        const { name } = startLocalSession(profile, command, entry.cwd, args, resumeSlug, undefined, { sessionClass: "human" });
+        const { name } = startLocalSession(profile, command, entry.cwd, args, resumeSlug, undefined, { sessionClass: "human", attachedTerminal: true });
         enrollFromRun({
             profile,
             slug: resumeSlug,
@@ -3432,6 +3543,7 @@ export async function main(argv) {
         .command("run <profile> [path]")
         .description("Start a LOCAL session in tmux (claude/codex/…) in <path> (default: cwd), then attach this terminal by default. h2a applies its embedded scroll-safe tmux profile at launch; no ~/.tmux.conf is required. Manage it with `h2a ls`, `h2a attach <slug>`, and `h2a stop <slug>`. Detach with Ctrl-b d; the session keeps running.")
         .option("--no-attach", "start detached and print the attach command instead (for scripts / fan-out orchestration)")
+        .option("--no-attached-terminal", "disable the persistent headless tmux client (legacy compatibility; cannot be used with --prompt-stdin)")
         .option("-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")
@@ -3485,6 +3597,11 @@ export async function main(argv) {
             process.exitCode = 2;
             return;
         }
+        if (opts.promptStdin && opts.attachedTerminal === false) {
+            process.stderr.write("[h2a] --prompt-stdin requires the attached terminal; remove --no-attached-terminal.\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;
@@ -3673,6 +3790,7 @@ export async function main(argv) {
             let resultJson;
             let agentPane;
             let promptFile;
+            let promptDelivery;
             if (opts.headless) {
                 const runDir = join(cwd, ".h2a", "runs", label);
                 mkdirSync(runDir, { recursive: true });
@@ -3690,6 +3808,7 @@ export async function main(argv) {
                         ? { terminateOnAgentExit: true }
                         : {}),
                     ...(structuredLaunch ? { refuseExisting: true } : {}),
+                    attachedTerminal: opts.attachedTerminal !== false,
                     sessionClass,
                 }));
             }
@@ -3725,18 +3844,54 @@ export async function main(argv) {
                     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;
+            if (!opts.headless && initialPrompt !== undefined) {
+                // NEVER paste-and-hope: `tmux new-session -d` returns before the
+                // agent TUI draws anything, and a prompt sent into that window is
+                // echoed by the raw terminal and then discarded. Delivery is
+                // OBSERVED — brief seen in a real composer, then real work — because
+                // reporting "started" over a lost brief is what left a lane inert
+                // for 33 minutes on 2026-07-28.
+                promptDelivery = deliverInitialPrompt(agentPane, initialPrompt, {
+                    capturePane: capturePaneVisible,
+                    clearComposer: clearPaneComposer,
+                    pasteBlock: pasteLiteralBlock,
+                    submit: submitPane,
+                    cpuMs: paneTreeCpuMs,
+                    sleep: sleepSync,
+                    now: () => Date.now(),
+                });
+                if (promptDelivery.state !== "working") {
+                    cleanupHeadlessPromptFile(promptFile);
+                    // Only claim the session is gone when the kill actually reported
+                    // success. "nothing is left running" over an unchecked call is the
+                    // same wider-than-its-evidence claim this change exists to remove,
+                    // and a surviving partial session is precisely the idle lane the
+                    // operator was just told could not happen.
+                    const stopped = killLocalSession(name);
+                    const detail = promptDelivery.state === "submitted-idle"
+                        ? `the brief was submitted but the agent never started working ` +
+                            `(${Math.round(promptDelivery.cpuDeltaMs)}ms of CPU): it is not "started"`
+                        : promptDelivery.reason;
+                    process.stderr.write(`[h2a] the initial prompt did not reach ${slug}: ${detail}\n` +
+                        (promptDelivery.state === "host-modal"
+                            ? `[h2a] fix: ${promptDelivery.hint}\n`
+                            : "") +
+                        (stopped
+                            ? `[h2a] the partial session was stopped, so nothing is left running idle\n`
+                            : `[h2a] WARNING: stopping the partial session FAILED — ${name} may still be alive; ` +
+                                `list it with h2a ls and stop it with h2a stop ${slug} --reason failed-launch\n`) +
+                        (promptDelivery.state !== "submitted-idle" &&
+                            promptDelivery.capture
+                            ? `[h2a] last screen:\n${promptDelivery.capture}\n`
+                            : ""));
+                    process.exitCode = 1;
+                    return;
+                }
             }
             const pid = agentPane
                 ? localSessionPanePid(agentPane)
                 : undefined;
+            const workerPid = agentPane !== undefined ? paneWorkerPid(agentPane) : undefined;
             if (structuredLaunch && pid === undefined) {
                 cleanupHeadlessPromptFile(promptFile);
                 killLocalSession(name);
@@ -3752,6 +3907,7 @@ export async function main(argv) {
                 slug,
                 tmuxSession: name,
                 ...(pid !== undefined ? { pid } : {}),
+                ...(workerPid !== undefined ? { workerPid } : {}),
                 cwd,
                 sessionClass,
                 ...(opts.resume !== undefined ? { convId: opts.resume } : {}),
@@ -3765,6 +3921,7 @@ export async function main(argv) {
                 ...(pid !== undefined ? { pid } : {}),
                 ...(outputLog !== undefined ? { outputLog } : {}),
                 ...(resultJson !== undefined ? { resultJson } : {}),
+                ...(promptDelivery !== undefined ? { promptDelivery } : {}),
             });
         }
         if (count > 1) {
@@ -3792,10 +3949,28 @@ export async function main(argv) {
                     h2aSidecar: only.h2aSidecar,
                     ...(only.pane !== undefined ? { pane: only.pane } : {}),
                     ...(only.pid !== undefined ? { pid: only.pid } : {}),
+                    // `pid` is the launch WRAPPER. Measured 2026-07-29: it showed 0s
+                    // of CPU after 37s while its codex child had burned 13s, so a
+                    // liveness check on `pid` alone reports a working agent as dead.
+                    // Name the process that actually works, and say it is distinct.
+                    ...(only.workerPid !== undefined
+                        ? { workerPid: only.workerPid }
+                        : {}),
                 },
                 attach: opts.headless
                     ? null
                     : { command: "h2a", args: ["attach", only.slug] },
+                // What was OBSERVED, not what was attempted: the brief was seen in
+                // a real composer, submitted, and the agent's CPU then moved.
+                ...(only.promptDelivery?.state === "working"
+                    ? {
+                        prompt: {
+                            delivered: true,
+                            waitedMs: only.promptDelivery.waitedMs,
+                            cpuDeltaMs: Math.round(only.promptDelivery.cpuDeltaMs),
+                        },
+                    }
+                    : {}),
                 ...(only.outputLog !== undefined
                     ? {
                         logs: { path: only.outputLog },
@@ -4358,6 +4533,74 @@ export async function main(argv) {
         if (claudeWarn)
             process.stderr.write(`${claudeWarn}\n`);
     });
+    jobsCommand
+        .command("leases")
+        .description("Session slot leases (machine-scoped): who holds a concurrency slot, when it last proved it was working, and which slots are reclaimable. READ-ONLY — it kills nothing and frees nothing.")
+        .option("--probe", "before reporting, run one supervising pass: beat the leases of sessions whose pane is burning CPU, record the others")
+        .action((opts) => {
+        const now = new Date().toISOString();
+        if (opts.probe === true)
+            superviseSessionLeases(listJobs(), now);
+        const leases = sessionLeaseStore().readAll();
+        if (leases.length === 0) {
+            process.stdout.write("no session leases\n");
+            return;
+        }
+        const nowMs = Date.parse(now);
+        const rows = leases
+            .slice()
+            .sort((a, b) => Date.parse(a.heartbeatAt) - Date.parse(b.heartbeatAt))
+            .map((lease) => {
+            const idle = nowMs - Date.parse(lease.heartbeatAt);
+            const state = isSessionLeaseAbandoned(lease, now) ? "RECLAIMABLE" : "held";
+            return (`${lease.sessionId.padEnd(24)} ${state.padEnd(12)} ` +
+                `idle ${formatIdle(idle).padEnd(7)} ttl ${formatIdle(lease.ttlMs).padEnd(6)} ` +
+                `holder ${lease.holder}`);
+        });
+        process.stdout.write(`${rows.join("\n")}\n`);
+        const reclaimable = reclaimProposals(leases, now).length;
+        if (reclaimable > 0) {
+            process.stderr.write(`[h2a] ${reclaimable} slot(s) reclaimable — free one with: h2a jobs reclaim <id> ` +
+                "(the session's tmux window is left running and can still be attached)\n");
+        }
+    });
+    jobsCommand
+        .command("reclaim <id>")
+        .description("Free the concurrency SLOT of a session that stopped working (its lease is abandoned): the job is marked terminal and its lease released. It does NOT kill anything — the tmux session keeps running and stays attachable. Refuses while the lease is still being beaten.")
+        .action((id) => {
+        const now = new Date().toISOString();
+        const store = sessionLeaseStore();
+        const lease = store.forSession(id);
+        if (!lease) {
+            process.stderr.write(`[h2a] no session lease for "${id}" — nothing to reclaim (see: h2a jobs leases)\n`);
+            process.exitCode = 1;
+            return;
+        }
+        // The one guard that matters: a session still proving it works keeps its
+        // slot, whatever the operator believes. Reclaiming is not arbitration.
+        if (!isSessionLeaseAbandoned(lease, now)) {
+            const idle = Date.parse(now) - Date.parse(lease.heartbeatAt);
+            process.stderr.write(`[h2a] refusing to reclaim ${id}: its lease still beats (last proof of work ` +
+                `${formatIdle(idle)} ago, TTL ${formatIdle(lease.ttlMs)}). It is working.\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const job = listJobs().find((e) => e.id === id);
+        const advanced = job ? advanceJob(id, "failed") : undefined;
+        try {
+            store.release({ sessionId: id, token: lease.token });
+        }
+        catch (err) {
+            process.stderr.write(`[h2a] lease release failed: ${err.message}\n`);
+        }
+        process.stdout.write(`reclaimed ${id} — slot freed after ` +
+            `${formatIdle(Date.parse(now) - Date.parse(lease.heartbeatAt))} without work\n`);
+        process.stderr.write(`[h2a] the session was NOT killed: ${job?.tmuxSession ?? "its tmux session"} is still running ` +
+            `(h2a jobs attach ${id}). ` +
+            (advanced === undefined
+                ? "No registry entry to advance — only the lease was released.\n"
+                : "The job is recorded terminal so the conductor can admit queued work.\n"));
+    });
     jobsCommand
         .command("status <id>")
         .description("Show a job's detail (+ output.log / result.json paths for headless jobs).")
@@ -4638,6 +4881,23 @@ export async function main(argv) {
         if (effectiveCap < cap) {
             process.stderr.write(`[h2a] conduct: AIMD breaker — admitting up to ${effectiveCap}/${cap} (rate-limit pressure)\n`);
         }
+        // (a'') SESSION LEASES — beat what is working, and REPORT what has stopped.
+        // A finished-but-alive session is invisible to (a): it is `isJobLive`, so
+        // reconcile and the stale sweep both skip it, and it keeps its slot for as
+        // long as it stays alive. The lease pass is the only thing here that reads
+        // inactivity rather than death. It proposes; it never frees a slot itself.
+        try {
+            const supervision = superviseSessionLeases(refreshed);
+            for (const proposal of supervision.proposals) {
+                process.stderr.write(`[h2a] conduct: ${proposal.sessionId} has held its slot without working for ` +
+                    `${formatIdle(proposal.idleMs)} (holder ${proposal.holder}, TTL ${formatIdle(proposal.ttlMs)}). ` +
+                    `NOT killed — inspect it with: h2a jobs attach ${proposal.sessionId}   ` +
+                    `free the slot with: h2a jobs reclaim ${proposal.sessionId}\n`);
+            }
+        }
+        catch {
+            // the lease store is advisory: a failure here must not stop the conductor
+        }
         // (b) start pending jobs under the EFFECTIVE cap (oldest-first FIFO).
         let started = 0;
         for (const id of planNextStarts(refreshed, effectiveCap)) {
@@ -5629,6 +5889,7 @@ export async function main(argv) {
         .option("--exec", "force exec-into-Pod-tmux attach (this is the DEFAULT when a tunnel is configured: UTF-8, native scrollback + copy)")
         .option("--ws", "force the legacy WS/SSE attach (control-plane proxy) instead of exec")
         .option("--local", "force local tmux lookup")
+        .option("--headless-terminal", "attach a persistent 160x48 PTY client without taking over this terminal (local sessions only)")
         .action(async (first, second, opts) => {
         // Local tmux session? (unless an explicit URL/sessionId pair is given).
         if (second === undefined && !looksLikeUrl(first)) {
@@ -5653,6 +5914,16 @@ export async function main(argv) {
                     process.exitCode = 1;
                     return;
                 }
+                if (opts.headlessTerminal) {
+                    const terminal = ensureHeadlessTerminal(localName);
+                    if (terminal.state === "unavailable") {
+                        process.stderr.write(`[h2a] could not attach a persistent terminal to ${first}: ${terminal.reason}\n`);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    process.stderr.write(`[h2a] persistent terminal ${terminal.state} for ${first} (${terminal.attachedClients} attached client(s))\n`);
+                    return;
+                }
                 process.exitCode = attachLocalSession(localName);
                 return;
             }