@iaforged/context-code 1.0.72 → 1.0.74

package/dist/src/utils/swarm/backends/TmuxBackend.js

@@ -0,0 +1,574 @@
+import { logForDebugging } from '../../debug.js';
+import { execFileNoThrow } from '../../execFileNoThrow.js';
+import { logError } from '../../log.js';
+import { count } from '../../array.js';
+import { sleep } from '../../sleep.js';
+import { getSwarmSocketName, HIDDEN_SESSION_NAME, SWARM_SESSION_NAME, SWARM_VIEW_WINDOW_NAME, TMUX_COMMAND, } from '../constants.js';
+import { getLeaderPaneId, isInsideTmux as isInsideTmuxFromDetection, isTmuxAvailable, } from './detection.js';
+import { registerTmuxBackend } from './registry.js';
+// Track whether the first pane has been used for external swarm session
+let firstPaneUsedForExternal = false;
+// Cached leader window target (session:window format) to avoid repeated queries
+let cachedLeaderWindowTarget = null;
+// Lock mechanism to prevent race conditions when spawning teammates in parallel
+let paneCreationLock = Promise.resolve();
+// Delay after pane creation to allow shell initialization (loading rc files, prompts, etc.)
+// 200ms is enough for most shell configurations including slow ones like starship/oh-my-zsh
+const PANE_SHELL_INIT_DELAY_MS = 200;
+function waitForPaneShellReady() {
+    return sleep(PANE_SHELL_INIT_DELAY_MS);
+}
+/**
+ * Acquires a lock for pane creation, ensuring sequential execution.
+ * Returns a release function that must be called when done.
+ */
+function acquirePaneCreationLock() {
+    let release;
+    const newLock = new Promise(resolve => {
+        release = resolve;
+    });
+    const previousLock = paneCreationLock;
+    paneCreationLock = newLock;
+    return previousLock.then(() => release);
+}
+/**
+ * Gets the tmux color name for a given agent color.
+ * These are tmux's built-in color names that work with pane-border-style.
+ */
+function getTmuxColorName(color) {
+    const tmuxColors = {
+        red: 'red',
+        blue: 'blue',
+        green: 'green',
+        yellow: 'yellow',
+        purple: 'magenta',
+        orange: 'colour208',
+        pink: 'colour205',
+        cyan: 'cyan',
+    };
+    return tmuxColors[color];
+}
+/**
+ * Runs a tmux command in the user's original tmux session (no socket override).
+ * Use this for operations that interact with the user's tmux panes (split-pane with leader).
+ */
+function runTmuxInUserSession(args) {
+    return execFileNoThrow(TMUX_COMMAND, args);
+}
+/**
+ * Runs a tmux command in the external swarm socket.
+ * Use this for operations in the standalone swarm session (when user is not in tmux).
+ */
+function runTmuxInSwarm(args) {
+    return execFileNoThrow(TMUX_COMMAND, ['-L', getSwarmSocketName(), ...args]);
+}
+/**
+ * TmuxBackend implements PaneBackend using tmux for pane management.
+ *
+ * When running INSIDE tmux (leader is in tmux):
+ * - Splits the current window to add teammates alongside the leader
+ * - Leader stays on left (30%), teammates on right (70%)
+ *
+ * When running OUTSIDE tmux (leader is in regular terminal):
+ * - Creates a claude-swarm session with a swarm-view window
+ * - All teammates are equally distributed (no leader pane)
+ */
+export class TmuxBackend {
+    type = 'tmux';
+    displayName = 'tmux';
+    supportsHideShow = true;
+    /**
+     * Checks if tmux is installed and available.
+     * Delegates to detection.ts for consistent detection logic.
+     */
+    async isAvailable() {
+        return isTmuxAvailable();
+    }
+    /**
+     * Checks if we're currently running inside a tmux session.
+     * Delegates to detection.ts for consistent detection logic.
+     */
+    async isRunningInside() {
+        return isInsideTmuxFromDetection();
+    }
+    /**
+     * Creates a new teammate pane in the swarm view.
+     * Uses a lock to prevent race conditions when multiple teammates are spawned in parallel.
+     */
+    async createTeammatePaneInSwarmView(name, color) {
+        const releaseLock = await acquirePaneCreationLock();
+        try {
+            const insideTmux = await this.isRunningInside();
+            if (insideTmux) {
+                return await this.createTeammatePaneWithLeader(name, color);
+            }
+            return await this.createTeammatePaneExternal(name, color);
+        }
+        finally {
+            releaseLock();
+        }
+    }
+    /**
+     * Sends a command to a specific pane.
+     */
+    async sendCommandToPane(paneId, command, useExternalSession = false) {
+        const runTmux = useExternalSession ? runTmuxInSwarm : runTmuxInUserSession;
+        const result = await runTmux(['send-keys', '-t', paneId, command, 'Enter']);
+        if (result.code !== 0) {
+            throw new Error(`Failed to send command to pane ${paneId}: ${result.stderr}`);
+        }
+    }
+    /**
+     * Sets the border color for a specific pane.
+     */
+    async setPaneBorderColor(paneId, color, useExternalSession = false) {
+        const tmuxColor = getTmuxColorName(color);
+        const runTmux = useExternalSession ? runTmuxInSwarm : runTmuxInUserSession;
+        // Set pane-specific border style using pane options (requires tmux 3.2+)
+        await runTmux([
+            'select-pane',
+            '-t',
+            paneId,
+            '-P',
+            `bg=default,fg=${tmuxColor}`,
+        ]);
+        await runTmux([
+            'set-option',
+            '-p',
+            '-t',
+            paneId,
+            'pane-border-style',
+            `fg=${tmuxColor}`,
+        ]);
+        await runTmux([
+            'set-option',
+            '-p',
+            '-t',
+            paneId,
+            'pane-active-border-style',
+            `fg=${tmuxColor}`,
+        ]);
+    }
+    /**
+     * Sets the title for a pane (shown in pane border if pane-border-status is set).
+     */
+    async setPaneTitle(paneId, name, color, useExternalSession = false) {
+        const tmuxColor = getTmuxColorName(color);
+        const runTmux = useExternalSession ? runTmuxInSwarm : runTmuxInUserSession;
+        // Set the pane title
+        await runTmux(['select-pane', '-t', paneId, '-T', name]);
+        // Enable pane border status with colored format
+        await runTmux([
+            'set-option',
+            '-p',
+            '-t',
+            paneId,
+            'pane-border-format',
+            `#[fg=${tmuxColor},bold] #{pane_title} #[default]`,
+        ]);
+    }
+    /**
+     * Enables pane border status for a window (shows pane titles).
+     */
+    async enablePaneBorderStatus(windowTarget, useExternalSession = false) {
+        const target = windowTarget || (await this.getCurrentWindowTarget());
+        if (!target) {
+            return;
+        }
+        const runTmux = useExternalSession ? runTmuxInSwarm : runTmuxInUserSession;
+        await runTmux([
+            'set-option',
+            '-w',
+            '-t',
+            target,
+            'pane-border-status',
+            'top',
+        ]);
+    }
+    /**
+     * Rebalances panes to achieve the desired layout.
+     */
+    async rebalancePanes(windowTarget, hasLeader) {
+        if (hasLeader) {
+            await this.rebalancePanesWithLeader(windowTarget);
+        }
+        else {
+            await this.rebalancePanesTiled(windowTarget);
+        }
+    }
+    /**
+     * Kills/closes a specific pane.
+     */
+    async killPane(paneId, useExternalSession = false) {
+        const runTmux = useExternalSession ? runTmuxInSwarm : runTmuxInUserSession;
+        const result = await runTmux(['kill-pane', '-t', paneId]);
+        return result.code === 0;
+    }
+    /**
+     * Hides a pane by moving it to a detached hidden session.
+     * Creates the hidden session if it doesn't exist, then uses break-pane to move the pane there.
+     */
+    async hidePane(paneId, useExternalSession = false) {
+        const runTmux = useExternalSession ? runTmuxInSwarm : runTmuxInUserSession;
+        // Create hidden session if it doesn't exist (detached, not visible)
+        await runTmux(['new-session', '-d', '-s', HIDDEN_SESSION_NAME]);
+        // Move the pane to the hidden session
+        const result = await runTmux([
+            'break-pane',
+            '-d',
+            '-s',
+            paneId,
+            '-t',
+            `${HIDDEN_SESSION_NAME}:`,
+        ]);
+        if (result.code === 0) {
+            logForDebugging(`[TmuxBackend] Hidden pane ${paneId}`);
+        }
+        else {
+            logForDebugging(`[TmuxBackend] Failed to hide pane ${paneId}: ${result.stderr}`);
+        }
+        return result.code === 0;
+    }
+    /**
+     * Shows a previously hidden pane by joining it back into the target window.
+     * Uses `tmux join-pane` to move the pane back, then reapplies main-vertical layout
+     * with leader at 30%.
+     */
+    async showPane(paneId, targetWindowOrPane, useExternalSession = false) {
+        const runTmux = useExternalSession ? runTmuxInSwarm : runTmuxInUserSession;
+        // join-pane -s: source pane to move
+        // -t: target window/pane to join into
+        // -h: join horizontally (side by side)
+        const result = await runTmux([
+            'join-pane',
+            '-h',
+            '-s',
+            paneId,
+            '-t',
+            targetWindowOrPane,
+        ]);
+        if (result.code !== 0) {
+            logForDebugging(`[TmuxBackend] Failed to show pane ${paneId}: ${result.stderr}`);
+            return false;
+        }
+        logForDebugging(`[TmuxBackend] Showed pane ${paneId} in ${targetWindowOrPane}`);
+        // Reapply main-vertical layout with leader at 30%
+        await runTmux(['select-layout', '-t', targetWindowOrPane, 'main-vertical']);
+        // Get the first pane (leader) and resize to 30%
+        const panesResult = await runTmux([
+            'list-panes',
+            '-t',
+            targetWindowOrPane,
+            '-F',
+            '#{pane_id}',
+        ]);
+        const panes = panesResult.stdout.trim().split('\n').filter(Boolean);
+        if (panes[0]) {
+            await runTmux(['resize-pane', '-t', panes[0], '-x', '30%']);
+        }
+        return true;
+    }
+    // Private helper methods
+    /**
+     * Gets the leader's pane ID.
+     * Uses the TMUX_PANE env var captured at module load to ensure we always
+     * get the leader's original pane, even if the user has switched panes.
+     */
+    async getCurrentPaneId() {
+        // Use the pane ID captured at startup (from TMUX_PANE env var)
+        const leaderPane = getLeaderPaneId();
+        if (leaderPane) {
+            return leaderPane;
+        }
+        // Fallback to dynamic query (shouldn't happen if we're inside tmux)
+        const result = await execFileNoThrow(TMUX_COMMAND, [
+            'display-message',
+            '-p',
+            '#{pane_id}',
+        ]);
+        if (result.code !== 0) {
+            logForDebugging(`[TmuxBackend] Failed to get current pane ID (exit ${result.code}): ${result.stderr}`);
+            return null;
+        }
+        return result.stdout.trim();
+    }
+    /**
+     * Gets the leader's window target (session:window format).
+     * Uses the leader's pane ID to query for its window, ensuring we get the
+     * correct window even if the user has switched to a different window.
+     * Caches the result since the leader's window won't change.
+     */
+    async getCurrentWindowTarget() {
+        // Return cached value if available
+        if (cachedLeaderWindowTarget) {
+            return cachedLeaderWindowTarget;
+        }
+        // Build the command - use -t to target the leader's pane specifically
+        const leaderPane = getLeaderPaneId();
+        const args = ['display-message'];
+        if (leaderPane) {
+            args.push('-t', leaderPane);
+        }
+        args.push('-p', '#{session_name}:#{window_index}');
+        const result = await execFileNoThrow(TMUX_COMMAND, args);
+        if (result.code !== 0) {
+            logForDebugging(`[TmuxBackend] Failed to get current window target (exit ${result.code}): ${result.stderr}`);
+            return null;
+        }
+        cachedLeaderWindowTarget = result.stdout.trim();
+        return cachedLeaderWindowTarget;
+    }
+    /**
+     * Gets the number of panes in a window.
+     */
+    async getCurrentWindowPaneCount(windowTarget, useSwarmSocket = false) {
+        const target = windowTarget || (await this.getCurrentWindowTarget());
+        if (!target) {
+            return null;
+        }
+        const args = ['list-panes', '-t', target, '-F', '#{pane_id}'];
+        const result = useSwarmSocket
+            ? await runTmuxInSwarm(args)
+            : await runTmuxInUserSession(args);
+        if (result.code !== 0) {
+            logError(new Error(`[TmuxBackend] Failed to get pane count for ${target} (exit ${result.code}): ${result.stderr}`));
+            return null;
+        }
+        return count(result.stdout.trim().split('\n'), Boolean);
+    }
+    /**
+     * Checks if a tmux session exists in the swarm socket.
+     */
+    async hasSessionInSwarm(sessionName) {
+        const result = await runTmuxInSwarm(['has-session', '-t', sessionName]);
+        return result.code === 0;
+    }
+    /**
+     * Creates the swarm session with a single window for teammates when running outside tmux.
+     */
+    async createExternalSwarmSession() {
+        const sessionExists = await this.hasSessionInSwarm(SWARM_SESSION_NAME);
+        if (!sessionExists) {
+            const result = await runTmuxInSwarm([
+                'new-session',
+                '-d',
+                '-s',
+                SWARM_SESSION_NAME,
+                '-n',
+                SWARM_VIEW_WINDOW_NAME,
+                '-P',
+                '-F',
+                '#{pane_id}',
+            ]);
+            if (result.code !== 0) {
+                throw new Error(`Failed to create swarm session: ${result.stderr || 'Unknown error'}`);
+            }
+            const paneId = result.stdout.trim();
+            const windowTarget = `${SWARM_SESSION_NAME}:${SWARM_VIEW_WINDOW_NAME}`;
+            logForDebugging(`[TmuxBackend] Created external swarm session with window ${windowTarget}, pane ${paneId}`);
+            return { windowTarget, paneId };
+        }
+        // Session exists, check if swarm-view window exists
+        const listResult = await runTmuxInSwarm([
+            'list-windows',
+            '-t',
+            SWARM_SESSION_NAME,
+            '-F',
+            '#{window_name}',
+        ]);
+        const windows = listResult.stdout.trim().split('\n').filter(Boolean);
+        const windowTarget = `${SWARM_SESSION_NAME}:${SWARM_VIEW_WINDOW_NAME}`;
+        if (windows.includes(SWARM_VIEW_WINDOW_NAME)) {
+            const paneResult = await runTmuxInSwarm([
+                'list-panes',
+                '-t',
+                windowTarget,
+                '-F',
+                '#{pane_id}',
+            ]);
+            const panes = paneResult.stdout.trim().split('\n').filter(Boolean);
+            return { windowTarget, paneId: panes[0] || '' };
+        }
+        // Create the swarm-view window
+        const createResult = await runTmuxInSwarm([
+            'new-window',
+            '-t',
+            SWARM_SESSION_NAME,
+            '-n',
+            SWARM_VIEW_WINDOW_NAME,
+            '-P',
+            '-F',
+            '#{pane_id}',
+        ]);
+        if (createResult.code !== 0) {
+            throw new Error(`Failed to create swarm-view window: ${createResult.stderr || 'Unknown error'}`);
+        }
+        return { windowTarget, paneId: createResult.stdout.trim() };
+    }
+    /**
+     * Creates a teammate pane when running inside tmux (with leader).
+     */
+    async createTeammatePaneWithLeader(teammateName, teammateColor) {
+        const currentPaneId = await this.getCurrentPaneId();
+        const windowTarget = await this.getCurrentWindowTarget();
+        if (!currentPaneId || !windowTarget) {
+            throw new Error('Could not determine current tmux pane/window');
+        }
+        const paneCount = await this.getCurrentWindowPaneCount(windowTarget);
+        if (paneCount === null) {
+            throw new Error('Could not determine pane count for current window');
+        }
+        const isFirstTeammate = paneCount === 1;
+        let splitResult;
+        if (isFirstTeammate) {
+            // First teammate: split horizontally from the leader pane
+            splitResult = await execFileNoThrow(TMUX_COMMAND, [
+                'split-window',
+                '-t',
+                currentPaneId,
+                '-h',
+                '-l',
+                '70%',
+                '-P',
+                '-F',
+                '#{pane_id}',
+            ]);
+        }
+        else {
+            // Additional teammates: split from an existing teammate pane
+            const listResult = await execFileNoThrow(TMUX_COMMAND, [
+                'list-panes',
+                '-t',
+                windowTarget,
+                '-F',
+                '#{pane_id}',
+            ]);
+            const panes = listResult.stdout.trim().split('\n').filter(Boolean);
+            const teammatePanes = panes.slice(1);
+            const teammateCount = teammatePanes.length;
+            const splitVertically = teammateCount % 2 === 1;
+            const targetPaneIndex = Math.floor((teammateCount - 1) / 2);
+            const targetPane = teammatePanes[targetPaneIndex] ||
+                teammatePanes[teammatePanes.length - 1];
+            splitResult = await execFileNoThrow(TMUX_COMMAND, [
+                'split-window',
+                '-t',
+                targetPane,
+                splitVertically ? '-v' : '-h',
+                '-P',
+                '-F',
+                '#{pane_id}',
+            ]);
+        }
+        if (splitResult.code !== 0) {
+            throw new Error(`Failed to create teammate pane: ${splitResult.stderr}`);
+        }
+        const paneId = splitResult.stdout.trim();
+        logForDebugging(`[TmuxBackend] Created teammate pane for ${teammateName}: ${paneId}`);
+        await this.setPaneBorderColor(paneId, teammateColor);
+        await this.setPaneTitle(paneId, teammateName, teammateColor);
+        await this.rebalancePanesWithLeader(windowTarget);
+        // Wait for shell to initialize before returning, so commands can be sent immediately
+        await waitForPaneShellReady();
+        return { paneId, isFirstTeammate };
+    }
+    /**
+     * Creates a teammate pane when running outside tmux (no leader in tmux).
+     */
+    async createTeammatePaneExternal(teammateName, teammateColor) {
+        const { windowTarget, paneId: firstPaneId } = await this.createExternalSwarmSession();
+        const paneCount = await this.getCurrentWindowPaneCount(windowTarget, true);
+        if (paneCount === null) {
+            throw new Error('Could not determine pane count for swarm window');
+        }
+        const isFirstTeammate = !firstPaneUsedForExternal && paneCount === 1;
+        let paneId;
+        if (isFirstTeammate) {
+            paneId = firstPaneId;
+            firstPaneUsedForExternal = true;
+            logForDebugging(`[TmuxBackend] Using initial pane for first teammate ${teammateName}: ${paneId}`);
+            await this.enablePaneBorderStatus(windowTarget, true);
+        }
+        else {
+            const listResult = await runTmuxInSwarm([
+                'list-panes',
+                '-t',
+                windowTarget,
+                '-F',
+                '#{pane_id}',
+            ]);
+            const panes = listResult.stdout.trim().split('\n').filter(Boolean);
+            const teammateCount = panes.length;
+            const splitVertically = teammateCount % 2 === 1;
+            const targetPaneIndex = Math.floor((teammateCount - 1) / 2);
+            const targetPane = panes[targetPaneIndex] || panes[panes.length - 1];
+            const splitResult = await runTmuxInSwarm([
+                'split-window',
+                '-t',
+                targetPane,
+                splitVertically ? '-v' : '-h',
+                '-P',
+                '-F',
+                '#{pane_id}',
+            ]);
+            if (splitResult.code !== 0) {
+                throw new Error(`Failed to create teammate pane: ${splitResult.stderr}`);
+            }
+            paneId = splitResult.stdout.trim();
+            logForDebugging(`[TmuxBackend] Created teammate pane for ${teammateName}: ${paneId}`);
+        }
+        await this.setPaneBorderColor(paneId, teammateColor, true);
+        await this.setPaneTitle(paneId, teammateName, teammateColor, true);
+        await this.rebalancePanesTiled(windowTarget);
+        // Wait for shell to initialize before returning, so commands can be sent immediately
+        await waitForPaneShellReady();
+        return { paneId, isFirstTeammate };
+    }
+    /**
+     * Rebalances panes in a window with a leader.
+     */
+    async rebalancePanesWithLeader(windowTarget) {
+        const listResult = await runTmuxInUserSession([
+            'list-panes',
+            '-t',
+            windowTarget,
+            '-F',
+            '#{pane_id}',
+        ]);
+        const panes = listResult.stdout.trim().split('\n').filter(Boolean);
+        if (panes.length <= 2) {
+            return;
+        }
+        await runTmuxInUserSession([
+            'select-layout',
+            '-t',
+            windowTarget,
+            'main-vertical',
+        ]);
+        const leaderPane = panes[0];
+        await runTmuxInUserSession(['resize-pane', '-t', leaderPane, '-x', '30%']);
+        logForDebugging(`[TmuxBackend] Rebalanced ${panes.length - 1} teammate panes with leader`);
+    }
+    /**
+     * Rebalances panes in a window without a leader (tiled layout).
+     */
+    async rebalancePanesTiled(windowTarget) {
+        const listResult = await runTmuxInSwarm([
+            'list-panes',
+            '-t',
+            windowTarget,
+            '-F',
+            '#{pane_id}',
+        ]);
+        const panes = listResult.stdout.trim().split('\n').filter(Boolean);
+        if (panes.length <= 1) {
+            return;
+        }
+        await runTmuxInSwarm(['select-layout', '-t', windowTarget, 'tiled']);
+        logForDebugging(`[TmuxBackend] Rebalanced ${panes.length} teammate panes with tiled layout`);
+    }
+}
+// Register the backend with the registry when this module is imported.
+// This side effect is intentional - the registry needs backends to self-register to avoid circular dependencies.
+// eslint-disable-next-line custom-rules/no-top-level-side-effects
+registerTmuxBackend(TmuxBackend);

