aicodeman 1.43.0 → 1.45.0

package/dist/tmux-manager.js

@@ -25,7 +25,7 @@ import { collectDescendants } from './proc-tree.js';
 import { execSync, exec, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 const execAsync = promisify(exec);
-import { existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, realpathSync } from 'node:fs';
 import { writeFile, rename } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { homedir } from 'node:os';
@@ -33,9 +33,10 @@ import { dataPath, DEFAULT_TMUX_SOCKET, CODEMAN_INSTANCE, SAFE_TMUX_SOCKET_PATTE
 import { getErrorMessage, DEFAULT_NICE_CONFIG, } from './types.js';
 import { getCli } from './config/cli-registry/registry.js';
 import { missingCliMessage, resolveCliBinDir } from './utils/cli-resolver.js';
-import { buildSpawnCommandFromRegistry, configSetenvValues, legacyConfigForMode, } from './session-cli-registry-bridge.js';
-import { resolveStatusLineCliCommand, readPlanUsageTelemetryEnabled, findEffectiveUserStatusLineCommand, } from './hooks-config.js';
-import { buildSshConnectionArgs, defaultRemoteCommandForMode, remoteLoginShellCommand, remoteSshTarget, remoteTmuxSessionAlive, } from './remote-hosts.js';
+import { buildSpawnCommandFromRegistry, configSetenvValues, launchGatePasses, legacyConfigForMode, } from './session-cli-registry-bridge.js';
+import { keepWarmOn } from './prompt-cache-keepwarm.js';
+import { resolveStatusLineCliCommand, readPlanUsageTelemetryEnabled, readKeepWarmSettings, findEffectiveUserStatusLineCommand, } from './hooks-config.js';
+import { buildSshConnectionArgs, defaultRemoteCommandForMode, remoteLoginShellCommand, remoteSshTarget, remoteTmuxSessionAlive, withRemoteTmuxPath, } from './remote-hosts.js';
 import { buildDockerBaseArgs, buildDockerCreateArgs, containerApiUrl, CONTAINER_HOME, defaultDockerCommandForMode, hostGatewayAlias, resolveDockerClaudeArtifacts, resolveDockerCredentialArtifacts, resolveDockerDaemonMountSource, } from './docker-hosts.js';
 import { wrapWithNice, SAFE_PATH_PATTERN, resolveLocalShell, loginShellArgs, waitForProcessesExit, } from './utils/index.js';
 import { decideReconnect, advanceBackoff, freshReconnectState, resetReconnectState, } from './remote-reconnect.js';
@@ -44,6 +45,7 @@ import { decideReconnect, advanceBackoff, freshReconnectState, resetReconnectSta
 // ============================================================================
 import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
 import { ensureDeepSeekStatusShim } from './deepseek-status-shim.js';
+import { NESTED_TMUX_PREFIX, nestedPrefixTableResetCommands, restrictTmuxPrefixTable } from './tmux-prefix-table.js';
 /** How long a cached process snapshot stays usable. */
 const PROC_SNAPSHOT_TTL_MS = 2000;
 /**
@@ -89,6 +91,22 @@ const DEFAULT_PANE_EXIT_INTERVAL_MS = 2000;
 const DEFAULT_REMOTE_RECONNECT_INTERVAL_MS = 5000;
 /** Stable cwd for tmux server/pane launch; actual session cwd is reached inside the pane. */
 const TMUX_LAUNCH_CWD = '/tmp';
+/**
+ * TMUX_LAUNCH_CWD in every spelling a pane can report it. tmux reads a pane's
+ * directory from its process, which comes back resolved (`/private/tmp` on
+ * macOS, where `/tmp` is a symlink), so the literal and the resolved spelling
+ * both count. Computed once.
+ */
+const TMUX_LAUNCH_CWD_SPELLINGS = (() => {
+    const spellings = new Set([TMUX_LAUNCH_CWD]);
+    try {
+        spellings.add(realpathSync(TMUX_LAUNCH_CWD));
+    }
+    catch {
+        // Unresolvable launch directory: the literal spelling is all there is.
+    }
+    return spellings;
+})();
 /** Claude Code native macOS recommendation for avoiding low nofile startup failures. */
 export const CLAUDE_CODE_NOFILE_LIMIT = 2147483646;
 /**
@@ -150,9 +168,13 @@ const PANE_LIST_SEP = '|';
  * know a variable substitutes the empty string rather than failing, which is how
  * tmux 3.2a answers `#{pane_dead_signal}` (added in 3.4), and the parser reads a
  * short row as "pid known, deadness unknown" rather than discarding it.
+ *
+ * `#{pane_current_path}` comes last on purpose: a directory name may contain the
+ * separator, and only the final field can absorb it without ambiguity.
  */
 const PANE_LIST_FORMAT = `#{session_name}${PANE_LIST_SEP}#{pane_pid}` +
-    `${PANE_LIST_SEP}#{pane_dead}${PANE_LIST_SEP}#{pane_dead_status}${PANE_LIST_SEP}#{pane_dead_signal}`;
+    `${PANE_LIST_SEP}#{pane_dead}${PANE_LIST_SEP}#{pane_dead_status}${PANE_LIST_SEP}#{pane_dead_signal}` +
+    `${PANE_LIST_SEP}#{pane_current_path}`;
 /**
  * 构建 pane 启动前的 nofile 修复命令。
  *
@@ -201,6 +223,8 @@ export function parsePaneRows(output) {
             dead: deadFlag === '1' ? true : deadFlag === '0' ? false : undefined,
             exitStatus: paneField(fields, 3),
             exitSignal: paneField(fields, 4),
+            // Everything after the fifth separator, so a path containing `|` stays whole.
+            currentPath: fields.slice(5).join(PANE_LIST_SEP) || undefined,
         });
     }
     return rows;
@@ -295,9 +319,11 @@ export function resolveTmuxPaneTarget(muxName, paneTarget) {
 let submitBufferSeq = 0;
 /**
  * Escape a final `;` for tmux. tmux splits commands on an argument that ENDS in
- * `;` (`set-buffer -- 'a;'` stores `a`, `send-keys -l 'a;'` types `a`, a lone `;`
+ * `;` (`set-buffer -- 'a;'` stores `a`, `send-keys -l -- 'a;'` types `a`, a lone `;`
  * is no argument at all); a final `\;` is its escape for a literal `;`. A `;`
- * anywhere else in the argument is literal already. Exported for unit testing.
+ * anywhere else in the argument is literal already. Every `send-keys -l` passes
+ * `--` before the text, like `set-buffer`, or tmux parses a text that starts with
+ * `-` as its own options. Exported for unit testing.
  */
 export function escapeTmuxTrailingSemicolon(text) {
     return text.endsWith(';') ? `${text.slice(0, -1)}\\;` : text;
@@ -864,6 +890,18 @@ export function buildCodexCommand(config) {
         return 'codex';
     return buildSpawnCommandFromRegistry(entry, { mode: 'codex', sessionId: '', codexConfig: config }) ?? 'codex';
 }
+/**
+ * Whether a launch carries `idleCompaction: false` in its one `--settings` JSON: keep-warm on
+ * at launch (`keepWarmOn`), the statusLine exporter injected (without its `prompt_cache` reports
+ * keep-warm cannot run, and the opt-out alone would only cost the user Claude Code's own idle
+ * compaction), and the CLI's `idleCompactionSetting` gate passed, fail-closed like `--name`:
+ * an unknown version means no key. Pure; `claudeCliVersion` as in buildSpawnCommand.
+ */
+export function decideIdleCompactionOptOut(o) {
+    return (o.statusLine === 'injected' &&
+        keepWarmOn(o.keepWarm, o.keepWarmDefault, !!o.spawnedByAgent) &&
+        launchGatePasses(o.mode, 'idleCompactionSetting', o.claudeCliVersion));
+}
 export function buildSpawnCommand(options) {
     // Every CLI's command shape is registry DATA, rendered by the argv engine — see
     // config/cli-registry/argv.ts for why config can never contain shell text. A `shell`-kind
@@ -938,7 +976,9 @@ export function remoteTmuxLocation(remote, sessionId) {
  *   ssh -o BatchMode=yes -t [<COD-107 connection opts>] user@host \
  *     'tmux -L codeman-remote new-session -A -s codeman-ssh-<id> -c <path> "cd <path> && exec <cli>" \
  *        \; set -t codeman-ssh-<id> status off \; set -t codeman-ssh-<id> mouse off \
- *        \; set -t codeman-ssh-<id> prefix C-q \; set -s escape-time 0'
+ *        \; set -t codeman-ssh-<id> prefix C-q \; set -s escape-time 0 \; \
+ *        bind-key -T prefix C-q send-prefix \; unbind-key -a -T prefix \; \
+ *        bind-key -T prefix C-q send-prefix \; set -t codeman-ssh-<id> remain-on-exit failed'
  *
  * COD-107 — the connection options (`-p`, `-i`, `-J`, SOCKS `-o ProxyCommand`,
  * arbitrary `-o`) come from the shared `buildSshConnectionArgs(remote)`, so the
@@ -1043,7 +1083,7 @@ export function buildRemoteLaunchCommand(options) {
         `tmux -L ${REMOTE_TMUX_SOCKET} new-session -A -s ${remoteName} -c ${shellescape(remote.remotePath)} ${shellescape(paneCommand)}`,
         `set -t ${remoteName} status off`,
         `set -t ${remoteName} mouse off`,
-        `set -t ${remoteName} prefix C-q`,
+        `set -t ${remoteName} prefix ${NESTED_TMUX_PREFIX}`,
         'set -s escape-time 0',
         // COD-106 — shared/collaborative sessions: tmux defaults to sizing a window
         // to the SMALLEST attached client, so two Codemans at different viewports
@@ -1052,6 +1092,15 @@ export function buildRemoteLaunchCommand(options) {
         // Per-session scoped (`set -t <name>`, matching #145's hardening) so a shared
         // remote tmux server's other sessions keep their own sizing behavior.
         `set -t ${remoteName} window-size latest`,
+        // The prefix TABLE is server-global (unlike `prefix C-q`, which is per
+        // session). This socket is dedicated to Codeman's owned sessions, so the
+        // same reduction as the local socket applies: Ctrl+Q then )/(/s/w/L must
+        // not switch-client / choose-tree onto a sibling. Bind, then unbind-all,
+        // then bind again: a user config that left the prefix table empty makes
+        // `unbind-key -a -T prefix` fail and abort the rest of this chain.
+        // BEFORE remain-on-exit, which stays last because an old remote tmux
+        // rejects `failed` and aborts the rest of the chain.
+        ...nestedPrefixTableResetCommands(),
         // #210: keep a CRASHED pane so the failure is still on screen. Without this,
         // tmux destroys the pane -> window -> session (and, being the only session,
         // the whole remote server) the instant the pane command exits, which tears the
@@ -1068,7 +1117,8 @@ export function buildRemoteLaunchCommand(options) {
         // LAST in the chain on purpose: tmux aborts the remaining commands of a `\;`
         // sequence once one errors (also verified), and `failed` needs tmux >= 3.2 on
         // the REMOTE host. Trailing, a rejection costs only this option; leading, it
-        // would silently drop status/mouse/prefix/escape-time/window-size with it.
+        // would silently drop status/mouse/prefix/escape-time/window-size and the
+        // prefix-table reduction with it.
         `set -t ${remoteName} remain-on-exit failed`,
     ].join(' \\; ');
     // ssh runs its trailing args through the remote login shell, so the entire
@@ -1080,7 +1130,14 @@ export function buildRemoteLaunchCommand(options) {
     // `ssh -o BatchMode=yes` (preserving the historical token order), then the rest
     // of the connection args, then the target and the quoted tmux invocation.
     const [ssh, batchMode, ...connectionArgs] = buildSshConnectionArgs(remote);
-    const sshParts = [ssh, batchMode, '-t', ...connectionArgs, remoteSshTarget(remote), shellescape(tmuxInvocation)];
+    const sshParts = [
+        ssh,
+        batchMode,
+        '-t',
+        ...connectionArgs,
+        remoteSshTarget(remote),
+        shellescape(withRemoteTmuxPath(tmuxInvocation)),
+    ];
     return sshParts.join(' ');
 }
 /**
@@ -1096,7 +1153,7 @@ export function buildRemoteKillCommand(options) {
     const remoteName = remoteTmuxSessionName(sessionId);
     const killCmd = `tmux -L ${REMOTE_TMUX_SOCKET} kill-session -t ${shellescape(remoteName)}`;
     const [ssh, ...connectionArgs] = buildSshConnectionArgs(remote);
-    return [ssh, ...connectionArgs, remoteSshTarget(remote), shellescape(killCmd)].join(' ');
+    return [ssh, ...connectionArgs, remoteSshTarget(remote), shellescape(withRemoteTmuxPath(killCmd))].join(' ');
 }
 // ========== Docker cases (COD-Docker) ==========
 //
@@ -1212,8 +1269,12 @@ export function buildDockerLaunchCommand(opts) {
         `new-session -A -s ${dkrName} -c ${workdir} ${shellescape(paneCommand)}`,
         `set -t ${dkrName} status off`,
         `set -t ${dkrName} mouse off`,
-        `set -t ${dkrName} prefix C-q`,
+        `set -t ${dkrName} prefix ${NESTED_TMUX_PREFIX}`,
         'set -s escape-time 0',
+        // Same reduction as the owned-remote chain: the in-container server is
+        // Codeman's (`-L codeman-docker`), and its stock prefix table would move
+        // the inner client to a sibling session on Ctrl+Q then )/(/s/w/L.
+        ...nestedPrefixTableResetCommands(),
     ].join(' \\; ');
     const execEnvFlags = [];
     for (const [k, v] of Object.entries(execEnv))
@@ -1423,7 +1484,14 @@ export function resolveDockerLaunchOptions(mode, docker, sessionId, resumeSessio
 export function buildRemoteAttachCommand(remote, remoteSessionName) {
     const tmuxInvocation = `tmux -L codeman attach -t ${shellescape(remoteSessionName)}`;
     const [ssh, batchMode, ...connectionArgs] = buildSshConnectionArgs(remote);
-    const sshParts = [ssh, batchMode, '-t', ...connectionArgs, remoteSshTarget(remote), shellescape(tmuxInvocation)];
+    const sshParts = [
+        ssh,
+        batchMode,
+        '-t',
+        ...connectionArgs,
+        remoteSshTarget(remote),
+        shellescape(withRemoteTmuxPath(tmuxInvocation)),
+    ];
     return sshParts.join(' ');
 }
 /**
@@ -1934,6 +2002,21 @@ export class TmuxManager extends EventEmitter {
         const command = await resolveStatusLineCliCommand(workingDir, enabled);
         return { command, state: command ? 'injected' : enabled ? 'workspace-statusline' : 'collection-off' };
     }
+    /**
+     * Whether this launch carries `idleCompaction: false` (decideIdleCompactionOptOut), with the
+     * keep-warm app default read fresh like the plan-usage switch above. Logged when keep-warm is
+     * on but the version gate keeps the key off, so a session that may still idle-compact says why.
+     */
+    async _resolveIdleCompactionOptOut(mode, statusLine, keepWarm, spawnedByAgent) {
+        if (statusLine !== 'injected')
+            return false; // no settings read for a launch that can never carry it
+        const { keepWarmDefault } = await readKeepWarmSettings();
+        const off = decideIdleCompactionOptOut({ mode, statusLine, keepWarm, keepWarmDefault, spawnedByAgent });
+        if (!off && keepWarmOn(keepWarm, keepWarmDefault, !!spawnedByAgent)) {
+            console.log(`[TmuxManager] Keep-warm is on but Claude Code's version is unknown or predates the idleCompaction setting; launching without the opt-out`);
+        }
+        return off;
+    }
     /**
      * Export the user's own REAL statusLine command (found by
      * findEffectiveUserStatusLineCommand) via tmux setenv, so the shared
@@ -1971,7 +2054,7 @@ export class TmuxManager extends EventEmitter {
      * In test mode: creates an in-memory session only (no real tmux session).
      */
     async createSession(options) {
-        const { sessionId, workingDir, mode, name, cliName, niceConfig, model, claudeMode, allowedTools, openCodeConfig, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, copilotConfig, deepSeekConfig, ompConfig, resumeSessionId, envOverrides, effort, advisorModel, historyLimit = DEFAULT_TMUX_HISTORY_LIMIT, remote, docker, owner, } = options;
+        const { sessionId, workingDir, mode, name, cliName, niceConfig, model, claudeMode, allowedTools, openCodeConfig, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, copilotConfig, deepSeekConfig, ompConfig, resumeSessionId, envOverrides, effort, advisorModel, keepWarm, spawnedByAgent, historyLimit = DEFAULT_TMUX_HISTORY_LIMIT, remote, docker, owner, } = options;
         const muxName = `codeman-${sessionId.slice(0, 8)}`;
         if (!isValidMuxName(muxName)) {
             throw new Error('Invalid session name: contains unsafe characters');
@@ -2022,6 +2105,7 @@ export class TmuxManager extends EventEmitter {
         }
         const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
         const { command: statusLineCommand, state: statusLine } = await this._resolveStatusLine(mode, workingDir, !!(remote || docker));
+        const idleCompactionOff = await this._resolveIdleCompactionOptOut(mode, statusLine, keepWarm, spawnedByAgent);
         // The user's own REAL statusLine, if any (walked via Claude Code's own
         // settings precedence) — exported below so the shared exporter script
         // can wrap it. Only worth discovering when we're actually injecting.
@@ -2045,6 +2129,7 @@ export class TmuxManager extends EventEmitter {
             effort,
             advisorModel,
             statusLineCommand,
+            idleCompactionOff,
             sessionName: cliName,
         });
         const config = niceConfig || DEFAULT_NICE_CONFIG;
@@ -2094,6 +2179,9 @@ export class TmuxManager extends EventEmitter {
             catch {
                 /* Non-critical */
             }
+            // Browser keystrokes reach the attach client, so tmux's stock prefix table would
+            // let Ctrl+B ( or s move a tab onto another session. Before the agent starts.
+            restrictTmuxPrefixTable(this.tmux());
             // Per-CLI env: API keys, config blobs, config-sourced vars, status bridges. All of
             // it is registry data, so this is one unconditional call rather than a per-mode ladder.
             this._configureCliEnv(muxName, sessionId, mode, legacyConfigForMode(mode, options));
@@ -2163,6 +2251,7 @@ export class TmuxManager extends EventEmitter {
                 attached: false,
                 name,
                 statusLine,
+                idleCompactionOff,
             };
             this.sessions.set(sessionId, session);
             this.saveSessions();
@@ -2250,7 +2339,7 @@ export class TmuxManager extends EventEmitter {
      * preserving the session and its scrollback buffer.
      */
     async respawnPane(options) {
-        const { sessionId, workingDir, mode, niceConfig, model, claudeMode, allowedTools, openCodeConfig, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, copilotConfig, deepSeekConfig, ompConfig, resumeSessionId, envOverrides, unsetEnvKeys, effort, advisorModel, remote, docker, cliName, } = options;
+        const { sessionId, workingDir, mode, niceConfig, model, claudeMode, allowedTools, openCodeConfig, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, copilotConfig, deepSeekConfig, ompConfig, resumeSessionId, envOverrides, unsetEnvKeys, effort, advisorModel, keepWarm, spawnedByAgent, remote, docker, cliName, } = options;
         const session = this.sessions.get(sessionId);
         if (!session)
             return null;
@@ -2261,6 +2350,7 @@ export class TmuxManager extends EventEmitter {
         const { pathExport } = this.buildPathExport(mode);
         const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
         const { command: statusLineCommand, state: statusLine } = await this._resolveStatusLine(mode, workingDir, !!(remote || docker));
+        const idleCompactionOff = await this._resolveIdleCompactionOptOut(mode, statusLine, keepWarm, spawnedByAgent);
         const userStatusLineCommand = statusLineCommand ? await findEffectiveUserStatusLineCommand(workingDir) : undefined;
         const baseCmd = buildSpawnCommand({
             mode,
@@ -2281,6 +2371,7 @@ export class TmuxManager extends EventEmitter {
             effort,
             advisorModel,
             statusLineCommand,
+            idleCompactionOff,
             sessionName: cliName,
         });
         const config = niceConfig || DEFAULT_NICE_CONFIG;
@@ -2313,8 +2404,9 @@ export class TmuxManager extends EventEmitter {
             const pid = this.getPanePid(muxName);
             if (pid)
                 session.pid = pid;
-            if (session.statusLine !== statusLine) {
+            if (session.statusLine !== statusLine || session.idleCompactionOff !== idleCompactionOff) {
                 session.statusLine = statusLine;
+                session.idleCompactionOff = idleCompactionOff;
                 this.saveSessions();
             }
             return pid;
@@ -2663,13 +2755,30 @@ export class TmuxManager extends EventEmitter {
         // socket tag to reconcile and no cross-socket ambiguity that could mark a
         // live session dead (the root cause of vanished/duplicate tabs).
         let active;
+        const paneDirs = new Map();
         try {
             const output = execSync(`${this.tmux()} list-panes -a -F '${PANE_LIST_FORMAT}' 2>/dev/null || true`, {
                 encoding: 'utf-8',
                 timeout: EXEC_TIMEOUT_MS,
-            }).trim();
+            });
+            // Not trimmed: the directory is the last field, so trimming would cut a
+            // trailing space off the last row's path. parsePaneRows skips empty lines.
             const rows = parsePaneRows(output);
             active = new Map(rows.map((row) => [row.sessionName, row.pid]));
+            // A discovered session's directory, from its first pane with a usable path.
+            // The path is admitted only if it passes the same check createSession and
+            // respawnPane apply, since it was set by whoever owns the pane, not by us.
+            // The launch directory counts as no answer: every pane starts there, and a
+            // remote or docker pane never cds out of it, so for such a session it is
+            // not the workspace — and a rediscovered record cannot tell it is one.
+            for (const row of rows) {
+                if (row.currentPath &&
+                    !TMUX_LAUNCH_CWD_SPELLINGS.has(row.currentPath) &&
+                    !paneDirs.has(row.sessionName) &&
+                    isValidPath(row.currentPath)) {
+                    paneDirs.set(row.sessionName, row.currentPath);
+                }
+            }
             // The same read answers both questions, so recovery starts with a pane-exit
             // reading rather than waiting for the first stats tick — which may never
             // come, since the collector only starts when boot found a live session.
@@ -2681,6 +2790,11 @@ export class TmuxManager extends EventEmitter {
             console.error('[TmuxManager] Failed to list tmux panes:', err);
             active = new Map();
         }
+        // Sessions that survived an upgrade may sit on a server whose prefix table was never
+        // reduced (createSession does it for new ones), so cover them at boot too. Only with
+        // panes listed: on an empty socket `list-keys` spins up a throwaway server instead.
+        if (active.size > 0)
+            restrictTmuxPrefixTable(this.tmux());
         // Check tracked sessions against the live pane list.
         for (const [sessionId, session] of this.sessions) {
             const pid = active.get(session.muxName);
@@ -2724,11 +2838,13 @@ export class TmuxManager extends EventEmitter {
                 muxName: sessionName,
                 pid,
                 createdAt: Date.now(),
-                workingDir: process.cwd(),
+                // Where the pane actually works, when tmux said; the server's cwd is only a fallback.
+                workingDir: paneDirs.get(sessionName) ?? process.cwd(),
                 mode: 'claude',
                 attached: false,
                 name: `Restored: ${sessionName}`,
-                // Every field above except the name and the pid is a guess: this record
+                // Every field above except the name, the pid and, when tmux reported a
+                // usable one, the directory is a guess: this record
                 // was rebuilt from the socket because Codeman's own bookkeeping did not
                 // have it. The synthetic id also cannot find the session's state.json
                 // entry, so a remote or docker session rediscovered this way arrives
@@ -3335,7 +3451,12 @@ export class TmuxManager extends EventEmitter {
      * - Text followed by `\r` goes in as ONE bracketed paste (buildPasteTextCommands),
      *   so Codex cannot fold the Enter into a paste burst; a single character is typed
      *   with `send-keys -l` instead, so a dialog answer selects (submitsAsKeys)
-     * - Text without `\r` is typed literally with `send-keys -l` (no key interpretation)
+     * - Single-line text without `\r` is typed literally with `send-keys -l` (no key
+     *   interpretation)
+     * - A `\n` inside the text is kept (`\r\n` loses only its `\r`), and multi-line text
+     *   always goes in as ONE bracketed paste, with or without a following Enter: inside
+     *   the paste markers a CLI that enabled bracketed paste receives the line breaks as
+     *   pasted text, where typed as keys each one could submit a line on its own
      * - `Enter` key is sent as a SEPARATE tmux invocation after a small delay
      * - Ink (Claude CLI) needs text and Enter split to avoid treating Enter as a newline
      */
@@ -3345,8 +3466,10 @@ export class TmuxManager extends EventEmitter {
             console.error(`[TmuxManager] sendInput failed: no session found for ${sessionId}. Known: ${Array.from(this.sessions.keys()).join(', ')}`);
             return false;
         }
-        // TEST MODE: No-op — don't send input to real tmux sessions
-        if (IS_TEST_MODE) {
+        // TEST MODE: No-op — don't send input to real tmux sessions. The gate lives in
+        // inputRunner() so a test subclass can record what WOULD reach tmux.
+        const run = this.inputRunner();
+        if (!run) {
             return true;
         }
         console.log(`[TmuxManager] sendInput to ${session.muxName}, input length: ${input.length}, hasCarriageReturn: ${input.includes('\r')}`);
@@ -3356,7 +3479,14 @@ export class TmuxManager extends EventEmitter {
         }
         try {
             const hasCarriageReturn = input.includes('\r');
-            const textPart = input.replace(/\r/g, '').replace(/\n/g, '').trimEnd();
+            // Leading and trailing blank lines are dropped, so neither `"\nfix it\r"` nor
+            // `"  \nfix it\r"` pastes an empty first line (nor `"fix it\n\r"` an empty last
+            // one). The leading match ends at a line break, so the first real line keeps its
+            // indentation.
+            const textPart = input
+                .replace(/\r/g, '')
+                .replace(/^\s*\n/, '')
+                .trimEnd();
             if (textPart && hasCarriageReturn) {
                 // Send text first, then Enter as a SEPARATE tmux command after a short delay.
                 // Ink (Claude CLI's terminal framework) needs them split — sending both in a
@@ -3367,25 +3497,29 @@ export class TmuxManager extends EventEmitter {
                 // selection dialog ignores a pasted `3` and Enter then confirms the
                 // highlighted option (see submitsAsKeys).
                 if (submitsAsKeys(textPart)) {
-                    await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" -l ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`, { timeout: EXEC_TIMEOUT_MS });
+                    await run(`${this.tmux()} send-keys -t "${session.muxName}" -l -- ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`);
                 }
                 else {
-                    await pasteText((cmd) => execAsync(cmd, { timeout: EXEC_TIMEOUT_MS }), buildPasteTextCommands(this.tmux(), session.muxName, textPart));
+                    await pasteText(run, buildPasteTextCommands(this.tmux(), session.muxName, textPart));
                 }
                 await new Promise((resolve) => setTimeout(resolve, 50));
-                await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" Enter`, {
-                    timeout: EXEC_TIMEOUT_MS,
-                });
+                await run(`${this.tmux()} send-keys -t "${session.muxName}" Enter`);
+            }
+            else if (textPart.includes('\n')) {
+                // Multi-line text, no Enter: pasted, because typed as keys every `\n` would
+                // reach the pane as a key the CLI may read as submit. A pane that has not
+                // enabled bracketed paste (POSIX sh, macOS /bin/bash 3.2) still gets every line
+                // break as a CR, so there every line but the last runs; before line breaks were
+                // kept, the joined text was typed and nothing ran.
+                await pasteText(run, buildPasteTextCommands(this.tmux(), session.muxName, textPart));
             }
             else if (textPart) {
                 // Text only, no Enter
-                await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" -l ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`, { timeout: EXEC_TIMEOUT_MS });
+                await run(`${this.tmux()} send-keys -t "${session.muxName}" -l -- ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`);
             }
             else if (hasCarriageReturn) {
                 // Enter only
-                await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" Enter`, {
-                    timeout: EXEC_TIMEOUT_MS,
-                });
+                await run(`${this.tmux()} send-keys -t "${session.muxName}" Enter`);
             }
             return true;
         }
@@ -3394,6 +3528,16 @@ export class TmuxManager extends EventEmitter {
             return false;
         }
     }
+    /**
+     * How {@link sendInput} reaches tmux, or null where it must not (vitest). Split
+     * out like {@link readPaneRows}: with the test-mode gate at the top of sendInput,
+     * no test could see which commands a submit actually sends.
+     */
+    inputRunner() {
+        if (IS_TEST_MODE)
+            return null;
+        return (cmd) => execAsync(cmd, { timeout: EXEC_TIMEOUT_MS });
+    }
     // ========== Pane Methods (for Agent Team teammate panes) ==========
     /**
      * Enable mouse mode for an existing tmux session.
@@ -3493,7 +3637,9 @@ export class TmuxManager extends EventEmitter {
     }
     /**
      * Send input to a specific pane within a tmux session.
-     * Uses the same literal text approach as sendInput() but targets a specific pane.
+     * Types the text literally with `send-keys -l`, line breaks stripped, then Enter
+     * when the input carried a `\r`. Unlike sendInput(), it neither pastes nor keeps
+     * the line breaks of multi-line text.
      */
     sendInputToPane(muxName, paneTarget, input) {
         if (IS_TEST_MODE)
@@ -3513,7 +3659,7 @@ export class TmuxManager extends EventEmitter {
             const hasCarriageReturn = input.includes('\r');
             const textPart = input.replace(/\r/g, '').replace(/\n/g, '').trimEnd();
             if (textPart && hasCarriageReturn) {
-                execSync(`${tmux} send-keys -t ${shellescape(target)} -l ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`, {
+                execSync(`${tmux} send-keys -t ${shellescape(target)} -l -- ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`, {
                     encoding: 'utf-8',
                     timeout: EXEC_TIMEOUT_MS,
                 });
@@ -3523,7 +3669,7 @@ export class TmuxManager extends EventEmitter {
                 });
             }
             else if (textPart) {
-                execSync(`${tmux} send-keys -t ${shellescape(target)} -l ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`, {
+                execSync(`${tmux} send-keys -t ${shellescape(target)} -l -- ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`, {
                     encoding: 'utf-8',
                     timeout: EXEC_TIMEOUT_MS,
                 });
@@ -3563,19 +3709,21 @@ export class TmuxManager extends EventEmitter {
     /**
      * Plain visible-frame text for the working/idle probe (see `session.ts`).
      *
-     * One `capture-pane` and nothing else: no `-e` styles, no `display-message`
-     * cursor query, no repaint reconstruction: this feeds a regex, not a
-     * terminal. Returns null in tests (no tmux) so callers fall back to their
-     * stream heuristics rather than reading an empty screen as "not working".
+     * One `capture-pane` and nothing else: no `display-message` cursor query, no
+     * repaint reconstruction: this feeds a regex, not a terminal. `styles` adds
+     * `-e` for a reader that must tell faint text from typed text (the keep-warm
+     * composer check); lines stay `\n`-separated either way. Returns null in tests
+     * (no tmux) so callers fall back to their stream heuristics rather than
+     * reading an empty screen as "not working".
      */
-    capturePaneText(muxName, paneTarget) {
+    capturePaneText(muxName, paneTarget, opts) {
         if (IS_TEST_MODE)
             return null;
         const target = resolveTmuxPaneTarget(muxName, paneTarget);
         if (!target)
             return null;
         try {
-            return execSync(`${this.tmux()} capture-pane -p -t ${shellescape(target)}`, {
+            return execSync(`${this.tmux()} capture-pane -p${opts?.styles ? ' -e' : ''} -t ${shellescape(target)}`, {
                 encoding: 'utf-8',
                 timeout: EXEC_TIMEOUT_MS,
             });