@sentropic/h2a-runtime 0.88.0 → 0.90.0

package/dist/tmux.d.ts

@@ -176,7 +176,44 @@ export type ManagedLaunchMetadata = {
     terminateOnAgentExit?: boolean;
     /** Refuse an existing name instead of reusing it (structured launch contract). */
     refuseExisting?: boolean;
+    /**
+     * Keep a real, fixed-size PTY client attached while the pane is remotely
+     * driven. Required before an initial TUI prompt can be delivered reliably.
+     */
+    attachedTerminal?: boolean;
+};
+/** Fixed PTY geometry for a non-human tmux client. */
+export declare const HEADLESS_TERMINAL_SIZE: {
+    readonly cols: 160;
+    readonly rows: 48;
+};
+export type HeadlessTerminalResult = {
+    readonly state: "already-attached";
+    readonly attachedClients: number;
+} | {
+    readonly state: "headless-attached";
+    readonly attachedClients: number;
+    readonly cols: number;
+    readonly rows: number;
+} | {
+    readonly state: "unavailable";
+    readonly reason: string;
+};
+export type EnsureHeadlessTerminalOptions = {
+    /** How long to wait for tmux to observe the new client. */
+    readonly timeoutMs?: number;
+    /** Poll cadence while the script-owned client starts. */
+    readonly pollMs?: number;
 };
+/**
+ * Give a detached tmux session a genuine terminal, without taking over the
+ * launcher terminal. `script` allocates a PTY and an intentionally idle pipe
+ * keeps its stdin open; without that pipe `script` receives EOF from a
+ * headless launcher and the tmux client immediately detaches. A pipe or `tmux
+ * send-keys` alone is not a terminal, and both Codex and Claude can drop their
+ * initial composer input when started that way.
+ */
+export declare function ensureHeadlessTerminal(session: string, options?: EnsureHeadlessTerminalOptions): HeadlessTerminalResult;
 /**
  * Pure builder for the global tmux options applied at every run/attach. Split
  * out of `ensureScrollConfig` so the option set (scroll/clipboard AND the
@@ -410,10 +447,48 @@ export declare function sessionAttached(name: string): boolean;
  * Paste a LITERAL line into a session's main pane, then submit it with a real
  * Enter key event. Content reaches `tmux load-buffer -` on stdin, then a named
  * buffer is pasted: arbitrary text is never interpreted by a shell and never
- * appears in a process argv. Enter is a separate key-name event. Used both for
- * initial prompts and interactive throttle nudges.
+ * appears in a process argv. Enter is a separate key-name event. Used for
+ * interactive throttle nudges (single lines).
  */
 export declare function sendKeysLiteral(name: string, keys: string): boolean;