package/dist/src/utils/swarm/backends/detection.js

@@ -0,0 +1,112 @@
+import { env } from '../../env.js';
+import { execFileNoThrow } from '../../execFileNoThrow.js';
+import { TMUX_COMMAND } from '../constants.js';
+/**
+ * Captured at module load time to detect if the user started Claude from within tmux.
+ * Shell.ts may override TMUX env var later, so we capture the original value.
+ */
+// eslint-disable-next-line custom-rules/no-process-env-top-level
+const ORIGINAL_USER_TMUX = process.env.TMUX;
+/**
+ * Captured at module load time to get the leader's tmux pane ID.
+ * TMUX_PANE is set by tmux to the pane ID (e.g., %0, %1) when a process runs inside tmux.
+ * We capture this at startup so we always know the leader's original pane, even if
+ * the user switches to a different pane later.
+ */
+// eslint-disable-next-line custom-rules/no-process-env-top-level
+const ORIGINAL_TMUX_PANE = process.env.TMUX_PANE;
+/** Cached result for isInsideTmux */
+let isInsideTmuxCached = null;
+/** Cached result for isInITerm2 */
+let isInITerm2Cached = null;
+/**
+ * Checks if we're currently running inside a tmux session (synchronous version).
+ * Uses the original TMUX value captured at module load, not process.env.TMUX,
+ * because Shell.ts overrides TMUX when Claude's socket is initialized.
+ *
+ * IMPORTANT: We ONLY check the TMUX env var. We do NOT run `tmux display-message`
+ * as a fallback because that command will succeed if ANY tmux server is running
+ * on the system, not just if THIS process is inside tmux.
+ */
+export function isInsideTmuxSync() {
+    return !!ORIGINAL_USER_TMUX;
+}
+/**
+ * Checks if we're currently running inside a tmux session.
+ * Uses the original TMUX value captured at module load, not process.env.TMUX,
+ * because Shell.ts overrides TMUX when Claude's socket is initialized.
+ * Caches the result since this won't change during the process lifetime.
+ *
+ * IMPORTANT: We ONLY check the TMUX env var. We do NOT run `tmux display-message`
+ * as a fallback because that command will succeed if ANY tmux server is running
+ * on the system, not just if THIS process is inside tmux.
+ */
+export async function isInsideTmux() {
+    if (isInsideTmuxCached !== null) {
+        return isInsideTmuxCached;
+    }
+    // Check the original TMUX env var (captured at module load)
+    // This tells us if the user started Claude from within their tmux session
+    // If TMUX is not set, we are NOT inside tmux - period.
+    isInsideTmuxCached = !!ORIGINAL_USER_TMUX;
+    return isInsideTmuxCached;
+}
+/**
+ * Gets the leader's tmux pane ID captured at module load.
+ * Returns null if not running inside tmux.
+ */
+export function getLeaderPaneId() {
+    return ORIGINAL_TMUX_PANE || null;
+}
+/**
+ * Checks if tmux is available on the system (installed and in PATH).
+ */
+export async function isTmuxAvailable() {
+    const result = await execFileNoThrow(TMUX_COMMAND, ['-V']);
+    return result.code === 0;
+}
+/**
+ * Checks if we're currently running inside iTerm2.
+ * Uses multiple detection methods:
+ * 1. TERM_PROGRAM env var set to "iTerm.app"
+ * 2. ITERM_SESSION_ID env var is present
+ * 3. env.terminal detection from utils/env.ts
+ *
+ * Caches the result since this won't change during the process lifetime.
+ *
+ * Note: iTerm2 backend uses AppleScript (osascript) which is built into macOS,
+ * so no external CLI tool installation is required.
+ */
+export function isInITerm2() {
+    if (isInITerm2Cached !== null) {
+        return isInITerm2Cached;
+    }
+    // Check multiple indicators for iTerm2
+    const termProgram = process.env.TERM_PROGRAM;
+    const hasItermSessionId = !!process.env.ITERM_SESSION_ID;
+    const terminalIsITerm = env.terminal === 'iTerm.app';
+    isInITerm2Cached =
+        termProgram === 'iTerm.app' || hasItermSessionId || terminalIsITerm;
+    return isInITerm2Cached;
+}
+/**
+ * The it2 CLI command name.
+ */
+export const IT2_COMMAND = 'it2';
+/**
+ * Checks if the it2 CLI tool is available AND can reach the iTerm2 Python API.
+ * Uses 'session list' (not '--version') because --version succeeds even when
+ * the Python API is disabled in iTerm2 preferences — which would cause
+ * 'session split' to fail later with no fallback.
+ */
+export async function isIt2CliAvailable() {
+    const result = await execFileNoThrow(IT2_COMMAND, ['session', 'list']);
+    return result.code === 0;
+}
+/**
+ * Resets all cached detection results. Used for testing.
+ */
+export function resetDetectionCache() {
+    isInsideTmuxCached = null;
+    isInITerm2Cached = null;
+}