@rynx-ai/runtime 0.1.11-beta.33 → 0.1.11-beta.35

package/dist/terminal/tmux.js

@@ -4,28 +4,123 @@
  *
  * The tmux SERVER (private socket, one per terminal) holds the real pane PTY and
  * survives client detach / browser reload / a brief runner reconnect. A client
- * ATTACH is a short-lived node-pty process bridging the pane's bytes to a caller
- * (the WS bridge). Multiple attaches can coexist: one owner (read-write) plus
- * any number of read-only viewers (`tmux attach -r`) — the co-drive model.
+ * ATTACH is a short-lived `tmux -C` control-mode process. The browser owns its
+ * character grid and scrollback: connect-time history comes from `capture-pane`
+ * and subsequent pane bytes come from `%output` notifications. Browser input is
+ * injected byte-exactly with `send-keys -H`.
  *
- * Control commands (new-session / send-keys / has-session / kill) run through
- * plain `execFile`; only the interactive attach needs a PTY. node-pty is loaded
- * lazily so importing this module never hard-fails when the native binding is
- * absent — {@link isTmuxAvailable} + a caller-side capability gate keep the
- * terminal overlay optional (the structured layer works without it).
+ * It deliberately does not attach tmux through a second PTY: tmux
+ * copy-mode/status chrome would otherwise own scrolling and selection instead
+ * of xterm.js.
  */
-import { execFile, execFileSync } from "node:child_process";
+import { execFile, execFileSync, spawn, } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { TmuxControlParser } from "./control-parser.js";
+import { SegmentedTerminalSpool, } from "./spool.js";
 const TMUX_TARGET = "main";
 const DEFAULT_COLS = 80;
 const DEFAULT_ROWS = 24;
