@openrig/cli 0.6.4 → 0.6.6

package/daemon/dist/adapters/tmux.js

@@ -104,11 +104,25 @@ function classifyWriteError(err) {
     }
     return { ok: false, code: "unknown", message: err.message };
 }
-/** Shell-quote a string using single quotes (POSIX-safe). */
+/** The most sessions one batched capture chains (#308). Not a byte bound: a chunk whose output overflows exec's buffer
+ *  fails and is split in half. */
+const CAPTURE_BATCH = 24;
 function shellQuote(s) {
     // Replace each ' with '"'"' (end quote, double-quote the apostrophe, resume quote)
     return "'" + s.replace(/'/g, "'\"'\"'") + "'";
 }
+/**
+ * An exact tmux target for a session name. tmux resolves a bare name by prefix when no session has that exact name,
+ * so a read or pipe for a session that just ended would act on another (`dev-impl@my-rig` on `dev-impl@my-rig2`).
+ * Pane, window and session ids (`%3`, `@1`, `$2`) and `session:window.pane` targets pass through unchanged (tmux
+ * turns `:` in a session name into `_`, so a `:` always means an explicit target). A pane or window command gets
+ * `=name:` (as the batched capture uses); a session command gets `=name`.
+ */
+function exactTarget(target, kind) {
+    if (/^[%@$]\d+$/.test(target) || target.includes(":"))
+        return target;
+    return kind === "session" ? `=${target}` : `=${target}:`;
+}
 /** Elements safe to leave bare in a POSIX shell word list. */
 const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
 /** Join argv for a POSIX shell — the legacy string form. Only used when
@@ -168,17 +182,17 @@ function parsePaneLine(line) {
     if (parts.length < 6)
         return null;
     const index = parseInt(parts[1], 10);
-    const width = parseInt(parts[3], 10);
-    const height = parseInt(parts[4], 10);
+    const width = parseInt(parts.at(-3), 10);
+    const height = parseInt(parts.at(-2), 10);
     if (isNaN(index) || isNaN(width) || isNaN(height))
         return null;
     return {
         id: parts[0],
         index,
-        cwd: parts[2],
+        cwd: parts.slice(2, -3).join(TMUX_FIELD_SEPARATOR),
         width,
         height,
-        active: parts[5] === "1",
+        active: parts.at(-1) === "1",
     };
 }
 function parseLines(output, parser) {
@@ -280,9 +294,20 @@ export class TmuxAdapter {
                     const result = classifyWriteError(error);
                     // Only termination consumes positive absence. Unknown probe failures
                     // still refuse, and guard-on never reaches this observation.
-                    if (allowAbsent && !result.ok && result.code === "session_not_found"
-                        && !/permission denied|operation not permitted|EACCES|EPERM/i.test(result.message))
-                        return result;
+                    if (allowAbsent && !result.ok
+                        && !/permission denied|operation not permitted|EACCES|EPERM/i.test(result.message)) {
+                        if (result.code === "session_not_found")
+                            return result;
+                        // list-panes reports a missing session as "can't find window" on
+                        // native tmux. Do not broaden write-error classification: only
+                        // termination may confirm the bound session's positive absence.
+                        if (/can't find window/i.test(result.message)) {
+                            const probe = await this.probeSession(bound.session);
+                            guard.checkInput(identity);
+                            if (probe.state === "absent")
+                                return { ok: false, code: "session_not_found", message: result.message };
+                        }
+                    }
                     throw error;
                 }
                 const pane = fresh ? created.pane : bound.pane;
@@ -369,8 +394,15 @@ export class TmuxAdapter {
         }
     }
     async listPanes(target) {
+        // Callers name a session (optionally with a window), or an immutable tmux
+        // id. Exact session matching prevents observing a prefix neighbor's pane.
+        // A bare leading '=' belongs to the literal session name. Only qualified
+        // targets already carry tmux's encoded exact-match syntax.
+        const namedTarget = target.includes(":") && target.startsWith("=") ? target : `=${target}`;
+        const exactTarget = /^[%$@]\d+$/.test(target) ? target
+            : namedTarget.includes(":") ? namedTarget : `${namedTarget}:`;
         try {
-            const output = await this.run(["tmux", "list-panes", "-t", target, "-F", PANE_FORMAT], `tmux list-panes -t ${shellQuote(target)} -F "${PANE_FORMAT}"`);
+            const output = await this.run(["tmux", "list-panes", "-t", exactTarget, "-F", PANE_FORMAT], `tmux list-panes -t ${shellQuote(exactTarget)} -F "${PANE_FORMAT}"`);
             return parseLines(output, parsePaneLine);
         }
         catch (err) {
@@ -394,7 +426,8 @@ export class TmuxAdapter {
             // Use `tmux has-session` directly for reliable existence check — avoids
             // parsing format-string output from `list-sessions` which can fail when
             // tab delimiters are malformed across tmux versions.
-            await this.run(["tmux", "has-session", "-t", name], `tmux has-session -t ${shellQuote(name)}`);
+            const target = `=${name}`; // canonical session name, never a prefix lookup
+            await this.run(["tmux", "has-session", "-t", target], `tmux has-session -t ${shellQuote(target)}`);
             return { state: "present" }; // exit 0 = session exists
         }
         catch (err) {
@@ -435,18 +468,25 @@ export class TmuxAdapter {
     /** The committed binding now owns identity; this is not filesystem cleanup. */
     finishLaunchBinding(session) { this.freshManaged.delete(session); }
     async createSessionUnchecked(name, cwd, env) {
+        // These are the daemon's resolved capture settings, not seat overrides.
+        // An empty per-session value prevents the tmux server's inherited values
+        // from pinning an old policy over config.json inside a newly launched seat.
+        // Explicit seat settings remain authoritative.
+        const seatEnv = {
+            OPENRIG_TRANSCRIPTS_LINES: "",
+            OPENRIG_TRANSCRIPTS_POLL_INTERVAL_SECONDS: "",
+            ...env,
+        };
         const argv = ["tmux", "new-session", "-d", "-s", name];
         if (cwd != null)
             argv.push("-c", cwd);
-        if (env)
-            for (const [k, v] of Object.entries(env))
-                argv.push("-e", `${k}=${v}`);
+        for (const [k, v] of Object.entries(seatEnv))
+            argv.push("-e", `${k}=${v}`);
         const legacyParts = ["tmux", "new-session", "-d", "-s", shellQuote(name)];
         if (cwd != null)
             legacyParts.push("-c", shellQuote(cwd));
-        if (env)
-            for (const [k, v] of Object.entries(env))
-                legacyParts.push("-e", shellQuote(`${k}=${v}`));
+        for (const [k, v] of Object.entries(seatEnv))
+            legacyParts.push("-e", shellQuote(`${k}=${v}`));
         try {
             await this.run(argv, legacyParts.join(" "));
             return { ok: true };
@@ -456,33 +496,40 @@ export class TmuxAdapter {
         }
     }
     /**
-     * Paste text at every size. Unbracketed input can be consumed as individual
+     * Bracketed paste by default, at every size. Unbracketed input can be consumed as individual
      * keystrokes by agent TUIs, losing text even below the old 8 KiB cutoff.
      * A file keeps payload bytes out of shell/tmux argv and its size limits.
      *   `-p`  bracket the paste when the receiving application enables that mode.
      *   `-r`  preserve raw LF. tmux's default paste-buffer replaces every LF with
-     *         CR, and CR (= `C-m` = Enter) is SUBMIT in the Claude/Codex TUIs - a
+     *         CR, and CR is SUBMIT in the Claude/Codex TUIs - a
      *         default paste of a multi-line pack would submit on every newline.
      *   `-d`  drop the buffer after a successful paste.
-     * The single trailing submit stays the caller's separate `sendKeys(["C-m"])`.
+     * `options.bracketed: false` omits `-p` for explicit prompt answers: bytes
+     * then act as keystrokes, including menu shortcuts and control keys.
+     * Any trailing submit stays the caller's separate `sendKeys(["Enter"])`.
      * Cleanup unlinks the temp file in `finally`; if the buffer was loaded but the
      * paste failed (e.g. missing target), an explicit `delete-buffer` runs so no
      * buffer leaks. Unique temp + buffer names per call keep parallel `rig up`
      * seats from colliding.
      */
-    async sendText(target, text) {
-        return this.guardedInput(target, (pane, beforeWrite) => this.sendTextUnchecked(pane, text, beforeWrite));
+    async sendText(target, text, beforeInput, options) {
+        return this.guardedInput(target, (pane, beforeWrite) => this.sendTextUnchecked(pane, text, () => { beforeWrite(); beforeInput?.(); }, options?.bracketed));
     }
-    async sendTextUnchecked(target, text, beforeWrite) {
+    async sendTextUnchecked(target, text, beforeWrite, bracketed = true) {
         const path = this.fileOps.tmpName();
         const buffer = this.fileOps.bufferName();
         let bufferLoaded = false;
+        let created = false;
         try {
-            await this.fileOps.writeFile(path, text);
+            await this.fileOps.writeFile(path, text, { mode: 0o600, flag: "wx" });
+            created = true;
             await this.run(["tmux", "load-buffer", "-b", buffer, path], `tmux load-buffer -b ${shellQuote(buffer)} ${shellQuote(path)}`);
             bufferLoaded = true;
             beforeWrite();
-            await this.run(["tmux", "paste-buffer", "-t", target, "-b", buffer, "-d", "-r", "-p"], `tmux paste-buffer -t ${shellQuote(target)} -b ${shellQuote(buffer)} -d -r -p`);
+            // Explicit prompt answers need key input, not bracketed-paste framing.
+            // Keep their bytes in the file: tmux command parsing and argv limits must
+            // not alter semicolons or reject long answers (#519, #602).
+            await this.run(["tmux", "paste-buffer", "-t", target, "-b", buffer, "-d", "-r", ...(bracketed ? ["-p"] : [])], `tmux paste-buffer -t ${shellQuote(target)} -b ${shellQuote(buffer)} -d -r${bracketed ? " -p" : ""}`);
             return { ok: true };
         }
         catch (err) {
@@ -497,10 +544,12 @@ export class TmuxAdapter {
             return classifyWriteError(err);
         }
         finally {
-            try {
-                await this.fileOps.unlink(path);
+            if (created) {
+                try {
+                    await this.fileOps.unlink(path);
+                }
+                catch { /* best-effort cleanup */ }
             }
-            catch { /* best-effort cleanup */ }
         }
     }
     /**
@@ -511,23 +560,50 @@ export class TmuxAdapter {
      * The shell removes its private script when consumed (not when pasted).
      * A shell that never consumes the invocation leaves the file for diagnosis.
      */
-    async sendShellCommand(target, command, beforeInput) {
+    async sendShellCommand(target, command, beforeInput, options = {}) {
         // Keep the managed selector for nested paste/Enter checks. A resolved pane
         // ID can also occur in detached bindings after a tmux restart; resolving it
         // again would lose the unambiguous session/node and its existing lease.
         // Each nested write still validates the lease and targets its observed pane.
-        return this.guardedInput(target, () => this.sendShellCommandUnchecked(target, command, beforeInput));
+        return this.guardedInput(target, () => this.sendShellCommandUnchecked(target, command, beforeInput, options));
     }
-    async sendShellCommandUnchecked(target, command, beforeInput) {
-        const path = this.fileOps.tmpName();
-        const invocation = `/bin/sh ${shellQuote(path)}`;
+    async sendShellCommandUnchecked(target, command, beforeInput, options) {
+        const commandBytes = Buffer.byteLength(command, "utf8");
+        // POSIX shells retain subshell isolation; unknown/unreadable panes use sh.
+        const paneShell = options.sourceInPane ? (await this.getPaneCommand(target) ?? "").replace(/^-/, "") : "";
+        const sourceInPane = ["bash", "zsh", "sh", "dash", "ksh"].includes(paneShell);
+        let path = options.stageIfLong && commandBytes <= 512 ? undefined : this.fileOps.tmpName();
+        let invocation = path ? sourceInPane ? `( . ${shellQuote(path)} )` : `/bin/sh ${shellQuote(path)}` : command;
+        if (path && paneShell === "fish") {
+            const quotedPath = shellQuote(path);
+            invocation = `/bin/sh ${quotedPath}`;
+            // Fish single quotes reinterpret POSIX backslashes. Keep those payloads
+            // (and paths) on sh, preserving existing executable launches byte-for-byte.
+            if (!command.includes("\\") && !path.includes("\\")) {
+                // Probe fixed syntax in the pane before sourcing, not the launch's exit
+                // status: even failed cleanup must not turn a later exit into a retry.
+                const sourced = `if eval 'OPENRIG_FISH_ASSIGNMENT_PROBE=1 /bin/sh -c :'; source ${quotedPath}; else; /bin/sh ${quotedPath}; end`;
+                // Repeating the path must not add a refusal for previously valid TMPDIRs.
+                if (Buffer.byteLength(sourced, "utf8") <= 512)
+                    invocation = sourced;
+            }
+        }
         if (Buffer.byteLength(invocation, "utf8") > 512) {
-            return { ok: false, code: "launch_path_too_long", message: "Temporary launch-script path exceeds the safe terminal input bound" };
+            // Pi commands below the canonical tty limit still fit when staging cannot.
+            if (options.stageIfLong && commandBytes < 1024) {
+                path = undefined;
+                invocation = command;
+            }
+            else {
+                return { ok: false, code: "launch_path_too_long", message: "Temporary launch-script path exceeds the safe terminal input bound" };
+            }
         }
         let created = false;
         try {
-            await this.fileOps.writeFile(path, `/bin/rm -f -- ${shellQuote(path)}\n${command}\n`, { mode: 0o600, flag: "wx" });
-            created = true;
+            if (path) {
+                await this.fileOps.writeFile(path, `/bin/rm -f -- ${shellQuote(path)}\n${options.execInScript ? "exec " : ""}${command}\n`, { mode: 0o600, flag: "wx" });
+                created = true;
+            }
             const text = beforeInput ? await this.guardedInput(target, (pane, check) => this.sendTextUnchecked(pane, invocation, () => { check(); beforeInput(); }))
                 : await this.sendText(target, invocation);
             if (!text.ok)
@@ -546,7 +622,7 @@ export class TmuxAdapter {
             return classifyWriteError(err);
         }
         finally {
-            if (created) {
+            if (created && path) {
                 try {
                     await this.fileOps.unlink(path);
                 }
@@ -554,8 +630,8 @@ export class TmuxAdapter {
             }
         }
     }
-    async sendKeys(target, keys) {
-        return this.guardedInput(target, pane => this.sendKeysUnchecked(pane, keys));
+    async sendKeys(target, keys, beforeInput) {
+        return this.guardedInput(target, (pane, beforeWrite) => { beforeWrite(); beforeInput?.(); return this.sendKeysUnchecked(pane, keys); });
     }
     async sendKeysUnchecked(target, keys) {
         try {
@@ -567,8 +643,9 @@ export class TmuxAdapter {
         }
     }
     async setWindowOption(target, option, value) {
+        const window = exactTarget(target, "window");
         try {
-            await this.run(["tmux", "set-option", "-w", "-t", target, option, value], `tmux set-option -w -t ${shellQuote(target)} ${shellQuote(option)} ${shellQuote(value)}`);
+            await this.run(["tmux", "set-option", "-w", "-t", window, option, value], `tmux set-option -w -t ${shellQuote(window)} ${shellQuote(option)} ${shellQuote(value)}`);
             return { ok: true };
         }
         catch (err) {
@@ -583,7 +660,7 @@ export class TmuxAdapter {
             return { ok: false, code: "validation_error", message: `resizeWindow: rows must be a positive integer, got ${rows}` };
         }
         try {
-            await this.run(["tmux", "resize-window", "-t", target, "-x", String(cols), "-y", String(rows)]);
+            await this.run(["tmux", "resize-window", "-t", exactTarget(target, "window"), "-x", String(cols), "-y", String(rows)]);
             return { ok: true };
         }
         catch (err) {
@@ -614,8 +691,20 @@ export class TmuxAdapter {
         return this.killSessionUnchecked(name);
     }
     async killSessionUnchecked(name) {
+        // The guarded path passes the immutable `$N` id, which stays as it is; a bare name is made exact.
+        const session = exactTarget(name, "session");
+        // Detach first so `detach-on-destroy off` cannot switch views onto another session.
+        try {
+            await this.run(["tmux", "detach-client", "-s", session], `tmux detach-client -s ${shellQuote(session)}`);
+        }
+        catch (err) {
+            // tmux 3.7 says "no current client" when nothing is attached (and for a missing session, which the kill classifies).
+            const message = err instanceof Error ? err.message : String(err);
+            if (!message.toLowerCase().includes("no current client"))
+                return classifyWriteError(err);
+        }
         try {
-            await this.run(["tmux", "kill-session", "-t", name], `tmux kill-session -t ${shellQuote(name)}`);
+            await this.run(["tmux", "kill-session", "-t", session], `tmux kill-session -t ${shellQuote(session)}`);
             const pane = this.freshProbes.get(name);
             this.freshProbes.delete(name);
             if (pane)
@@ -648,7 +737,8 @@ export class TmuxAdapter {
         return this.guardedInput(paneTarget, pane => this.respawnPaneUnchecked(pane, command, opts));
     }
     async respawnPaneUnchecked(paneTarget, command, opts) {
-        const argv = ["tmux", "respawn-pane", "-t", paneTarget];
+        const exact = exactTarget(paneTarget, "pane");
+        const argv = ["tmux", "respawn-pane", "-t", exact];
         if (opts?.cwd != null)
             argv.push("-c", opts.cwd);
         if (opts?.env)
@@ -657,7 +747,7 @@ export class TmuxAdapter {
         // The respawn command is ONE argv unit: tmux runs it via the shell.
         if (command != null && command.length > 0)
             argv.push(command);
-        const legacyRespawn = ["tmux", "respawn-pane", "-t", shellQuote(paneTarget)];
+        const legacyRespawn = ["tmux", "respawn-pane", "-t", shellQuote(exact)];
         if (opts?.cwd != null)
             legacyRespawn.push("-c", shellQuote(opts.cwd));
         if (opts?.env)
@@ -678,8 +768,9 @@ export class TmuxAdapter {
      *  Set to `on` BEFORE the retiree is signalled to exit (else the pane is destroyed on exit and there
      *  is nothing to respawn into). */
     async setRemainOnExit(paneTarget, on) {
+        const exact = exactTarget(paneTarget, "pane");
         try {
-            await this.run(["tmux", "set-option", "-p", "-t", paneTarget, "remain-on-exit", on ? "on" : "off"], `tmux set-option -p -t ${shellQuote(paneTarget)} remain-on-exit ${on ? "on" : "off"}`);
+            await this.run(["tmux", "set-option", "-p", "-t", exact, "remain-on-exit", on ? "on" : "off"], `tmux set-option -p -t ${shellQuote(exact)} remain-on-exit ${on ? "on" : "off"}`);
             return { ok: true };
         }
         catch (err) {
@@ -689,8 +780,9 @@ export class TmuxAdapter {
     /** Seat-handover cutover: is the pane's process dead (the retiree exited; the pane held by
      *  remain-on-exit)? A known-missing pane also proves physical cutover; unknown probe errors stay false. */
     async isPaneDead(paneId) {
+        const exact = exactTarget(paneId, "pane");
         try {
-            const output = await this.run(["tmux", "display-message", "-p", "-t", paneId, "#{pane_dead}"], `tmux display-message -p -t ${shellQuote(paneId)} "#{pane_dead}"`);
+            const output = await this.run(["tmux", "display-message", "-p", "-t", exact, "#{pane_dead}"], `tmux display-message -p -t ${shellQuote(exact)} "#{pane_dead}"`);
             return output.trim() === "1";
         }
         catch (error) {
@@ -721,8 +813,9 @@ export class TmuxAdapter {
     }
     /** Get the PID of the foreground process in a pane. Returns null if unavailable. */
     async getPanePid(paneId) {
+        const target = exactTarget(paneId, "pane");
         try {
-            const output = await this.run(["tmux", "display-message", "-p", "-t", paneId, "#{pane_pid}"], `tmux display-message -p -t ${shellQuote(paneId)} "#{pane_pid}"`);
+            const output = await this.run(["tmux", "display-message", "-p", "-t", target, "#{pane_pid}"], `tmux display-message -p -t ${shellQuote(target)} "#{pane_pid}"`);
             const trimmed = output.trim();
             const parsed = parseInt(trimmed, 10);
             return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
@@ -746,8 +839,9 @@ export class TmuxAdapter {
     }
     /** Get the current foreground command in a pane. Returns null if unavailable. */
     async getPaneCommand(paneId) {
+        const target = exactTarget(paneId, "pane");
         try {
-            const output = await this.run(["tmux", "display-message", "-p", "-t", paneId, "#{pane_current_command}"], `tmux display-message -p -t ${shellQuote(paneId)} "#{pane_current_command}"`);
+            const output = await this.run(["tmux", "display-message", "-p", "-t", target, "#{pane_current_command}"], `tmux display-message -p -t ${shellQuote(target)} "#{pane_current_command}"`);
             const trimmed = output.trim();
             return trimmed || null;
         }
@@ -755,14 +849,33 @@ export class TmuxAdapter {
             return null;
         }
     }
+    /** A launch metadata read. Callers must never put credential values in terminal input. */
+    async getSessionEnv(session, key) {
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(key))
+            throw new Error("Invalid session environment key.");
+        try {
+            const output = await this.run(["tmux", "show-environment", "-t", session, key], `tmux show-environment -t ${shellQuote(session)} ${shellQuote(key)}`);
+            if (output.trim() === `-${key}`)
+                return undefined;
+            if (!output.startsWith(`${key}=`))
+                throw new Error("Unexpected session environment response.");
+            return output.slice(key.length + 1).replace(/\r?\n$/, "");
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes(`unknown variable: ${key}`))
+                return undefined;
+            throw new Error("Cannot read the session's launch environment.");
+        }
+    }
     /** OPR.0.4.3.28 Part C — usable-presence check for a session-env variable.
      *  Returns whether the var has a nonblank value, NEVER that value, and null
      *  when the session environment cannot be inspected. Listing the environment
      *  distinguishes a genuinely absent var from `tmux show-environment <var>`'s
      *  nonzero lookup exit. */
     async hasSessionEnv(sessionName, varName) {
+        const target = exactTarget(sessionName, "session");
         try {
-            const output = await this.run(["tmux", "show-environment", "-t", sessionName], `tmux show-environment -t ${shellQuote(sessionName)}`);
+            const output = await this.run(["tmux", "show-environment", "-t", target], `tmux show-environment -t ${shellQuote(target)}`);
             const prefix = `${varName}=`;
             return output.split(/\r?\n/).some((line) => line.startsWith(prefix) && line.slice(prefix.length).trim().length > 0);
         }
@@ -779,8 +892,9 @@ export class TmuxAdapter {
         // shell, so its inner quoting stays POSIX here (psmux documents the same
         // `cat >` server-side form for its own path).
         const sink = "cat >> " + shellQuote(outputPath);
+        const target = exactTarget(sessionName, "pane");
         try {
-            await this.run(["tmux", "pipe-pane", "-t", sessionName, sink], `tmux pipe-pane -t ${shellQuote(sessionName)} ${shellQuote(sink)}`);
+            await this.run(["tmux", "pipe-pane", "-t", target, sink], `tmux pipe-pane -t ${shellQuote(target)} ${shellQuote(sink)}`);
             return { ok: true };
         }
         catch (err) {
@@ -789,8 +903,9 @@ export class TmuxAdapter {
     }
     /** Stop pipe-pane on a session. */
     async stopPipePane(sessionName) {
+        const target = exactTarget(sessionName, "pane");
         try {
-            await this.run(["tmux", "pipe-pane", "-t", sessionName], `tmux pipe-pane -t ${shellQuote(sessionName)}`);
+            await this.run(["tmux", "pipe-pane", "-t", target], `tmux pipe-pane -t ${shellQuote(target)}`);
             return { ok: true };
         }
         catch (err) {
@@ -798,9 +913,93 @@ export class TmuxAdapter {
         }
     }
     /** Capture pane content (last N lines). Returns null if unavailable. */
+    /**
+     * Capture many sessions' panes with a few tmux calls instead of one per session (#308). One `list-sessions` says
+     * which targets exist: a missing one maps to null (as a failed per-target capture) without a fork. The live ones
+     * are captured in chunks of CAPTURE_BATCH chained commands (a `display-message` marker, then `capture-pane`), each
+     * pane's output delimited by a marker unique to the call, so the text equals what `capturePaneContent` returns.
+     * Targets are exact (`=<name>:`): no prefix match, and a name with a "." still resolves. tmux stops a chain at its
+     * first failing command, so a chunk that fails is split in half and retried (an oversized output, or a session gone
+     * since the listing); a single session that still fails is left OUT of the map, and the caller reads it per target.
+     * Null when tmux can't be listed at all. Each entry carries the time its own chunk was read (`capturedAt`), so a
+     * slow later chunk can't make an earlier capture look fresh.
+     */
+    async capturePanesContent(targets, lines = 20, now = () => new Date()) {
+        let live;
+        try {
+            const listing = await this.run(["tmux", "list-sessions", "-F", "#{session_name}"], "tmux list-sessions -F '#{session_name}'");
+            live = new Set(listing.split("\n").map((s) => s.trim()).filter(Boolean));
+        }
+        catch {
+            return null;
+        }
+        const out = new Map();
+        const listedAt = now();
+        const present = [];
+        for (const t of new Set(targets)) {
+            if (live.has(t))
+                present.push(t);
+            else
+                out.set(t, { text: null, capturedAt: listedAt });
+        }
+        // A chunk that fails is split in half and retried, down to one session: its output overflowed exec's buffer (wide,
+        // colour-dense panes: each capture is the visible pane plus the requested history) or a session vanished since
+        // the listing. A single session that still fails is left out: the caller reads it per target.
+        /** Capture one chunk with a single chained tmux call into `out`; on failure, split it in half and retry each half. */
+        const captureChunk = async (chunk) => {
+            const nonce = randomUUID().replace(/-/g, "");
+            const mark = (k) => `__openrig_capture_${nonce}_${k}__`;
+            const argv = ["tmux", ...chunk.flatMap((t, k) => [
+                    ...(k > 0 ? [";"] : []),
+                    "display-message", "-p", "-t", `=${t}:`, mark(k), ";", "capture-pane", "-p", "-t", `=${t}:`, "-S", `-${lines}`,
+                ])];
+            const legacy = "tmux " + chunk.map((t, k) => `display-message -p -t ${shellQuote(`=${t}:`)} ${shellQuote(mark(k))} \\; capture-pane -p -t ${shellQuote(`=${t}:`)} -S -${lines}`).join(" \\; ");
+            let output;
+            let capturedAt;
+            try {
+                output = await this.run(argv, legacy);
+                capturedAt = now(); // when THIS chunk's panes were read, not when the sweep ends
+            }
+            catch {
+                if (chunk.length > 1) {
+                    const half = Math.ceil(chunk.length / 2);
+                    await captureChunk(chunk.slice(0, half));
+                    await captureChunk(chunk.slice(half));
+                }
+                return; // a single session that failed: read per target by the caller
+            }
+            const segments = chunk.map(() => null);
+            let cur = -1;
+            const outLines = output.split("\n");
+            if (outLines.length && outLines[outLines.length - 1] === "")
+                outLines.pop(); // the final newline, not a line
+            for (const line of outLines) {
+                const m = line.startsWith(`__openrig_capture_${nonce}_`) ? /_(\d+)__$/.exec(line) : null;
+                if (m && line === mark(Number(m[1]))) {
+                    cur = Number(m[1]);
+                    segments[cur] = [];
+                }
+                else if (cur >= 0) {
+                    segments[cur].push(line);
+                }
+            }
+            chunk.forEach((t, k) => {
+                const seg = segments[k];
+                if (seg == null)
+                    return; // its marker never printed: read per target
+                // capture-pane prints its lines newline-terminated, as the per-target read returns them
+                const text = seg.length ? seg.join("\n") + "\n" : "";
+                out.set(t, { text: text === "" ? null : text, capturedAt });
+            });
+        };
+        for (let i = 0; i < present.length; i += CAPTURE_BATCH)
+            await captureChunk(present.slice(i, i + CAPTURE_BATCH));
+        return out;
+    }
     async capturePaneContent(paneId, lines = 20) {
+        const target = exactTarget(paneId, "pane");
         try {
-            const output = await this.run(["tmux", "capture-pane", "-p", "-t", paneId, "-S", `-${lines}`], `tmux capture-pane -p -t ${shellQuote(paneId)} -S -${lines}`);
+            const output = await this.run(["tmux", "capture-pane", "-p", "-t", target, "-S", `-${lines}`], `tmux capture-pane -p -t ${shellQuote(target)} -S -${lines}`);
             return output || null;
         }
         catch {
@@ -814,8 +1013,9 @@ export class TmuxAdapter {
      * the absolute-paint seed exists to eliminate.
      */
     async capturePaneScreen(paneId) {
+        const target = exactTarget(paneId, "pane");
         try {
-            const output = await this.run(["tmux", "capture-pane", "-p", "-t", paneId], `tmux capture-pane -p -t ${shellQuote(paneId)}`);
+            const output = await this.run(["tmux", "capture-pane", "-p", "-t", target], `tmux capture-pane -p -t ${shellQuote(target)}`);
             return output || null;
         }
         catch {
@@ -829,8 +1029,9 @@ export class TmuxAdapter {
      * produces a garbage seed.
      */
     async getPaneCursorPosition(paneId) {
+        const exact = exactTarget(paneId, "pane");
         try {
-            const output = await this.run(["tmux", "display-message", "-p", "-t", paneId, CURSOR_FORMAT], `tmux display-message -p -t ${shellQuote(paneId)} "${CURSOR_FORMAT}"`);
+            const output = await this.run(["tmux", "display-message", "-p", "-t", exact, CURSOR_FORMAT], `tmux display-message -p -t ${shellQuote(exact)} "${CURSOR_FORMAT}"`);
             const [xRaw, yRaw, widthRaw, heightRaw] = output.trim().split(TMUX_FIELD_SEPARATOR);
             const x = Number.parseInt(xRaw ?? "", 10);
             const y = Number.parseInt(yRaw ?? "", 10);
@@ -855,8 +1056,10 @@ export class TmuxAdapter {
      * scopes are never crossed (guard b2).
      */
     async setSessionOption(sessionName, key, value) {
+        // set/show-option take a target-pane even when the option is session-scoped.
+        const exact = exactTarget(sessionName, "pane");
         try {
-            await this.run(["tmux", "set-option", "-t", sessionName, key, value], `tmux set-option -t ${shellQuote(sessionName)} ${shellQuote(key)} ${shellQuote(value)}`);
+            await this.run(["tmux", "set-option", "-t", exact, key, value], `tmux set-option -t ${shellQuote(exact)} ${shellQuote(key)} ${shellQuote(value)}`);
             return { ok: true };
         }
         catch (err) {
@@ -896,8 +1099,10 @@ export class TmuxAdapter {
     }
     /** Get a session-scoped user option value. Returns null if not set or error. */
     async getSessionOption(sessionName, key) {
+        // set/show-option take a target-pane even when the option is session-scoped.
+        const exact = exactTarget(sessionName, "pane");
         try {
-            const output = await this.run(["tmux", "show-option", "-v", "-t", sessionName, key], `tmux show-option -v -t ${shellQuote(sessionName)} ${shellQuote(key)}`);
+            const output = await this.run(["tmux", "show-option", "-v", "-t", exact, key], `tmux show-option -v -t ${shellQuote(exact)} ${shellQuote(key)}`);
             return output.trim() || null;
         }
         catch {
@@ -925,9 +1130,59 @@ export class TmuxAdapter {
      *   - `null` when the target is missing OR the value is unparseable
      *     (consumers treat null as "no signal", distinct from "idle").
      */
+    /** Every session's current-window `#{window_activity}` in ONE tmux call, keyed by session name: the same value
+     *  `readPaneLastActivity(<session name>)` reads (display-message -t <session> resolves to the session's current
+     *  window). Only well-formed timestamps are included, so a missing key means "read it the per-target way". Null when
+     *  tmux can't be read at all. The session name is the LAST field, so a separator inside it stays intact. */
+    async readAllSessionWindowActivity() {
+        try {
+            const format = ["#{window_active}", "#{window_activity}", "#{session_name}"].join(TMUX_FIELD_SEPARATOR);
+            const output = await this.run(["tmux", "list-windows", "-a", "-F", format], `tmux list-windows -a -F '${format}'`);
+            const out = new Map();
+            for (const line of output.split("\n")) {
+                const first = line.indexOf(TMUX_FIELD_SEPARATOR), second = line.indexOf(TMUX_FIELD_SEPARATOR, first + 1);
+                if (first < 0 || second < 0)
+                    continue;
+                const active = line.slice(0, first), activity = line.slice(first + 1, second).trim(), session = line.slice(second + 1);
+                if (!session || active !== "1" || !/^\d+$/.test(activity))
+                    continue;
+                const n = Number(activity);
+                if (Number.isFinite(n) && n > 0)
+                    out.set(session, n);
+            }
+            return out;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Every pane's pid and current command in ONE tmux call, keyed by pane id (%N): the values `getPanePid` /
+     *  `getPaneCommand` read per pane. Panes without a valid pid are left out (read those per pane). Null when tmux can't
+     *  be read at all. The command is the LAST field, so a separator inside it stays intact. */
+    async readAllPaneProcesses() {
+        try {
+            const format = ["#{pane_id}", "#{pane_pid}", "#{pane_current_command}"].join(TMUX_FIELD_SEPARATOR);
+            const output = await this.run(["tmux", "list-panes", "-a", "-F", format], `tmux list-panes -a -F '${format}'`);
+            const out = new Map();
+            for (const line of output.split("\n")) {
+                const first = line.indexOf(TMUX_FIELD_SEPARATOR), second = line.indexOf(TMUX_FIELD_SEPARATOR, first + 1);
+                if (first <= 0 || second < 0)
+                    continue;
+                const id = line.slice(0, first), pid = parseInt(line.slice(first + 1, second).trim(), 10);
+                if (!Number.isFinite(pid) || pid <= 0)
+                    continue;
+                out.set(id, { pid, command: line.slice(second + 1).trim() || null });
+            }
+            return out;
+        }
+        catch {
+            return null;
+        }
+    }
     async readPaneLastActivity(paneId) {
+        const exact = exactTarget(paneId, "pane");
         try {
-            const output = await this.run(["tmux", "display-message", "-p", "-t", paneId, "#{window_activity}"], `tmux display-message -p -t ${shellQuote(paneId)} '#{window_activity}'`);
+            const output = await this.run(["tmux", "display-message", "-p", "-t", exact, "#{window_activity}"], `tmux display-message -p -t ${shellQuote(exact)} '#{window_activity}'`);
             const trimmed = output.trim();
             if (!/^\d+$/.test(trimmed))
                 return null;
@@ -966,8 +1221,9 @@ export class TmuxAdapter {
      * kills, or rebinds a session and never touches OpenRig routing/identity.
      */
     async switchClient(client, target) {
+        const exact = exactTarget(target, "session");
         try {
-            await this.run(["tmux", "switch-client", "-c", client, "-t", target], `tmux switch-client -c ${shellQuote(client)} -t ${shellQuote(target)}`);
+            await this.run(["tmux", "switch-client", "-c", client, "-t", exact], `tmux switch-client -c ${shellQuote(client)} -t ${shellQuote(exact)}`);
             return { ok: true };
         }
         catch (err) {