@volter/supercode-terminal 0.2.30

package/substrate/tmux.js

@@ -0,0 +1,899 @@
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { requireCommand, run, runAsync, runWithInputAsync, spawnInherited } from "./internal/exec.js";
+import { snapshotDescendantPids } from "./internal/process-tree.js";
+const TMUX_INSTALL_HINT = "Install it with: brew install tmux";
+const PTY_ALLOCATION_HINT = [
+    "The tmux host could not create a pane because the OS could not allocate a pseudo-terminal.",
+    "This usually means local terminal/pty capacity is exhausted by existing terminal or tmux sessions.",
+    "No sessions were automatically closed. Inspect existing sessions and close only work that is safe to stop."
+].join(" ");
+// Session-scoped tmux user option that records which provider created a session.
+const ownerOption = "@supercode-owner";
+// Optional dedicated tmux server (`tmux -L <socket>`). A `-L` server is fully
+// separate from the user's DEFAULT server — the default can't see it and
+// `kill-server` on it can't escape — so a provider (or a test) can run in
+// complete isolation. `undefined` = the default server, i.e. production behavior
+// unchanged. Always passed explicitly (never global/ambient state) so concurrent
+// providers and tests can't race it.
+function tmuxArgs(socket, args) {
+    return socket ? ["-L", socket, ...args] : args;
+}
+export function assertTmux() {
+    requireCommand("tmux", TMUX_INSTALL_HINT);
+}
+export function targetForSession(sessionName) {
+    if (!sessionName) {
+        throw new Error("A session name is required.");
+    }
+    return `${sessionName}:0`;
+}
+export function assertSession(name, socket) {
+    assertTmux();
+    if (!name) {
+        throw new Error("--name is required.");
+    }
+    run("tmux", tmuxArgs(socket, ["has-session", "-t", name]));
+}
+// Async: window creation runs on the provider event loop (createWindow →
+// createWindowSession), so every tmux invocation here uses runAsync (spawn, not
+// spawnSync) and the pane-ready poll below uses sleepAsync — see waitForPanesReady.
+// Nothing in this function may block the loop.
+export async function createSession({ command, cwd, env, name, owner, ownerOption: ownershipOption = ownerOption, panes, sessionOptions = {}, settings = {}, socket }) {
+    assertTmux();
+    if (!name) {
+        throw new Error("--name is required.");
+    }
+    if (!Number.isInteger(panes) || panes < 1) {
+        throw new Error("--panes must be a positive integer.");
+    }
+    if (command !== undefined && !command.program) {
+        throw new Error("A command program is required.");
+    }
+    // Global server options must be in place before the first pane spawns —
+    // history-limit is read at pane creation. On a fresh dedicated `-L` socket no
+    // server exists yet and `set-option -g` will NOT start one (only commands like
+    // new-session do), so chain the option-set and the create into ONE tmux
+    // invocation: the trailing new-session keeps alive the server its preceding
+    // set-options just configured. On an already-running server they are simply
+    // reapplied.
+    const sessionEnv = env ?? {};
+    const bootstrapDirectories = [];
+    const paneBootstrapArgs = (pane) => {
+        const commandArgs = command === undefined ? [] : [command.program, ...(command.arguments ?? [])];
+        if (Object.keys(sessionEnv).length === 0)
+            return commandArgs;
+        const directory = mkdtempSync(join(tmpdir(), "tmux-session-env-"));
+        bootstrapDirectories.push(directory);
+        const shell = process.env.SHELL ?? "/bin/sh";
+        return writeSessionEnvironmentBootstrap(directory, pane, sessionEnv, commandArgs.length === 0 ? [shell, "-l"] : commandArgs);
+    };
+    try {
+        const startArgs = [...sessionServerOptionArgs(), "new-session", "-d", "-s", name];
+        if (cwd) {
+            startArgs.push("-c", cwd);
+        }
+        startArgs.push(...paneBootstrapArgs(0));
+        await runTmuxSessionCreateAsync(startArgs, { cwd, operation: "create tmux session", session: name, socket });
+        if (owner) {
+            await runAsync("tmux", tmuxArgs(socket, ["set-option", "-t", name, ownershipOption, owner]));
+        }
+        for (const [option, value] of Object.entries(sessionOptions).sort(([left], [right]) => left.localeCompare(right))) {
+            await setSessionOptionAsync(name, option, value, socket);
+        }
+        for (const [option, value] of Object.entries(settings).sort(([left], [right]) => left.localeCompare(right))) {
+            await setSessionSettingAsync(name, option, value, socket);
+        }
+        await declareSessionColorEnvironmentAsync(socket);
+        const target = targetForSession(name);
+        for (let i = 1; i < panes; i += 1) {
+            const splitArgs = ["split-window", "-t", target];
+            if (cwd) {
+                splitArgs.push("-c", cwd);
+            }
+            splitArgs.push(...paneBootstrapArgs(i));
+            await runTmuxSessionCreateAsync(splitArgs, { cwd, operation: "split tmux window", session: name, socket });
+            await runAsync("tmux", tmuxArgs(socket, ["select-layout", "-t", target, "tiled"]));
+        }
+        await waitForPanesReady({ expectedPanes: panes, socket, target });
+        for (const directory of bootstrapDirectories)
+            await waitForSessionBootstrapCleanup(directory);
+        return { name, panes };
+    }
+    catch (error) {
+        for (const directory of bootstrapDirectories)
+            rmSync(directory, { force: true, recursive: true });
+        throw error;
+    }
+}
+function assertUserOption(option) {
+    if (!/^@[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(option)) {
+        throw new Error("A tmux user option must start with @ and contain only letters, numbers, underscores, or hyphens.");
+    }
+}
+// The boundary between a session name and a per-session value in one `-F` line.
+// tmux 3.3a (Debian bookworm, Ubuntu 22.04 — every stock Linux container) rewrites
+// EVERY control character in format output to `_`, so a tab comes back
+// indistinguishable from data and every value parses as missing: the session's
+// context key and owner both read as unset, `panes.list` reports `pane: null`, and
+// attach/share by context refuse a pane that is right there. A colon survives, and
+// tmux itself guarantees a session name never holds one — it rewrites `:` and `.` in
+// a name to `_` at creation — so the FIRST colon is always the field boundary and the
+// value (opaque, colons allowed) takes the whole remainder. Same rule as
+// `listPanesFormat`: printable separator, free-text field last.
+const sessionValueSeparator = ":";
+/** Read one namespaced user option for every live session in one tmux call. */
+export async function sessionOptionValuesAsync(option, socket) {
+    assertTmux();
+    assertUserOption(option);
+    let output;
+    try {
+        output = await runAsync("tmux", tmuxArgs(socket, ["list-sessions", "-F", `#{session_name}${sessionValueSeparator}#{${option}}`]));
+    }
+    catch {
+        return new Map();
+    }
+    const values = new Map();
+    for (const line of output.split("\n")) {
+        const separator = line.indexOf(sessionValueSeparator);
+        if (separator < 1)
+            continue;
+        const name = line.slice(0, separator);
+        const value = line.slice(separator + 1);
+        if (value)
+            values.set(name, value);
+    }
+    return values;
+}
+/** Set one of tmux's own session options on one session. */
+export async function setSessionSettingAsync(session, option, value, socket) {
+    if (!session)
+        throw new Error("A session name is required.");
+    if (!/^[a-z][a-z0-9-]*$/.test(option))
+        throw new Error(`Not a tmux session option name: ${option}`);
+    if (/\0|\t|\r|\n/.test(value))
+        throw new Error("A tmux option value cannot contain control separators.");
+    await runAsync("tmux", tmuxArgs(socket, ["set-option", "-t", session, option, value]));
+}
+/** Set one session-scoped user option without exposing it in the session name. */
+export async function setSessionOptionAsync(session, option, value, socket) {
+    if (!session)
+        throw new Error("A session name is required.");
+    assertUserOption(option);
+    if (/\0|\t|\r|\n/.test(value))
+        throw new Error("A tmux user option value cannot contain control separators.");
+    await runAsync("tmux", tmuxArgs(socket, ["set-option", "-t", session, option, value]));
+}
+// Names of the live tmux sessions stamped with exactly this owner. Used to
+// reclaim a provider's own sessions without name-guessing: an unset `@supercode-owner`
+// reads as empty, so untagged (user/foreign) sessions never match, and exact
+// equality means owner `host` never sweeps owner `host-2`'s sessions.
+// The `@supercode-owner` mark on one session (the value, or undefined if the session
+// doesn't exist or is untagged). Lets a caller kill ONLY a session it owns —
+// never a user's own same-named session on the shared default server.
+export function sessionOwner(session, socket, ownershipOption = ownerOption) {
+    if (!session) {
+        return undefined;
+    }
+    try {
+        const value = run("tmux", tmuxArgs(socket, ["show-options", "-t", session, "-v", ownershipOption])).trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined; // no such session
+    }
+}
+export function sessionsOwnedBy(owner, socket, ownershipOption = ownerOption) {
+    assertTmux();
+    if (!owner) {
+        return [];
+    }
+    let output;
+    try {
+        output = run("tmux", tmuxArgs(socket, ["list-sessions", "-F", `#{session_name}${sessionValueSeparator}#{${ownershipOption}}`]));
+    }
+    catch {
+        return []; // no server / no sessions
+    }
+    const owned = [];
+    for (const line of output.split("\n")) {
+        const separator = line.indexOf(sessionValueSeparator);
+        if (separator < 1)
+            continue;
+        const name = line.slice(0, separator);
+        const tag = line.slice(separator + 1);
+        if (name && tag === owner) {
+            owned.push(name);
+        }
+    }
+    return owned;
+}
+// Kill a session and the processes it spawned. tmux kill-session SIGHUPs the
+// pane's foreground group, but agents fork detached helpers (MCP servers, node
+// children) that survive that signal, reparent to init, and pile up until the
+// host is out of resources (issue #10 — the same mechanism that, on the iTerm
+// driver, let `killall iTerm2` orphan dozens of live claude processes: closing
+// the GUI window never touched these). Snapshot the live descendant tree BEFORE
+// killing the session — once the pane's shell exits its children reparent and
+// can no longer be found from the (gone) root pid — then SIGKILL whatever the
+// snapshot held. Best-effort throughout; the shared home for every driver that
+// backs a window with a tmux session (virtual-tmux, iTerm).
+export function killSessionProcessTree({ session, socket }) {
+    // Scope the pid lookup to this session (not the global `-a` list) and run it
+    // only on an explicit close/reap/dispose (event-driven, not the per-cycle
+    // observe loop). The sync `ps` below (via snapshotDescendantPids) is likewise
+    // occasional, never on a hot path.
+    let rootPids = [];
+    try {
+        rootPids = run("tmux", tmuxArgs(socket, ["list-panes", "-t", session, "-F", "#{pane_pid}"]))
+            .split("\n")
+            .map((line) => Number(line.trim()))
+            .filter((pid) => Number.isInteger(pid) && pid > 0);
+    }
+    catch {
+        // tmux may already be down; still attempt the kill-session below.
+    }
+    // Capture ONLY this session's descendant pids — snapshotDescendantPids walks
+    // down from the pane pids. (The whole machine's process table is NOT a safe
+    // input: SIGKILLing every row would kill every process the user owns — every
+    // terminal, the tmux server, the console. That was the all-terminals-die bug.)
+    const descendantPids = rootPids.length > 0 ? snapshotDescendantPids(rootPids) : [];
+    try {
+        run("tmux", tmuxArgs(socket, ["kill-session", "-t", session]));
+    }
+    catch {
+        // session may already be gone
+    }
+    for (const pid of descendantPids) {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            // already exited
+        }
+    }
+}
+// Live tmux session names. Throws if there is no server / no sessions, which
+// callers treat as "nothing to reconcile".
+export function listTmuxSessionNames(socket) {
+    return run("tmux", tmuxArgs(socket, ["list-sessions", "-F", "#{session_name}"])).split("\n").map((line) => line.trim()).filter(Boolean);
+}
+// A session belongs to a provider's prefix iff it is the bare `prefix` or a
+// `prefix-*` child. The exact `-` boundary is load-bearing: prefix `worker` must
+// not claim `worker-pool-1`. The single home for that rule.
+function matchesProviderPrefix(name, prefix) {
+    return name === prefix || name.startsWith(`${prefix}-`);
+}
+// `prefix-*` (and the bare `prefix`) sessions that a provider does not track.
+// Pure so the orphan-reclaim decision is unit-tested without a live tmux server.
+export function selectOrphanSessions({ allSessions, ownedSessions, prefix }) {
+    const owned = ownedSessions instanceof Set ? ownedSessions : new Set(ownedSessions);
+    return allSessions.filter((name) => matchesProviderPrefix(name, prefix) && !owned.has(name));
+}
+// Split the live `prefix-*` sessions into what a provider still owns and what it
+// orphaned. `discovered`/`tracked`/`kept` are sorted for a stable summary;
+// `orphans` follows allSessions order (the kill order). Pure — the classification
+// is unit-tested without a live tmux server, mirroring selectOrphanSessions.
+// `tracked` is every owned prefix session (some may be dead — not in `discovered`);
+// `kept` is the owned sessions still live (`discovered` ∩ owned). Orphans are
+// never owned, so they never appear in `kept`.
+export function classifyPrefixSessions({ allSessions, ownedSessions, prefix }) {
+    const owned = ownedSessions instanceof Set ? ownedSessions : new Set(ownedSessions);
+    const discovered = allSessions.filter((name) => matchesProviderPrefix(name, prefix)).sort();
+    const tracked = [...owned].filter((name) => matchesProviderPrefix(name, prefix)).sort();
+    const kept = discovered.filter((name) => owned.has(name));
+    const orphans = selectOrphanSessions({ allSessions, ownedSessions: owned, prefix });
+    return { discovered, kept, orphans, tracked };
+}
+// The tmux server daemonizes with the environment of whichever process first
+// touches it; a provider launched from a CI or agent shell carries NO_COLOR=1
+// (plus npm's COLOR=0 and CODEX_CI=1), every pane inherits it, and programs
+// render monochrome. Declare the color environment in the server's global
+// environment before any pane spawns instead of inheriting that accident.
+// (The first set-environment call also starts the server, so a fresh server
+// is cleaned before its first session exists.)
+async function declareSessionColorEnvironmentAsync(socket) {
+    for (const variable of ["NO_COLOR", "COLOR", "CODEX_CI"]) {
+        await runAsync("tmux", tmuxArgs(socket, ["set-environment", "-gu", variable]));
+    }
+    await runAsync("tmux", tmuxArgs(socket, ["set-environment", "-g", "COLORTERM", "truecolor"]));
+}
+// Server-wide options every managed session should carry, emitted as a chained-
+// command prefix for the session-create invocation (see createSession for why
+// they must share one tmux invocation). The iTerm/WezTerm/virtual-tmux browser
+// mirrors run `tmux attach-session`, so they are full-screen tmux clients:
+// native scrollback is bypassed and, with tmux's default `mouse off`, the wheel
+// is unbound — nothing scrolls. `mouse on` binds the wheel to copy-mode in every
+// client; `history-limit` (read at pane creation) gives every pane a deep
+// scrollback. Each command ends with a standalone `;` so the trailing new-session
+// runs in the same invocation — `run` uses spawnSync without a shell, so the `;`
+// reaches tmux as a literal command separator, not a shell metacharacter.
+// A supercode pane (p_*) that ends leaves one line in the pane-exit log: its exit
+// status or signal when it failed (the session keeps a failed pane just long
+// enough for tmux to report it, then closes it), `closed` when it ended cleanly.
+const PANE_EXIT_LOG = '"${SUPERCODE_HOME:-$HOME/.config/supercode}/pane-exits.log"';
+const PANE_DIED_HOOK = "if-shell -F '#{m:p_*,#{session_name}}' { run-shell 'printf \"%s %s died status=%s signal=%s\\n\" \"$(date +%FT%T)\" \"#{session_name}\" \"#{pane_dead_status}\" \"#{pane_dead_signal}\" >> " + PANE_EXIT_LOG + "' ; kill-pane }";
+const SESSION_CLOSED_HOOK = "if-shell -F '#{m:p_*,#{hook_session_name}}' { run-shell 'printf \"%s %s closed\\n\" \"$(date +%FT%T)\" \"#{hook_session_name}\" >> " + PANE_EXIT_LOG + "' }";
+function sessionServerOptionArgs() {
+    return [
+        "set-option", "-g", "history-limit", "50000", ";",
+        "set-option", "-g", "mouse", "on", ";",
+        // The relay clients (tmux-stream attaches as screen-256color; a person's own
+        // terminal attaches as something else) draw into the viewer's normal screen,
+        // so lines that scroll off land in the viewer's own scrollback, and they
+        // pass clipboard, focus and extended keys through. Indexed, so re-applying
+        // on every create replaces one entry instead of appending.
+        "set-option", "-s", "terminal-overrides[90]", "screen-256color:smcup@:rmcup@", ";",
+        "set-option", "-s", "terminal-features[90]", "screen-256color:clipboard:focus:extkeys:title", ";",
+        // Harness TUIs (Claude Code) track focus; tmux forwards focus in/out only with this on.
+        "set-option", "-s", "focus-events", "on", ";",
+        "set-hook", "-g", "pane-died[90]", PANE_DIED_HOOK, ";",
+        "set-hook", "-g", "session-closed[90]", SESSION_CLOSED_HOOK, ";"
+    ];
+}
+const tmuxClientEnvironmentNames = [
+    "COLORTERM",
+    "DISPLAY",
+    "HOME",
+    "LANG",
+    "LANGUAGE",
+    "LC_ALL",
+    "LC_CTYPE",
+    "LOGNAME",
+    "PATH",
+    "SHELL",
+    "TERM",
+    "TERM_PROGRAM",
+    "TMPDIR",
+    "TMUX_TMPDIR",
+    "USER",
+    "WAYLAND_DISPLAY",
+    "XAUTHORITY",
+    "XDG_RUNTIME_DIR"
+];
+function tmuxClientEnvironment(source = process.env) {
+    const environment = {};
+    for (const name of tmuxClientEnvironmentNames) {
+        const value = source[name];
+        if (value !== undefined)
+            environment[name] = value;
+    }
+    return environment;
+}
+function writeSessionEnvironmentBootstrap(directory, pane, environment, command) {
+    const environmentPath = join(directory, `pane-${pane}.env`);
+    const wrapperPath = join(directory, `pane-${pane}.sh`);
+    const lines = Object.entries(environment).map(([name, value]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+            throw new Error(`Invalid session environment variable name: ${JSON.stringify(name)}.`);
+        }
+        return `export ${name}=${shellQuote(value)}`;
+    });
+    writeFileSync(environmentPath, `${lines.join("\n")}\n`, { flag: "wx", mode: 0o600 });
+    writeFileSync(wrapperPath, [
+        "#!/bin/sh",
+        'environment_path="$1"',
+        "shift",
+        "set -a",
+        '. "$environment_path"',
+        "set +a",
+        'rm -f -- "$environment_path" "$0"',
+        'rmdir -- "$(dirname -- "$0")" 2>/dev/null || true',
+        'exec "$@"',
+        ""
+    ].join("\n"), { flag: "wx", mode: 0o700 });
+    return [wrapperPath, environmentPath, ...command];
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+async function waitForSessionBootstrapCleanup(directory, timeoutMs = 10_000) {
+    const startedAt = Date.now();
+    while (existsSync(directory) && Date.now() - startedAt < timeoutMs) {
+        await sleepAsync(10);
+    }
+    if (existsSync(directory)) {
+        throw new Error(`Timed out waiting for the tmux pane environment bootstrap to self-delete: ${directory}.`);
+    }
+}
+async function runTmuxSessionCreateAsync(args, context) {
+    try {
+        return await runAsync("tmux", tmuxArgs(context.socket, args), { env: tmuxClientEnvironment(), inheritEnv: false });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (isPtyAllocationFailure(message)) {
+            throw new Error([
+                `${context.operation} failed for session "${context.session}".`,
+                context.cwd ? `cwd: ${context.cwd}.` : undefined,
+                PTY_ALLOCATION_HINT,
+                `Original tmux error: ${message}`
+            ].filter(Boolean).join(" "));
+        }
+        throw error;
+    }
+}
+function isPtyAllocationFailure(message) {
+    return /fork failed:\s*Device not configured/i.test(message)
+        || /openpty:\s*Device not configured/i.test(message)
+        || /create window failed/i.test(message) && /Device not configured/i.test(message);
+}
+// Async: this poll runs inside createSession, on the createWindow path (the
+// provider event loop). Both the delay (sleepAsync, a real setTimeout) and the
+// per-iteration status check (inspectPanesAsync, a non-blocking spawn) yield the
+// loop between iterations — nothing here uses spawnSync or Atomics.wait, so
+// concurrent window creates never stall socket heartbeats. See CLAUDE.md's
+// event-loop invariant.
+export async function waitForPanesReady({ expectedPanes, socket, target, timeoutMs = 3000 }) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        const panes = await inspectPanesAsync(target, socket);
+        const ready = panes.length === expectedPanes
+            && panes.every((pane) => pane.dead === false && pane.id);
+        if (ready) {
+            return panes;
+        }
+        await sleepAsync(50);
+    }
+    throw new Error(`Timed out waiting for ${expectedPanes} tmux panes to become ready in ${target}.`);
+}
+const inspectPanesSeparator = "|";
+const inspectPanesFormat = [
+    "#{pane_index}",
+    "#{pane_id}",
+    "#{pane_dead}",
+    "#{pane_current_command}"
+].join(inspectPanesSeparator);
+function parseInspectPanesOutput(output) {
+    const trimmed = output.trim();
+    if (!trimmed) {
+        return [];
+    }
+    return trimmed.split("\n").map((line) => {
+        const [pane, id, dead, currentCommand] = line.split(inspectPanesSeparator);
+        if (pane === undefined || id === undefined || dead === undefined) {
+            throw new Error(`Could not parse tmux pane line: ${line}`);
+        }
+        return {
+            currentCommand: currentCommand ?? "",
+            dead: dead === "1",
+            id,
+            pane: Number(pane)
+        };
+    });
+}
+export function inspectPanes(target, socket) {
+    return parseInspectPanesOutput(run("tmux", tmuxArgs(socket, ["list-panes", "-t", target, "-F", inspectPanesFormat])));
+}
+// Async twin used by waitForPanesReady (the createWindow/createSession path) so
+// the readiness poll never blocks the provider event loop with a synchronous
+// spawn — see CLAUDE.md's event-loop invariant.
+export async function inspectPanesAsync(target, socket) {
+    return parseInspectPanesOutput(await runAsync("tmux", tmuxArgs(socket, ["list-panes", "-t", target, "-F", inspectPanesFormat])));
+}
+const listPanesSeparator = "|";
+const listPanesFormat = [
+    "#{session_name}",
+    "#{window_index}",
+    "#{pane_index}",
+    "#{pane_id}",
+    "#{pane_pid}",
+    "#{pane_current_path}",
+    "#{pane_active}",
+    // The process in the foreground of the pane's tty: the pane's own shell when
+    // nothing is running, the command's name while one is. `inspectPanes` has
+    // always read it per-target; enumerating it here is what lets a caller
+    // listing every pane at once tell a prompt from work in progress without a
+    // second tmux call per pane.
+    "#{pane_current_command}",
+    // Last, and last for a reason: the title is free text a user controls, and
+    // the separator is a bare "|". A field after it would be lost to the first
+    // pipe somebody types into a pane title.
+    "#{pane_title}"
+].join(listPanesSeparator);
+function parseListPanesOutput(output) {
+    const trimmed = output.trim();
+    if (!trimmed) {
+        return [];
+    }
+    return trimmed.split("\n").map((line) => {
+        const [session, window, pane, id, rootPid, cwd, active, currentCommand, title] = line.split(listPanesSeparator);
+        if (session === undefined || window === undefined || pane === undefined || id === undefined || rootPid === undefined || cwd === undefined || active === undefined) {
+            throw new Error(`Could not parse tmux pane line: ${line}`);
+        }
+        const parsedRootPid = Number(rootPid);
+        if (!Number.isInteger(parsedRootPid) || parsedRootPid < 1) {
+            throw new Error(`Could not parse tmux pane pid: ${line}`);
+        }
+        return {
+            active: active === "1",
+            currentCommand: currentCommand ?? "",
+            cwd,
+            id,
+            pane: Number(pane),
+            rootPid: parsedRootPid,
+            session,
+            title: title ?? "",
+            window: Number(window)
+        };
+    });
+}
+export function listPanes(socket) {
+    assertTmux();
+    return parseListPanesOutput(run("tmux", tmuxArgs(socket, ["list-panes", "-a", "-F", listPanesFormat])));
+}
+// Async twin used by the observe loop so the (frequent) pane enumeration never
+// blocks the provider event loop.
+export async function listPanesAsync(socket) {
+    assertTmux();
+    return parseListPanesOutput(await runAsync("tmux", tmuxArgs(socket, ["list-panes", "-a", "-F", listPanesFormat])));
+}
+const clientForTtySeparator = "|";
+const clientForTtyFormat = [
+    "#{client_tty}",
+    "#{session_name}",
+    "#{window_index}",
+    "#{pane_index}",
+    "#{client_width}",
+    "#{client_height}"
+].join(clientForTtySeparator);
+function parseClientForTty(output, tty) {
+    if (!output) {
+        return undefined;
+    }
+    for (const line of output.split("\n")) {
+        const [clientTty, session, window, pane, widthText, heightText] = line.split(clientForTtySeparator);
+        if (clientTty === undefined || session === undefined || window === undefined || pane === undefined || widthText === undefined || heightText === undefined) {
+            throw new Error(`Could not parse tmux client line: ${line}`);
+        }
+        if (clientTty === tty) {
+            const width = Number(widthText);
+            const height = Number(heightText);
+            if (!Number.isInteger(width) || width < 1 || !Number.isInteger(height) || height < 1) {
+                throw new Error(`Could not parse tmux client size: ${line}`);
+            }
+            return { height, target: `${session}:${window}.${pane}`, width };
+        }
+    }
+    return undefined;
+}
+export function clientForTty(tty, socket) {
+    assertTmux();
+    if (!tty) {
+        throw new Error("A client tty is required.");
+    }
+    return parseClientForTty(run("tmux", tmuxArgs(socket, ["list-clients", "-F", clientForTtyFormat])).trim(), tty);
+}
+// Async twin of clientForTty for the observe loop (the iTerm unmanaged path) — a
+// per-window client lookup off the event loop instead of a synchronous fan-out.
+export async function clientForTtyAsync(tty, socket) {
+    assertTmux();
+    if (!tty) {
+        throw new Error("A client tty is required.");
+    }
+    return parseClientForTty((await runAsync("tmux", tmuxArgs(socket, ["list-clients", "-F", clientForTtyFormat]))).trim(), tty);
+}
+// The reverse lookup: the ttys of every client attached to a session (0 or 1
+// for a managed iTerm window). Lets the iTerm close path resolve a window by
+// its attached tty instead of a recorded window id that may have gone stale.
+// Returns [] when the session does not exist or nothing is attached — both are
+// ordinary states on the close path, not errors.
+export function clientTtysForSession(session, socket) {
+    assertTmux();
+    if (!session) {
+        throw new Error("A session name is required.");
+    }
+    let output;
+    try {
+        output = run("tmux", tmuxArgs(socket, ["list-clients", "-t", session, "-F", "#{client_tty}"])).trim();
+    }
+    catch {
+        return [];
+    }
+    return output.split("\n").filter((tty) => tty.length > 0);
+}
+export function getWindowSize({ name, socket, window = 0 }) {
+    assertSession(name, socket);
+    const separator = "|";
+    const output = run("tmux", tmuxArgs(socket, [
+        "display-message",
+        "-p",
+        "-t",
+        `${name}:${window}`,
+        `#{window_width}${separator}#{window_height}`
+    ])).trim();
+    const [width, height] = output.split(separator).map(Number);
+    if (width === undefined || height === undefined || !Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
+        throw new Error(`Could not determine tmux window size for ${name}:${window}.`);
+    }
+    return { height, width };
+}
+export function getStatusLineCount(name, socket) {
+    assertSession(name, socket);
+    const value = run("tmux", tmuxArgs(socket, ["show-options", "-Aqv", "-t", name, "status"])).trim();
+    if (value === "off")
+        return 0;
+    if (value === "on")
+        return 1;
+    const lines = Number(value);
+    if (!Number.isInteger(lines) || lines < 0 || lines > 5) {
+        throw new Error(`Could not determine tmux status height for ${name}.`);
+    }
+    return lines;
+}
+// Every window-0 size in ONE async exec, keyed by session. The observe loop uses
+// this to size windows off the event loop instead of a synchronous getWindowSize
+// per window — that per-window fan-out blocked the provider loop under a large fleet
+// (see CLAUDE.md: nothing sync on the observe path). Sessions absent here (transient /
+// not-yet-created) just fall to the caller's default and self-correct next observe.
+export async function listWindowSizesAsync(socket) {
+    assertTmux();
+    const separator = "|";
+    let output;
+    try {
+        output = (await runAsync("tmux", tmuxArgs(socket, [
+            "list-windows",
+            "-a",
+            "-F",
+            `#{session_name}${separator}#{window_index}${separator}#{window_width}${separator}#{window_height}`
+        ]))).trim();
+    }
+    catch (error) {
+        // No tmux server = no sessions = no sizes. A tmux server exits with its
+        // last session, so an idle provider (--count 0, nothing launched yet, or
+        // everything reaped) has no server to ask — that is the empty state, not
+        // an observe failure. Without this, every observe on an idle provider
+        // throws, the snapshot reports observation:failed forever, and the console
+        // paints a perfectly healthy machine as degraded. Genuine tmux breakage
+        // (binary missing, socket permission) still throws.
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("no server running") || message.includes("error connecting to")) {
+            return new Map();
+        }
+        throw error;
+    }
+    const sizes = new Map();
+    if (!output) {
+        return sizes;
+    }
+    for (const line of output.split("\n")) {
+        const [session, windowIndex, width, height] = line.split(separator);
+        // Match getWindowSize, which reads window 0; ignore extra windows of a session.
+        if (!session || windowIndex !== "0") {
+            continue;
+        }
+        const parsedWidth = Number(width);
+        const parsedHeight = Number(height);
+        if (Number.isInteger(parsedWidth) && Number.isInteger(parsedHeight) && parsedWidth >= 1 && parsedHeight >= 1) {
+            sizes.set(session, { height: parsedHeight, width: parsedWidth });
+        }
+    }
+    return sizes;
+}
+// Out-of-band pane styling via window-active-style. tmux applies this when it
+// draws, so every native client of the pane (a direct attach, the iTerm2 /
+// WezTerm windows) renders it without writing into the cell grid — scrollback
+// and the mirror's capture-pane output are untouched. Best-effort: a vanished
+// session must not throw into the caller's effect timer.
+export async function setPaneStyle(target, style, socket) {
+    assertTmux();
+    await runAsync("tmux", tmuxArgs(socket, ["set-option", "-p", "-t", target, "window-active-style", style]));
+}
+export async function clearPaneStyle(target, socket) {
+    assertTmux();
+    await runAsync("tmux", tmuxArgs(socket, ["set-option", "-p", "-u", "-t", target, "window-active-style"]));
+}
+export function capturePane({ lines, preserveEscapes = false, socket, target }) {
+    assertTmux();
+    if (!target) {
+        throw new Error("--target is required.");
+    }
+    return run("tmux", tmuxArgs(socket, capturePaneArgs({ lines, preserveEscapes, target })));
+}
+function capturePaneArgs({ lines, preserveEscapes, target }) {
+    const args = ["capture-pane", "-p", "-t", target];
+    if (preserveEscapes) {
+        args.splice(1, 0, "-e");
+    }
+    if (lines !== undefined) {
+        if (!Number.isInteger(lines) || lines < 1) {
+            throw new Error("--lines must be a positive integer.");
+        }
+        args.push("-S", `-${lines}`);
+    }
+    return args;
+}
+// Async twin used by the observe loop. The N per-pane captures can then run
+// concurrently (Promise.all) instead of blocking the event loop in sequence.
+export async function capturePaneAsync({ lines, preserveEscapes = false, socket, target }) {
+    assertTmux();
+    if (!target) {
+        throw new Error("--target is required.");
+    }
+    return runAsync("tmux", tmuxArgs(socket, capturePaneArgs({ lines, preserveEscapes, target })));
+}
+export async function sendInterruptAsync({ socket, target }) {
+    assertTmux();
+    if (!target) {
+        throw new Error("A pane target is required.");
+    }
+    await runAsync("tmux", tmuxArgs(socket, ["send-keys", "-t", target, "Escape"]));
+}
+export async function sendInputAsync({ data, deadlineMs, socket, submitMode = "retry", target }) {
+    assertTmux();
+    if (!target) {
+        throw new Error("A pane target is required.");
+    }
+    if (typeof data !== "string") {
+        throw new Error("Input data must be a string.");
+    }
+    const submittedText = submittedTextFromInput(data);
+    if (submittedText !== undefined) {
+        // A completed prompt is one semantic payload, regardless of whether it
+        // happens to contain newlines. Sending a long single line as thousands of
+        // synthetic key events can leave an interactive composer holding the
+        // draft even though tmux acknowledged every byte. A bracketed paste gives
+        // the editor one bounded payload and an explicit paste-complete boundary
+        // before the separate submit key.
+        if (submittedText.length > 0) {
+            await sendSubmittedPasteAsync({ deadlineMs, socket, submitMode, target, text: submittedText });
+            return "submitted-paste";
+        }
+        await sendSubmitKeysAsync({ deadlineMs, socket, submitMode, target });
+        return "submitted-line";
+    }
+    for (const token of tokenizeTerminalInput(data)) {
+        if ("literal" in token) {
+            await runAsync("tmux", tmuxArgs(socket, ["send-keys", "-t", target, "-l", "--", token.literal]), terminalInputRunOptions(deadlineMs));
+        }
+        else {
+            await runAsync("tmux", tmuxArgs(socket, ["send-keys", "-t", target, token.key]), terminalInputRunOptions(deadlineMs));
+        }
+    }
+    return "keystream";
+}
+export function attachSession({ name, socket, window }) {
+    assertTmux();
+    if (!name) {
+        throw new Error("--name is required.");
+    }
+    const target = window === undefined ? name : `${name}:${window}`;
+    spawnInherited("tmux", tmuxArgs(socket, ["attach-session", "-t", target]));
+}
+const SINGLE_SUBMIT_DELAY_MS = 500;
+const SUBMITTED_LINE_DELAYS_MS = [500, 1500, 3500];
+async function sleepAsync(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Submitted text is a payload the caller finished with Enter (a launch
+// command or a chat message), as opposed to a raw keystroke stream. It must
+// contain only pasteable characters: anything else (ESC sequences, control
+// characters, DEL, a bare CR mid-body) is key forwarding and has to go
+// through the tokenizer.
+export function submittedTextFromInput(data) {
+    if (!data.endsWith("\n") && !data.endsWith("\r")) {
+        return undefined;
+    }
+    const text = data.replace(/(?:\r\n|\n|\r)$/, "");
+    for (const char of text) {
+        if (char === "\n" || char === "\t") {
+            continue;
+        }
+        if (char === "\u007f" || char < " ") {
+            return undefined;
+        }
+    }
+    return text;
+}
+let pasteBufferCounter = 0;
+async function sendSubmittedPasteAsync({ deadlineMs, socket, submitMode, target, text }) {
+    pasteBufferCounter += 1;
+    const buffer = `terminal-input-${process.pid}-${pasteBufferCounter}`;
+    await runWithInputAsync("tmux", tmuxArgs(socket, ["load-buffer", "-b", buffer, "-"]), text, terminalInputRunOptions(deadlineMs));
+    // -p wraps the paste in bracketed-paste markers when the application has
+    // requested them, so line editors insert the content literally instead of
+    // interpreting newlines and tabs as keystrokes.
+    if (submitMode === "single") {
+        await runAsync("tmux", tmuxArgs(socket, ["paste-buffer", "-d", "-p", "-b", buffer, "-t", target]), terminalInputRunOptions(deadlineMs));
+        // Interactive TUIs process bracketed-paste completion asynchronously. A
+        // submit key in the same tmux command can arrive before the editor has
+        // committed the paste, while tmux still reports successful delivery.
+        await sendSubmitKeysAsync({ deadlineMs, socket, submitMode, target });
+        return;
+    }
+    await runAsync("tmux", tmuxArgs(socket, ["paste-buffer", "-d", "-p", "-b", buffer, "-t", target]), terminalInputRunOptions(deadlineMs));
+    await sendSubmitKeysAsync({ deadlineMs, socket, submitMode, target });
+}
+async function sendSubmitKeysAsync({ deadlineMs, socket, submitMode, target }) {
+    if (submitMode === "single") {
+        await sleepAsync(SINGLE_SUBMIT_DELAY_MS);
+        await runAsync("tmux", tmuxArgs(socket, ["send-keys", "-t", target, "Enter"]), terminalInputRunOptions(deadlineMs));
+        return;
+    }
+    for (const delayMs of SUBMITTED_LINE_DELAYS_MS) {
+        await sleepAsync(delayMs);
+        await runAsync("tmux", tmuxArgs(socket, ["send-keys", "-t", target, "Enter"]), terminalInputRunOptions(deadlineMs));
+    }
+}
+function terminalInputRunOptions(deadlineMs) {
+    if (deadlineMs === undefined)
+        return {};
+    const timeoutMs = deadlineMs - Date.now();
+    if (timeoutMs <= 0)
+        throw new Error("Terminal input expired before delivery.");
+    return { timeoutMs };
+}
+function tokenizeTerminalInput(data) {
+    const tokens = [];
+    for (let i = 0; i < data.length; i += 1) {
+        const char = data[i];
+        const next3 = data.slice(i, i + 3);
+        if (next3 === "\u001b[A") {
+            tokens.push({ key: "Up" });
+            i += 2;
+            continue;
+        }
+        if (next3 === "\u001b[B") {
+            tokens.push({ key: "Down" });
+            i += 2;
+            continue;
+        }
+        if (next3 === "\u001b[C") {
+            tokens.push({ key: "Right" });
+            i += 2;
+            continue;
+        }
+        if (next3 === "\u001b[D") {
+            tokens.push({ key: "Left" });
+            i += 2;
+            continue;
+        }
+        if (char === "\r" || char === "\n") {
+            tokens.push({ key: "Enter" });
+            continue;
+        }
+        if (char === "\u007f") {
+            tokens.push({ key: "BSpace" });
+            continue;
+        }
+        if (char === "\t") {
+            tokens.push({ key: "Tab" });
+            continue;
+        }
+        if (char === "\u0003") {
+            tokens.push({ key: "C-c" });
+            continue;
+        }
+        if (char === "\u0015") {
+            tokens.push({ key: "C-u" });
+            continue;
+        }
+        if (char === undefined) {
+            throw new Error("Unexpected end of input.");
+        }
+        const controlKey = controlKeyName(char);
+        if (controlKey) {
+            tokens.push({ key: controlKey });
+            continue;
+        }
+        if (char < " ") {
+            throw new Error(`Unsupported control input: ${JSON.stringify(char)}.`);
+        }
+        const previous = tokens.at(-1);
+        if (previous && "literal" in previous) {
+            previous.literal += char;
+        }
+        else {
+            tokens.push({ literal: char });
+        }
+    }
+    return tokens;
+}
+function controlKeyName(char) {
+    const code = char.charCodeAt(0);
+    if (code < 1 || code > 26) {
+        return undefined;
+    }
+    return `C-${String.fromCharCode(96 + code)}`;
+}