@zq-silk/yui 0.2.0 → 0.4.2

package/dist/tmux/tmuxManager.js

@@ -1,10 +1,14 @@
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { resolve } from "node:path";
 import { runtimeError } from "../errors/cliError.js";
+import { usableInteractiveTerminal } from "../output/terminal.js";
 import { handoffTerminal } from "./terminalHandoff.js";
 import { CommandExecutionError } from "./commandExecutor.js";
 const DEFAULT_READINESS_TIMEOUT_MS = 15_000;
 const DEFAULT_READINESS_POLL_MS = 50;
+const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
+const DEFAULT_HISTORY_LIMIT = 100_000;
+const PANE_STATE_MARKER = "__YUI_PANE_STATE__";
 export class TmuxReadinessTimeoutError extends Error {
     taskId;
     roleName;
@@ -32,12 +36,17 @@ export class TmuxManager {
     tmuxBin;
     executor;
     #yuiHome;
+    #serverName;
+    #onRoleTargetRecorded;
     #terminalInput;
+    #terminalType;
     #closeInteractiveInput;
     #readinessTimeoutMs;
     #readinessPollMs;
     #initialColumns;
     #initialRows;
+    #historyLimit;
+    #onWarning;
     #now;
     #sleep;
     constructor(tmuxBin, executor, yuiHomeOrOptions = {}) {
@@ -47,12 +56,17 @@ export class TmuxManager {
             ? { yuiHome: yuiHomeOrOptions }
             : yuiHomeOrOptions;
         this.#yuiHome = options.yuiHome ?? process.env.YUI_HOME ?? process.cwd();
+        this.#serverName = yuiTmuxServerName(this.#yuiHome);
+        this.#onRoleTargetRecorded = options.onRoleTargetRecorded;
         this.#terminalInput = options.terminalInput ?? process.stdin;
+        this.#terminalType = usableInteractiveTerminal(options.terminalType ?? process.env.TERM);
         this.#closeInteractiveInput = options.closeInteractiveInput ?? (() => { });
         this.#readinessTimeoutMs = positiveInteger(options.readinessTimeoutMs, DEFAULT_READINESS_TIMEOUT_MS, "readiness timeout");
         this.#readinessPollMs = positiveInteger(options.readinessPollMs, DEFAULT_READINESS_POLL_MS, "readiness poll interval");
         this.#initialColumns = positiveInteger(options.initialColumns, 120, "initial tmux columns");
         this.#initialRows = positiveInteger(options.initialRows, 40, "initial tmux rows");
+        this.#historyLimit = positiveInteger(options.historyLimit, DEFAULT_HISTORY_LIMIT, "tmux history limit");
+        this.#onWarning = options.onWarning;
         this.#now = options.now ?? Date.now;
         this.#sleep = options.sleep ?? blockingSleep;
     }
@@ -61,29 +75,83 @@ export class TmuxManager {
         this.attachRole(taskId, role.name);
     }
     ensureRoleWindow(taskId, role, launch) {
-        if (this.windowNames(taskId).includes(role.name))
+        if (this.windowNames(taskId).includes(role.name)) {
+            this.recordRoleTarget(taskId, role.name);
+            this.configureServerHistory();
             return false;
+        }
         if (launch === undefined) {
             throw runtimeError(`Agent launch plan is required to create Role window: ${role.name}.`);
         }
+        // Persist the exact target before any tmux mutation. If the recorder
+        // cannot prove the current ephemeral identity/token, do not create a
+        // pane that a later reaper could not fence.
+        this.recordRoleTarget(taskId, role.name);
         if (!this.hasSession(taskId)) {
-            this.executor.run(this.tmuxBin, [
+            this.run([
+                "start-server",
+                ";",
+                "set-option", "-g", "history-limit", String(this.#historyLimit),
+                ";",
                 "new-session", "-d",
                 "-x", String(this.#initialColumns),
                 "-y", String(this.#initialRows),
                 "-s", this.sessionName(taskId),
                 "-n", role.name,
-                "-c", safeValue(role.workspace, "Role workspace"),
+                "-c", safeValue(role.cwd ?? role.workspace, "Role cwd"),
                 "--",
                 ...launchCommand(launch)
             ]);
         }
         else {
-            this.executor.run(this.tmuxBin, [
+            this.configureServerHistory();
+            this.run([
                 "new-window",
                 "-t", this.sessionName(taskId),
                 "-n", role.name,
-                "-c", safeValue(role.workspace, "Role workspace"),
+                "-c", safeValue(role.cwd ?? role.workspace, "Role cwd"),
+                "--",
+                ...launchCommand(launch)
+            ]);
+        }
+        return true;
+    }
+    async ensureRoleWindowAsync(taskId, role, launch) {
+        const snapshot = await this.sessionWindowNamesAsync(taskId);
+        if (snapshot.names.includes(role.name)) {
+            this.recordRoleTarget(taskId, role.name);
+            await this.configureServerHistoryAsync();
+            return false;
+        }
+        if (launch === undefined) {
+            throw runtimeError(`Agent launch plan is required to create Role window: ${role.name}.`);
+        }
+        // Keep the async launch ordering identical to the sync path: a recorder
+        // failure is a precondition failure, never a post-launch cleanup hint.
+        this.recordRoleTarget(taskId, role.name);
+        if (!snapshot.exists) {
+            await this.runAsync([
+                "start-server",
+                ";",
+                "set-option", "-g", "history-limit", String(this.#historyLimit),
+                ";",
+                "new-session", "-d",
+                "-x", String(this.#initialColumns),
+                "-y", String(this.#initialRows),
+                "-s", this.sessionName(taskId),
+                "-n", role.name,
+                "-c", safeValue(role.cwd ?? role.workspace, "Role cwd"),
+                "--",
+                ...launchCommand(launch)
+            ]);
+        }
+        else {
+            await this.configureServerHistoryAsync();
+            await this.runAsync([
+                "new-window",
+                "-t", this.sessionName(taskId),
+                "-n", role.name,
+                "-c", safeValue(role.cwd ?? role.workspace, "Role cwd"),
                 "--",
                 ...launchCommand(launch)
             ]);
@@ -91,13 +159,123 @@ export class TmuxManager {
         return true;
     }
     attachRole(taskId, roleName) {
-        handoffTerminal(this.#terminalInput, this.#closeInteractiveInput);
-        this.executor.run(this.tmuxBin, [
-            "attach-session", "-t", this.target(taskId, roleName)
-        ], { inheritStdio: true });
+        let historyNotice;
+        if (this.#onWarning !== undefined) {
+            const history = this.inspectRoleHistory(taskId, roleName);
+            if (history.limited) {
+                historyNotice = roleHistoryWarning(history);
+                this.#onWarning(historyNotice);
+            }
+        }
+        const readOnly = this.hasWritableClient(taskId);
+        const clientSession = this.createInteractiveClientSession(taskId, historyNotice);
+        try {
+            handoffTerminal(this.#terminalInput, this.#closeInteractiveInput);
+            this.run([
+                "attach-session",
+                ...(readOnly ? ["-r"] : []),
+                "-t", `${clientSession}:${safeValue(roleName, "Role name")}`
+            ], {
+                inheritStdio: true,
+                environment: { TERM: this.#terminalType }
+            });
+        }
+        finally {
+            this.destroyInteractiveClientSession(clientSession);
+        }
+    }
+    /**
+     * A grouped session shares the Agent windows while keeping the selected
+     * window and terminal options local to this one human client.
+     */
+    createInteractiveClientSession(taskId, attachedNotice) {
+        const clientSession = `yui-client-${randomBytes(12).toString("hex")}`;
+        this.run([
+            "new-session", "-d",
+            "-t", this.sessionName(taskId),
+            "-s", clientSession
+        ]);
+        try {
+            // Let tmux use the outer terminal's native alternate screen. Mouse mode
+            // keeps scrollback inside the long-lived Role pane instead of mixing it
+            // with terminal output that predates this attach.
+            this.run(["set-option", "-t", clientSession, "status", "off"]);
+            this.run(["set-option", "-t", clientSession, "mouse", "on"]);
+            this.run([
+                "set-hook", "-t", clientSession, "client-detached",
+                `kill-session -t ${clientSession}`
+            ]);
+            if (attachedNotice !== undefined) {
+                this.run([
+                    "set-hook", "-t", clientSession, "client-attached",
+                    `display-message -d 10000 ${tmuxWord(attachedNotice)}`
+                ]);
+            }
+            return clientSession;
+        }
+        catch (error) {
+            this.destroyInteractiveClientSession(clientSession);
+            throw error;
+        }
+    }
+    destroyInteractiveClientSession(clientSession) {
+        try {
+            this.run(["kill-session", "-t", safeValue(clientSession, "tmux client session")]);
+        }
+        catch (error) {
+            if (!isExplicitlyAbsentTmuxSession(error))
+                throw error;
+        }
+    }
+    inspectRoleHistory(taskId, roleName) {
+        const output = this.run([
+            "display-message", "-p",
+            "-t", this.target(taskId, roleName),
+            "#{history_limit}"
+        ]).trim();
+        const actual = Number(output);
+        if (!Number.isSafeInteger(actual) || actual <= 0) {
+            throw runtimeError(`Tmux returned an invalid history limit for ${taskId}/${roleName}.`);
+        }
+        return {
+            actual,
+            configured: this.#historyLimit,
+            limited: actual < this.#historyLimit
+        };
+    }
+    /** Multiple viewers are safe, but only the first attached human may type. */
+    hasWritableClient(taskId) {
+        const formatSeparator = "\u001f";
+        const encodedSeparator = "\\037";
+        const taskSession = this.sessionName(taskId);
+        try {
+            const clients = this.run([
+                "list-clients",
+                "-F",
+                `#{session_name}${formatSeparator}#{session_group}${formatSeparator}#{client_readonly}`
+            ]);
+            return clients.split("\n").some((line) => {
+                if (line.length === 0)
+                    return false;
+                const separator = line.includes(encodedSeparator) ? encodedSeparator : formatSeparator;
+                const [sessionName, sessionGroup, readOnly, ...extra] = line.split(separator);
+                if (sessionName === undefined
+                    || sessionGroup === undefined
+                    || readOnly === undefined
+                    || extra.length > 0) {
+                    throw runtimeError("Tmux returned an invalid client state row.");
+                }
+                return (sessionName === taskSession || sessionGroup === taskSession) && readOnly === "0";
+            });
+        }
+        catch (error) {
+            if (isExplicitlyAbsentTmuxSession(error))
+                return false;
+            throw error;
+        }
     }
     captureRole(taskId, roleName, lines = 80) {
-        return this.executor.run(this.tmuxBin, [
+        return this.run([
             "capture-pane", "-p", "-t", this.target(taskId, roleName), "-S", `-${lines}`
         ]);
     }
@@ -131,7 +309,7 @@ export class TmuxManager {
     }
     inspectPane(taskId, roleName) {
         const target = this.target(taskId, roleName);
-        const output = this.executor.run(this.tmuxBin, [
+        const output = this.run([
             "display-message", "-p", "-t", target,
             "#{pane_dead}|#{pane_pid}|#{pane_current_command}"
         ]).trim();
@@ -144,27 +322,84 @@ export class TmuxManager {
         const pidText = output.slice(separator + 1, secondSeparator);
         const currentCommand = output.slice(secondSeparator + 1);
         const pid = Number(pidText);
-        const content = this.executor.run(this.tmuxBin, [
-            "capture-pane", "-p", "-t", target, "-S", "-40"
-        ]);
         return {
             taskId,
             roleName,
             target,
             dead: dead === "1",
             ...(Number.isSafeInteger(pid) && pid > 0 ? { pid } : {}),
-            currentCommand,
-            content
+            currentCommand
+        };
+    }
+    async inspectPaneAsync(taskId, roleName) {
+        return (await this.inspectDeliveryPaneAsync(taskId, roleName)).pane;
+    }
+    /** Reads receipt and pane identity through one tmux client without terminal output. */
+    async inspectDeliveryPaneAsync(taskId, roleName, receiptId) {
+        const target = this.target(taskId, roleName);
+        const receiptOption = receiptId === undefined
+            ? undefined
+            : deliveryReceiptOption(receiptId);
+        const receiptFormat = receiptOption === undefined ? "" : `#{${receiptOption}}`;
+        const output = await this.runAsync([
+            "display-message", "-p", "-t", target,
+            [
+                PANE_STATE_MARKER,
+                "#{pane_dead}",
+                "#{pane_pid}",
+                "#{cursor_x}",
+                "#{cursor_y}",
+                "#{history_size}",
+                "#{pane_current_command}",
+                receiptFormat
+            ].join("|")
+        ]);
+        const state = output.trimEnd().split("|");
+        if (state.length !== 8 || state[0] !== PANE_STATE_MARKER) {
+            throw runtimeError(`Tmux returned an invalid pane state for ${roleName}.`);
+        }
+        const [, deadText, pidText, cursorXText, cursorYText, historySizeText, currentCommand, receiptText] = state;
+        if ((deadText !== "0" && deadText !== "1")
+            || currentCommand === undefined
+            || receiptText === undefined
+            || (receiptText !== "" && receiptText !== "1")) {
+            throw runtimeError(`Tmux returned an invalid pane state for ${roleName}.`);
+        }
+        const pid = positiveNumber(pidText);
+        const cursorX = nonNegativeNumber(cursorXText);
+        const cursorY = nonNegativeNumber(cursorYText);
+        const historySize = nonNegativeNumber(historySizeText);
+        if (cursorX === undefined || cursorY === undefined || historySize === undefined) {
+            throw runtimeError(`Tmux returned an invalid pane state for ${roleName}.`);
+        }
+        return {
+            pane: {
+                taskId,
+                roleName,
+                target,
+                dead: deadText === "1",
+                ...(pid === undefined ? {} : { pid }),
+                currentCommand,
+                cursorX,
+                cursorY,
+                historySize
+            },
+            receiptPresent: receiptText === "1"
         };
     }
     /** Reads every Role pane in one tmux call without capturing terminal output. */
     inspectTaskRolePanes(taskId) {
-        const separator = "\u001f";
+        const formatSeparator = "\u001f";
+        // tmux escapes control bytes in formatted output using backslash-octal
+        // notation, so an argv separator of 0x1f is returned as the four
+        // printable characters "\\037". Accept the raw form as well for test
+        // executors and older implementations that do not escape it.
+        const encodedSeparator = "\\037";
         let output;
         try {
-            output = this.executor.run(this.tmuxBin, [
+            output = this.run([
                 "list-panes", "-s", "-t", this.sessionName(taskId), "-F",
-                `#{window_name}${separator}#{pane_dead}${separator}#{pane_pid}${separator}#{pane_current_command}`
+                `#{window_name}${formatSeparator}#{pane_dead}${formatSeparator}#{pane_pid}${formatSeparator}#{pane_current_command}`
             ]);
         }
         catch (error) {
@@ -175,6 +410,7 @@ export class TmuxManager {
         return output.split("\n").flatMap((line) => {
             if (line.length === 0)
                 return [];
+            const separator = line.includes(encodedSeparator) ? encodedSeparator : formatSeparator;
             const [roleName, deadText, pidText, currentCommand, ...extra] = line.split(separator);
             if (roleName === undefined
                 || deadText === undefined
@@ -195,6 +431,88 @@ export class TmuxManager {
                 }];
         });
     }
+    /**
+     * Reads the Role pane inventory for this YUI_HOME in one tmux server call.
+     * Terminal contents are deliberately excluded; recovery can inspect process
+     * identity later for the small set of suspicious panes.
+     */
+    inspectRolePaneInventory() {
+        const formatSeparator = "\u001f";
+        const encodedSeparator = "\\037";
+        const sessionPrefix = yuiTmuxSessionPrefix(this.#yuiHome);
+        let output;
+        try {
+            output = this.run([
+                "list-panes", "-a", "-F",
+                [
+                    "#{session_name}",
+                    "#{window_name}",
+                    "#{pane_dead}",
+                    "#{pane_pid}",
+                    "#{pane_current_command}"
+                ].join(formatSeparator)
+            ]);
+        }
+        catch (error) {
+            if (isExplicitlyAbsentTmuxSession(error))
+                return [];
+            throw error;
+        }
+        return output.split("\n").flatMap((line) => {
+            if (line.length === 0)
+                return [];
+            const separator = line.includes(encodedSeparator) ? encodedSeparator : formatSeparator;
+            const [sessionName, roleName, deadText, pidText, currentCommand, ...extra] = line.split(separator);
+            if (sessionName === undefined
+                || roleName === undefined
+                || deadText === undefined
+                || pidText === undefined
+                || currentCommand === undefined
+                || extra.length > 0
+                || (deadText !== "0" && deadText !== "1")) {
+                throw runtimeError("Tmux returned an invalid Role pane inventory row.");
+            }
+            if (!sessionName.startsWith(sessionPrefix))
+                return [];
+            const taskId = sessionName.slice(sessionPrefix.length);
+            if (taskId.length === 0 || roleName.length === 0) {
+                throw runtimeError("Tmux returned an invalid Yui Role pane identity.");
+            }
+            const pid = Number(pidText);
+            return [{
+                    taskId,
+                    roleName,
+                    target: this.target(taskId, roleName),
+                    dead: deadText === "1",
+                    ...(Number.isSafeInteger(pid) && pid > 0 ? { pid } : {}),
+                    currentCommand
+                }];
+        });
+    }
+    async inspectRolePaneInventoryAsync() {
+        const formatSeparator = "\u001f";
+        const encodedSeparator = "\\037";
+        const sessionPrefix = yuiTmuxSessionPrefix(this.#yuiHome);
+        let output;
+        try {
+            output = await this.runAsync([
+                "list-panes", "-a", "-F",
+                [
+                    "#{session_name}",
+                    "#{window_name}",
+                    "#{pane_dead}",
+                    "#{pane_pid}",
+                    "#{pane_current_command}"
+                ].join(formatSeparator)
+            ]);
+        }
+        catch (error) {
+            if (isExplicitlyAbsentTmuxSession(error))
+                return [];
+            throw error;
+        }
+        return parseRolePaneInventory(output, formatSeparator, encodedSeparator, sessionPrefix, (taskId, roleName) => this.target(taskId, roleName));
+    }
     /**
      * The receipt test, receipt write, literal input and Enter all run through a
      * single tmux server command queue. Retrying the same receipt cannot type the
@@ -207,8 +525,8 @@ export class TmuxManager {
         safeValue(receiptId, "tmux delivery receipt id");
         safeValue(input, "tmux input");
         // A delivered run is normally still busy on the next Controller scan. The
-        // pane receipt is authoritative for that retry, so do not wait for the
-        // composer merely to discover that the input was already sent.
+        // pane receipt is authoritative for that retry, so return before another
+        // process-readiness check when the input was already sent.
         if (this.hasDeliveryReceipt(taskId, roleName, receiptId)) {
             return "already-sent";
         }
@@ -224,24 +542,111 @@ export class TmuxManager {
         const target = this.target(taskId, roleName);
         const digest = createHash("sha256").update(receiptId).digest("hex");
         const option = `@yui_delivery_${digest}`;
+        const buffer = `yui_delivery_${digest}`;
         const sentMarker = `__YUI_DELIVERY_SENT_${digest}__`;
         const presentMarker = `__YUI_DELIVERY_PRESENT_${digest}__`;
+        const alreadyApplied = [
+            `delete-buffer -b ${buffer}`,
+            `display-message -p ${presentMarker}`
+        ].join(" ; ");
         const apply = [
+            // One bracketed paste preserves literal and multiline input without
+            // expanding it into a long sequence of tmux key events.
+            `paste-buffer -dpr -b ${buffer} -t ${tmuxWord(target)}`,
+            // Full-screen clients can finish handling the bracketed paste after tmux
+            // has already queued the next key. Let the client settle before Enter so
+            // the receipt proves that a submission key followed the completed paste.
+            `run-shell ${tmuxWord("sleep 0.05")}`,
+            `send-keys -t ${tmuxWord(target)} Enter`,
+            // A receipt is proof that Enter was accepted, never merely that an
+            // attempt began.
             `set-option -w -t ${tmuxWord(target)} ${option} 1`,
-            `send-keys -l -t ${tmuxWord(target)} -- ${tmuxWord(input)}`,
+            `display-message -p ${sentMarker}`
+        ].join(" ; ");
+        try {
+            const output = this.run([
+                "set-buffer", "-b", buffer, "--", input,
+                ";",
+                "if-shell", "-t", target, "-F", `#{==:#{${option}},1}`,
+                alreadyApplied,
+                apply
+            ]).trim();
+            if (output === sentMarker)
+                return "sent";
+            if (output === presentMarker)
+                return "already-sent";
+            throw runtimeError(`Tmux did not confirm delivery receipt ${receiptId}.`);
+        }
+        catch (error) {
+            try {
+                this.run(["delete-buffer", "-b", buffer]);
+            }
+            catch {
+                // The apply branch normally consumed it with paste-buffer -d.
+            }
+            throw error;
+        }
+    }
+    async sendReadyRoleInputOnceAsync(taskId, roleName, receiptId, input, expectedPane) {
+        safeValue(receiptId, "tmux delivery receipt id");
+        safeValue(input, "tmux input");
+        const target = this.target(taskId, roleName);
+        const digest = createHash("sha256").update(receiptId).digest("hex");
+        const option = deliveryReceiptOption(receiptId);
+        const buffer = `yui_delivery_${digest}`;
+        const sentMarker = `__YUI_DELIVERY_SENT_${digest}__`;
+        const presentMarker = `__YUI_DELIVERY_PRESENT_${digest}__`;
+        const notReadyMarker = `__YUI_DELIVERY_NOT_READY_${digest}__`;
+        const alreadyApplied = [
+            `delete-buffer -b ${buffer}`,
+            `display-message -p ${presentMarker}`
+        ].join(" ; ");
+        const apply = [
+            `paste-buffer -dpr -b ${buffer} -t ${tmuxWord(target)}`,
+            `run-shell ${tmuxWord("sleep 0.05")}`,
             `send-keys -t ${tmuxWord(target)} Enter`,
+            `set-option -w -t ${tmuxWord(target)} ${option} 1`,
             `display-message -p ${sentMarker}`
         ].join(" ; ");
-        const output = this.executor.run(this.tmuxBin, [
-            "if-shell", "-t", target, "-F", `#{==:#{${option}},1}`,
-            `display-message -p ${presentMarker}`,
-            apply
-        ]).trim();
-        if (output === sentMarker)
-            return "sent";
-        if (output === presentMarker)
-            return "already-sent";
-        throw runtimeError(`Tmux did not confirm delivery receipt ${receiptId}.`);
+        const guard = expectedPane === undefined ? undefined : deliveryPaneGuard(expectedPane);
+        const applyIfUnchanged = guard === undefined
+            ? apply
+            : [
+                "if-shell -t",
+                tmuxWord(target),
+                "-F",
+                tmuxWord(guard),
+                tmuxWord(apply),
+                tmuxWord([
+                    `delete-buffer -b ${buffer}`,
+                    `display-message -p ${notReadyMarker}`
+                ].join(" ; "))
+            ].join(" ");
+        try {
+            const output = (await this.runAsync([
+                "set-buffer", "-b", buffer, "--", input,
+                ";",
+                "if-shell", "-t", target, "-F", `#{==:#{${option}},1}`,
+                alreadyApplied,
+                applyIfUnchanged
+            ])).trim();
+            if (output === sentMarker)
+                return "sent";
+            if (output === presentMarker)
+                return "already-sent";
+            if (output === notReadyMarker)
+                return "not-ready";
+            throw runtimeError(`Tmux did not confirm delivery receipt ${receiptId}.`);
+        }
+        catch (error) {
+            try {
+                await this.runAsync(["delete-buffer", "-b", buffer]);
+            }
+            catch {
+                // The apply branch normally consumed it with paste-buffer -d.
+            }
+            throw error;
+        }
     }
     sendRoleInputOnceIfReady(taskId, roleName, receiptId, input, readinessProbe) {
         if (readinessProbe === undefined) {
@@ -254,16 +659,42 @@ export class TmuxManager {
             return "not-ready";
         return this.sendReadyRoleInputOnce(taskId, roleName, receiptId, input);
     }
+    async sendRoleInputOnceIfReadyAsync(taskId, roleName, receiptId, input, readinessProbe) {
+        if (readinessProbe === undefined) {
+            throw new TmuxReadinessProbeRequiredError();
+        }
+        let inspected;
+        try {
+            inspected = await this.inspectDeliveryPaneAsync(taskId, roleName, receiptId);
+        }
+        catch (error) {
+            if (isExplicitlyAbsentTmuxSession(error))
+                return "unavailable";
+            throw error;
+        }
+        if (inspected.receiptPresent)
+            return "already-sent";
+        if (!readinessProbe(inspected.pane))
+            return "not-ready";
+        return this.sendReadyRoleInputOnceAsync(taskId, roleName, receiptId, input, inspected.pane);
+    }
     hasDeliveryReceipt(taskId, roleName, receiptId) {
         safeValue(receiptId, "tmux delivery receipt id");
         const digest = createHash("sha256").update(receiptId).digest("hex");
         const option = `@yui_delivery_${digest}`;
-        return this.executor.run(this.tmuxBin, [
+        return this.run([
             "show-options", "-wqv", "-t", this.target(taskId, roleName), option
         ]).trim() === "1";
     }
+    async hasDeliveryReceiptAsync(taskId, roleName, receiptId) {
+        safeValue(receiptId, "tmux delivery receipt id");
+        const option = deliveryReceiptOption(receiptId);
+        return (await this.runAsync([
+            "show-options", "-wqv", "-t", this.target(taskId, roleName), option
+        ])).trim() === "1";
+    }
     detachRole(taskId) {
-        this.executor.run(this.tmuxBin, ["detach-client", "-s", this.sessionName(taskId)]);
+        this.run(["detach-client", "-s", this.sessionName(taskId)]);
     }
     restartRole(taskId, role, launch) {
         try {
@@ -288,26 +719,70 @@ export class TmuxManager {
             return "exited";
         return this.windowNames(taskId).includes(roleName) ? "running" : "exited";
     }
+    async probeRoleStatusAsync(taskId, roleName) {
+        const snapshot = await this.sessionWindowNamesAsync(taskId);
+        return snapshot.names.includes(roleName) ? "running" : "exited";
+    }
     stopTask(taskId) {
-        if (!this.hasSession(taskId))
+        const taskSession = this.sessionName(taskId);
+        const sessions = this.taskSessionGroupNames(taskId);
+        if (sessions.length === 0 && !this.hasSession(taskId))
             return false;
-        this.executor.run(this.tmuxBin, ["kill-session", "-t", this.sessionName(taskId)]);
+        this.recordTaskTargets(taskId);
+        for (const session of [...sessions.filter((name) => name !== taskSession), taskSession]) {
+            try {
+                this.run(["kill-session", "-t", session]);
+            }
+            catch (error) {
+                if (!isExplicitlyAbsentTmuxSession(error))
+                    throw error;
+            }
+        }
+        return true;
+    }
+    async stopTaskAsync(taskId) {
+        const taskSession = this.sessionName(taskId);
+        const sessions = await this.taskSessionGroupNamesAsync(taskId);
+        if (sessions.length === 0 && !(await this.hasSessionAsync(taskId)))
+            return false;
+        await this.recordTaskTargetsAsync(taskId);
+        for (const session of [...sessions.filter((name) => name !== taskSession), taskSession]) {
+            try {
+                await this.runAsync(["kill-session", "-t", session]);
+            }
+            catch (error) {
+                if (!isExplicitlyAbsentTmuxSession(error))
+                    throw error;
+            }
+        }
         return true;
     }
     stopRole(taskId, roleName) {
-        this.executor.run(this.tmuxBin, ["send-keys", "-t", this.target(taskId, roleName), "C-c"]);
+        this.recordRoleTarget(taskId, roleName);
+        this.run(["send-keys", "-t", this.target(taskId, roleName), "C-c"]);
     }
     killRole(taskId, roleName) {
-        this.executor.run(this.tmuxBin, ["kill-window", "-t", this.target(taskId, roleName)]);
+        this.recordRoleTarget(taskId, roleName);
+        this.run(["kill-window", "-t", this.target(taskId, roleName)]);
+    }
+    async killRoleAsync(taskId, roleName) {
+        this.recordRoleTarget(taskId, roleName);
+        await this.runAsync(["kill-window", "-t", this.target(taskId, roleName)]);
     }
     renameRole(taskId, oldRoleName, newRoleName) {
-        this.executor.run(this.tmuxBin, [
-            "rename-window", "-t", this.target(taskId, oldRoleName), safeValue(newRoleName, "Role name")
+        const target = this.target(taskId, oldRoleName);
+        const nextRoleName = safeValue(newRoleName, "Role name");
+        // Retain the new exact fence even if tmux later rejects the rename. The
+        // stale fence is conservative and lets a later bounded retry revalidate
+        // the pane instead of guessing or dropping ownership evidence.
+        this.recordRoleTarget(taskId, newRoleName);
+        this.run([
+            "rename-window", "-t", target, nextRoleName
         ]);
     }
     hasSession(taskId) {
         try {
-            this.executor.run(this.tmuxBin, ["has-session", "-t", this.sessionName(taskId)]);
+            this.run(["has-session", "-t", this.sessionName(taskId)]);
             return true;
         }
         catch (error) {
@@ -320,19 +795,181 @@ export class TmuxManager {
             throw error;
         }
     }
+    async hasSessionAsync(taskId) {
+        try {
+            await this.runAsync(["has-session", "-t", this.sessionName(taskId)]);
+            return true;
+        }
+        catch (error) {
+            if (isExplicitlyAbsentTmuxSession(error))
+                return false;
+            if (!(error instanceof CommandExecutionError))
+                return false;
+            throw error;
+        }
+    }
     windowNames(taskId) {
         if (!this.hasSession(taskId))
             return [];
-        return this.executor.run(this.tmuxBin, [
-            "list-windows", "-t", this.sessionName(taskId), "-F", "#{window_name}"
-        ]).split("\n").map((name) => name.trim()).filter(Boolean);
+        try {
+            return this.run([
+                "list-windows", "-t", this.sessionName(taskId), "-F", "#{window_name}"
+            ]).split("\n").map((name) => name.trim()).filter(Boolean);
+        }
+        catch (error) {
+            if (isUnavailableTmuxStatus(error))
+                return [];
+            throw error;
+        }
+    }
+    async sessionWindowNamesAsync(taskId) {
+        try {
+            const names = (await this.runAsync([
+                "list-windows", "-t", this.sessionName(taskId), "-F", "#{window_name}"
+            ])).split("\n").map((name) => name.trim()).filter(Boolean);
+            return { exists: true, names };
+        }
+        catch (error) {
+            if (isUnavailableTmuxStatus(error))
+                return { exists: false, names: [] };
+            throw error;
+        }
     }
     sessionName(taskId) {
         return yuiTmuxSessionName(this.#yuiHome, taskId);
     }
+    taskSessionGroupNames(taskId) {
+        const formatSeparator = "\u001f";
+        const encodedSeparator = "\\037";
+        const taskSession = this.sessionName(taskId);
+        let output;
+        try {
+            output = this.run([
+                "list-sessions", "-F",
+                `#{session_name}${formatSeparator}#{session_group}`
+            ]);
+        }
+        catch (error) {
+            if (isExplicitlyAbsentTmuxSession(error))
+                return [];
+            throw error;
+        }
+        return parseTaskSessionGroupNames(output, taskSession, formatSeparator, encodedSeparator);
+    }
+    async taskSessionGroupNamesAsync(taskId) {
+        const formatSeparator = "\u001f";
+        const encodedSeparator = "\\037";
+        const taskSession = this.sessionName(taskId);
+        let output;
+        try {
+            output = await this.runAsync([
+                "list-sessions", "-F",
+                `#{session_name}${formatSeparator}#{session_group}`
+            ]);
+        }
+        catch (error) {
+            if (isExplicitlyAbsentTmuxSession(error))
+                return [];
+            throw error;
+        }
+        return parseTaskSessionGroupNames(output, taskSession, formatSeparator, encodedSeparator);
+    }
     target(taskId, roleName) {
         return yuiTmuxTarget(this.#yuiHome, taskId, roleName);
     }
+    recordRoleTarget(taskId, roleName) {
+        this.#onRoleTargetRecorded?.(this.target(taskId, roleName));
+    }
+    recordTaskTargets(taskId) {
+        if (this.#onRoleTargetRecorded === undefined)
+            return;
+        for (const pane of this.inspectTaskRolePanes(taskId)) {
+            this.#onRoleTargetRecorded(pane.target);
+        }
+    }
+    async recordTaskTargetsAsync(taskId) {
+        if (this.#onRoleTargetRecorded === undefined)
+            return;
+        for (const pane of await this.inspectRolePaneInventoryAsync()) {
+            if (pane.taskId === taskId)
+                this.#onRoleTargetRecorded(pane.target);
+        }
+    }
+    configureServerHistory() {
+        this.run([
+            "start-server",
+            ";",
+            "set-option", "-g", "history-limit", String(this.#historyLimit)
+        ]);
+    }
+    async configureServerHistoryAsync() {
+        await this.runAsync([
+            "start-server",
+            ";",
+            "set-option", "-g", "history-limit", String(this.#historyLimit)
+        ]);
+    }
+    /** Every operation is pinned to the server derived from this YUI_HOME. */
+    run(args, options) {
+        const bounded = options?.inheritStdio === true
+            ? options
+            : { ...options, timeoutMs: options?.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS };
+        return this.executor.run(this.tmuxBin, ["-L", this.#serverName, ...args], bounded);
+    }
+    runAsync(args, options) {
+        const bounded = {
+            ...options,
+            timeoutMs: options?.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS
+        };
+        if (this.executor.runAsync !== undefined) {
+            return this.executor.runAsync(this.tmuxBin, ["-L", this.#serverName, ...args], bounded);
+        }
+        return Promise.resolve().then(() => this.run(args, bounded));
+    }
+}
+function parseRolePaneInventory(output, formatSeparator, encodedSeparator, sessionPrefix, target) {
+    return output.split("\n").flatMap((line) => {
+        if (line.length === 0)
+            return [];
+        const separator = line.includes(encodedSeparator) ? encodedSeparator : formatSeparator;
+        const [sessionName, roleName, deadText, pidText, currentCommand, ...extra] = line.split(separator);
+        if (sessionName === undefined
+            || roleName === undefined
+            || deadText === undefined
+            || pidText === undefined
+            || currentCommand === undefined
+            || extra.length > 0
+            || (deadText !== "0" && deadText !== "1")) {
+            throw runtimeError("Tmux returned an invalid Role pane inventory row.");
+        }
+        if (!sessionName.startsWith(sessionPrefix))
+            return [];
+        const taskId = sessionName.slice(sessionPrefix.length);
+        if (taskId.length === 0 || roleName.length === 0) {
+            throw runtimeError("Tmux returned an invalid Yui Role pane identity.");
+        }
+        const pid = Number(pidText);
+        return [{
+                taskId,
+                roleName,
+                target: target(taskId, roleName),
+                dead: deadText === "1",
+                ...(Number.isSafeInteger(pid) && pid > 0 ? { pid } : {}),
+                currentCommand
+            }];
+    });
+}
+function parseTaskSessionGroupNames(output, taskSession, formatSeparator, encodedSeparator) {
+    return output.split("\n").flatMap((line) => {
+        if (line.length === 0)
+            return [];
+        const separator = line.includes(encodedSeparator) ? encodedSeparator : formatSeparator;
+        const [sessionName, sessionGroup, ...extra] = line.split(separator);
+        if (sessionName === undefined || sessionGroup === undefined || extra.length > 0) {
+            throw runtimeError("Tmux returned an invalid session group row.");
+        }
+        return sessionName === taskSession || sessionGroup === taskSession ? [sessionName] : [];
+    });
 }
 /** A small FIFO boundary for Controller scheduler passes. */
 export class TmuxDeliveryPump {
@@ -363,8 +1000,22 @@ export class TmuxDeliveryPump {
 }
 export function yuiTmuxSessionName(yuiHome, taskId) {
     const safeTaskId = safeValue(taskId, "Task id");
+    return `${yuiTmuxSessionPrefix(yuiHome)}${safeTaskId}`;
+}
+function yuiTmuxSessionPrefix(yuiHome) {
     const namespace = createHash("sha256").update(resolve(yuiHome)).digest("hex").slice(0, 12);
-    return `yui-${namespace}-${safeTaskId}`;
+    return `yui-${namespace}-`;
+}
+/**
+ * tmux socket labels are not paths. Keep the label in a deliberately narrow,
+ * fixed-size alphabet so it is safe as argv and leaves ample Unix socket-path
+ * headroom. resolve() makes equivalent absolute/relative YUI_HOME paths share
+ * one server without depending on whether the directory already exists.
+ */
+export function yuiTmuxServerName(yuiHome) {
+    const canonicalHome = resolve(safeValue(yuiHome, "YUI_HOME"));
+    const digest = createHash("sha256").update(canonicalHome).digest("hex").slice(0, 24);
+    return `yui-${digest}`;
 }
 export function yuiTmuxTarget(yuiHome, taskId, roleName) {
     return `${yuiTmuxSessionName(yuiHome, taskId)}:${safeValue(roleName, "Role name")}`;
@@ -378,9 +1029,10 @@ function launchCommand(launch) {
         }
         return `${key}=${safeValue(value, `Agent environment ${key}`)}`;
     });
-    return environment.length === 0
-        ? [command, ...args]
-        : ["env", ...environment, command, ...args];
+    // The launch plan is a complete environment assembled by the planner for
+    // this exact Agent. Never inherit the Controller or tmux server environment:
+    // it may contain credentials belonging to another configured Agent.
+    return ["env", "-i", "--", ...environment, command, ...args];
 }
 function isExplicitlyAbsentTmuxSession(error) {
     if (!(error instanceof CommandExecutionError))
@@ -388,9 +1040,49 @@ function isExplicitlyAbsentTmuxSession(error) {
     return /can't find (?:session|window|pane)|no server running|error connecting to .+ \(No such file or directory\)/i
         .test(error.stderr);
 }
+function isUnavailableTmuxStatus(error) {
+    return isExplicitlyAbsentTmuxSession(error)
+        || (error instanceof CommandExecutionError
+            && /server exited unexpectedly/i.test(error.stderr));
+}
 function tmuxWord(value) {
     return JSON.stringify(value);
 }
+function deliveryReceiptOption(receiptId) {
+    safeValue(receiptId, "tmux delivery receipt id");
+    return `@yui_delivery_${createHash("sha256").update(receiptId).digest("hex")}`;
+}
+function deliveryPaneGuard(pane) {
+    if (pane.dead
+        || pane.pid === undefined
+        || pane.cursorX === undefined
+        || pane.cursorY === undefined
+        || pane.historySize === undefined
+        || !/^[A-Za-z0-9_.+-]+$/.test(pane.currentCommand)) {
+        return "0";
+    }
+    const comparisons = [
+        "#{==:#{pane_dead},0}",
+        `#{==:#{pane_pid},${pane.pid}}`,
+        `#{==:#{cursor_x},${pane.cursorX}}`,
+        `#{==:#{cursor_y},${pane.cursorY}}`,
+        `#{==:#{history_size},${pane.historySize}}`,
+        `#{==:#{pane_current_command},${pane.currentCommand}}`
+    ];
+    return comparisons.slice(1).reduce((combined, comparison) => `#{&&:${combined},${comparison}}`, comparisons[0]);
+}
+function positiveNumber(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+function nonNegativeNumber(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
 function safeValue(value, label) {
     if (value.length === 0 || value.includes("\0")) {
         throw new TypeError(`${label} must be non-empty and contain no NUL bytes`);
@@ -404,6 +1096,12 @@ function positiveInteger(value, fallback, label) {
     }
     return resolved;
 }
+function roleHistoryWarning(history) {
+    return "This existing Role has a "
+        + `${history.actual.toLocaleString("en-US")}-line tmux history. `
+        + "Please exit and re-enter the Role to use "
+        + `${history.configured.toLocaleString("en-US")} lines.`;
+}
 function blockingSleep(milliseconds) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
 }