aiwcli 0.15.1 → 0.15.3

package/dist/commands/launch.d.ts

@@ -22,6 +22,7 @@ export default class LaunchCommand extends BaseCommand {
     run(): Promise<void>;
     private buildTmuxShellCommand;
     private isTmuxAvailable;
+    private isWindowsTerminalAvailable;
     private sanitizeTmuxSessionName;
     private buildUniqueTmuxSessionName;
     private enableTmuxMouseIfPossible;

package/dist/commands/launch.js

@@ -26,7 +26,7 @@ export default class LaunchCommand extends BaseCommand {
         '  0  Success - AI assistant launched and exited successfully\n' +
         '  1  General error - unexpected runtime failure\n' +
         '  2  Invalid usage - check your arguments and flags\n' +
-        '  3  Environment error - CLI/tmux not found (install Claude Code from https://claude.ai/download, Codex from npm, tmux from your package manager)';
+        '  3  Environment error - CLI not found (install Claude Code from https://claude.ai/download, Codex from npm)';
     static examples = [
         '<%= config.bin %> <%= command.id %>  # Auto-launches tmux with a fresh session when not already in tmux',
         '<%= config.bin %> <%= command.id %> --codex  # Launch Codex with --yolo flag',
@@ -112,11 +112,7 @@ export default class LaunchCommand extends BaseCommand {
             // Spawn AI CLI with sandbox permissions disabled
             // AIW hook system provides safety guardrails
             // Continue launch regardless of version check result (graceful degradation)
-            if (shouldAutoTmux) {
-                if (!this.isTmuxAvailable()) {
-                    this.error('tmux is required for default launch mode but was not found on PATH.\n' +
-                        'Install tmux, or rerun with --no-tmux to launch directly.', { exit: EXIT_CODES.ENVIRONMENT_ERROR });
-                }
+            if (shouldAutoTmux && this.isTmuxAvailable()) {
                 const shellCommand = this.buildTmuxShellCommand(cliCommand, cliArgs);
                 const sessionFromFlag = flags['tmux-session']?.trim();
                 if (sessionFromFlag && sessionFromFlag.length > 0) {
@@ -131,15 +127,24 @@ export default class LaunchCommand extends BaseCommand {
                     exitCode = await spawnProcess('tmux', ['new-session', '-s', sessionName, shellCommand]);
                 }
             }
+            else if (shouldAutoTmux && this.isWindowsTerminalAvailable()) {
+                this.logInfo('tmux unavailable; launching in Windows Terminal split pane');
+                exitCode = await spawnProcess('wt', ['split-pane', '--', cliCommand, ...cliArgs]);
+            }
             else {
-                if (disableTmux)
+                if (shouldAutoTmux) {
+                    this.logInfo('No pane launcher available. Launching directly.');
+                }
+                else if (disableTmux) {
                     this.debug('tmux launch disabled via --no-tmux');
+                }
                 else if (insideTmux) {
                     this.debug('Already inside tmux; launching directly in current pane');
                     this.enableTmuxMouseIfPossible();
                 }
-                else if (!interactiveTty)
+                else if (!interactiveTty) {
                     this.debug('Non-interactive terminal detected; launching directly');
+                }
                 exitCode = await spawnProcess(cliCommand, cliArgs);
             }
         }
@@ -168,6 +173,17 @@ export default class LaunchCommand extends BaseCommand {
             return false;
         }
     }
+    isWindowsTerminalAvailable() {
+        if (process.platform !== 'win32')
+            return false;
+        try {
+            execSync('where wt', { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     sanitizeTmuxSessionName(input) {
         const trimmed = input.trim().toLowerCase();
         const safe = trimmed

package/dist/templates/_shared/.claude/skills/codex/SKILL.md

@@ -1,42 +1,35 @@
 ---
 name: codex
-description: Launch Codex CLI in a tmux pane. USE WHEN codex OR send to codex OR codex implement OR hand off to codex OR launch codex OR codex plan OR run codex.
+description: Delegate implementation to Codex sub-agents. USE WHEN codex OR send to codex OR codex implement OR hand off to codex OR launch codex OR codex plan OR run codex.
 user-invocable: true
 ---
 
-# Codex CLI
+Read `.aiwcli/_shared/skills/codex/SKILL.md` for delegation patterns and examples.
 
-Launch Codex in a tmux split pane and optionally inject a prompt.
+## Role
 
-## Command
+You are the orchestrator. Codex instances are your implementation sub-agents. Decide what to delegate, how to split work, and review results when summaries arrive.
 
-`bun .aiwcli/_shared/skills/prompt-codex/scripts/launch-codex.ts [flags] <mode>`
+## Command
 
-**Modes:** `plan` (inject active plan) | `--file <path>` (inject file) | `<text...>` (inject inline text)
+```
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [flags] <mode>
+```
 
-**Flags:**
-- `--model <name>` — Model aliases: `spark`, `codex`, `gpt`. Tiers: `fast`, `standard`, `smart`. Or any full model ID.
-- `--sandbox <mode>` — `read-only`, `workspace-write`, `danger-full-access`. Default: Codex default.
-- `--context <id>` — Pass the active context ID so Codex receives project orientation (context folder, notes path). **Always pass this when an active context exists** (check the `Active Context:` system reminder for the ID).
+The script blocks until Codex exits and prints a summary — run with Bash `run_in_background: true` so you stay unblocked.
 
-## Model Reference
+**Modes:** `plan` | `--file <path>` | `<inline text...>`
 
-| Name | Resolves To |
-|------|-------------|
-| `spark` | `gpt-5.3-codex-spark` (fastest) |
-| `codex` | `gpt-5.3-codex` (default) |
-| `gpt` | `gpt-5.2` (non-Codex GPT) |
-| `fast` | `gpt-5.3-codex-spark` (tier) |
-| `standard` | `gpt-5.3-codex` (tier) |
-| `smart` | `gpt-5.3-codex` (tier) |
+**Key flags:**
+- `--context <id>` — Project orientation. Pass when implementing a plan.
+- `--prompt <text>` — Scope the agent's work to a specific plan section or task.
+- `--model <name>` — `spark`, `codex`, `gpt`, or tier: `fast`, `standard`, `smart`.
+- `--no-watch` — Fire-and-forget (skip waiting for summary).
 
-## Examples
+## Delegation Decision
 
-- `/codex --model spark --context <context-id> plan` — hand off active plan to Spark with context
-- `/codex --model codex --context <context-id> Refactor auth to use JWT` — inline prompt with context
-- `/codex --file ./spec.md` — inject file contents (no context)
+**One-shot:** Plan is small or tightly coupled → launch one Codex with `plan` mode. Wait for the summary, then review.
 
-## Requirements
+**Parallel:** Plan has independent sections → launch multiple Codex instances, each scoped with `--prompt` to its section. All share the same `--context`. Review when summaries arrive, check for conflicts.
 
-- Must be running inside tmux
-- `codex` CLI must be on PATH
+**Ad-hoc:** No plan, just a task → pass inline text (e.g., `"Fix the failing test in auth.ts"`).

package/dist/templates/_shared/.codex/workflows/codex.md

@@ -0,0 +1,11 @@
+# Codex Workflow
+
+Use Codex CLI handoff instructions from `.aiwcli/_shared/skills/codex/SKILL.md`.
+
+## Command
+
+`bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [flags] <mode>`
+
+**Modes:** `plan` | `--file <path>` | `<inline text...>`
+
+**Common flags:** `--model <name>`, `--sandbox <mode>`, `--context <id>`, `--prompt <text>`, `--no-yolo`, `--capture`

package/dist/templates/_shared/lib-ts/agent-exec/backends/tmux.ts

@@ -8,17 +8,20 @@
  */
 
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 
 import { execFileAsync } from "../../base/subprocess-utils.js";
+import {
+  buildShellCaptureScript,
+  cleanupSentinelIpc,
+  createSentinelIpcPaths,
+  readSentinelExitCode,
+  readTextIfExists,
+  waitForSentinelFile,
+} from "../../base/sentinel-ipc.js";
 import { getTmuxAvailability, quoteForSh, normalizeSplitFlag } from "../../base/tmux-driver.js";
 import type { ExecutionBackend, ExecutionRequest, ExecutionResult } from "../execution-backend.js";
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 export interface TmuxBackendOptions {
   splitFlag?: string;
   splitTarget?: string;
@@ -32,7 +35,7 @@ export class TmuxBackend implements ExecutionBackend {
   }
 
   async execute(request: ExecutionRequest): Promise<ExecutionResult> {
-    const tmux = getTmuxAvailability();
+    const tmux = getTmuxAvailability({ requireSessionEnv: true });
     if (!tmux.available || !tmux.tmuxPath) {
       return {
         stdout: "",
@@ -43,38 +46,23 @@ export class TmuxBackend implements ExecutionBackend {
       };
     }
 
-    // Create temp directory for IPC files
     const agentName = path.basename(request.cliPath).replace(/\.[^.]+$/, "");
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), `aiwcli-agent-${agentName}-`));
-
-    const promptPath = path.join(tmpDir, "prompt.txt");
-    const stdoutPath = path.join(tmpDir, "stdout.txt");
-    const stderrPath = path.join(tmpDir, "stderr.txt");
-    const sentinelPath = path.join(tmpDir, "sentinel.txt");
+    const ipc = createSentinelIpcPaths(`aiwcli-agent-${agentName}`);
 
     try {
-      // Write prompt to file for stdin redirection
-      fs.writeFileSync(promptPath, request.input, "utf-8");
+      fs.writeFileSync(ipc.inputPath, request.input, "utf-8");
 
-      // Build env prefix
       const envEntries = Object.entries(request.env).filter(
-        ([, v]) => v !== undefined,
+        ([, value]) => value !== undefined,
       ) as Array<[string, string]>;
       const envPrefix = envEntries
-        .map(([k, v]) => `${k}=${quoteForSh(v)}`)
+        .map(([key, value]) => `${key}=${quoteForSh(value)}`)
         .join(" ");
 
-      // Build command
-      const quotedArgs = request.args.map((a) => quoteForSh(a)).join(" ");
-      const script = [
-        `${envPrefix} ${quoteForSh(request.cliPath)} ${quotedArgs}`,
-        `< ${quoteForSh(promptPath)}`,
-        `> ${quoteForSh(stdoutPath)}`,
-        `2> ${quoteForSh(stderrPath)}`,
-        `; echo $? > ${quoteForSh(sentinelPath)}`,
-      ].join(" ");
-
-      // Launch tmux pane
+      const quotedArgs = request.args.map((arg) => quoteForSh(arg)).join(" ");
+      const command = `${envPrefix} ${quoteForSh(request.cliPath)} ${quotedArgs}`.trim();
+      const script = buildShellCaptureScript(command, ipc, quoteForSh);
+
       const splitFlag = normalizeSplitFlag(this.options.splitFlag);
       const tmuxArgs = ["split-window", splitFlag, "-P", "-F", "#{pane_id}"];
       if (this.options.splitTarget) {
@@ -94,16 +82,9 @@ export class TmuxBackend implements ExecutionBackend {
       }
 
       const paneId = split.stdout.trim().split(/\r?\n/).pop() ?? "";
+      const finished = await waitForSentinelFile(ipc.sentinelPath, request.timeoutMs);
 
-      // Poll for sentinel file
-      const deadline = Date.now() + request.timeoutMs;
-      while (Date.now() < deadline) {
-        if (fs.existsSync(sentinelPath)) break;
-        await sleep(250);
-      }
-
-      if (!fs.existsSync(sentinelPath)) {
-        // Timeout: kill pane
+      if (!finished) {
         if (paneId) {
           await execFileAsync(tmux.tmuxPath, ["kill-pane", "-t", paneId], { timeout: 3000 });
         }
@@ -116,12 +97,10 @@ export class TmuxBackend implements ExecutionBackend {
         };
       }
 
-      // Read results
-      const exitCode = parseInt(fs.readFileSync(sentinelPath, "utf-8").trim(), 10) || 1;
-      const stdout = fs.existsSync(stdoutPath) ? fs.readFileSync(stdoutPath, "utf-8") : "";
-      const stderr = fs.existsSync(stderrPath) ? fs.readFileSync(stderrPath, "utf-8") : "";
+      const exitCode = readSentinelExitCode(ipc.sentinelPath, 1);
+      const stdout = readTextIfExists(ipc.stdoutPath);
+      const stderr = readTextIfExists(ipc.stderrPath);
 
-      // If outputFilePath specified and exists, read from it instead
       if (request.outputFilePath && fs.existsSync(request.outputFilePath)) {
         return {
           stdout: fs.readFileSync(request.outputFilePath, "utf-8"),
@@ -134,12 +113,7 @@ export class TmuxBackend implements ExecutionBackend {
 
       return { stdout, stderr, exitCode, killed: false, signal: null };
     } finally {
-      // Clean up temp dir
-      try {
-        fs.rmSync(tmpDir, { recursive: true, force: true });
-      } catch {
-        // Best-effort cleanup
-      }
+      cleanupSentinelIpc(ipc);
     }
   }
 }

package/dist/templates/_shared/lib-ts/base/launchers/tmux-launcher.ts

@@ -0,0 +1,173 @@
+import { execFileAsync, findExecutable } from "../subprocess-utils.js";
+import { findBestSplit, listPanes } from "../tmux-pane-placement.js";
+import type { PaneLaunchOptions, PaneLaunchResult, PaneLauncher } from "../pane-launcher.js";
+
+export type TmuxSplitFlag = "-h" | "-v";
+
+export interface TmuxAvailability {
+  available: boolean;
+  tmuxPath?: string;
+  reason?: string;
+}
+
+export interface TmuxLauncherOptions {
+  requireSessionEnv?: boolean;
+}
+
+export function quoteForSh(input: string): string {
+  return `'${input.replaceAll("'", "'\"'\"'")}'`;
+}
+
+export function normalizeSplitFlag(value: string | undefined): TmuxSplitFlag {
+  return value?.trim() === "-v" ? "-v" : "-h";
+}
+
+export function getTmuxAvailability(options?: TmuxLauncherOptions): TmuxAvailability {
+  const requireSessionEnv = options?.requireSessionEnv ?? true;
+  if (requireSessionEnv && !process.env.TMUX) {
+    return { available: false, reason: "TMUX is not set" };
+  }
+
+  const tmuxPath = findExecutable("tmux");
+  if (!tmuxPath) {
+    return { available: false, reason: "tmux not found on PATH" };
+  }
+
+  return { available: true, tmuxPath };
+}
+
+function splitFlagFromDimensions(width: number, height: number): TmuxSplitFlag {
+  // Terminal cells are ~2x taller than wide. Correct for aspect ratio so BSP
+  // splits the visually longer axis, not just the higher character count.
+  const CELL_ASPECT_RATIO = 2.0;
+  return width >= height * CELL_ASPECT_RATIO ? "-h" : "-v";
+}
+
+function getLastLine(text: string): string {
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  return lines.at(-1) ?? "";
+}
+
+async function resolveSplitFlagForTargetPane(
+  tmuxPath: string,
+  splitTarget: string,
+): Promise<TmuxSplitFlag | null> {
+  const size = await execFileAsync(
+    tmuxPath,
+    ["display-message", "-p", "-t", splitTarget, "#{pane_width} #{pane_height}"],
+    { timeout: 3000 },
+  );
+  if (size.exitCode !== 0) return null;
+
+  const parts = size.stdout.trim().split(/\s+/);
+  if (parts.length < 2) return null;
+
+  const width = Number.parseInt(parts[0] ?? "", 10);
+  const height = Number.parseInt(parts[1] ?? "", 10);
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+
+  return splitFlagFromDimensions(width, height);
+}
+
+async function resolveAutoSplit(
+  tmuxPath: string,
+  splitTarget?: string,
+): Promise<{ splitFlag: TmuxSplitFlag; splitTarget?: string }> {
+  const explicitTarget = splitTarget?.trim();
+  if (explicitTarget) {
+    const splitFlag = await resolveSplitFlagForTargetPane(tmuxPath, explicitTarget);
+    return {
+      splitFlag: splitFlag ?? "-h",
+      splitTarget: explicitTarget,
+    };
+  }
+
+  const panes = await listPanes(tmuxPath);
+  const placement = findBestSplit(panes);
+  if (!placement) return { splitFlag: "-h" };
+
+  return {
+    splitFlag: placement.splitFlag,
+    splitTarget: placement.targetPane,
+  };
+}
+
+export class TmuxLauncher implements PaneLauncher {
+  readonly backend = "tmux" as const;
+  private options: TmuxLauncherOptions;
+
+  constructor(options?: TmuxLauncherOptions) {
+    this.options = options ?? {};
+  }
+
+  async available(): Promise<boolean> {
+    return getTmuxAvailability(this.options).available;
+  }
+
+  async launch(options: PaneLaunchOptions): Promise<PaneLaunchResult> {
+    const tmux = getTmuxAvailability(this.options);
+    if (!tmux.available || !tmux.tmuxPath) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: tmux.reason ?? "tmux unavailable",
+      };
+    }
+
+    const splitDirection = options.splitDirection ?? "h";
+    const explicitTarget = options.splitTarget?.trim();
+
+    let splitFlag: TmuxSplitFlag;
+    let splitTarget: string | undefined;
+
+    if (splitDirection === "auto") {
+      try {
+        const resolved = await resolveAutoSplit(tmux.tmuxPath, explicitTarget);
+        splitFlag = resolved.splitFlag;
+        splitTarget = resolved.splitTarget;
+      } catch {
+        splitFlag = "-h";
+        splitTarget = explicitTarget;
+      }
+    } else {
+      splitFlag = splitDirection === "v" ? "-v" : "-h";
+      splitTarget = explicitTarget;
+    }
+
+    const body = options.cwd?.trim()
+      ? `cd ${quoteForSh(options.cwd.trim())} && ${options.command}`
+      : options.command;
+
+    const tmuxArgs = ["split-window", splitFlag, "-P", "-F", "#{pane_id}"];
+    if (splitTarget) tmuxArgs.push("-t", splitTarget);
+    tmuxArgs.push(`bash -lc ${quoteForSh(body)}`);
+
+    const split = await execFileAsync(tmux.tmuxPath, tmuxArgs, { timeout: 5000 });
+    if (split.exitCode !== 0) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "tmux split-window failed",
+        stderr: split.stderr.trim() || undefined,
+      };
+    }
+
+    const paneId = getLastLine(split.stdout) || undefined;
+    return {
+      launched: true,
+      backend: this.backend,
+      paneId,
+    };
+  }
+
+  async kill(paneId: string): Promise<void> {
+    if (!paneId) return;
+
+    const tmux = getTmuxAvailability(this.options);
+    if (!tmux.available || !tmux.tmuxPath) return;
+
+    await execFileAsync(tmux.tmuxPath, ["kill-pane", "-t", paneId], {
+      timeout: 3000,
+    });
+  }
+}

package/dist/templates/_shared/lib-ts/base/launchers/window-launcher.ts

@@ -0,0 +1,93 @@
+import { execFileAsync, findExecutable } from "../subprocess-utils.js";
+import { quoteForSh } from "./tmux-launcher.js";
+import type { PaneLaunchOptions, PaneLaunchResult, PaneLauncher } from "../pane-launcher.js";
+
+function quoteForPowerShell(input: string): string {
+  return `'${input.replaceAll("'", "''")}'`;
+}
+
+function findPowerShell(): string | null {
+  return findExecutable("pwsh") ?? findExecutable("powershell");
+}
+
+export class WindowLauncher implements PaneLauncher {
+  readonly backend = "window" as const;
+
+  async available(): Promise<boolean> {
+    if (process.platform !== "win32") return false;
+    return Boolean(findPowerShell() ?? findExecutable("mintty"));
+  }
+
+  async launch(options: PaneLaunchOptions): Promise<PaneLaunchResult> {
+    if (process.platform !== "win32") {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "window launcher only available on Windows",
+      };
+    }
+
+    const powershellPath = findPowerShell();
+    if (powershellPath) {
+      const cwd = options.cwd?.trim() || process.cwd();
+      const startProcess = [
+        `$cmd = ${quoteForPowerShell(options.command)}`,
+        `$wd = ${quoteForPowerShell(cwd)}`,
+        `Start-Process -FilePath ${quoteForPowerShell(powershellPath)} -WorkingDirectory $wd -ArgumentList @('-NoProfile','-Command',$cmd) | Out-Null`,
+      ].join("; ");
+
+      const psLaunch = await execFileAsync(
+        powershellPath,
+        ["-NoProfile", "-Command", startProcess],
+        { timeout: 5000, shell: false },
+      );
+
+      if (psLaunch.exitCode === 0) {
+        return {
+          launched: true,
+          backend: this.backend,
+        };
+      }
+
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "Start-Process launch failed",
+        stderr: psLaunch.stderr.trim() || undefined,
+      };
+    }
+
+    const minttyPath = findExecutable("mintty");
+    if (!minttyPath) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "PowerShell and mintty are both unavailable",
+      };
+    }
+
+    const shellBody = options.cwd?.trim()
+      ? `cd ${quoteForSh(options.cwd.trim())} && ${options.command}`
+      : options.command;
+
+    const minttyLaunch = await execFileAsync(
+      minttyPath,
+      ["-e", "bash", "-lc", shellBody],
+      { timeout: 5000, shell: false },
+    );
+
+    if (minttyLaunch.exitCode !== 0) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "mintty launch failed",
+        stderr: minttyLaunch.stderr.trim() || undefined,
+      };
+    }
+
+    return {
+      launched: true,
+      backend: this.backend,
+    };
+  }
+}

package/dist/templates/_shared/lib-ts/base/launchers/wt-launcher.ts

@@ -0,0 +1,64 @@
+import { execFileAsync, findExecutable } from "../subprocess-utils.js";
+import type { PaneLaunchOptions, PaneLaunchResult, PaneLauncher } from "../pane-launcher.js";
+
+function findPowerShell(): string {
+  return findExecutable("pwsh") ?? findExecutable("powershell") ?? "powershell";
+}
+
+export class WtLauncher implements PaneLauncher {
+  readonly backend = "wt" as const;
+
+  async available(): Promise<boolean> {
+    if (process.platform !== "win32") return false;
+    return Boolean(findExecutable("wt") ?? findExecutable("wt.exe"));
+  }
+
+  async launch(options: PaneLaunchOptions): Promise<PaneLaunchResult> {
+    if (process.platform !== "win32") {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "wt launcher only available on Windows",
+      };
+    }
+
+    const wtPath = findExecutable("wt") ?? findExecutable("wt.exe");
+    if (!wtPath) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "wt.exe not found on PATH",
+      };
+    }
+
+    const args = ["split-pane"];
+    const splitDirection = options.splitDirection ?? "auto";
+    if (splitDirection === "h") args.push("-H");
+    if (splitDirection === "v") args.push("-V");
+
+    if (options.cwd?.trim()) args.push("-d", options.cwd.trim());
+    if (options.title?.trim()) args.push("--title", options.title.trim());
+
+    const powershellPath = findPowerShell();
+    args.push("--", powershellPath, "-NoProfile", "-Command", options.command);
+
+    const result = await execFileAsync(wtPath, args, {
+      timeout: 5000,
+      shell: false,
+    });
+
+    if (result.exitCode !== 0) {
+      return {
+        launched: false,
+        backend: this.backend,
+        reason: "wt split-pane failed",
+        stderr: result.stderr.trim() || undefined,
+      };
+    }
+
+    return {
+      launched: true,
+      backend: this.backend,
+    };
+  }
+}