+/**
+ * Paste text as ONE block, WITHOUT submitting it.
+ *
+ * `-p` wraps the payload in bracketed-paste markers. Measured 2026-07-29 on
+ * Claude Code 2.1.220: without `-p`, a multi-line brief is submitted line by
+ * line — line 1 left as its own request while line 2 stayed in the composer.
+ * With `-p` the whole block lands as a single entry that one Enter submits.
+ */
+export declare function pasteLiteralBlock(name: string, keys: string): boolean;
+/** Submit whatever the composer currently holds (one real Enter key event). */
+export declare function submitPane(name: string): boolean;
+/**
+ * Best-effort composer wipe. Ctrl-U only kills to the start of the CURRENT
+ * line, so a multi-line composer needs several — measured: one C-u left a
+ * multi-line brief in place, and retrying the paste then STACKED copies.
+ * Delivery never depends on this succeeding; it types only once.
+ */
+export declare function clearPaneComposer(name: string): boolean;
+/**
+ * VISIBLE text of one pane, or undefined when tmux cannot be read — unlike
+ * `capturePane`, which flattens a failure into "". Delivery needs the
+ * difference: an unreadable pane is not an empty one.
+ */
+export declare function capturePaneVisible(pane: string): string | undefined;
+/**
+ * CPU time (ms) of the process tree behind a pane — the liveness signal used to
+ * tell a working agent from one parked on its placeholder.
+ */
+export declare function paneTreeCpuMs(pane: string): number | undefined;
+/**
+ * The pid actually doing the work behind a pane.
+ *
+ * The pane's own pid is the launch WRAPPER: measured 2026-07-29, it reported 0s
+ * of CPU after 37s while its `codex` child had burned 13s. Anything that judges
+ * a lane by the reported pid alone — a supervisor, a status bar, a conductor —
+ * is reading the wrong process, and gets a false answer in both directions.
+ */
+export declare function paneWorkerPid(pane: string): number | undefined;
 /**
  * Attach the real terminal straight into the Pod's tmux session via
  * `kubectl exec -it`. The local terminal talks to tmux directly (no WS proxy),

package/dist/tmux.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tmux.d.ts","sourceRoot":"","sources":["../src/tmux.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tmux.d.ts","sourceRoot":"","sources":["../src/tmux.ts"],"names":[],"mappings":"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"}

package/dist/tmux.js

@@ -10,12 +10,13 @@
  *    the LOCAL terminal owns scrollback + copy (OSC52) with no WS proxy in the
  *    middle — this is what fixes "I can't copy the code claude printed".
  */
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { getTmuxProfileConfig } from "./config.js";
-import { mkdtempSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { basename, join } from "node:path";
 import { homedir, tmpdir } from "node:os";
+import { readProcessTreeCpuMs, readWorkerPid } from "./proc-cpu.js";
 import { LAUNCH_OPTION_PREFIX, buildLaunchContext, launchContextOptions, parseLaunchContext, redactSecrets, } from "./launch-context.js";
 import { SESSION_CLASS_ENV } from "./session-class.js";
 const TMUX = "tmux";
@@ -352,6 +353,91 @@ export function getLocalSessionDisplayName(session) {
     const v = r.stdout.trim();
     return v || undefined;
 }
+/** Fixed PTY geometry for a non-human tmux client. */
+export const HEADLESS_TERMINAL_SIZE = { cols: 160, rows: 48 };
+const HEADLESS_TERMINAL_TIMEOUT_MS = 5_000;
+const HEADLESS_TERMINAL_POLL_MS = 50;
+const HEADLESS_TERMINAL_MARKER = "@h2a_attached_terminal";
+function sleepBlocking(ms) {
+    if (ms <= 0)
+        return;
+    const cell = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(cell, 0, 0, ms);
+}
+/**
+ * Give a detached tmux session a genuine terminal, without taking over the
+ * launcher terminal. `script` allocates a PTY and an intentionally idle pipe
+ * keeps its stdin open; without that pipe `script` receives EOF from a
+ * headless launcher and the tmux client immediately detaches. A pipe or `tmux
+ * send-keys` alone is not a terminal, and both Codex and Claude can drop their
+ * initial composer input when started that way.
+ */
+export function ensureHeadlessTerminal(session, options = {}) {
+    const attached = sessionAttachedCount(session);
+    if (attached !== undefined && attached > 0) {
+        return { state: "already-attached", attachedClients: attached };
+    }
+    if (attached === undefined) {
+        return {
+            state: "unavailable",
+            reason: `tmux could not inspect session ${session}`,
+        };
+    }
+    if (!commandAvailable("script")) {
+        return {
+            state: "unavailable",
+            reason: "the util-linux `script` command is required to allocate a persistent PTY",
+        };
+    }
+    let launchError;
+    try {
+        const child = spawn("/bin/sh", [
+            "-c",
+            `exec tail -f /dev/null | script -qefc 'export TERM=xterm-256color; stty cols ${HEADLESS_TERMINAL_SIZE.cols} rows ${HEADLESS_TERMINAL_SIZE.rows}; exec tmux -u attach-session -t "$H2A_HEADLESS_TARGET"' /dev/null`,
+        ], {
+            detached: true,
+            stdio: "ignore",
+            env: {
+                ...process.env,
+                H2A_HEADLESS_TARGET: exactSessionTarget(session),
+            },
+        });
+        child.on("error", (error) => {
+            launchError = error.message;
+        });
+        child.unref();
+    }
+    catch (error) {
+        return {
+            state: "unavailable",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const timeoutMs = options.timeoutMs ?? HEADLESS_TERMINAL_TIMEOUT_MS;
+    const pollMs = options.pollMs ?? HEADLESS_TERMINAL_POLL_MS;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const clients = sessionAttachedCount(session);
+        if (clients !== undefined && clients > 0) {
+            setSessionOption(session, HEADLESS_TERMINAL_MARKER, `headless:${HEADLESS_TERMINAL_SIZE.cols}x${HEADLESS_TERMINAL_SIZE.rows}`);
+            return {
+                state: "headless-attached",
+                attachedClients: clients,
+                ...HEADLESS_TERMINAL_SIZE,
+            };
+        }
+        if (launchError) {
+            return { state: "unavailable", reason: launchError };
+        }
+        if (Date.now() >= deadline) {
+            return {
+                state: "unavailable",
+                reason: `tmux client did not attach within ${timeoutMs}ms`,
+            };
+        }
+        sleepBlocking(Math.min(pollMs, Math.max(1, deadline - Date.now())));
+    }
+}
 /**
  * First clipboard CLI found on PATH, or undefined. With `mouse on`, a mouse
  * drag is captured by tmux (copy-mode) instead of the terminal's NATIVE
@@ -567,7 +653,7 @@ export function ensureScrollConfig(profile) {
 export function startLocalSession(profile, command, cwd, args = [], label, tmuxProfile = getTmuxProfileConfig().profile, metadata = {}) {
     const slug = slugify(label ?? cwd);
     const name = localSessionName(slug);
-    const { sessionClass, terminateOnAgentExit = false, refuseExisting = false, ...launchMetadata } = metadata;
+    const { sessionClass, terminateOnAgentExit = false, refuseExisting = false, attachedTerminal = false, ...launchMetadata } = metadata;
     ensureScrollConfig(tmuxProfile);
     const existing = resolveLocalSessionSlug(slug);
     if (existing.kind === "ambiguous") {
@@ -579,12 +665,31 @@ export function startLocalSession(profile, command, cwd, args = [], label, tmuxP
         }
         const agentPane = persistAgentPaneMetadata(existing.session.name, profile, cwd);
         persistLaunchContext(existing.session.name, buildLaunchContext({ profile, cwd, label, ...launchMetadata }));
+        if (attachedTerminal) {
+            const terminal = ensureHeadlessTerminal(existing.session.name);
+            if (terminal.state === "unavailable") {
+                throw new Error(`could not attach a persistent terminal to ${existing.session.slug}: ${terminal.reason}`);
+            }
+        }
         return {
             name: existing.session.name,
             slug: existing.session.slug,
             ...(agentPane ? { agentPane } : {}),
         };
     }
+    const agentCommand = [
+        ...anthopicEnvUnsetCommandPrefix(),
+        "/bin/bash",
+        "-lc",
+        terminateOnAgentExit ? STRUCTURED_LOCAL_WRAPPER : LOCAL_WRAPPER,
+        ...(terminateOnAgentExit
+            ? [command]
+            : [
+                localRelaunchCommand(profile, cwd, label, metadata.resumeId ? ["--resume", metadata.resumeId] : []),
+                command,
+            ]),
+        ...args,
+    ];
     const r = spawnSync(TMUX, [
         "new-session",
         "-d",
@@ -601,17 +706,13 @@ export function startLocalSession(profile, command, cwd, args = [], label, tmuxP
         profile,
         "-c",
         cwd,
-        ...anthopicEnvUnsetCommandPrefix(),
-        "/bin/bash",
-        "-lc",
-        terminateOnAgentExit ? STRUCTURED_LOCAL_WRAPPER : LOCAL_WRAPPER,
-        ...(terminateOnAgentExit
-            ? [command]
-            : [
-                localRelaunchCommand(profile, cwd, label, metadata.resumeId ? ["--resume", metadata.resumeId] : []),
-                command,
-            ]),
-        ...args,
+        // A detached pane has no actual terminal client. Do not start a TUI
+        // there: a process that reads stdin before the PTY client attaches sees
+        // EOF, while one that starts rendering can lose the first prompt. Keep a
+        // benign pane alive, attach and verify the PTY, then respawn the agent.
+        ...(attachedTerminal
+            ? ["/bin/bash", "-lc", "exec sleep 86400"]
+            : agentCommand),
     ], {
         encoding: "utf8",
         stdio: ["inherit", "pipe", "inherit"],
@@ -622,10 +723,31 @@ export function startLocalSession(profile, command, cwd, args = [], label, tmuxP
     const printedPane = r.stdout?.trim();
     const capturedPane = validTmuxPaneId(printedPane) ? printedPane : undefined;
     const agentPane = persistAgentPaneMetadata(name, profile, cwd, capturedPane);
-    if ((terminateOnAgentExit || refuseExisting) && !agentPane) {
+    if ((terminateOnAgentExit || refuseExisting || attachedTerminal) && !agentPane) {
         killLocalSession(name);
         throw new Error(`tmux did not return a live agent pane for ${slug}`);
     }
+    if (attachedTerminal) {
+        const terminal = ensureHeadlessTerminal(name);
+        if (terminal.state === "unavailable") {
+            killLocalSession(name);
+            throw new Error(`could not attach a persistent terminal to ${slug}: ${terminal.reason}`);
+        }
+        const respawned = spawnSync(TMUX, [
+            "respawn-pane",
+            "-k",
+            "-t",
+            agentPane,
+            "-c",
+            cwd,
+            ...tmuxEnvironmentArgs(sessionClass),
+            ...agentCommand,
+        ], { stdio: ["ignore", "ignore", "ignore"] });
+        if (respawned.status !== 0) {
+            killLocalSession(name);
+            throw new Error(`tmux could not start the agent pane for ${slug} after terminal attachment`);
+        }
+    }
     // Record the profile as a session option so `remote ls` can show it.
     spawnSync(TMUX, ["set-option", "-t", name, "@profile", profile], {
         stdio: "ignore",
@@ -755,7 +877,7 @@ export function cleanupHeadlessPromptFile(promptFile) {
  * we never send keys into a session a human is driving. Best-effort.
  */
 export function sessionAttachedCount(name) {
-    const r = spawnSync(TMUX, ["display", "-p", "-t", `=${name}`, "#{session_attached}"], { encoding: "utf8" });
+    const r = spawnSync(TMUX, ["display", "-p", "-t", exactSessionTarget(name), "#{session_attached}"], { encoding: "utf8" });
     if (r.status !== 0 || r.stdout === undefined)
         return undefined;
     const n = Number.parseInt(r.stdout.trim(), 10);
@@ -845,8 +967,25 @@ export function commandAvailable(cmd) {
 function validTmuxPaneId(value) {
     return value !== undefined && /^%\d+$/.test(value);
 }
+/**
+ * Exact, fail-closed SESSION target for `-t`, for both `show-options` and
+ * `set-option`.
+ *
+ * Measured on tmux 3.6:
+ *   -t <name>     bare  -> resolves exact THEN unique-PREFIX, so `set-option -t
+ *                          h2a-foo` mutates `h2a-foobar` when h2a-foo is gone.
+ *   -t =<name>          -> `=` marks a PANE target here; both commands miss the
+ *                          session, and `-q` swallows the error so a read returns
+ *                          "" — which is why the status surface silently never
+ *                          installed on this tmux.
+ *   -t =<name>:         -> `=` exact + trailing `:` (the session's target):
+ *                          resolves the EXACT session, fails closed when it is
+ *                          absent, and works for read and write alike.
+ * So the correct exact-session form is `=<name>:`.
+ */
 function exactSessionTarget(session) {
-    return session.startsWith("=") ? session : `=${session}`;
+    const bare = session.replace(/^=/, "").replace(/:$/, "");
+    return `=${bare}:`;
 }
 function readSessionOption(session, option) {
     const r = spawnSync(TMUX, ["show-options", "-qv", "-t", exactSessionTarget(session), option], { encoding: "utf8" });
@@ -1422,7 +1561,7 @@ export function relaunchInSession(name, command) {
  */
 export function sessionAttached(name) {
     try {
-        const r = spawnSync(TMUX, ["display", "-p", "-t", `=${name}`, "#{session_attached}"], { encoding: "utf8" });
+        const r = spawnSync(TMUX, ["display", "-p", "-t", exactSessionTarget(name), "#{session_attached}"], { encoding: "utf8" });
         if (r.status !== 0)
             return true; // can't tell → assume attached (never nudge)
         const n = Number((r.stdout ?? "").trim());
@@ -1438,10 +1577,18 @@ export function sessionAttached(name) {
  * Paste a LITERAL line into a session's main pane, then submit it with a real
  * Enter key event. Content reaches `tmux load-buffer -` on stdin, then a named
  * buffer is pasted: arbitrary text is never interpreted by a shell and never
- * appears in a process argv. Enter is a separate key-name event. Used both for
- * initial prompts and interactive throttle nudges.
+ * appears in a process argv. Enter is a separate key-name event. Used for
+ * interactive throttle nudges (single lines).
  */
 export function sendKeysLiteral(name, keys) {
+    if (!loadAndPaste(name, keys, false))
+        return false;
+    const enter = spawnSync(TMUX, ["send-keys", "-t", name, "Enter"], {
+        stdio: "ignore",
+    });
+    return enter.status === 0;
+}
+function loadAndPaste(name, keys, bracketed) {
     const buffer = `h2a-${process.pid}-${randomUUID()}`;
     const loaded = spawnSync(TMUX, ["load-buffer", "-b", buffer, "-"], {
         input: keys,
@@ -1450,15 +1597,114 @@ export function sendKeysLiteral(name, keys) {
     });
     if (loaded.status !== 0)
         return false;
-    const pasted = spawnSync(TMUX, ["paste-buffer", "-b", buffer, "-d", "-t", name], { stdio: "ignore" });
+    const pasted = spawnSync(TMUX, [
+        "paste-buffer",
+        ...(bracketed ? ["-p"] : []),
+        "-b",
+        buffer,
+        "-d",
+        "-t",
+        name,
+    ], { stdio: "ignore" });
     if (pasted.status !== 0) {
         spawnSync(TMUX, ["delete-buffer", "-b", buffer], { stdio: "ignore" });
         return false;
     }
-    const enter = spawnSync(TMUX, ["send-keys", "-t", name, "Enter"], {
+    return true;
+}
+/**
+ * Paste text as ONE block, WITHOUT submitting it.
+ *
+ * `-p` wraps the payload in bracketed-paste markers. Measured 2026-07-29 on
+ * Claude Code 2.1.220: without `-p`, a multi-line brief is submitted line by
+ * line — line 1 left as its own request while line 2 stayed in the composer.
+ * With `-p` the whole block lands as a single entry that one Enter submits.
+ */
+export function pasteLiteralBlock(name, keys) {
+    return loadAndPaste(name, keys, true);
+}
+/** Submit whatever the composer currently holds (one real Enter key event). */
+export function submitPane(name) {
+    const r = spawnSync(TMUX, ["send-keys", "-t", name, "Enter"], {
         stdio: "ignore",
     });
-    return enter.status === 0;
+    return r.status === 0;
+}
+/**
+ * Best-effort composer wipe. Ctrl-U only kills to the start of the CURRENT
+ * line, so a multi-line composer needs several — measured: one C-u left a
+ * multi-line brief in place, and retrying the paste then STACKED copies.
+ * Delivery never depends on this succeeding; it types only once.
+ */
+export function clearPaneComposer(name) {
+    let ok = true;
+    for (let i = 0; i < 4; i += 1) {
+        const r = spawnSync(TMUX, ["send-keys", "-t", name, "C-u"], {
+            stdio: "ignore",
+        });
+        ok = ok && r.status === 0;
+    }
+    return ok;
+}
+/**
+ * VISIBLE text of one pane, or undefined when tmux cannot be read — unlike
+ * `capturePane`, which flattens a failure into "". Delivery needs the
+ * difference: an unreadable pane is not an empty one.
+ */
+export function capturePaneVisible(pane) {
+    const r = spawnSync(TMUX, ["capture-pane", "-p", "-t", pane], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (r.status !== 0 || r.stdout === undefined)
+        return undefined;
+    return r.stdout;
+}
+/**
+ * CPU time (ms) of the process tree behind a pane — the liveness signal used to
+ * tell a working agent from one parked on its placeholder.
+ */
+export function paneTreeCpuMs(pane) {
+    const pid = localSessionPanePid(pane);
+    if (pid === undefined)
+        return undefined;
+    return readProcessTreeCpuMs(pid, procReaderDeps());
+}
+/**
+ * The pid actually doing the work behind a pane.
+ *
+ * The pane's own pid is the launch WRAPPER: measured 2026-07-29, it reported 0s
+ * of CPU after 37s while its `codex` child had burned 13s. Anything that judges
+ * a lane by the reported pid alone — a supervisor, a status bar, a conductor —
+ * is reading the wrong process, and gets a false answer in both directions.
+ */
+export function paneWorkerPid(pane) {
+    const pid = localSessionPanePid(pane);
+    if (pid === undefined)
+        return undefined;
+    return readWorkerPid(pid, procReaderDeps());
+}
+function procReaderDeps() {
+    return {
+        listPids: () => {
+            try {
+                return readdirSync("/proc")
+                    .map((entry) => Number.parseInt(entry, 10))
+                    .filter((value) => Number.isInteger(value) && value > 0);
+            }
+            catch {
+                return [];
+            }
+        },
+        readStat: (target) => {
+            try {
+                return readFileSync(`/proc/${target}/stat`, "utf8");
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
 }
 /**
  * Attach the real terminal straight into the Pod's tmux session via