aiwcli 0.15.5 → 0.15.7

package/dist/lib/terminal.js

@@ -27,38 +27,68 @@
  *
  * @module lib/terminal
  */
-import { execSync, spawn } from 'node:child_process';
-/**
- * Return a copy of process.env with Claude Code nesting-detection vars removed.
- *
- * Claude Code sets CLAUDECODE and CLAUDE_CODE_ENTRYPOINT when running. Child
- * processes that inherit these vars are blocked from launching their own Claude
- * Code instance ("cannot launch claude within claude").
- *
- * Source of truth: packages/cli/src/templates/_shared/lib-ts/base/subprocess-utils.ts
- * → getInternalSubprocessEnv() — if Claude Code adds more nesting-detection vars
- * in a future release, add them here too.
- */
-function cleanTerminalEnv() {
-    const env = { ...process.env };
-    delete env['CLAUDECODE'];
-    delete env['CLAUDE_CODE_ENTRYPOINT'];
-    return env;
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { cleanClaudeEnv } from './mux-utils.js';
+import { isCommandAvailable } from './runtime/executable-policy.js';
+import { isWindowsPlatform } from './runtime/platform-adapter.js';
+import { findMsysBash } from './runtime/tmux-preflight.js';
+import { escapeSingleQuotedPath } from './shell-quoting.js';
+import { detectPowerShell, findAvailableLinuxTerminal, isWSL, resolveWindowsTerminalStrategy, } from './terminal-strategy.js';
+/** @internal */
+export function resolveTerminalPlatform(platform, isWSLResult) {
+    if (isWindowsPlatform(platform))
+        return 'windows';
+    if (platform === 'darwin')
+        return 'darwin';
+    if (isWSLResult)
+        return 'wsl';
+    return 'linux';
 }
-/**
- * Detect which PowerShell is available on Windows.
- * Prefers PowerShell 7 (pwsh) over legacy PowerShell.
- *
- * @returns 'pwsh' if PowerShell 7 is available, 'powershell' otherwise
- */
-function detectPowerShell() {
-    try {
-        execSync('where pwsh', { stdio: 'ignore' });
-        return 'pwsh';
-    }
-    catch {
-        return 'powershell';
-    }
+/** @internal */
+export function buildMacTerminalSpawnArgs(cwd, command) {
+    const escapedPath = escapeSingleQuotedPath(cwd, 'bash');
+    const fullCommand = `cd '${escapedPath}' && ${command}`;
+    const escapedCommand = fullCommand.replaceAll('\\', '\\\\').replaceAll('"', String.raw `\"`);
+    return {
+        command: 'osascript',
+        args: ['-e', `tell application "Terminal" to do script "${escapedCommand}"`],
+    };
+}
+/** @internal */
+export function buildWindowsTerminalSpawnArgs(cwd, command, powershellCmd) {
+    return {
+        command: 'wt',
+        args: ['-d', cwd, powershellCmd, '-NoExit', '-Command', command],
+    };
+}
+/** @internal */
+export function buildPowerShellFallbackSpawnArgs(cwd, command, powershellCmd) {
+    const escapedPath = escapeSingleQuotedPath(cwd, 'powershell');
+    const psCommand = `Start-Process ${powershellCmd} -ArgumentList '-NoExit','-Command',"cd '${escapedPath}'; ${command}"`;
+    return {
+        command: powershellCmd,
+        args: ['-Command', psCommand],
+    };
+}
+/** @internal */
+export function buildLinuxTerminalSpawnArgs(cwd, command, terminalInfo) {
+    const escapedPath = escapeSingleQuotedPath(cwd, 'bash');
+    const fullCommand = `cd '${escapedPath}' && ${command}`;
+    return {
+        command: terminalInfo.cmd,
+        args: terminalInfo.getArgs(fullCommand),
+    };
+}
+/** @internal */
+export function buildWSLTerminalSpawnArgs(cwd, command) {
+    const escapedPath = escapeSingleQuotedPath(cwd, 'bash');
+    const bashCmd = `cd '${escapedPath}' && ${command}; exec bash`;
+    return {
+        command: 'wt.exe',
+        args: ['wsl.exe', '--', 'bash', '-c', bashCmd],
+    };
 }
 /**
  * Launch PowerShell fallback when Windows Terminal is not available.
@@ -70,13 +100,12 @@ function detectPowerShell() {
  */
 async function launchPowerShellFallback(cwd, command, powershellCmd, debugLog) {
     return new Promise((resolve) => {
-        const escapedPath = cwd.replaceAll("'", "''");
-        const psCommand = `Start-Process ${powershellCmd} -ArgumentList '-NoExit','-Command',"cd '${escapedPath}'; ${command}"`;
-        debugLog?.(`Launching PowerShell fallback with command: ${psCommand}`);
-        const terminal = spawn(powershellCmd, ['-Command', psCommand], {
+        const spawnArgs = buildPowerShellFallbackSpawnArgs(cwd, command, powershellCmd);
+        debugLog?.(`Launching PowerShell fallback with command: ${spawnArgs.args[1]}`);
+        const terminal = spawn(spawnArgs.command, spawnArgs.args, {
             detached: true,
             stdio: 'ignore',
-            env: cleanTerminalEnv(),
+            env: cleanClaudeEnv(),
         });
         terminal.on('error', (err) => {
             resolve({ success: false, error: `Failed to launch PowerShell: ${err.message}` });
@@ -90,32 +119,91 @@ async function launchPowerShellFallback(cwd, command, powershellCmd, debugLog) {
  *
  * @param cwd - Working directory
  * @param command - Command to execute
+ * @param shellPreference - Preferred shell for Windows launches
  * @param debugLog - Optional debug logging function
  */
-async function launchWindowsTerminal(cwd, command, debugLog) {
-    const powershellCmd = detectPowerShell();
-    debugLog?.(`Detected PowerShell: ${powershellCmd}`);
-    return new Promise((resolve) => {
-        const terminal = spawn('wt', ['-d', cwd, powershellCmd, '-NoExit', '-Command', command], {
-            detached: true,
-            stdio: 'ignore',
-            env: cleanTerminalEnv(),
-        });
-        terminal.on('error', (err) => {
-            // If wt.exe not found, try fallback to Start-Process
-            if (err.message.includes('ENOENT')) {
-                debugLog?.('Windows Terminal not found, using PowerShell fallback');
-                launchPowerShellFallback(cwd, command, powershellCmd, debugLog)
-                    .then(resolve)
-                    .catch(() => resolve({ success: false, error: 'Failed to launch PowerShell fallback' }));
+async function launchWindowsTerminal(cwd, command, shellPreference, debugLog) {
+    const powershellCmd = detectPowerShell(isCommandAvailable);
+    debugLog?.(`Detected PowerShell: ${powershellCmd}; shell preference: ${shellPreference}`);
+    const gitBashPath = findMsysBash();
+    const minttyPath = gitBashPath
+        ? path.join(path.dirname(gitBashPath), 'mintty.exe')
+        : null;
+    const hasMintty = Boolean(minttyPath && existsSync(minttyPath));
+    const strategyOrder = resolveWindowsTerminalStrategy(shellPreference, gitBashPath, hasMintty, powershellCmd);
+    const tryStrategy = async (strategy) => {
+        if (strategy === 'powershell-fallback') {
+            debugLog?.('Using PowerShell fallback launcher');
+            return launchPowerShellFallback(cwd, command, powershellCmd, debugLog);
+        }
+        if (strategy === 'mintty') {
+            if (!minttyPath || !gitBashPath) {
+                return { success: false, error: 'mintty or Git Bash not found' };
             }
-            else {
-                resolve({ success: false, error: `Failed to launch terminal: ${err.message}` });
+            const escapedPath = escapeSingleQuotedPath(cwd, 'bash');
+            const bashCmd = `cd '${escapedPath}' && ${command}; exec bash`;
+            debugLog?.(`Using mintty for Windows terminal: ${minttyPath}`);
+            return new Promise((resolve) => {
+                const terminal = spawn(minttyPath, [gitBashPath, '-lc', bashCmd], {
+                    detached: true,
+                    stdio: 'ignore',
+                    env: cleanClaudeEnv(),
+                    windowsHide: true,
+                });
+                terminal.on('error', (err) => {
+                    resolve({ success: false, error: `mintty launch failed: ${err.message}` });
+                });
+                terminal.unref();
+                resolve({ success: true });
+            });
+        }
+        if (strategy === 'git-bash-in-wt') {
+            if (!gitBashPath) {
+                return { success: false, error: 'Git Bash not found' };
             }
+            const escapedPath = escapeSingleQuotedPath(cwd, 'bash');
+            const bashCmd = `cd '${escapedPath}' && ${command}; exec bash`;
+            debugLog?.(`Using Git Bash for Windows terminal: ${gitBashPath}`);
+            return new Promise((resolve) => {
+                const terminal = spawn('wt', ['-d', cwd, gitBashPath, '-lc', bashCmd], {
+                    detached: true,
+                    stdio: 'ignore',
+                    env: cleanClaudeEnv(),
+                });
+                terminal.on('error', (err) => {
+                    resolve({ success: false, error: `Git Bash launch via wt failed: ${err.message}` });
+                });
+                terminal.unref();
+                resolve({ success: true });
+            });
+        }
+        debugLog?.('Using Windows Terminal with PowerShell');
+        return new Promise((resolve) => {
+            const spawnArgs = buildWindowsTerminalSpawnArgs(cwd, command, powershellCmd);
+            const terminal = spawn(spawnArgs.command, spawnArgs.args, {
+                detached: true,
+                stdio: 'ignore',
+                env: cleanClaudeEnv(),
+            });
+            terminal.on('error', (err) => {
+                resolve({ success: false, error: `Failed to launch terminal: ${err.message}` });
+            });
+            terminal.unref();
+            resolve({ success: true });
         });
-        terminal.unref();
-        resolve({ success: true });
-    });
+    };
+    const tryStrategies = async (index = 0) => {
+        const strategy = strategyOrder[index];
+        if (!strategy) {
+            return { success: false, error: 'Failed to launch Windows terminal with all available strategies' };
+        }
+        const result = await tryStrategy(strategy);
+        if (result.success)
+            return result;
+        debugLog?.(`Strategy ${strategy} failed: ${result.error}`);
+        return tryStrategies(index + 1);
+    };
+    return tryStrategies();
 }
 /**
  * Launch macOS Terminal.app with command.
@@ -126,16 +214,12 @@ async function launchWindowsTerminal(cwd, command, debugLog) {
  */
 async function launchMacTerminal(cwd, command, debugLog) {
     return new Promise((resolve) => {
-        // Escape single quotes for bash context
-        const escapedPath = cwd.replaceAll("'", String.raw `'\''`);
-        const fullCommand = `cd '${escapedPath}' && ${command}`;
-        // Escape double quotes and backslashes for AppleScript context
-        const escapedCommand = fullCommand.replaceAll('\\', '\\\\').replaceAll('"', String.raw `\"`);
-        debugLog?.(`Launching macOS Terminal with command: ${fullCommand}`);
-        const terminal = spawn('osascript', ['-e', `tell application "Terminal" to do script "${escapedCommand}"`], {
+        const spawnArgs = buildMacTerminalSpawnArgs(cwd, command);
+        debugLog?.(`Launching macOS Terminal with command: cd '${escapeSingleQuotedPath(cwd, 'bash')}' && ${command}`);
+        const terminal = spawn(spawnArgs.command, spawnArgs.args, {
             detached: true,
             stdio: 'ignore',
-            env: cleanTerminalEnv(),
+            env: cleanClaudeEnv(),
         });
         terminal.on('error', (err) => {
             resolve({ success: false, error: `Failed to launch Terminal.app: ${err.message}` });
@@ -144,56 +228,24 @@ async function launchMacTerminal(cwd, command, debugLog) {
         resolve({ success: true });
     });
 }
-/**
- * Linux terminal emulator configurations.
- */
-const LINUX_TERMINALS = [
-    { cmd: 'gnome-terminal', getArgs: (command) => ['--', 'bash', '-c', `${command}; exec bash`] },
-    { cmd: 'konsole', getArgs: (command) => ['-e', `bash -c "${command}; exec bash"`] },
-    { cmd: 'xterm', getArgs: (command) => ['-e', `bash -c "${command}; exec bash"`] },
-    { cmd: 'x-terminal-emulator', getArgs: (command) => ['-e', `bash -c "${command}; exec bash"`] },
-];
-/**
- * Find the first available Linux terminal emulator.
- * Checks gnome-terminal, konsole, xterm, x-terminal-emulator in order.
- *
- * @returns Terminal configuration if found, null otherwise
- */
-function findAvailableLinuxTerminal() {
-    for (const terminal of LINUX_TERMINALS) {
-        try {
-            execSync(`which ${terminal.cmd}`, { stdio: 'ignore' });
-            return terminal;
-        }
-        catch {
-            // Terminal not found, try next
-            continue;
-        }
-    }
-    return null;
-}
-function isWSL() {
-    return Boolean(process.env['WSL_DISTRO_NAME']);
-}
 /**
  * Launch Windows Terminal (wt.exe) from WSL, running the command inside a new bash session.
  *
  * Uses wt.exe → wsl.exe → bash so the new terminal inherits the correct WSL distro.
- * Claude Code nesting-detection vars are stripped via cleanTerminalEnv().
+ * Claude Code nesting-detection vars are stripped via cleanClaudeEnv().
  *
  * @param cwd - Working directory (WSL path)
  * @param command - Command to execute
  * @param debugLog - Optional debug logging function
  */
 async function launchWSLTerminal(cwd, command, debugLog) {
-    const escapedPath = cwd.replaceAll("'", String.raw `'\''`);
-    const bashCmd = `cd '${escapedPath}' && ${command}; exec bash`;
-    debugLog?.(`Launching WSL via wt.exe with command: ${bashCmd}`);
+    const spawnArgs = buildWSLTerminalSpawnArgs(cwd, command);
+    debugLog?.(`Launching WSL via wt.exe with command: ${spawnArgs.args[4]}`);
     return new Promise((resolve) => {
-        const proc = spawn('wt.exe', ['wsl.exe', '--', 'bash', '-c', bashCmd], {
+        const proc = spawn(spawnArgs.command, spawnArgs.args, {
             detached: true,
             stdio: 'ignore',
-            env: cleanTerminalEnv(),
+            env: cleanClaudeEnv(),
         });
         proc.on('error', (err) => {
             resolve({ success: false, error: `wt.exe failed: ${err.message}` });
@@ -212,23 +264,21 @@ async function launchWSLTerminal(cwd, command, debugLog) {
  */
 async function launchLinuxTerminal(cwd, command, debugLog) {
     // Find available terminal first (synchronous)
-    const terminal = findAvailableLinuxTerminal();
+    const terminal = findAvailableLinuxTerminal(isCommandAvailable);
     if (!terminal) {
         return {
             error: 'No supported terminal emulator found. Please install gnome-terminal, konsole, or xterm.',
             success: false,
         };
     }
-    // Escape single quotes for bash shell
-    const escapedPath = cwd.replaceAll("'", String.raw `'\''`);
-    const fullCommand = `cd '${escapedPath}' && ${command}`;
-    debugLog?.(`Launching ${terminal.cmd} with command: ${fullCommand}`);
+    const spawnArgs = buildLinuxTerminalSpawnArgs(cwd, command, terminal);
+    debugLog?.(`Launching ${terminal.cmd} with command: cd '${escapeSingleQuotedPath(cwd, 'bash')}' && ${command}`);
     // Launch terminal (single async operation)
     return new Promise((resolve) => {
-        const proc = spawn(terminal.cmd, terminal.getArgs(fullCommand), {
+        const proc = spawn(spawnArgs.command, spawnArgs.args, {
             detached: true,
             stdio: 'ignore',
-            env: cleanTerminalEnv(),
+            env: cleanClaudeEnv(),
         });
         proc.on('error', (err) => {
             resolve({ error: `Failed to launch ${terminal.cmd}: ${err.message}`, success: false });
@@ -269,12 +319,12 @@ async function launchLinuxTerminal(cwd, command, debugLog) {
  * ```
  */
 export async function launchTerminal(options) {
-    const { cwd, command, debugLog } = options;
+    const { cwd, command, debugLog, windowsShellPreference = 'default' } = options;
     const { platform } = process;
     debugLog?.(`Launching terminal in ${cwd} with command: ${command}`);
     debugLog?.(`Platform: ${platform}`);
-    if (platform === 'win32') {
-        return launchWindowsTerminal(cwd, command, debugLog);
+    if (isWindowsPlatform(platform)) {
+        return launchWindowsTerminal(cwd, command, windowsShellPreference, debugLog);
     }
     if (platform === 'darwin') {
         return launchMacTerminal(cwd, command, debugLog);

package/dist/lib/tmux-pane-placement.d.ts

@@ -0,0 +1,17 @@
+/**
+ * BSP split algorithm for tmux pane placement.
+ * Extracted from template core/lib-ts/base/tmux-pane-placement.ts.
+ */
+export type TmuxSplitFlag = '-h' | '-v';
+export interface TmuxPaneInfo {
+    active: boolean;
+    height: number;
+    paneId: string;
+    width: number;
+}
+export interface PlacementResult {
+    splitFlag: TmuxSplitFlag;
+    targetPane: string;
+}
+export declare function listPanes(tmuxPath: string): Promise<TmuxPaneInfo[]>;
+export declare function findBestSplit(panes: TmuxPaneInfo[]): null | PlacementResult;

package/dist/lib/tmux-pane-placement.js

@@ -0,0 +1,58 @@
+/**
+ * BSP split algorithm for tmux pane placement.
+ * Extracted from template core/lib-ts/base/tmux-pane-placement.ts.
+ */
+import { execFileAsync } from './runtime/subprocess-utils.js';
+const LIST_PANES_FORMAT = '#{pane_id} #{pane_width} #{pane_height} #{pane_active}';
+export async function listPanes(tmuxPath) {
+    const result = await execFileAsync(tmuxPath, ['list-panes', '-F', LIST_PANES_FORMAT], {
+        timeout: 3000,
+    });
+    if (result.exitCode !== 0)
+        return [];
+    const panes = [];
+    for (const rawLine of result.stdout.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        const parts = line.split(/\s+/);
+        if (parts.length < 4)
+            continue;
+        const paneId = parts[0] ?? '';
+        const width = Number.parseInt(parts[1] ?? '', 10);
+        const height = Number.parseInt(parts[2] ?? '', 10);
+        const activeRaw = parts[3] ?? '';
+        if (!paneId || !Number.isFinite(width) || !Number.isFinite(height))
+            continue;
+        panes.push({
+            paneId,
+            width,
+            height,
+            active: activeRaw === '1',
+        });
+    }
+    return panes;
+}
+export function findBestSplit(panes) {
+    if (panes.length === 0)
+        return null;
+    let best = panes[0];
+    let bestArea = best.width * best.height;
+    for (let i = 1; i < panes.length; i++) {
+        const pane = panes[i];
+        if (!pane)
+            continue;
+        const area = pane.width * pane.height;
+        if (area > bestArea) {
+            best = pane;
+            bestArea = area;
+        }
+    }
+    const CELL_ASPECT_RATIO = 2;
+    const visualWidth = best.width;
+    const visualHeight = best.height * CELL_ASPECT_RATIO;
+    return {
+        targetPane: best.paneId,
+        splitFlag: visualWidth >= visualHeight ? '-h' : '-v',
+    };
+}

package/dist/lib/tmux-primitives.d.ts

@@ -0,0 +1,5 @@
+export { quoteForSh } from './shell-quoting.js';
+/** Fixed tmux server socket. Multiple named sessions share one server. */
+export declare const TMUX_SOCKET_PATH: string;
+/** Convert Windows path to MSYS2 POSIX path for tmux args. C:\foo\bar → /c/foo/bar */
+export declare function toMsysPosixPath(winPath: string): string;

package/dist/lib/tmux-primitives.js

@@ -0,0 +1,15 @@
+import * as os from 'node:os';
+import path from 'node:path';
+export { quoteForSh } from './shell-quoting.js';
+/** Fixed tmux server socket. Multiple named sessions share one server. */
+export const TMUX_SOCKET_PATH = path.join(os.tmpdir(), 'aiwcli-tmux.sock');
+/** Convert Windows path to MSYS2 POSIX path for tmux args. C:\foo\bar → /c/foo/bar */
+export function toMsysPosixPath(winPath) {
+    if (process.platform !== 'win32')
+        return winPath;
+    const normalized = winPath.replaceAll('\\', '/');
+    const match = normalized.match(/^([A-Za-z]):\/(.*)/u);
+    if (!match)
+        return normalized;
+    return `/${match[1].toLowerCase()}/${match[2]}`;
+}

package/dist/lib/tmux-session.d.ts

@@ -0,0 +1,32 @@
+export interface TmuxSessionOptions {
+    /** Prepend tmux mouse enable command (default true). */
+    enableMouse?: boolean;
+    /** Platform override for deterministic tests. */
+    platform?: NodeJS.Platform | undefined;
+    /** Optional prompt text to deliver as a positional arg via temp file. */
+    promptText?: string | undefined;
+    reattach?: boolean;
+    sessionName: string;
+    /** CLI args (e.g. ['--dangerously-skip-permissions']). */
+    toolArgs: string[];
+    /** Absolute path to tool binary (or bare command name on Unix). */
+    toolPath: string;
+}
+export type TmuxColorMode = 'c256' | 'truecolor';
+export declare function buildTmuxRuntimeBootstrapCommands(platform?: NodeJS.Platform, enableMouse?: boolean): string[];
+/** Color mode policy for tmux-launched sessions. */
+export declare function resolveTmuxColorMode(platform?: NodeJS.Platform): TmuxColorMode;
+/**
+ * Resolve the absolute path to a tool binary (e.g. 'claude', 'codex').
+ *  On Windows prefers .exe, then extensionless, then .cmd.
+ *  Returns null when the tool is not on PATH.
+ */
+export declare function findToolPath(name: string): null | string;
+/** Build the shell command string from structured options. */
+export declare function buildShellCommand(opts: TmuxSessionOptions): string;
+/**
+ * Best-effort configure tmux session: mouse, scrollback, 256-color, and truecolor.
+ * Batches all settings into a single tmux invocation using \; command separator.
+ * Unix only — Windows uses psmux (native ConPTY handles mouse/color natively).
+ */
+export declare function configureTmuxSession(): void;

package/dist/lib/tmux-session.js

@@ -0,0 +1,86 @@
+import { execSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import * as os from 'node:os';
+import path from 'node:path';
+import { resolveExecutable } from './runtime/executable-policy.js';
+import { isNonWindowsPlatform, resolveTmuxColorModeForPlatform, } from './runtime/platform-adapter.js';
+import { quoteForSh } from './tmux-primitives.js';
+export function buildTmuxRuntimeBootstrapCommands(platform = process.platform, enableMouse = true) {
+    const commands = [];
+    if (enableMouse) {
+        commands.push('tmux set-option -g mouse on >/dev/null 2>&1 || true');
+    }
+    // Increase scrollback buffer from default 2000
+    commands.push('tmux set-option -g history-limit 50000 >/dev/null 2>&1 || true');
+    // Configure terminal overrides for truecolor on Unix.
+    // Note: default-terminal is set before session creation.
+    // Windows uses psmux (native ConPTY) which handles color/cursor natively.
+    if (isNonWindowsPlatform(platform)) {
+        commands.push('tmux set -a terminal-overrides ",xterm*:Tc,alacritty:Tc" >/dev/null 2>&1 || true');
+    }
+    return commands;
+}
+/** Color mode policy for tmux-launched sessions. */
+export function resolveTmuxColorMode(platform = process.platform) {
+    return resolveTmuxColorModeForPlatform(platform);
+}
+/**
+ * Resolve the absolute path to a tool binary (e.g. 'claude', 'codex').
+ *  On Windows prefers .exe, then extensionless, then .cmd.
+ *  Returns null when the tool is not on PATH.
+ */
+export function findToolPath(name) {
+    return resolveExecutable(name, { windowsProfile: 'exeThenExtensionlessThenCmd' });
+}
+/** Build the shell command string from structured options. */
+export function buildShellCommand(opts) {
+    const { toolPath, toolArgs, promptText, enableMouse = true, platform = process.platform } = opts;
+    const colorMode = resolveTmuxColorMode(platform);
+    const parts = buildTmuxRuntimeBootstrapCommands(platform, enableMouse);
+    const cmdParts = [];
+    cmdParts.push(quoteForSh(toolPath));
+    for (const arg of toolArgs) {
+        cmdParts.push(quoteForSh(arg));
+    }
+    // Deliver prompt via temp file — avoids nested bash→tmux→sh quoting
+    if (promptText) {
+        const tmpFile = path.join(os.tmpdir(), `aiwcli-prompt-${Date.now()}-${process.pid}.txt`);
+        writeFileSync(tmpFile, promptText, { encoding: 'utf8', mode: 0o600 });
+        const bootstrap = `Read startup instructions from this file path before taking action: ${tmpFile}. Use that file as the initial context.`;
+        cmdParts.push(quoteForSh(bootstrap));
+    }
+    // Export COLORTERM only when truecolor is intentionally enabled.
+    if (colorMode === 'truecolor') {
+        parts.push('export COLORTERM=truecolor');
+    }
+    else {
+        parts.push('unset COLORTERM');
+    }
+    parts.push(`exec ${cmdParts.join(' ')}`);
+    return parts.join('; ');
+}
+/**
+ * Best-effort configure tmux session: mouse, scrollback, 256-color, and truecolor.
+ * Batches all settings into a single tmux invocation using \; command separator.
+ * Unix only — Windows uses psmux (native ConPTY handles mouse/color natively).
+ */
+export function configureTmuxSession() {
+    if (!isNonWindowsPlatform())
+        return;
+    try {
+        execSync('tmux set-option -g mouse on \\; ' +
+            'set-option -g history-limit 50000 \\; ' +
+            'set -g default-terminal "tmux-256color" \\; ' +
+            'set -a terminal-overrides ",xterm*:Tc,alacritty:Tc"', { stdio: 'ignore', timeout: 3000 });
+    }
+    catch {
+        // Fallback: tmux-256color may not be in terminfo — try screen-256color
+        try {
+            execSync('tmux set-option -g mouse on \\; ' +
+                'set-option -g history-limit 50000 \\; ' +
+                'set -g default-terminal "screen-256color" \\; ' +
+                'set -a terminal-overrides ",xterm*:Tc,alacritty:Tc"', { stdio: 'ignore', timeout: 3000 });
+        }
+        catch { /* best-effort */ }
+    }
+}

package/dist/lib/tty-detection.js

@@ -36,7 +36,7 @@ export function shouldUseColors(proc = process) {
     const env = proc.env ?? process.env;
     const noColor = env.NO_COLOR;
     const forceColor = env.FORCE_COLOR;
-    // NO_COLOR takes precedence (any value disables colors)
+    // NO_COLOR takes precedence (unknown value disables colors)
     if (noColor !== undefined) {
         return false;
     }