package/dist/templates/_shared/lib-ts/base/pane-launcher.ts

@@ -0,0 +1,55 @@
+import { TmuxLauncher } from "./launchers/tmux-launcher.js";
+import { WindowLauncher } from "./launchers/window-launcher.js";
+import { WtLauncher } from "./launchers/wt-launcher.js";
+
+export type PaneBackend = "tmux" | "wt" | "window" | "exec";
+export type PaneSplitDirection = "h" | "v" | "auto";
+
+export interface PaneLaunchOptions {
+  command: string;
+  splitDirection?: PaneSplitDirection;
+  splitTarget?: string;
+  cwd?: string;
+  title?: string;
+}
+
+export interface PaneLaunchResult {
+  launched: boolean;
+  backend: PaneBackend;
+  paneId?: string;
+  reason?: string;
+  stderr?: string;
+}
+
+export interface PaneLauncher {
+  readonly backend: PaneBackend;
+  available(): Promise<boolean>;
+  launch(options: PaneLaunchOptions): Promise<PaneLaunchResult>;
+  kill?(paneId: string): Promise<void>;
+}
+
+export interface PaneLauncherFactoryOptions {
+  /** Include tmux launcher only when running inside a tmux session. Default: true. */
+  requireTmuxSession?: boolean;
+}
+
+/**
+ * Resolve the first available pane launcher for the current environment.
+ * Detection order: tmux -> Windows Terminal -> window fallback.
+ */
+export async function createPaneLauncher(
+  options?: PaneLauncherFactoryOptions,
+): Promise<PaneLauncher | null> {
+  const requireTmuxSession = options?.requireTmuxSession ?? true;
+
+  const tmux = new TmuxLauncher({ requireSessionEnv: requireTmuxSession });
+  if (await tmux.available()) return tmux;
+
+  const wt = new WtLauncher();
+  if (await wt.available()) return wt;
+
+  const window = new WindowLauncher();
+  if (await window.available()) return window;
+
+  return null;
+}