cortex-agents 2.3.1 → 4.0.0

package/dist/utils/terminal.js

@@ -36,7 +36,11 @@ export function readSession(worktreePath) {
 }
 // ─── Helper: build the shell command for the new tab ─────────────────────────
 function buildTabCommand(opts) {
-    return `cd "${opts.worktreePath}" && "${opts.opencodeBin}" --agent ${opts.agent}`;
+    // Escape all user-controlled inputs to prevent command injection
+    const safePath = shellEscape(opts.worktreePath);
+    const safeBin = shellEscape(opts.opencodeBin);
+    const safeAgent = shellEscape(opts.agent);
+    return `cd "${safePath}" && "${safeBin}" --agent "${safeAgent}"`;
 }
 // ─── Helper: safe process kill ───────────────────────────────────────────────
 function killPid(pid) {
@@ -51,7 +55,165 @@ function killPid(pid) {
 // ═════════════════════════════════════════════════════════════════════════════
 // Driver Implementations
 // ═════════════════════════════════════════════════════════════════════════════
-// ─── tmux (multiplexer — highest priority) ───────────────────────────────────
+// ─── IDE Drivers (highest priority — prefer integrated terminals) ────────────
+/**
+ * Base class for IDE drivers that use CLI commands to open windows.
+ * IDEs don't support programmatic closing, so closeTab returns false.
+ */
+class IDEDriver {
+    async openTab(opts) {
+        const cliAvailable = await which(this.cliBinary);
+        if (!cliAvailable) {
+            throw new Error(`${this.name} CLI not found. Install the \`${this.cliBinary}\` command.`);
+        }
+        // Open the worktree in a new IDE window
+        // The integrated terminal will automatically be available
+        try {
+            await exec(this.cliBinary, ["--new-window", opts.worktreePath]);
+            return {
+                sessionId: `${this.name}-${opts.branchName}`,
+            };
+        }
+        catch {
+            // Some IDEs don't support --new-window, try without
+            try {
+                await exec(this.cliBinary, [opts.worktreePath]);
+                return {
+                    sessionId: `${this.name}-${opts.branchName}`,
+                };
+            }
+            catch {
+                throw new Error(`Failed to open ${this.name} window`);
+            }
+        }
+    }
+    async closeTab(session) {
+        // IDEs don't support programmatic tab/window closing via CLI
+        // Return false to indicate we couldn't close it
+        return false;
+    }
+}
+// ─── VS Code ─────────────────────────────────────────────────────────────────
+class VSCodeDriver extends IDEDriver {
+    name = "vscode";
+    cliBinary = "code";
+    envVars = ["VSCODE_PID", "VSCODE_CWD"];
+    detect() {
+        return !!process.env.VSCODE_PID ||
+            !!process.env.VSCODE_CWD ||
+            process.env.TERM_PROGRAM === "vscode";
+    }
+    async openTab(opts) {
+        const cliAvailable = await which(this.cliBinary);
+        if (!cliAvailable) {
+            throw new Error("VS Code CLI not found. Install the `code` command via VS Code's Command Palette (Cmd+Shift+P → 'Shell Command: Install code command in PATH')");
+        }
+        try {
+            // Open in new window with the worktree folder
+            await exec(this.cliBinary, ["--new-window", opts.worktreePath]);
+            return {
+                sessionId: `vscode-${opts.branchName}`,
+            };
+        }
+        catch {
+            throw new Error("Failed to open VS Code window");
+        }
+    }
+}
+// ─── Cursor ──────────────────────────────────────────────────────────────────
+class CursorDriver extends IDEDriver {
+    name = "cursor";
+    cliBinary = "cursor";
+    envVars = ["CURSOR_TRACE_ID", "CURSOR_SHELL_VERSION"];
+    detect() {
+        return !!process.env.CURSOR_TRACE_ID ||
+            !!process.env.CURSOR_SHELL_VERSION;
+    }
+}
+// ─── Windsurf ────────────────────────────────────────────────────────────────
+class WindsurfDriver extends IDEDriver {
+    name = "windsurf";
+    cliBinary = "windsurf";
+    envVars = ["WINDSURF_PARENT_PROCESS", "WINDSURF_EDITOR"];
+    detect() {
+        return !!process.env.WINDSURF_PARENT_PROCESS ||
+            !!process.env.WINDSURF_EDITOR;
+    }
+    async openTab(opts) {
+        const cliAvailable = await which(this.cliBinary);
+        if (!cliAvailable) {
+            throw new Error("Windsurf CLI not found. Ensure Windsurf is installed and the `windsurf` command is in PATH.");
+        }
+        // Windsurf may not support --new-window, try direct path
+        try {
+            await exec(this.cliBinary, [opts.worktreePath]);
+            return {
+                sessionId: `windsurf-${opts.branchName}`,
+            };
+        }
+        catch {
+            throw new Error("Failed to open Windsurf window");
+        }
+    }
+}
+// ─── Zed ─────────────────────────────────────────────────────────────────────
+class ZedDriver extends IDEDriver {
+    name = "zed";
+    cliBinary = "zed";
+    envVars = ["ZED_TERM"];
+    detect() {
+        return !!process.env.ZED_TERM || process.env.TERM_PROGRAM === "zed";
+    }
+    async openTab(opts) {
+        const cliAvailable = await which(this.cliBinary);
+        if (!cliAvailable) {
+            throw new Error("Zed CLI not found. Ensure Zed is installed and the `zed` command is in PATH.");
+        }
+        try {
+            await exec(this.cliBinary, [opts.worktreePath]);
+            return {
+                sessionId: `zed-${opts.branchName}`,
+            };
+        }
+        catch {
+            throw new Error("Failed to open Zed window");
+        }
+    }
+}
+// ─── JetBrains IDEs ──────────────────────────────────────────────────────────
+class JetBrainsDriver {
+    name = "jetbrains";
+    detect() {
+        const env = process.env.TERMINAL_EMULATOR || "";
+        return env.includes("JetBrains") || !!process.env.JETBRAINS_IDE;
+    }
+    async openTab(opts) {
+        // JetBrains IDEs don't have a universal CLI for opening folders
+        // We'll try common JetBrains CLI tools
+        const jetbrainsClis = ["idea", "webstorm", "pycharm", "goland", "clion", "rustrover"];
+        for (const cli of jetbrainsClis) {
+            const cliAvailable = await which(cli);
+            if (cliAvailable) {
+                try {
+                    await exec(cli, [opts.worktreePath]);
+                    return {
+                        sessionId: `jetbrains-${opts.branchName}`,
+                    };
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        throw new Error("JetBrains IDE CLI not found. Open the worktree manually in your JetBrains IDE:\n" +
+            `  File → Open → ${opts.worktreePath}`);
+    }
+    async closeTab(session) {
+        // JetBrains IDEs don't support programmatic closing
+        return false;
+    }
+}
+// ─── tmux (multiplexer — highest priority among terminals) ───────────────────
 class TmuxDriver {
     name = "tmux";
     detect() {
@@ -494,6 +656,159 @@ class GnomeTerminalDriver {
         return false;
     }
 }
+// ─── Ghostty (macOS/Linux) ───────────────────────────────────────────────────
+class GhosttyDriver {
+    name = "ghostty";
+    detect() {
+        return !!process.env.GHOSTTY_RESOURCES_DIR ||
+            process.env.TERM_PROGRAM === "ghostty";
+    }
+    async openTab(opts) {
+        const safePath = shellEscape(opts.worktreePath);
+        const safeBin = shellEscape(opts.opencodeBin);
+        const safeAgent = shellEscape(opts.agent);
+        // macOS: use AppleScript to create a new tab in the running Ghostty instance
+        if (process.platform === "darwin") {
+            const script = `tell application "Ghostty"
+  activate
+end tell
+tell application "System Events"
+  tell process "Ghostty"
+    keystroke "t" using command down
+    delay 0.3
+    keystroke "cd \\"${safePath}\\" && \\"${safeBin}\\" --agent ${safeAgent}"
+    key code 36
+  end tell
+end tell`;
+            try {
+                await exec("osascript", ["-e", script]);
+                return {};
+            }
+            catch {
+                // Fall through to spawn
+            }
+        }
+        // Linux / fallback: spawn a new ghostty window
+        const cmd = buildTabCommand(opts);
+        const ghosttyBin = await which("ghostty");
+        if (ghosttyBin) {
+            const child = spawn("ghostty", [
+                "-e",
+                "bash",
+                "-c",
+                cmd,
+            ], { cwd: opts.worktreePath });
+            return { pid: child.pid ?? undefined };
+        }
+        throw new Error("Failed to open Ghostty tab");
+    }
+    async closeTab(session) {
+        if (session.pid)
+            return killPid(session.pid);
+        return false;
+    }
+}
+// ─── Alacritty (Linux/macOS) ─────────────────────────────────────────────────
+class AlacrittyDriver {
+    name = "alacritty";
+    detect() {
+        return !!process.env.ALACRITTY_WINDOW_ID ||
+            !!process.env.ALACRITTY_LOG ||
+            process.env.TERM_PROGRAM === "alacritty";
+    }
+    async openTab(opts) {
+        const cmd = buildTabCommand(opts);
+        // Alacritty doesn't support tabs natively — open a new window
+        const child = spawn("alacritty", [
+            "--working-directory",
+            opts.worktreePath,
+            "--title",
+            `Worktree: ${opts.branchName}`,
+            "-e",
+            "bash",
+            "-c",
+            cmd,
+        ], { cwd: opts.worktreePath });
+        return { pid: child.pid ?? undefined };
+    }
+    async closeTab(session) {
+        if (session.pid)
+            return killPid(session.pid);
+        return false;
+    }
+}
+// ─── Hyper (Electron-based) ──────────────────────────────────────────────────
+class HyperDriver {
+    name = "hyper";
+    detect() {
+        return process.env.TERM_PROGRAM === "Hyper";
+    }
+    async openTab(opts) {
+        const safePath = shellEscape(opts.worktreePath);
+        const safeBin = shellEscape(opts.opencodeBin);
+        const safeAgent = shellEscape(opts.agent);
+        // macOS: use AppleScript to open a new tab in Hyper
+        if (process.platform === "darwin") {
+            const script = `tell application "Hyper"
+  activate
+end tell
+tell application "System Events"
+  tell process "Hyper"
+    keystroke "t" using command down
+    delay 0.3
+    keystroke "cd \\"${safePath}\\" && \\"${safeBin}\\" --agent ${safeAgent}"
+    key code 36
+  end tell
+end tell`;
+            try {
+                await exec("osascript", ["-e", script]);
+                return {};
+            }
+            catch {
+                // Fall through to spawn
+            }
+        }
+        // Fallback: spawn via hyper CLI
+        const hyperBin = await which("hyper");
+        if (hyperBin) {
+            const child = spawn("hyper", [opts.worktreePath], { cwd: opts.worktreePath });
+            return { pid: child.pid ?? undefined };
+        }
+        throw new Error("Failed to open Hyper tab");
+    }
+    async closeTab(session) {
+        if (session.pid)
+            return killPid(session.pid);
+        return false;
+    }
+}
+// ─── Rio (Rust-based terminal) ───────────────────────────────────────────────
+class RioDriver {
+    name = "rio";
+    detect() {
+        return process.env.TERM_PROGRAM === "rio";
+    }
+    async openTab(opts) {
+        const cmd = buildTabCommand(opts);
+        // Rio supports tabs but has no IPC — spawn a new window
+        const rioBin = await which("rio");
+        if (rioBin) {
+            const child = spawn("rio", [
+                "-e",
+                "bash",
+                "-c",
+                cmd,
+            ], { cwd: opts.worktreePath });
+            return { pid: child.pid ?? undefined };
+        }
+        throw new Error("Failed to open Rio terminal");
+    }
+    async closeTab(session) {
+        if (session.pid)
+            return killPid(session.pid);
+        return false;
+    }
+}
 // ─── Fallback (PID-based, always matches) ────────────────────────────────────
 class FallbackDriver {
     name = "fallback";
@@ -571,17 +886,32 @@ class FallbackDriver {
 /**
  * Ordered list of terminal drivers. Detection runs first-to-last.
  *
- * Priority: multiplexers first (tmux), then terminal emulators, then fallback.
- * This ensures that if the user is in tmux inside iTerm2, we open a tmux window.
+ * Priority: IDEs first (vscode, cursor, windsurf), then multiplexers (tmux),
+ * then terminal emulators, then fallback.
+ * This ensures that if the user is in VS Code's terminal, we offer to open
+ * in VS Code rather than a standalone terminal.
  */
 const DRIVERS = [
+    // IDE drivers - highest priority (prefer integrated terminals)
+    new VSCodeDriver(),
+    new CursorDriver(),
+    new WindsurfDriver(),
+    new ZedDriver(),
+    new JetBrainsDriver(),
+    // Multiplexer
     new TmuxDriver(),
+    // Terminal emulators
     new ITerm2Driver(),
     new TerminalAppDriver(),
     new KittyDriver(),
     new WeztermDriver(),
+    new GhosttyDriver(),
+    new AlacrittyDriver(),
+    new HyperDriver(),
+    new RioDriver(),
     new KonsoleDriver(),
     new GnomeTerminalDriver(),
+    // Fallback
     new FallbackDriver(),
 ];
 /** Map of driver name → driver instance for reverse lookup. */
@@ -612,7 +942,7 @@ export function getDriverByName(name) {
  * This is the main entry point for worktree_remove cleanup.
  */
 export async function closeSession(session) {
-    if (session.mode === "terminal") {
+    if (session.mode === "terminal" || session.mode === "ide") {
         const driver = getDriverByName(session.terminal);
         if (driver) {
             const closed = await driver.closeTab(session);
@@ -625,3 +955,310 @@ export async function closeSession(session) {
         return killPid(session.pid);
     return false;
 }
+// ─── IDE Detection Helpers ───────────────────────────────────────────────────
+/**
+ * Check if a given driver is an IDE driver (VS Code, Cursor, Windsurf, Zed, JetBrains).
+ * Used to determine whether to attempt a fallback when the IDE CLI is unavailable.
+ */
+export function isIDEDriver(driver) {
+    return driver instanceof IDEDriver || driver instanceof JetBrainsDriver;
+}
+/**
+ * Detect the first non-IDE terminal driver that matches the environment.
+ * Used as a fallback when the IDE CLI is not available (e.g., `code` not in PATH).
+ *
+ * Skips IDE drivers and JetBrains, tries tmux, iTerm2, Terminal.app, kitty, etc.
+ * Returns null if no terminal driver matches (only fallback driver left).
+ */
+export function detectFallbackDriver() {
+    for (const driver of DRIVERS) {
+        // Skip IDE drivers — we want a real terminal emulator
+        if (driver instanceof IDEDriver || driver instanceof JetBrainsDriver)
+            continue;
+        // Skip the generic fallback — prefer a specific driver
+        if (driver instanceof FallbackDriver)
+            continue;
+        if (driver.detect())
+            return driver;
+    }
+    // If no specific terminal detected, use the fallback driver
+    return new FallbackDriver();
+}
+/**
+ * Check if we're currently inside an IDE's integrated terminal.
+ * Returns the IDE driver if detected, null otherwise.
+ */
+export function detectIDE() {
+    for (const driver of DRIVERS) {
+        // IDE drivers are VSCodeDriver, CursorDriver, WindsurfDriver, etc.
+        // They come before TmuxDriver in the array
+        if (driver instanceof IDEDriver && driver.detect()) {
+            return driver;
+        }
+        // Also check JetBrains separately (not an IDEDriver subclass)
+        if (driver instanceof JetBrainsDriver && driver.detect()) {
+            return driver;
+        }
+    }
+    return null;
+}
+/**
+ * Check if a specific IDE's CLI is available on the system.
+ */
+export async function isIDECliAvailable(ideName) {
+    const cliMap = {
+        vscode: "code",
+        cursor: "cursor",
+        windsurf: "windsurf",
+        zed: "zed",
+        jetbrains: "idea", // or webstorm, pycharm, etc.
+    };
+    const cli = cliMap[ideName];
+    if (!cli)
+        return false;
+    return !!(await which(cli));
+}
+/**
+ * Get a list of all available IDE CLIs on the system.
+ * Useful for offering launch options.
+ */
+export async function getAvailableIDEs() {
+    const ides = ["vscode", "cursor", "windsurf", "zed"];
+    const available = [];
+    for (const ide of ides) {
+        if (await isIDECliAvailable(ide)) {
+            available.push(ide);
+        }
+    }
+    return available;
+}
+// ─── Strategy 1: Environment variable detection (skip IDE drivers) ───────────
+function detectTerminalFromEnv() {
+    for (const driver of DRIVERS) {
+        if (isIDEDriver(driver))
+            continue;
+        if (driver instanceof FallbackDriver)
+            continue;
+        if (driver.detect())
+            return driver;
+    }
+    return null;
+}
+// ─── Strategy 2: Process-tree detection ──────────────────────────────────────
+/**
+ * Map of known process names (lowercase) to terminal driver names.
+ * Used by process-tree detection to match parent processes.
+ */
+const PROCESS_NAME_MAP = {
+    // macOS process names (from ps -o comm=)
+    "iterm2": "iterm2",
+    "terminal": "terminal.app",
+    "kitty": "kitty",
+    "ghostty": "ghostty",
+    "alacritty": "alacritty",
+    "wezterm-gui": "wezterm",
+    "wezterm": "wezterm",
+    "hyper": "hyper",
+    "rio": "rio",
+    // Linux process names
+    "gnome-terminal-server": "gnome-terminal",
+    "gnome-terminal-": "gnome-terminal",
+    "konsole": "konsole",
+    // Multiplexers
+    "tmux: server": "tmux",
+    "tmux": "tmux",
+};
+/**
+ * Walk up the process parent chain to find a known terminal emulator.
+ * Works on macOS (ps) and Linux (/proc). Stops after 15 ancestors or PID <= 1.
+ */
+async function detectFromProcessTree() {
+    const MAX_DEPTH = 15;
+    let pid = process.ppid || process.pid;
+    const visited = new Set();
+    if (process.platform === "darwin" || process.platform === "linux") {
+        for (let depth = 0; depth < MAX_DEPTH && pid > 1 && !visited.has(pid); depth++) {
+            visited.add(pid);
+            try {
+                let comm = "";
+                let ppid = 0;
+                if (process.platform === "linux") {
+                    // Linux: read /proc/<pid>/comm and /proc/<pid>/stat
+                    try {
+                        const commData = fs.readFileSync(`/proc/${pid}/comm`, "utf-8").trim();
+                        comm = commData;
+                        const statData = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+                        // Format: pid (comm) state ppid ...
+                        const match = statData.match(/\)\s+\S+\s+(\d+)/);
+                        ppid = match ? parseInt(match[1], 10) : 0;
+                    }
+                    catch {
+                        break; // Can't read /proc — permission denied or process gone
+                    }
+                }
+                else {
+                    // macOS: use ps to get parent PID and command name
+                    const result = await exec("ps", ["-o", "ppid=", "-o", "comm=", "-p", String(pid)], {
+                        timeout: 2000,
+                        nothrow: true,
+                    });
+                    const output = result.stdout.trim();
+                    if (!output)
+                        break;
+                    // Parse: "  1234 /Applications/Ghostty.app/Contents/MacOS/ghostty"
+                    const spaceIdx = output.trimStart().indexOf(" ");
+                    if (spaceIdx === -1)
+                        break;
+                    const trimmed = output.trimStart();
+                    ppid = parseInt(trimmed.substring(0, spaceIdx), 10);
+                    const fullPath = trimmed.substring(spaceIdx).trim();
+                    // Extract just the binary name from the full path
+                    comm = fullPath.split("/").pop() || fullPath;
+                }
+                if (!comm)
+                    break;
+                // Match against known process names (case-insensitive)
+                const commLower = comm.toLowerCase();
+                for (const [processName, driverName] of Object.entries(PROCESS_NAME_MAP)) {
+                    if (commLower === processName || commLower.startsWith(processName)) {
+                        const driver = getDriverByName(driverName);
+                        if (driver) {
+                            return { driver, detail: `process "${comm}" at PID ${pid}` };
+                        }
+                    }
+                }
+                pid = ppid;
+            }
+            catch {
+                break; // ps failed or process tree unavailable
+            }
+        }
+    }
+    return null;
+}
+// ─── Strategy 3: Frontmost app detection (macOS only) ────────────────────────
+/**
+ * Map of macOS bundle identifiers to terminal driver names.
+ */
+const BUNDLE_ID_MAP = {
+    "com.googlecode.iterm2": "iterm2",
+    "com.apple.terminal": "terminal.app",
+    "net.kovidgoyal.kitty": "kitty",
+    "com.mitchellh.ghostty": "ghostty",
+    "org.alacritty": "alacritty",
+    "com.github.wez.wezterm": "wezterm",
+    "co.zeit.hyper": "hyper",
+    "com.raphaelamorim.rio": "rio",
+};
+/**
+ * Detect the frontmost application on macOS and match to a terminal driver.
+ * Uses AppleScript to query System Events for the frontmost process's bundle ID.
+ *
+ * This catches cases where the process tree doesn't contain the terminal
+ * (e.g., launched via Spotlight or a launcher).
+ */
+async function detectFromFrontmostApp() {
+    if (process.platform !== "darwin")
+        return null;
+    try {
+        const script = 'tell application "System Events" to get bundle identifier of first process whose frontmost is true';
+        const result = await exec("osascript", ["-e", script], { timeout: 3000, nothrow: true });
+        const bundleId = result.stdout.trim().toLowerCase();
+        if (!bundleId)
+            return null;
+        // Direct lookup
+        const driverName = BUNDLE_ID_MAP[bundleId];
+        if (driverName) {
+            const driver = getDriverByName(driverName);
+            if (driver) {
+                return { driver, detail: `frontmost app bundle "${bundleId}"` };
+            }
+        }
+        // Partial match (e.g., "com.apple.Terminal" vs "com.apple.terminal")
+        for (const [knownBundle, driverName] of Object.entries(BUNDLE_ID_MAP)) {
+            if (bundleId.includes(knownBundle) || knownBundle.includes(bundleId)) {
+                const driver = getDriverByName(driverName);
+                if (driver) {
+                    return { driver, detail: `frontmost app bundle "${bundleId}" (partial match)` };
+                }
+            }
+        }
+    }
+    catch {
+        // AppleScript failed — accessibility permissions may be missing
+    }
+    return null;
+}
+// ─── Strategy 4: User preference from .cortex/config.json ───────────────────
+/**
+ * Read the user's preferred terminal from .cortex/config.json.
+ * Format: { "preferredTerminal": "ghostty" }
+ *
+ * Accepts any driver name registered in the DRIVERS array.
+ * This is the escape hatch for unusual setups where auto-detection fails.
+ */
+function getPreferredTerminal(projectRoot) {
+    const roots = [
+        projectRoot,
+        process.cwd(),
+        process.env.HOME,
+    ].filter(Boolean);
+    for (const root of roots) {
+        const configPath = path.join(root, ".cortex", "config.json");
+        if (!fs.existsSync(configPath))
+            continue;
+        try {
+            const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+            if (config.preferredTerminal && typeof config.preferredTerminal === "string") {
+                const driver = getDriverByName(config.preferredTerminal);
+                if (driver && !isIDEDriver(driver)) {
+                    return driver;
+                }
+            }
+        }
+        catch {
+            // Invalid JSON — skip
+        }
+    }
+    return null;
+}
+// ─── Main entry point: detectTerminalDriver() ───────────────────────────────
+/**
+ * Async multi-strategy detection of the user's terminal emulator.
+ *
+ * This is the PRIMARY function for "Open in terminal tab" — it NEVER returns
+ * an IDE driver. Use `detectDriver()` for IDE-first detection (e.g., "Open in IDE").
+ *
+ * Strategy chain:
+ *   1. Environment variables (fast, synchronous)
+ *   2. Process-tree walk (macOS: ps, Linux: /proc)
+ *   3. Frontmost application (macOS: AppleScript)
+ *   4. User preference (.cortex/config.json)
+ *   5. FallbackDriver (last resort)
+ *
+ * @param projectRoot — optional project root for reading .cortex/config.json
+ */
+export async function detectTerminalDriver(projectRoot) {
+    // Strategy 1: Environment variables (fastest — no subprocess needed)
+    const envDriver = detectTerminalFromEnv();
+    if (envDriver) {
+        return { driver: envDriver, strategy: "env", detail: `env match: ${envDriver.name}` };
+    }
+    // Strategy 2: Process-tree walk
+    const treeResult = await detectFromProcessTree();
+    if (treeResult) {
+        return { driver: treeResult.driver, strategy: "process-tree", detail: treeResult.detail };
+    }
+    // Strategy 3: Frontmost app (macOS only)
+    const frontmostResult = await detectFromFrontmostApp();
+    if (frontmostResult) {
+        return { driver: frontmostResult.driver, strategy: "frontmost-app", detail: frontmostResult.detail };
+    }
+    // Strategy 4: User preference
+    const preferred = getPreferredTerminal(projectRoot);
+    if (preferred) {
+        return { driver: preferred, strategy: "user-config", detail: `config: ${preferred.name}` };
+    }
+    // Strategy 5: Fallback
+    return { driver: new FallbackDriver(), strategy: "fallback", detail: "no terminal detected" };
+}