-/** tmux pane scrollback depth. Matches the browser xterm `scrollback` so a
- *  wheel-scroll (tmux copy-mode, enabled by `mouse on`) reaches as far back as
- *  the terminal shows. Mirrors reference implementation's `TerminalEnvSpec.scrollback`. */
-const DEFAULT_SCROLLBACK = 20000;
+const DEFAULT_SCROLLBACK = 10_000;
+const SEND_KEYS_HEX_BYTES_PER_CALL = 1024;
+const TMUX_SEND_TIMEOUT_MS = 10_000;
+const PANE_METADATA_FORMAT = [
+    "#{cursor_x}",
+    "#{cursor_y}",
+    "#{cursor_flag}",
+    "#{alternate_on}",
+    "#{mouse_standard_flag}",
+    "#{mouse_button_flag}",
+    "#{mouse_all_flag}",
+    "#{mouse_sgr_flag}",
+    "#{mouse_utf8_flag}",
+    "#{keypad_cursor_flag}",
+    "#{bracket_paste_flag}",
+    "#{pane_width}",
+    "#{pane_height}",
+].join(",");
+/** Decode tmux's three-digit octal escapes in a `%output` payload. */
+export function unescapeControlOutput(value) {
+    const source = Buffer.from(value);
+    const output = [];
+    for (let i = 0; i < source.length; i += 1) {
+        if (source[i] === 0x5c &&
+            i + 3 < source.length &&
+            source[i + 1] >= 0x30 && source[i + 1] <= 0x37 &&
+            source[i + 2] >= 0x30 && source[i + 2] <= 0x37 &&
+            source[i + 3] >= 0x30 && source[i + 3] <= 0x37) {
+            output.push((source[i + 1] - 0x30) * 64 +
+                (source[i + 2] - 0x30) * 8 +
+                (source[i + 3] - 0x30));
+            i += 3;
+        }
+        else {
+            output.push(source[i]);
+        }
+    }
+    return Uint8Array.from(output);
+}
+/** Byte-exact control commands for one browser input frame. */
+export function hexSendKeysCommands(target, data) {
+    const source = Buffer.from(data);
+    const commands = [];
+    for (let start = 0; start < source.length; start += SEND_KEYS_HEX_BYTES_PER_CALL) {
+        const chunk = source.subarray(start, start + SEND_KEYS_HEX_BYTES_PER_CALL);
+        const hex = Array.from(chunk, (byte) => byte.toString(16).padStart(2, "0")).join(" ");
+        commands.push(Buffer.from(`send-keys -t ${target} -H ${hex}\n`, "ascii"));
+    }
+    return commands;
+}
+/** Global tmux argv for a control-mode attach. Exported to pin role semantics. */
+export function controlAttachArgs(socketPath, role) {
+    const args = ["-u", "-S", socketPath, "-f", "/dev/null", "-C", "attach"];
+    if (role === "read-only")
+        args.push("-r");
+    args.push("-t", TMUX_TARGET);
+    return args;
+}
+/** Options applied before pane creation so per-pane values take effect. */
+export function tmuxManagedOptionCommands(spec) {
+    const commands = [
+        ["set-option", "-g", "history-limit", String(spec.scrollback)],
+        ["set-option", "-sq", "extended-keys", "on"],
+        ["set-option", "-sq", "extended-keys-format", "csi-u"],
+        ["set-option", "-g", "mouse", "off"],
+        ["set-option", "-g", "focus-events", "on"],
+        ["set-option", "-g", "escape-time", "0"],
+        ["set-option", "-g", "prefix", "None"],
+        ["set-option", "-g", "prefix2", "None"],
+        ["unbind-key", "-a", "-T", "prefix"],
+        ["unbind-key", "-q", "-T", "root", "MouseDown3Pane"],
+        ["unbind-key", "-q", "-T", "root", "M-MouseDown3Pane"],
+        ["unbind-key", "-q", "-T", "root", "MouseDown3Status"],
+        ["unbind-key", "-q", "-T", "root", "M-MouseDown3Status"],
+        ["unbind-key", "-q", "-T", "root", "MouseDown3StatusLeft"],
+        ["unbind-key", "-q", "-T", "root", "M-MouseDown3StatusLeft"],
+        ["set-option", "-g", "status", "off"],
+    ];
+    if (spec.keepAliveAfterExit) {
+        commands.push(["set-option", "-gq", "remain-on-exit", "on"], ["set-option", "-sq", "exit-empty", "off"]);
+    }
+    if (spec.allowPassthrough) {
+        commands.push(["set-option", "-g", "allow-passthrough", "on"]);
+    }
+    return commands;
+}
+/** Extract the pane size from tmux's `%layout-change` notification. */
+export function controlLayoutDimensions(line) {
+    const match = Buffer.from(line).toString("ascii").match(/^%layout-change\s+\S+\s+\S+,(\d+)x(\d+),/);
+    if (!match)
+        return undefined;
+    const cols = Number(match[1]);
+    const rows = Number(match[2]);
+    if (!Number.isSafeInteger(cols) || !Number.isSafeInteger(rows) || cols <= 0 || rows <= 0) {
+        return undefined;
+    }
+    return { cols, rows };
+}
 /** Resolve the exact tmux executable selected by the current Rynx distribution. */
 export function resolveTmuxBin(explicit, env = process.env) {
     if (explicit !== undefined)
@@ -38,9 +133,12 @@ export function resolveTmuxBin(explicit, env = process.env) {
 /** Deterministic private socket owned by one terminal name. Parent-side
  * shutdown uses the same mapping when the runner child is too wedged to clean
  * up its own tmux server. */
-export function tmuxSocketPath(name) {
+export function tmuxSocketPath(name, ownerPid = process.pid) {
+    return join(tmuxInstanceDir(name, ownerPid), "tmux.sock");
+}
+export function tmuxInstanceDir(name, ownerPid = process.pid) {
     const key = createHash("sha256").update(name).digest("hex").slice(0, 16);
-    return join(tmpdir(), "rynx-term", `${key}.sock`);
+    return join(tmpdir(), "rynx-term", `${ownerPid}-${key}`);
 }
 /** Read tmux's own output-activity clock for a private terminal window.
  *
@@ -50,10 +148,13 @@ export function tmuxSocketPath(name) {
  * may have stalled when the idle reaper needs an independent liveness signal.
  * Missing servers, command failures, timeouts, and unparseable output are all
  * treated as unknown (`null`). */
-export function tmuxWindowActivityAt(name, tmuxBin = resolveTmuxBin()) {
-    const socketPath = tmuxSocketPath(name);
+export function tmuxWindowActivityAt(name, tmuxBin = resolveTmuxBin(), ownerPid = process.pid) {
+    const socketPath = tmuxSocketPath(name, ownerPid);
     return new Promise((resolve) => {
-        execFile(tmuxBin, ["-S", socketPath, "display-message", "-p", "-t", TMUX_TARGET, "#{window_activity}"], { timeout: 2_000 }, (error, stdout) => {
+        execFile(tmuxBin, [
+            "-S", socketPath, "-f", "/dev/null",
+            "display-message", "-p", "-t", TMUX_TARGET, "#{window_activity}",
+        ], { timeout: 2_000 }, (error, stdout) => {
             if (error) {
                 resolve(null);
                 return;
@@ -71,40 +172,91 @@ export function tmuxWindowActivityAt(name, tmuxBin = resolveTmuxBin()) {
 /** Whether tmux itself reports an attached client for this private terminal.
  * This remains authoritative if a parent-side attachment bookkeeping edge was
  * missed during a transport failure. */
-export function tmuxHasAttachedClient(name, tmuxBin = resolveTmuxBin()) {
-    const socketPath = tmuxSocketPath(name);
+export function tmuxHasAttachedClient(name, tmuxBin = resolveTmuxBin(), ownerPid = process.pid) {
+    const socketPath = tmuxSocketPath(name, ownerPid);
     return new Promise((resolve) => {
-        execFile(tmuxBin, ["-S", socketPath, "list-clients", "-t", TMUX_TARGET, "-F", "#{client_name}"], { timeout: 2_000 }, (error, stdout) => {
+        execFile(tmuxBin, [
+            "-S", socketPath, "-f", "/dev/null",
+            "list-clients", "-t", TMUX_TARGET, "-F", "#{client_name}",
+        ], { timeout: 2_000 }, (error, stdout) => {
             resolve(!error && stdout.toString().split("\n").some((line) => line.trim().length > 0));
         });
     });
 }
-/** Best-effort close of one private tmux server. Mirrors reference implementation's bounded
- * `TerminalInstance.close`: attempt `kill-server`, then retire the private
- * socket regardless of command outcome. The registry has already forgotten
- * the resource, so cleanup failure is diagnostic rather than a second
- * lifecycle state. */
-export function terminateTmuxServer(name, tmuxBin = resolveTmuxBin()) {
-    const socketPath = tmuxSocketPath(name);
-    if (!existsSync(socketPath))
-        return true;
-    const base = ["-u", "-S", socketPath];
+/** Best-effort close of one private tmux server. Attempt `kill-server`, then
+ * retire the private socket regardless of command outcome. The registry has
+ * already forgotten the resource, so cleanup failure is diagnostic rather than
+ * a second lifecycle state. */
+export function terminateTmuxServer(name, tmuxBin = resolveTmuxBin(), ownerPid = process.pid) {
+    const instanceDir = tmuxInstanceDir(name, ownerPid);
+    const socketPath = join(instanceDir, "tmux.sock");
+    const base = ["-u", "-S", socketPath, "-f", "/dev/null"];
+    if (existsSync(socketPath)) {
+        try {
+            execFileSync(tmuxBin, [...base, "kill-server"], {
+                stdio: "ignore",
+                timeout: 5_000,
+            });
+        }
+        catch {
+            // Close is best-effort; still retire the resource if tmux does not respond.
+        }
+    }
+    rmSync(instanceDir, { recursive: true, force: true });
+    return true;
+}
+function processAlive(pid) {
     try {
-        execFileSync(tmuxBin, [...base, "kill-server"], {
-            stdio: "ignore",
-            timeout: 5_000,
-        });
+        process.kill(pid, 0);
+        return true;
     }
-    catch {
-        // reference implementation treats close as best-effort and still retires the resource.
+    catch (error) {
+        return error.code === "EPERM";
     }
+}
+/** Reap private terminal servers whose owning runner process is gone. Dirs
+ * without an owner marker are deliberately ignored. */
+export function reapOrphanedTerminals(opts = {}) {
+    const root = opts.root ?? join(tmpdir(), "rynx-term");
+    const tmuxBin = resolveTmuxBin(opts.tmuxBin);
+    const isProcessAlive = opts.isProcessAlive ?? processAlive;
+    let entries;
     try {
-        unlinkSync(socketPath);
+        entries = readdirSync(root, { encoding: "utf8" });
     }
     catch {
-        // Gone already, or best-effort filesystem cleanup failed.
+        return 0;
     }
-    return true;
+    let reaped = 0;
+    for (const entry of entries) {
+        const instanceDir = join(root, entry);
+        let ownerPid;
+        try {
+            ownerPid = Number.parseInt(readFileSync(join(instanceDir, "owner.pid"), "utf8").trim(), 10);
+            if (!Number.isSafeInteger(ownerPid) || ownerPid <= 0)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (isProcessAlive(ownerPid))
+            continue;
+        const socketPath = join(instanceDir, "tmux.sock");
+        if (existsSync(socketPath)) {
+            try {
+                execFileSync(tmuxBin, ["-u", "-S", socketPath, "-f", "/dev/null", "kill-server"], {
+                    stdio: "ignore",
+                    timeout: 10_000,
+                });
+            }
+            catch {
+                // An already-dead or wedged server is still an orphaned instance.
+            }
+        }
+        rmSync(instanceDir, { recursive: true, force: true });
+        reaped += 1;
+    }
+    return reaped;
 }
 /** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
 export function isTmuxAvailable(tmuxBin = resolveTmuxBin()) {
@@ -116,18 +268,141 @@ export function isTmuxAvailable(tmuxBin = resolveTmuxBin()) {
         return false;
     }
 }
-async function loadPtySpawn() {
-    const mod = (await import("node-pty"));
-    return mod.spawn;
-}
 /** Ensure a UTF-8 locale so tmux renders multibyte (CJK) output correctly. A
  *  pm2/systemd-spawned daemon often has no LANG/LC_*, so tmux treats CJK bytes as
- *  single-byte and mangles Chinese. reference implementation inherits a UTF-8 locale from its launch
- *  env; a pm2 daemon may not — so inject one when none is present. */
+ *  single-byte and mangles Chinese. Inject a UTF-8 locale when none is present. */
 function withUtf8Locale(env) {
     const hasUtf8 = [env.LC_ALL, env.LC_CTYPE, env.LANG].some((v) => v != null && /utf-?8/i.test(v));
     return hasUtf8 ? env : { ...env, LANG: "en_US.UTF-8", LC_CTYPE: "en_US.UTF-8" };
 }
+/** Detached launchers commonly supply no TERM, or TERM=dumb. Native TUIs
+ * reject that environment before they can render into the tmux pane. Preserve
+ * an explicit usable value and provide the same terminal class used by the
+ * browser surface otherwise. */
+function withTerminalEnvironment(env) {
+    const localized = withUtf8Locale(env);
+    const term = localized.TERM?.trim();
+    return !term || term === "dumb" ? { ...localized, TERM: "xterm-256color" } : localized;
+}
+function parsePaneMetadata(value) {
+    const fields = value.toString("utf8").trim().split(",");
+    if (fields.length < 4)
+        return undefined;
+    while (fields.length < 13)
+        fields.push("0");
+    const cursorX = Number(fields[0]);
+    const cursorY = Number(fields[1]);
+    const paneWidth = Number(fields[11]);
+    const paneHeight = Number(fields[12]);
+    if (!Number.isSafeInteger(cursorX) ||
+        !Number.isSafeInteger(cursorY) ||
+        !Number.isSafeInteger(paneWidth) ||
+        !Number.isSafeInteger(paneHeight) ||
+        paneWidth <= 0 ||
+        paneHeight <= 0)
+        return undefined;
+    return {
+        cursorX,
+        cursorY,
+        cursorVisible: fields[2] === "1",
+        alternateOn: fields[3] === "1",
+        mouseStandard: fields[4] === "1",
+        mouseButton: fields[5] === "1",
+        mouseAll: fields[6] === "1",
+        mouseSgr: fields[7] === "1",
+        mouseUtf8: fields[8] === "1",
+        appCursorKeys: fields[9] === "1",
+        bracketPaste: fields[10] === "1",
+        paneWidth,
+        paneHeight,
+    };
+}
+function captureSeedEnvelope(metadata) {
+    const prefix = [];
+    if (metadata?.alternateOn)
+        prefix.push(Buffer.from("\x1b[?1049h", "binary"));
+    prefix.push(Buffer.from("\x1b[H\x1b[2J", "binary"));
+    const suffix = [];
+    if (metadata) {
+        suffix.push(Buffer.from(`\x1b[${metadata.cursorY + 1};${metadata.cursorX + 1}H`, "binary"));
+        suffix.push(Buffer.from(metadata.cursorVisible ? "\x1b[?25h" : "\x1b[?25l", "binary"));
+        if (metadata.mouseStandard)
+            suffix.push(Buffer.from("\x1b[?1000h", "binary"));
+        if (metadata.mouseButton)
+            suffix.push(Buffer.from("\x1b[?1002h", "binary"));
+        if (metadata.mouseAll)
+            suffix.push(Buffer.from("\x1b[?1003h", "binary"));
+        if (metadata.mouseUtf8)
+            suffix.push(Buffer.from("\x1b[?1005h", "binary"));
+        if (metadata.mouseSgr)
+            suffix.push(Buffer.from("\x1b[?1006h", "binary"));
+        if (metadata.appCursorKeys)
+            suffix.push(Buffer.from("\x1b[?1h", "binary"));
+        if (metadata.bracketPaste)
+            suffix.push(Buffer.from("\x1b[?2004h", "binary"));
+    }
+    return { prefix: Buffer.concat(prefix), suffix: Buffer.concat(suffix) };
+}
+function waitForSpawn(proc) {
+    return new Promise((resolve, reject) => {
+        const onSpawn = () => {
+            proc.off("error", onError);
+            resolve();
+        };
+        const onError = (error) => {
+            proc.off("spawn", onSpawn);
+            reject(error);
+        };
+        proc.once("spawn", onSpawn);
+        proc.once("error", onError);
+    });
+}
+function writeWithDrain(proc, data) {
+    return new Promise((resolve, reject) => {
+        let callbackDone = false;
+        let drainDone = false;
+        let settled = false;
+        const cleanup = () => {
+            proc.stdin.off("drain", onDrain);
+            proc.stdin.off("error", onError);
+            proc.off("exit", onExit);
+        };
+        const finish = () => {
+            if (settled || !callbackDone || !drainDone)
+                return;
+            settled = true;
+            cleanup();
+            resolve();
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const onDrain = () => {
+            drainDone = true;
+            finish();
+        };
+        const onError = (error) => fail(error);
+        const onExit = () => fail(new Error("tmux control client exited before input drained"));
+        proc.stdin.once("error", onError);
+        proc.once("exit", onExit);
+        const accepted = proc.stdin.write(data, (error) => {
+            if (error) {
+                fail(error);
+                return;
+            }
+            callbackDone = true;
+            finish();
+        });
+        drainDone = accepted;
+        if (!accepted)
+            proc.stdin.once("drain", onDrain);
+        finish();
+    });
+}
 export class TmuxTerminal {
     name;
     socketPath;
@@ -137,8 +412,11 @@ export class TmuxTerminal {
     env;
     cols;
     rows;
+    scrollback;
+    tmuxAllowPassthrough;
+    tmuxStartOnAttach;
+    keepAliveAfterExit;
     tmuxBin;
-    injectedSpawn;
     started = false;
     lastPaneSnapshot = "";
     /** Shared by every attachment watcher and by the lifecycle watcher's
@@ -146,20 +424,21 @@ export class TmuxTerminal {
      * out once per attached client. */
     paneLivenessFlight;
     /** Shared by lifecycle callers so capture + pane-dead remains one ordered
-     * reference implementation-style observation per Terminal. */
+     * observation per Terminal. */
     lifecycleLivenessFlight;
     constructor(opts) {
         this.name = opts.name;
         this.cwd = opts.cwd;
         this.command = opts.command ?? process.env.SHELL ?? "/bin/bash";
         this.args = opts.args ?? [];
-        this.env = withUtf8Locale(opts.env ?? process.env);
+        this.env = withTerminalEnvironment(opts.env ?? process.env);
         this.cols = opts.cols ?? DEFAULT_COLS;
         this.rows = opts.rows ?? DEFAULT_ROWS;
+        this.scrollback = opts.scrollback ?? DEFAULT_SCROLLBACK;
+        this.tmuxAllowPassthrough = opts.tmuxAllowPassthrough ?? false;
+        this.tmuxStartOnAttach = opts.tmuxStartOnAttach ?? false;
+        this.keepAliveAfterExit = opts.keepAliveAfterExit ?? false;
         this.tmuxBin = resolveTmuxBin(opts.tmuxBin);
-        this.injectedSpawn = opts.ptySpawn;
-        const dir = join(tmpdir(), "rynx-term");
-        mkdirSync(dir, { recursive: true });
         // A short hash of the (per-session-unique) name keeps the socket path well
         // under the unix-domain path limit (~104 chars on macOS) — a full session id
         // like `sess_<uuid>-main` under $TMPDIR would overflow it and fail with
@@ -171,7 +450,10 @@ export class TmuxTerminal {
         // `-u` forces tmux to emit UTF-8 even when the launch env has no UTF-8 locale (a
         // pm2/systemd-spawned daemon often has no LANG) — without it multibyte CJK output
         // is mangled. Belt-and-suspenders with the UTF-8 locale injected into `this.env`.
-        return ["-u", "-S", this.socketPath];
+        // The private server is configured entirely by this class. Ignoring the
+        // user's tmux.conf keeps keyboard, mouse, status and plugin behavior
+        // deterministic across every command and control attach.
+        return ["-u", "-S", this.socketPath, "-f", "/dev/null"];
     }
     /** Create the private tmux server + detached session running the inner
      *  command. Idempotent: a second call is a no-op once the session exists. */
@@ -180,93 +462,49 @@ export class TmuxTerminal {
             return;
         // Clear any stale server on this deterministic private socket before launch.
         terminateTmuxServer(this.name, this.tmuxBin);
-        // `new-session -d` starts detached; `-x/-y` seed the pane size so output
-        // wraps sanely before the first client attaches and resizes it.
-        execFileSync(this.tmuxBin, [
-            ...this.base(),
-            "new-session",
-            "-d",
-            "-s",
-            TMUX_TARGET,
-            "-x",
-            String(this.cols),
-            "-y",
-            String(this.rows),
-            "-c",
-            this.cwd,
-            this.command,
-            ...this.args,
-        ], { env: this.env, stdio: "ignore" });
-        this.configureSession();
-        this.started = true;
-    }
-    /**
-     * Apply reference implementation's tmux option suite to the private server (inner/terminal.py).
-     * These are NOT cosmetic — several fix real co-drive behavior that the tmux
-     * defaults break:
-     *  - `mouse on`: the web terminal's wheel scrolls the pane's scrollback (and
-     *    mouse events reach a TUI that requests them). Without it, no scrolling.
-     *  - `extended-keys on` + `csi-u`: tmux forwards Kitty Keyboard Protocol / CSI-u
-     *    keys (Ctrl+C, Shift+Enter, modified keys) that codex/claude TUIs request —
-     *    without it tmux downgrades them and the vendor TUI mis-reads modifiers.
-     *  - `escape-time 0`: kills tmux's default 500 ms wait after ESC, which otherwise
-     *    makes arrow keys / Alt-combos / pasted CSI feel laggy or mis-parse.
-     *  - `prefix None` + `prefix2 None` + unbind the prefix table: the user's
-     *    keystrokes (notably C-b) go to the pane, never tmux — a co-drive terminal
-     *    must not intercept a prefix.
-     *  - `focus-events on`, `allow-passthrough on`, `history-limit`: focus reporting,
-     *    passthrough sequences, scrollback depth.
-     *  - `remain-on-exit on` + `exit-empty off`: keep the dead pane + server after the
-     *    inner CLI exits so its last output stays capturable and `#{pane_dead}` reads
-     *    the exit (liveness probe), instead of the server vanishing.
-     *  - `MouseDown3*` unbinds: no right-click menu to spawn extra panes/windows.
-     *  - `status off`: hide tmux chrome. reference implementation keeps the status line only to show
-     *    a conversation link; rynx has none, so the whole line (and its
-     *    `[main] 0:node*` window list) is hidden.
-     * `-q`/`-gq`/`-sq` keep an older tmux that lacks an option from failing launch.
-     * Batched into one invocation with `;` command separators (one spawn).
-     */
-    configureSession() {
-        const commands = [
-            // input + scrollback
-            ["set-option", "-g", "history-limit", String(DEFAULT_SCROLLBACK)],
-            ["set-option", "-sq", "extended-keys", "on"],
-            ["set-option", "-sq", "extended-keys-format", "csi-u"],
-            ["set-option", "-g", "mouse", "on"],
-            ["set-option", "-g", "focus-events", "on"],
-            ["set-option", "-g", "escape-time", "0"],
-            // persistence: outlive the inner CLI's exit (see `#{pane_dead}` liveness)
-            ["set-option", "-gq", "remain-on-exit", "on"],
-            ["set-option", "-sq", "exit-empty", "off"],
-            // passthrough escape sequences
-            ["set-option", "-g", "allow-passthrough", "on"],
-            // lockdown: no prefix, no right-click pane/window creation
-            ["set-option", "-g", "prefix", "None"],
-            ["set-option", "-g", "prefix2", "None"],
-            ["unbind-key", "-a", "-T", "prefix"],
-            ["unbind-key", "-q", "-T", "root", "MouseDown3Pane"],
-            ["unbind-key", "-q", "-T", "root", "M-MouseDown3Pane"],
-            ["unbind-key", "-q", "-T", "root", "MouseDown3Status"],
-            ["unbind-key", "-q", "-T", "root", "M-MouseDown3Status"],
-            ["unbind-key", "-q", "-T", "root", "MouseDown3StatusLeft"],
-            ["unbind-key", "-q", "-T", "root", "M-MouseDown3StatusLeft"],
-            // hide tmux chrome (no conversation link to show, unlike reference implementation)
-            ["set-option", "-g", "status", "off"],
-        ];
-        const argv = [...this.base()];
-        commands.forEach((cmd, i) => {
-            if (i > 0)
-                argv.push(";");
-            argv.push(...cmd);
+        const instanceDir = tmuxInstanceDir(this.name);
+        mkdirSync(instanceDir, { recursive: true, mode: 0o700 });
+        writeFileSync(join(instanceDir, "owner.pid"), String(process.pid), { mode: 0o600 });
+        const commands = tmuxManagedOptionCommands({
+            scrollback: this.scrollback,
+            allowPassthrough: this.tmuxAllowPassthrough,
+            keepAliveAfterExit: this.keepAliveAfterExit,
         });
+        const startChannel = "rynx-terminal-start";
+        if (this.tmuxStartOnAttach) {
+            commands.push(["set-hook", "-g", "client-attached", `wait-for -S ${startChannel}`]);
+        }
+        const paneCommand = this.tmuxStartOnAttach
+            ? [
+                "/bin/sh",
+                "-lc",
+                `tmux wait-for ${startChannel}; exec \"$@\"`,
+                "sh",
+                this.command,
+                ...this.args,
+            ]
+            : [this.command, ...this.args];
+        commands.push([
+            "new-session", "-d", "-s", TMUX_TARGET,
+            "-x", String(this.cols), "-y", String(this.rows),
+            "-c", this.cwd,
+            ...paneCommand,
+        ]);
+        if (this.keepAliveAfterExit) {
+            commands.push(["set-hook", "-w", "pane-died", "detach-client -a"]);
+        }
+        const argv = [...this.base(), "start-server"];
+        for (const command of commands)
+            argv.push(";", ...command);
         execFileSync(this.tmuxBin, argv, { env: this.env, stdio: "ignore" });
+        this.started = true;
     }
     /** Whether the terminal's INNER PROCESS is still running. Probes the pane's
      *  `#{pane_dead}` flag rather than mere session existence: with
      *  `remain-on-exit on` the session/server deliberately outlive the inner CLI's
      *  exit (a dead pane shows tmux's "Pane is dead"), so `has-session` succeeding
      *  no longer implies a live process. Alive only when the session exists AND its
-     *  pane process has not exited. Mirrors reference implementation's `_terminal.is_alive`. */
+     *  pane process has not exited. */
     isAlive() {
         if (!this.started)
             return false;
@@ -285,8 +523,8 @@ export class TmuxTerminal {
     /** Async pane-liveness probe — MUST NOT block the event loop. The attach
      *  pane-death watcher polls this on an interval; a synchronous `execFileSync`
      *  there stalls the runner child's event loop (freezing the PTY stream → the
-     *  terminal appears "stuck"). Exactly like reference implementation's definitive pane probe,
-     *  every command error is `unknown`; only `#{pane_dead}=1` is `dead`. */
+     *  terminal appears "stuck"). Every command error is `unknown`; only
+     *  `#{pane_dead}=1` is definitive evidence of `dead`. */
     livenessAsync() {
         if (!this.started)
             return Promise.resolve("dead");
@@ -320,7 +558,7 @@ export class TmuxTerminal {
         });
         return flight;
     }
-    /** reference implementation's always-on terminal lifecycle watcher first captures the pane:
+    /** The always-on terminal lifecycle watcher first captures the pane:
      * a control command that ran and reports the target missing is terminal exit;
      * a probe that cannot spawn is inconclusive. If capture succeeds, the normal
      * definitive `pane_dead` probe distinguishes live from exited. */
@@ -340,8 +578,8 @@ export class TmuxTerminal {
                 }
                 this.lastPaneSnapshot = stdout.toString();
                 void this.livenessAsync().then((liveness) => {
-                    // A successful capture proves the target exists. reference implementation treats a
-                    // subsequent pane-dead probe failure as non-dead for this tick.
+                    // A successful capture proves the target exists. A subsequent
+                    // pane-dead probe failure is non-dead for this tick.
                     resolve(liveness === "dead" ? "dead" : "alive");
                 });
             });
@@ -378,7 +616,7 @@ export class TmuxTerminal {
     /** Type literal text into the pane (agent injection / co-drive from a
      *  non-PTY caller). `-l` sends the text literally rather than as key names. */
     sendKeys(text) {
-        execFile(this.tmuxBin, [...this.base(), "send-keys", "-t", TMUX_TARGET, "-l", "--", text], { env: this.env }, () => undefined);
+        execFileSync(this.tmuxBin, [...this.base(), "send-keys", "-c", "", "-t", TMUX_TARGET, "-l", "--", text], { env: this.env, stdio: "ignore", timeout: TMUX_SEND_TIMEOUT_MS });
     }
     /**
      * The visible pane text (synchronous). Used by the claude-native injection
@@ -391,6 +629,7 @@ export class TmuxTerminal {
             const snapshot = execFileSync(this.tmuxBin, [...this.base(), "capture-pane", "-t", TMUX_TARGET, "-p"], {
                 env: this.env,
                 encoding: "utf8",
+                timeout: TMUX_SEND_TIMEOUT_MS,
             });
             this.lastPaneSnapshot = snapshot;
             return snapshot;
@@ -407,21 +646,22 @@ export class TmuxTerminal {
     }
     /** Interrupt the pane's running TUI turn with an Escape key — codex/claude both
      *  cancel an in-flight response on a single Esc ("esc to interrupt"). A key NAME
-     *  (no `-l`) so tmux interprets it. Mirrors reference implementation's `inject_interrupt`. */
+     *  (no `-l`) so tmux interprets it. */
     interrupt() {
         this.sendKeyNames("Escape");
     }
     /** Clear the current input line before an injection so leftover keystrokes
      *  can't prepend to the pasted draft. `C-a` (Home) + `C-k` (kill-to-end) is
-     *  the safe pair — `C-u` only clears backwards from the cursor (reference implementation). */
+     *  the safe pair because `C-u` only clears backwards from the cursor. */
     clearInputLine() {
         this.sendKeyNames("C-a", "C-k");
     }
     /** Send one or more tmux key NAMES (e.g. `Enter`, `C-a`) to the pane. */
     sendKeyNames(...keys) {
-        execFileSync(this.tmuxBin, [...this.base(), "send-keys", "-t", TMUX_TARGET, ...keys], {
+        execFileSync(this.tmuxBin, [...this.base(), "send-keys", "-c", "", "-t", TMUX_TARGET, ...keys], {
             env: this.env,
             stdio: "ignore",
+            timeout: TMUX_SEND_TIMEOUT_MS,
         });
     }
     /**
@@ -437,76 +677,311 @@ export class TmuxTerminal {
             env: this.env,
             input: text,
             stdio: ["pipe", "ignore", "ignore"],
+            timeout: TMUX_SEND_TIMEOUT_MS,
         });
-        execFileSync(this.tmuxBin, [...this.base(), "paste-buffer", "-p", "-d", "-b", bufferName, "-t", TMUX_TARGET], { env: this.env, stdio: "ignore" });
+        execFileSync(this.tmuxBin, [...this.base(), "paste-buffer", "-p", "-d", "-b", bufferName, "-t", TMUX_TARGET], { env: this.env, stdio: "ignore", timeout: TMUX_SEND_TIMEOUT_MS });
     }
-    /**
-     * Attach a client. `role: "read-only"` passes tmux `-r` so the viewer cannot
-     * type and `ignore-size` so even its initial PTY dimensions cannot resize the
-     * owner's pane (defense-in-depth on top of the WS bridge dropping input and
-     * resize frames).
-     */
-    async attach(role, dims) {
+    execTmuxBuffer(args) {
+        return new Promise((resolve) => {
+            const proc = spawn(this.tmuxBin, [...this.base(), ...args], {
+                env: this.env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            const chunks = [];
+            let byteLength = 0;
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            proc.stdout.on("data", (chunk) => {
+                chunks.push(Buffer.from(chunk));
+                byteLength += chunk.byteLength;
+            });
+            proc.stderr.resume();
+            proc.once("error", () => finish(undefined));
+            proc.once("close", (code) => {
+                finish(code === 0 ? Buffer.concat(chunks, byteLength) : undefined);
+            });
+        });
+    }
+    /** Prepare connect-time history without creating a live tmux client. */
+    async prepare(role, dims) {
         this.start();
-        const spawn = this.injectedSpawn ?? (await loadPtySpawn());
-        const args = [...this.base(), "attach-session"];
-        if (role === "read-only")
-            args.push("-r", "-f", "ignore-size");
-        args.push("-t", TMUX_TARGET);
-        const proc = spawn(this.tmuxBin, args, {
-            name: "xterm-256color",
-            cols: dims?.cols ?? this.cols,
-            rows: dims?.rows ?? this.rows,
+        const captured = await this.controlModeSeedSpool(role);
+        let state = "prepared";
+        return {
+            seedBytes: captured.spool.finalOffset ?? 0,
+            ...(captured.dimensions ? { dimensions: captured.dimensions } : {}),
+            readSeed: (offset, maxBytes) => captured.spool.read(offset, maxBytes),
+            start: async () => {
+                if (state !== "prepared")
+                    throw new Error("terminal preparation is no longer startable");
+                if (captured.spool.retainedBytes !== 0) {
+                    throw new Error("terminal history must be consumed before live attach starts");
+                }
+                state = "started";
+                captured.spool.close();
+                return await this.startPullAttachment(role, dims, captured.dimensions);
+            },
+            kill: () => {
+                if (state !== "prepared")
+                    return;
+                state = "closed";
+                captured.spool.close();
+            },
+        };
+    }
+    async controlModeSeedSpool(role) {
+        const metadata = parsePaneMetadata(await this.execTmuxBuffer([
+            "display-message",
+            "-p",
+            "-t",
+            TMUX_TARGET,
+            PANE_METADATA_FORMAT,
+        ]) ?? Buffer.alloc(0));
+        let spool = new SegmentedTerminalSpool();
+        const captureArgs = ["capture-pane", "-e", "-p", "-J", "-t", TMUX_TARGET];
+        if (metadata && !metadata.alternateOn)
+            captureArgs.push("-S", "-");
+        const envelope = captureSeedEnvelope(metadata);
+        spool.append(envelope.prefix);
+        let captureError;
+        let pendingByte;
+        let previousByte;
+        let normalized = [];
+        const flushNormalized = () => {
+            if (normalized.length === 0)
+                return;
+            spool.append(Uint8Array.from(normalized));
+            normalized = [];
+        };
+        const emitBodyByte = (byte) => {
+            if (byte === 0x0a && previousByte !== 0x0d)
+                normalized.push(0x0d);
+            normalized.push(byte);
+            previousByte = byte;
+            if (normalized.length >= 64 * 1024)
+                flushNormalized();
+        };
+        const captureSucceeded = await new Promise((resolve) => {
+            const proc = spawn(this.tmuxBin, [...this.base(), ...captureArgs], {
+                env: this.env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            proc.stdout.on("data", (chunk) => {
+                if (captureError)
+                    return;
+                try {
+                    for (const byte of chunk) {
+                        if (pendingByte !== undefined)
+                            emitBodyByte(pendingByte);
+                        pendingByte = byte;
+                    }
+                }
+                catch (error) {
+                    captureError = error instanceof Error ? error : new Error(String(error));
+                    proc.kill("SIGTERM");
+                }
+            });
+            proc.stderr.resume();
+            proc.once("error", (error) => {
+                captureError = error;
+                resolve(false);
+            });
+            proc.once("close", (code) => resolve(code === 0 && !captureError));
+        });
+        if (!captureSucceeded) {
+            spool.close();
+            spool = new SegmentedTerminalSpool();
+            spool.end();
+        }
+        else {
+            // `capture-pane -p` contributes one formatting newline which was not
+            // present in the pane. Keep every other byte, including an actual CRLF.
+            if (pendingByte !== undefined && pendingByte !== 0x0a)
+                emitBodyByte(pendingByte);
+            flushNormalized();
+            spool.append(envelope.suffix);
+            spool.end();
+        }
+        return {
+            spool,
+            ...(metadata
+                ? { dimensions: { cols: metadata.paneWidth, rows: metadata.paneHeight } }
+                : {}),
+        };
+    }
+    async startPullAttachment(role, _dims, initialDimensions) {
+        const proc = spawn(this.tmuxBin, controlAttachArgs(this.socketPath, role), {
             cwd: this.cwd,
             env: this.env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        await waitForSpawn(proc);
+        const spool = new SegmentedTerminalSpool();
+        const resizeListeners = [];
+        let currentDimensions = initialDimensions;
+        let requestedReason;
+        let exitCode = 0;
+        let readerFinished = false;
+        let discardOutput = false;
+        let terminateTimer;
+        let forceKillTimer;
+        let commandTail = Promise.resolve();
+        let resolveReaderDone;
+        const readerDone = new Promise((resolve) => {
+            resolveReaderDone = resolve;
         });
-        // Pane-death watcher: with `remain-on-exit on` a dead pane keeps the attach
-        // process alive (so `proc.onExit` never fires) while tmux paints "Pane is dead".
-        // Poll `#{pane_dead}` and synthesize an exit so the web bridge closes the WS and
-        // shows the dead-pane overlay instead of leaking tmux's "Pane is dead" text
-        // (reference implementation: the server closes the socket on pane death → StatusOverlay).
-        // Multi-listener, not a single slot: the runner child (and any future
-        // subscriber) register `onExit`; a single-slot setter would let a later
-        // `onExit` silently CLOBBER an earlier one (that clobber is exactly how the
-        // old owner-slot release was lost — a tab switch then re-attached read-only).
-        const exitListeners = [];
-        let exited = false;
-        const fireExit = (exitCode) => {
-            if (exited)
+        const processRunning = () => proc.exitCode === null && proc.signalCode === null;
+        const clearTerminationTimers = () => {
+            if (terminateTimer)
+                clearTimeout(terminateTimer);
+            if (forceKillTimer)
+                clearTimeout(forceKillTimer);
+            terminateTimer = undefined;
+            forceKillTimer = undefined;
+        };
+        const requestTeardown = (reason, graceMs) => {
+            requestedReason ??= reason;
+            if (!proc.stdin.destroyed)
+                proc.stdin.end();
+            if (terminateTimer || forceKillTimer || !processRunning())
+                return;
+            terminateTimer = setTimeout(() => {
+                terminateTimer = undefined;
+                if (processRunning())
+                    proc.kill("SIGTERM");
+            }, graceMs);
+            terminateTimer.unref?.();
+            forceKillTimer = setTimeout(() => {
+                forceKillTimer = undefined;
+                if (processRunning())
+                    proc.kill("SIGKILL");
+            }, graceMs + 750);
+            forceKillTimer.unref?.();
+        };
+        const failReader = (error) => {
+            if (discardOutput)
                 return;
-            exited = true;
-            if (deadTimer)
-                clearInterval(deadTimer);
-            for (const listener of exitListeners)
-                listener({ exitCode });
+            discardOutput = true;
+            const failure = error instanceof Error ? error : new Error(String(error));
+            requestedReason = "internal";
+            spool.fail(failure);
+            requestTeardown(requestedReason, 0);
         };
-        // Skip the poll under injectedSpawn (tests use a fake pane; `isAlive` shells out
-        // to real tmux). `unref` so a lingering attach never keeps the process alive.
-        const deadTimer = this.injectedSpawn
-            ? undefined
-            : setInterval(() => {
-                if (exited)
+        const parser = new TmuxControlParser({
+            onOutput: (chunk) => {
+                if (discardOutput)
                     return;
-                // ASYNC probe (never execFileSync here — that would block the event loop
-                // and freeze the PTY stream, making the terminal unresponsive).
-                void this.livenessAsync().then((liveness) => {
-                    if (liveness === "dead" && !exited)
-                        fireExit(0);
-                });
-            }, 1000);
-        deadTimer?.unref?.();
-        proc.onExit((info) => fireExit(info.exitCode));
+                try {
+                    spool.append(chunk);
+                }
+                catch (error) {
+                    failReader(error);
+                }
+            },
+            onControlLine: (line) => {
+                const dimensions = controlLayoutDimensions(line);
+                if (dimensions &&
+                    (dimensions.cols !== currentDimensions?.cols || dimensions.rows !== currentDimensions?.rows)) {
+                    currentDimensions = dimensions;
+                    for (const listener of resizeListeners)
+                        listener(dimensions);
+                }
+                const text = Buffer.from(line);
+                if (text.subarray(0, 5).equals(Buffer.from("%exit", "ascii")) ||
+                    text.subarray(0, 13).equals(Buffer.from("%window-close", "ascii"))) {
+                    requestTeardown("terminal_exited", 0);
+                }
+            },
+        });
+        const finishReader = () => {
+            if (readerFinished)
+                return;
+            readerFinished = true;
+            clearInterval(deadTimer);
+            clearTerminationTimers();
+            try {
+                parser.end();
+                if (!discardOutput)
+                    spool.end();
+            }
+            catch (error) {
+                failReader(error);
+            }
+            const reason = requestedReason ?? "terminal_exited";
+            resolveReaderDone({
+                reason,
+                finalOffset: spool.finalOffset ?? 0,
+                exitCode,
+            });
+        };
+        const enqueueCommands = (commands) => {
+            const operation = commandTail.then(async () => {
+                if (!processRunning() || proc.stdin.destroyed)
+                    throw new Error("tmux control client is closed");
+                for (const command of commands)
+                    await writeWithDrain(proc, command);
+            });
+            commandTail = operation.catch(() => undefined);
+            return operation;
+        };
+        const deadTimer = setInterval(() => {
+            if (readerFinished)
+                return;
+            void this.livenessAsync().then((liveness) => {
+                if (liveness === "dead" && !readerFinished)
+                    requestTeardown("terminal_exited", 0);
+            });
+        }, 1000);
+        deadTimer.unref?.();
+        proc.stdout.on("data", (chunk) => {
+            try {
+                parser.write(chunk);
+            }
+            catch (error) {
+                failReader(error);
+            }
+        });
+        proc.stdout.once("end", finishReader);
+        proc.stdout.once("close", finishReader);
+        proc.stdin.on("error", () => undefined);
+        proc.once("exit", (code) => {
+            exitCode = code ?? 0;
+            requestedReason ??= "terminal_exited";
+            clearTerminationTimers();
+        });
+        proc.once("error", (error) => {
+            exitCode = 1;
+            failReader(error);
+        });
+        proc.stderr.resume();
         return {
-            onData: (listener) => proc.onData(listener),
-            onExit: (listener) => {
-                exitListeners.push(listener);
+            ...(initialDimensions ? { dimensions: initialDimensions } : {}),
+            readerDone,
+            read: (offset, maxBytes) => spool.read(offset, maxBytes),
+            onResize: (listener) => {
+                resizeListeners.push(listener);
+                if (currentDimensions)
+                    queueMicrotask(() => listener(currentDimensions));
+            },
+            write: async (data) => {
+                if (role !== "owner" || readerFinished || data.byteLength === 0)
+                    return;
+                await enqueueCommands(hexSendKeysCommands(TMUX_TARGET, data));
+            },
+            resize: async (cols, rows) => {
+                if (readerFinished)
+                    return;
+                await enqueueCommands([`refresh-client -C ${cols}x${rows}\n`]);
             },
-            write: (data) => proc.write(data),
-            resize: (cols, rows) => proc.resize(cols, rows),
             kill: () => {
-                if (deadTimer)
-                    clearInterval(deadTimer);
-                proc.kill();
+                if (!readerFinished)
+                    requestTeardown("client_closed", 250);
+                void readerDone.finally(() => spool.close());
             },
         };
     }