pi-terminal-mux 0.3.0 → 0.3.2

package/README.md

@@ -37,6 +37,7 @@ if (!isMuxAvailable()) {
 const surface = createSurface("my-agent");
 
 // Long commands are written to a script file first to avoid terminal line wrapping
+// (Bash by default; pass interpreter: "powershell" on Windows for PowerShell)
 const scriptPath = sendLongCommand(surface, "pi --session abc", {
   scriptPreamble: "export MY_FLAG=1",
 });
@@ -72,12 +73,12 @@ If the forced backend's runtime is unavailable, `getMuxBackend()` returns `null`
 
 | Function | Description |
 |----------|-------------|
-| `createSurface(name)` | Smart placement (cmux: first right-split then tabs; zellij: tab-aware tiled/stacked; muxy/otty: breadth-first splits; orca: new tab in the current worktree), returns a surface handle |
-| `createSurfaceSplit(name, direction, fromSurface?)` | Split in an explicit direction (left/right/up/down) |
+| `createSurface(name)` | Smart placement (cmux: first right-split then tabs; zellij: tab-aware tiled/stacked; muxy/otty/orca: breadth-first splits; orca falls back to a new tab without an agent handle), returns a surface handle |
+| `createSurfaceSplit(name, direction, fromSurface?, options?)` | Split in an explicit direction (left/right/up/down). `options.activate` (WezTerm only, default `false`) focuses the new pane after splitting |
 | `sendCommand(surface, command)` | Send a command and press Enter |
-| `sendLongCommand(surface, command, opts?)` | Write long commands to a script file first; `opts.scriptPreamble` injects env exports; returns the script path |
+| `sendLongCommand(surface, command, opts?)` | Write long commands to a script file first. `opts.scriptPreamble` injects leading lines; `opts.interpreter` (`"bash"` default, or `"powershell"` on Windows) selects the scripting runtime; returns the script path |
 | `sendEscape(surface)` | Send one ESC keypress |
-| `readScreen(surface, lines?)` / `readScreenAsync` | Read the last N screen lines |
+| `readScreen(surface, lines?, options?)` / `readScreenAsync` | Read the last N screen lines. `options.source` (herdr-only) forwards a herdr read source such as `"recent_unwrapped"`; other backends ignore it |
 | `closeSurface(surface)` | Close the surface |
 | `renameSurface(surface, name)` / `renameCurrentTab(title)` / `renameAgent(surface, name)` / `renameWorkspace(title)` | Naming, degrading per backend capability |
 | `pollForExit(surface, signal, opts)` | Wait for the process in a surface to exit: `.exit` sidecar file first, then a screen sentinel (`__SUBAGENT_DONE_<code>__`); headless uses child process exit |
@@ -95,6 +96,16 @@ Backend-native functions are also re-exported (e.g. `createHerdrSurface`, `split
 
 When no backend is detected, `createSurface` returns a `headless:`-prefixed surface, `sendLongCommand` spawns a background child process writing to a log file, and `readScreen` / `pollForExit` / `closeSurface` keep the same semantics — callers need no special-casing.
 
+## Windows PowerShell support
+
+All platforms keep **Bash as the default** scripting runtime to preserve existing caller semantics. On Windows 11 PowerShell/WezTerm/herdr, opt in explicitly:
+
+- **Command submission (WezTerm)**: the Enter terminator is `\r` on `win32` and `\n` elsewhere, so PowerShell input is submitted exactly once instead of stopping at the continuation prompt.
+- **Long commands (`sendLongCommand`)**: pass `interpreter: "powershell"` to generate a `.ps1` and run it via `powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File <path>` (mux) or `-Command "& <path>"` (headless). Explicit `scriptPath` is preserved as-is; auto paths choose `.ps1`/`.sh` by interpreter. Omitted `interpreter` keeps the existing Bash command, `.sh` paths and `$?` numeric sentinels unchanged.
+- **Screen capture (`readScreen` / `readScreenAsync`)**: pass `{ source: "recent_unwrapped" }` (herdr-only) to select herdr's soft-wrap merged capture; omitted options keep herdr `recent` and other backends keep their own read semantics.
+
+These are opt-in capabilities — existing Bash callers and `pi-interactive-subagents` continue to run under the default Bash runtime on every platform.
+
 ## Environment variables
 
 | Variable | Description |

package/README.zh-CN.md

@@ -36,6 +36,7 @@ if (!isMuxAvailable()) {
 const surface = createSurface("my-agent");
 
 // 长命令自动落脚本文件，避免终端宽度截断
+// （默认 Bash；Windows 上显式传 interpreter: "powershell" 切到 PowerShell）
 const scriptPath = sendLongCommand(surface, "pi --session abc", {
   scriptPreamble: "export MY_FLAG=1",
 });
@@ -71,12 +72,12 @@ closeSurface(surface);
 
 | 函数 | 说明 |
 |------|------|
-| `createSurface(name)` | 智能放置新 surface（cmux 首次右分屏后续开 tab、zellij tab 感知平铺/堆叠、muxy/otty 广度优先分屏、orca 在当前 worktree 新建 tab），返回 surface 标识 |
-| `createSurfaceSplit(name, direction, fromSurface?)` | 指定方向（left/right/up/down）分屏 |
+| `createSurface(name)` | 智能放置新 surface（cmux 首次右分屏后续开 tab、zellij tab 感知平铺/堆叠、muxy/otty/orca 广度优先分屏；orca 缺少 agent handle 时新建 tab），返回 surface 标识 |
+| `createSurfaceSplit(name, direction, fromSurface?, options?)` | 指定方向（left/right/up/down）分屏；`options.activate`（仅 wezterm，默认 false）分屏后聚焦新 pane |
 | `sendCommand(surface, command)` | 发送命令并回车执行 |
-| `sendLongCommand(surface, command, opts?)` | 长命令先写脚本文件再执行；`opts.scriptPreamble` 可注入 env export；返回脚本路径 |
+| `sendLongCommand(surface, command, opts?)` | 长命令先写脚本文件再执行；`opts.scriptPreamble` 可注入前置片段；`opts.interpreter`（默认 `"bash"`，Windows 可显式 `"powershell"`）选择脚本运行时；返回脚本路径 |
 | `sendEscape(surface)` | 发送一次 ESC |
-| `readScreen(surface, lines?)` / `readScreenAsync` | 读取屏幕尾部 N 行 |
+| `readScreen(surface, lines?, options?)` / `readScreenAsync` | 读取屏幕尾部 N 行；`options.source`（仅 herdr）透传 herdr 读屏来源（如 `"recent_unwrapped"`），其他后端忽略 |
 | `closeSurface(surface)` | 关闭 surface |
 | `renameSurface(surface, name)` / `renameCurrentTab(title)` / `renameAgent(surface, name)` / `renameWorkspace(title)` | 命名（按后端能力降级或跳过） |
 | `pollForExit(surface, signal, opts)` | 等待 surface 内进程退出：优先 `.exit` sidecar 文件，其次屏幕 sentinel（`__SUBAGENT_DONE_<code>__`），headless 走子进程 exit |
@@ -94,6 +95,16 @@ closeSurface(surface);
 
 探测不到任何后端时，`createSurface` 返回 `headless:` 前缀的 surface，`sendLongCommand` 直接 spawn 后台子进程并把输出写入日志文件，`readScreen`/`pollForExit`/`closeSurface` 语义保持不变，调用方无需特判。
 
+## Windows PowerShell 支持
+
+所有平台默认保持 **Bash** 作为脚本运行时，以不变更现有调用方语义。Windows 11 PowerShell/WezTerm/herdr 组合下显式开启：
+
+- **命令提交（wezterm）**：Enter 终止符在 `win32` 用 `\r`、其他平台用 `\n`，PowerShell 输入只会提交一次，不会停在续行提示。
+- **长命令（`sendLongCommand`）**：传 `interpreter: "powershell"` 会生成 `.ps1`，mux 通过 `powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File <path>` 执行、headless 走 `-Command "& <path>"`。显式 `scriptPath` 原样保留；自动路径按解释器选 `.ps1`/`.sh`。未传 interpreter 时保持既有 Bash command、`.sh` 路径与 `$?` 数值哨兵不变。
+- **读屏（`readScreen` / `readScreenAsync`）**：传 `{ source: "recent_unwrapped" }`（仅 herdr）选择 herdr 的软换行合并捕获；不传 options 时 herdr 保持 `recent`，其他后端保持各自读屏语义。
+
+这些都是可选项——既有 Bash 调用方与 `pi-interactive-subagents` 在所有平台继续走默认 Bash 运行时。
+
 ## 环境变量
 
 | 变量 | 说明 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-terminal-mux",
-  "version": "0.3.0",
-  "description": "Terminal multiplexer abstraction for pi extensions — unified surface API across muxy, cmux, tmux, zellij, wezterm, herdr and otty, with headless fallback",
+  "version": "0.3.2",
+  "description": "Terminal multiplexer abstraction for pi extensions — unified surface API across muxy, cmux, tmux, zellij, wezterm, herdr, otty and orca, with headless fallback",
   "type": "module",
   "main": "./index.ts",
   "exports": {

package/src/backends/herdr.ts

@@ -308,6 +308,13 @@ export function sendHerdrEscape(paneId: string): void {
   herdrExecSilent(["pane", "send-keys", paneId, "Escape"]);
 }
 
+/**
+ * 将 herdr source 归一化为 CLI 使用的标志值（recent_unwrapped -> recent-unwrapped，其余原样）。
+ */
+export function herdrSourceFlag(source: "visible" | "recent" | "recent_unwrapped"): string {
+  return source === "recent_unwrapped" ? "recent-unwrapped" : source;
+}
+
 /**
  * 读取 pane 屏幕内容。
  * SKILL.md：`herdr pane read <id> --source <src> --lines N` 直接打印文本（非 JSON）。
@@ -320,8 +327,7 @@ export function sendHerdrEscape(paneId: string): void {
  */
 export function readHerdrScreen(paneId: string, lines = 50, source: "visible" | "recent" | "recent_unwrapped" = "visible"): string {
   // SKILL.md 列出的 source 选项
-  const sourceFlag = source === "recent_unwrapped" ? "recent-unwrapped" : source;
-  return herdrExec(["pane", "read", paneId, "--source", sourceFlag, "--lines", String(lines)]);
+  return herdrExec(["pane", "read", paneId, "--source", herdrSourceFlag(source), "--lines", String(lines)]);
 }
 
 /**

package/src/backends/orca.ts

@@ -18,9 +18,8 @@
  * 与其他 backend 的关键差异：
  *   1. Orca 注入 ORCA_TERMINAL_HANDLE（类似 cmux 的 CMUX_SURFACE_ID），
  *      模块加载时冻结为 AGENT_ORCA_TERMINAL_HANDLE。
- *   2. create() 走"新 tab"而非分屏：Orca 是 worktree 中心的工作台，
- *      官方建议 agent 用 `terminal create` 开新终端；不拆分 agent 自己的
- *      pane，避免压缩 pi 的 UI。因此不使用 shared.ts 的 BFS 分屏状态机。
+ *   2. create() 与 muxy/herdr/otty 一样从 agent terminal 分屏，并通过
+ *      shared.ts 的 BFS 状态机轮转 right/down；没有 agent handle 时回退为新 tab。
  *   3. Escape 通过发送裸 ESC（`\u001b`，即 `0x1b`）字节实现，TUI 会将其解释为 Escape 键。
  *   4. rename 作用于 tab 标题；split 出来的 pane 与源 pane 共享 tab，
  *      所以 createSplit 不做 rename（否则会把 agent 所在 tab 一起改名）。
@@ -32,7 +31,8 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { createBackendLogger, hasCommand } from "./shared.ts";
+import { tmpdir } from "node:os";
+import { BfsSplitStateManager, createBackendLogger, hasCommand, withFileLock } from "./shared.ts";
 import type { BackendOps } from "./types.ts";
 
 const ORCA_RUNTIME_CHECK_TIMEOUT_MS = 1_500;
@@ -139,6 +139,49 @@ export function orcaSplitDirection(direction: "left" | "right" | "up" | "down"):
   return direction === "left" || direction === "right" ? "vertical" : "horizontal";
 }
 
+// ── Orca BFS 分屏状态 ──
+
+/**
+ * 返回 Orca subagent 分屏状态 marker 路径。
+ * 使用 agent handle 隔离不同 Orca 会话，路径放在系统临时目录中。
+ */
+function orcaStateFile(): string {
+  const agentHandle = AGENT_ORCA_TERMINAL_HANDLE ?? "default";
+  const safe = agentHandle.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return `${tmpdir()}/orca-subagent-pane-${safe}.json`;
+}
+
+/**
+ * 从 BFS marker 中移除已关闭的 pane，避免后续 create 使用僵尸 handle。
+ */
+function cleanupOrcaStateForSurface(handle: string): void {
+  try {
+    const state = new BfsSplitStateManager(orcaStateFile());
+    state.remove(handle);
+  } catch (e) {
+    orcaLog(`[state] cleanup failed for ${handle}: ${(e as Error).message}`);
+  }
+}
+
+/**
+ * 调用 `orca terminal create` 新建 tab，作为没有 agent handle 时的回退。
+ */
+function createOrcaTab(name: string): string {
+  try {
+    const raw = orcaExec(["terminal", "create", "--title", name, "--json"]);
+    const handle = extractOrcaCreateHandle(parseOrcaJson(raw));
+    if (!handle) {
+      orcaLog(`[create] no handle in tab response for name=${JSON.stringify(name)}`);
+      return "";
+    }
+    orcaLog(`[create] fallback=tab new=${handle} name=${JSON.stringify(name)}`);
+    return handle;
+  } catch (e) {
+    orcaLog(`[create] fallback tab failed: ${(e as Error).message}`);
+    return "";
+  }
+}
+
 // ── Orca CLI 调用的薄封装 ──
 
 /**
@@ -193,22 +236,62 @@ function orcaExecSilent(args: string[]): void {
 /**
  * 创建一个新的 subagent terminal。
  *
- * 实现：`orca terminal create --title <name>` 在当前 worktree 新建 tab
- * （CLI 语义：不抢焦点）。与 otty/muxy 的 BFS 分屏不同，新 tab 不会压缩
- * agent 自己的 pane，符合 Orca 的 worktree 中心工作流。
+ * 实现：与 muxy/herdr/otty 一致，使用持久化 BFS 状态从 agent terminal 分屏：
+ *   - 第一次从 agent pane 向右分屏；
+ *   - 后续按 BFS 状态机轮转 right/down，均保持 agent 焦点不变（Orca split CLI 默认不抢焦点）。
  *
- * 失败返回 ""（与 otty createSurface 一致，调用方统一处理）。
+ * Orca 没有注入 agent handle 时回退为新建 tab，兼容手动调用原生 API 的场景。
+ * 失败返回 ""（与其他 backend create 一致，调用方统一处理）。
  */
 export function createOrcaSurface(name: string): string {
+  const agentHandle = AGENT_ORCA_TERMINAL_HANDLE;
+  if (!agentHandle) return createOrcaTab(name);
+
+  const markerFile = orcaStateFile();
+  const lockPath = `${markerFile}.lock`;
+
   try {
-    const raw = orcaExec(["terminal", "create", "--title", name, "--json"]);
-    const handle = extractOrcaCreateHandle(parseOrcaJson(raw));
-    if (!handle) {
-      orcaLog(`[create] no handle in response for name=${JSON.stringify(name)}`);
-      return "";
-    }
-    orcaLog(`[create] new=${handle} name=${JSON.stringify(name)}`);
-    return handle;
+    return withFileLock(lockPath, { timeoutMs: 3_000 }, () => {
+      let state = new BfsSplitStateManager(markerFile);
+
+      // 首次 split：从 agent pane 向右分屏。
+      if (state.panes().length === 0) {
+        const newHandle = splitOrcaTerminal("right", agentHandle);
+        if (!newHandle) {
+          orcaLog(`[create] first split failed from=${agentHandle}`);
+          return "";
+        }
+        state.add(newHandle);
+        orcaLog(`[create] mode=first dir=right from=${agentHandle} new=${newHandle} name=${JSON.stringify(name)}`);
+        return newHandle;
+      }
+
+      const next = state.next();
+      if (!next) return "";
+
+      // 正常路径按 BFS 状态机分屏；目标 pane 失效时清空状态并从 agent pane 恢复。
+      let newHandle = splitOrcaTerminal(next.direction, next.source);
+      if (newHandle) {
+        state.advance();
+        state.add(newHandle);
+        orcaLog(
+          `[create] mode=next dir=${next.direction} from=${next.source} new=${newHandle} name=${JSON.stringify(name)}`,
+        );
+        return newHandle;
+      }
+
+      orcaLog(`[create] pane ${next.source} unavailable, reset and retry from agent pane`);
+      for (const pane of state.panes()) state.remove(pane);
+      state = new BfsSplitStateManager(markerFile);
+      newHandle = splitOrcaTerminal("right", agentHandle);
+      if (!newHandle) {
+        orcaLog(`[create] reset split failed from=${agentHandle}`);
+        return "";
+      }
+      state.add(newHandle);
+      orcaLog(`[create] mode=recovered dir=right from=${agentHandle} new=${newHandle} name=${JSON.stringify(name)}`);
+      return newHandle;
+    });
   } catch (e) {
     orcaLog(`[create] failed: ${(e as Error).message}`);
     return "";
@@ -299,36 +382,40 @@ function queryOrcaTerminalExists(handle: string): boolean | null {
 /**
  * 关闭 terminal。
  *
- * create() 生成的 surface 独占一个 tab，split 生成的 pane 共享 tab。
+ * create() 和 createSplit() 生成的 pane 可能与其他 pane 共享 tab。
  * 策略（best-effort，绝不 throw，避免 pollForExit 退出流程被打断）：
  *   1. `terminal close`（关 pane/session）
  *   2. 验证 handle 是否还在列表；不在了则完成
  *   3. 仍在则补 `terminal close --tab`（单 pane tab 的残留情况）
- *   4. 仍失败仅 log warn
+ *   4. 清理 BFS marker；仍失败仅 log warn
  */
 export function closeOrcaSurface(handle: string): void {
-  orcaExecSilent(["terminal", "close", "--terminal", handle, "--json"]);
+  try {
+    orcaExecSilent(["terminal", "close", "--terminal", handle, "--json"]);
 
-  let exists = queryOrcaTerminalExists(handle);
-  if (exists === false) {
-    orcaLog(`[close] terminal ${handle} closed`);
-    return;
-  }
-  if (exists === null) {
-    // 查询失败不能当作已关闭；继续尝试 --tab 兜底
-    orcaLog(`[close] WARN terminal ${handle} list query failed, cannot verify close`);
-  }
+    let exists = queryOrcaTerminalExists(handle);
+    if (exists === false) {
+      orcaLog(`[close] terminal ${handle} closed`);
+      return;
+    }
+    if (exists === null) {
+      // 查询失败不能当作已关闭；继续尝试 --tab 兜底
+      orcaLog(`[close] WARN terminal ${handle} list query failed, cannot verify close`);
+    }
 
-  orcaLog(`[close] terminal ${handle} still present, trying --tab`);
-  orcaExecSilent(["terminal", "close", "--terminal", handle, "--tab", "--json"]);
+    orcaLog(`[close] terminal ${handle} still present, trying --tab`);
+    orcaExecSilent(["terminal", "close", "--terminal", handle, "--tab", "--json"]);
 
-  exists = queryOrcaTerminalExists(handle);
-  if (exists === false) {
-    orcaLog(`[close] terminal ${handle} closed via --tab`);
-  } else if (exists === null) {
-    orcaLog(`[close] WARN terminal ${handle} close sent but unverifiable (list query failed)`);
-  } else {
-    orcaLog(`[close] WARN terminal ${handle} still present after close --tab`);
+    exists = queryOrcaTerminalExists(handle);
+    if (exists === false) {
+      orcaLog(`[close] terminal ${handle} closed via --tab`);
+    } else if (exists === null) {
+      orcaLog(`[close] WARN terminal ${handle} close sent but unverifiable (list query failed)`);
+    } else {
+      orcaLog(`[close] WARN terminal ${handle} still present after close --tab`);
+    }
+  } finally {
+    cleanupOrcaStateForSurface(handle);
   }
 }
 
@@ -345,7 +432,7 @@ export function renameOrcaTerminal(handle: string, name: string): void {
 
 /** BackendOps 适配器：所有方法薄包装 orca 原生函数 */
 export const ops: BackendOps = {
-  /** 创建 orca surface（新 tab，不抢焦点） */
+  /** 创建 orca surface（从 agent terminal BFS 分屏；无 handle 时回退新 tab） */
   create(name: string): string {
     return createOrcaSurface(name);
   },

package/src/backends/types.ts

@@ -5,6 +5,15 @@
  * Record<MuxBackend, BackendOps> 实现全键派发。
  */
 
+/**
+ * 分屏 options（后端特有能力提示，非后端忽略）。
+ * activate 仅供 wezterm 使用：split 成功后调用 activate-pane 聚焦新 pane；默认 false 保持当前焦点。
+ */
+export interface CreateSplitOptions {
+  /** 是否激活新创建的 pane（仅 wezterm 支持，默认 false） */
+  activate?: boolean;
+}
+
 /**
  * 后端 per-surface 操作接口（内部契约，不进 index.ts）。
  * create / createSplit / send / sendEscape / read / readAsync / close / rename
@@ -13,8 +22,14 @@
 export interface BackendOps {
   /** 创建新 surface（智能放置，如分屏/堆叠/新 tab） */
   create(name: string): string;
-  /** 指定方向分屏创建新 surface */
-  createSplit(name: string, direction: "left" | "right" | "up" | "down", fromSurface?: string): string;
+  /**
+   * 指定方向分屏创建新 surface。fromSurface 第 3 参、options 第 4 参均为可选尾部参数；
+   * 该签名由统一 surface API 的向后兼容要求强制（旧 3 参调用保持类型与行为不变）：
+   * 仓库现有调用点 pi-interactive-subagents/test/integration/harness.ts 仍以
+   * createSurfaceSplit(name, direction, fromSurface) 三位置参调用，options 只能作为第 4 个尾部参数追加。
+   * 故按外部 API 兼容签名豁免参数数量约束。
+   */
+  createSplit(name: string, direction: "left" | "right" | "up" | "down", fromSurface?: string, options?: CreateSplitOptions): string;
   /** 向 surface 发送命令字符串并执行 */
   send(surface: string, command: string): void;
   /** 向 surface 发送 Escape 按键 */

package/src/backends/wezterm.ts

@@ -15,6 +15,29 @@ const execFileAsync = promisify(execFile);
 /** WezTerm 后端日志（统一格式，写入 /tmp/pi-mux-wezterm.log） */
 const weztermLog = createBackendLogger("wezterm", "/tmp/pi-mux-wezterm.log");
 
+/** WezTerm CLI 基础段 */
+const CLI = "cli";
+/** 激活 pane 的命令段 */
+const ACTIVATE_PANE_CMD = "activate-pane";
+const PANE_ID_FLAG = "--pane-id";
+
+/**
+ * 生成激活 WezTerm pane 的 CLI 参数数组。
+ * 仅当 split 成功取得合法 pane id 后才调用（paneId 校验失败的场景不走到这里）。
+ */
+export function weztermActivateArgs(paneId: string): string[] {
+  return [CLI, ACTIVATE_PANE_CMD, PANE_ID_FLAG, paneId];
+}
+
+/**
+ * 返回命令提交终止符。Windows 的 ConPTY 中 LF 会让 PowerShell 停在续行提示，
+ * 必须用 CR 提交；其他平台继续使用 LF（不用 CRLF，避免多余换行）。
+ * platform 参数可注入以便单元测试，缺省按当前进程平台决策。
+ */
+export function commandTerminator(platform: string = process.platform): string {
+  return platform === "win32" ? "\r" : "\n";
+}
+
 export const ops: BackendOps = {
   create(name: string): string {
     // WezTerm 的 createSurface 退化为 createSurfaceSplit "right"
@@ -22,8 +45,15 @@ export const ops: BackendOps = {
     return ops.createSplit(name, "right", fromSurface);
   },
 
-  // BackendOps 接口定义含 4 参（含可选 fromSurface），此为实现契约。
-  createSplit(name: string, direction: "left" | "right" | "up" | "down", fromSurface?: string): string {
+  // BackendOps 接口定义含 4 参（含可选 fromSurface / options），此为实现契约。
+  // 该签名由统一 surface API 的向后兼容要求强制（fromSurface 保持第 3 位置参数，
+  // activate 只能作为第 4 个尾部 options 追加），故按外部 API 签名豁免参数数量约束。
+  createSplit(
+    name: string,
+    direction: "left" | "right" | "up" | "down",
+    fromSurface?: string,
+    options?: { activate?: boolean },
+  ): string {
     const args = ["cli", "split-pane"];
     if (direction === "left") args.push("--left");
     else if (direction === "right") args.push("--right");
@@ -45,6 +75,9 @@ export const ops: BackendOps = {
     } catch {
       // Optional — tab title is cosmetic.
     }
+    if (options?.activate) {
+      execFileSync("wezterm", weztermActivateArgs(paneId), { encoding: "utf8" });
+    }
     weztermLog(
       `[split] dir=${direction} from=${fromSurface ?? "<unset>"} new=${paneId} name=${JSON.stringify(name)}`,
     );
@@ -54,7 +87,7 @@ export const ops: BackendOps = {
   send(surface: string, command: string): void {
     execFileSync(
       "wezterm",
-      ["cli", "send-text", "--pane-id", surface, "--no-paste", command + "\n"],
+      ["cli", "send-text", "--pane-id", surface, "--no-paste", command + commandTerminator()],
       { encoding: "utf8" },
     );
   },

package/src/headless.ts

@@ -24,6 +24,21 @@ import { isMuxAvailable } from "./detection.ts";
 
 const HEADLESS_SURFACE_PREFIX = "headless:";
 
+/**
+ * PowerShell 启动器常量。
+ * headless 模式用 powershell.exe 直接 -Command 执行命令（配合 -ExecutionPolicy Bypass 允许运行脚本）。
+ */
+const POWERSHELL_EXECUTABLE = "powershell.exe";
+const POWERSHELL_SPAWN_FLAGS = [
+  "-NoLogo",
+  "-NoProfile",
+  "-ExecutionPolicy",
+  "Bypass",
+  "-Command",
+] as const;
+/** 显式选择 PowerShell 解释器的标识 */
+const INTERPRETER_POWERSHELL = "powershell";
+
 /** headless surface 关闭时 SIGTERM 到 SIGKILL 的等待间隔（毫秒） */
 const HEADLESS_KILL_TIMEOUT_MS = 3000;
 
@@ -56,17 +71,22 @@ export function createHeadlessSurface(name: string): string {
 // ── 后台子进程管理 ──
 
 /**
- * 在 headless surface 上启动一个 bash 子进程，stdout/stderr 写入日志文件。
+ * 在 headless surface 上启动一个子进程，stdout/stderr 写入日志文件。
  * 返回日志文件路径，调用方通过 readHeadlessScreen 读取输出。
  *
  * 注意：spawnHeadlessProcess 签名与原 mux.ts 完全一致（公开 API，不可改签名），
  * 第 4 个参数 options 为可选对象，不计入函数参数数量规则的违规。
+ * interpreter 缺省为 bash；显式选择 "powershell" 时用 powershell.exe -Command 直接执行命令。
  */
 export function spawnHeadlessProcess(
   surface: string,
   name: string,
   command: string,
-  options?: { cwd?: string; env?: Record<string, string> },
+  options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+    interpreter?: "bash" | "powershell";
+  },
 ): { logFile: string } {
   const safeId = surface.replace(/[^a-zA-Z0-9_-]/g, "_");
   const logFile = join(tmpdir(), `pi-subagent-${safeId}.log`);
@@ -78,11 +98,22 @@ export function spawnHeadlessProcess(
   }
   env.PI_SUBAGENT_HEADLESS = "1";
 
-  const child = spawn("bash", ["-c", command], {
-    cwd: options?.cwd || process.cwd(),
-    stdio: ["ignore", "pipe", "pipe"],
-    env,
-  });
+  const isPowerShell = options?.interpreter === INTERPRETER_POWERSHELL;
+  const child = isPowerShell
+    ? spawn(
+        POWERSHELL_EXECUTABLE,
+        [...POWERSHELL_SPAWN_FLAGS, command],
+        {
+          cwd: options?.cwd || process.cwd(),
+          stdio: ["ignore", "pipe", "pipe"],
+          env,
+        },
+      )
+    : spawn("bash", ["-c", command], {
+        cwd: options?.cwd || process.cwd(),
+        stdio: ["ignore", "pipe", "pipe"],
+        env,
+      });
 
   child.stdout.pipe(logStream);
   child.stderr.pipe(logStream);

package/src/mux.ts

@@ -57,7 +57,12 @@ export {
   getLastSplitSource,
   clearLastSplitSource,
 } from "./surface.ts";
-export type { PollResult } from "./surface.ts";
+export type {
+  PollResult,
+  CreateSurfaceSplitOptions,
+  SendLongCommandOptions,
+  ReadScreenOptions,
+} from "./surface.ts";
 
 // ── Cmux 公开解析函数 ──
 export {

package/src/shell.ts

@@ -34,6 +34,15 @@ export function shellEscape(s: string): string {
   return "'" + s.replace(/'/g, "'\\''") + "'";
 }
 
+/**
+ * PowerShell single-quote escape: wraps the string in single quotes,
+ * escaping any embedded single quotes by doubling them ('' in single-quoted strings),
+ * per PowerShell string literal rules.
+ */
+export function powershellEscape(s: string): string {
+  return "'" + s.replace(/'/g, "''") + "'";
+}
+
 /**
  * Return the last N lines of text.
  * 非公开 API，供 readScreen 等内部使用。

package/src/surface.ts

@@ -34,7 +34,7 @@ import {
   getHeadlessProcessExit,
   drainHeadlessProcess,
 } from "./headless.ts";
-import { shellEscape } from "./shell.ts";
+import { shellEscape, powershellEscape } from "./shell.ts";
 import type { MuxBackend } from "./detection.ts";
 import type { BackendOps } from "./backends/types.ts";
 
@@ -53,6 +53,8 @@ import { sendOttyCommand, sendOttyEscape, readOttyScreen, closeOttySurface, rena
 import { renameOrcaTerminal } from "./backends/orca.ts";
 
 const execFileAsync = promisify(execFile);
+const ORCA_BACKEND: MuxBackend = "orca";
+const HERDR_BACKEND: MuxBackend = "herdr";
 
 // ── 全键注册表 ──
 
@@ -117,6 +119,8 @@ export function createSurface(name: string): string {
     lastSplitSource = AGENT_MUXY_PANE_ID ?? null;
   } else if (backend === "otty") {
     lastSplitSource = AGENT_OTTY_PANE_ID ?? null;
+  } else if (backend === ORCA_BACKEND) {
+    lastSplitSource = AGENT_ORCA_TERMINAL_HANDLE ?? null;
   } else {
     // tmux / wezterm / zellij / herdr
     lastSplitSource = process.env.TMUX_PANE ?? null;
@@ -125,13 +129,28 @@ export function createSurface(name: string): string {
   return backendOps[backend].create(name);
 }
 
+/**
+ * 分屏来源/激活 options 的公开类型。
+ * activate 仅 wezterm 支持；其他后端忽略该提示并保持既有焦点行为。
+ */
+export interface CreateSurfaceSplitOptions {
+  /** 是否在分屏后激活新创建的 pane（仅 wezterm；默认 false，保持当前焦点） */
+  activate?: boolean;
+}
+
 /**
  * 指定方向分屏创建新 surface。
+ *
+ * 签名沿用法（外部 API 兼容豁免参数数量约束）：前三个位置参数 name/direction/fromSurface 是现有
+ * 公开契约，仓库内调用方（pi-interactive-subagents/test/integration/harness.ts）仍以
+ * createSurfaceSplit(name, direction, fromSurface) 三位置参调用，合并为参数对象会破坏这些调用点的
+ * 源码兼容；因此新增能力只能作为第 4 个可选尾部参数 options 追加，旧 3 参调用类型与行为保持不变。
  */
 export function createSurfaceSplit(
   name: string,
   direction: "left" | "right" | "up" | "down",
   fromSurface?: string,
+  options?: CreateSurfaceSplitOptions,
 ): string {
   const backend = requireMuxBackend();
 
@@ -167,7 +186,7 @@ export function createSurfaceSplit(
     lastSplitSource = source ?? null;
   }
 
-  return backendOps[backend].createSplit(name, direction, fromSurface);
+  return backendOps[backend].createSplit(name, direction, fromSurface, options);
 }
 
 /**
@@ -193,85 +212,163 @@ export function sendEscape(surface: string): void {
   backendOps[backend].sendEscape(surface);
 }
 
+/**
+ * sendLongCommand 选项。interpreter 缺省为 "bash"，与既有全部调用方保持兼容；
+ * Windows PowerShell 调用方显式传 "powershell" 才切换到 PowerShell 脚本运行时。
+ */
+export interface SendLongCommandOptions {
+  /** 显式脚本文件路径（原样保留，不自动改扩展名） */
+  scriptPath?: string;
+  /** 脚本前置片段（Shebang 除外；默认 Bash 时用于注入 env export 等） */
+  scriptPreamble?: string;
+  /** 脚本解释器，默认 "bash"；显式 "powershell" 时按 PowerShell 语法生成 .ps1 并执行 */
+  interpreter?: "bash" | "powershell";
+}
+
+// ── 长命令脚本运行时常量 ──
+
+/** 默认解释器：所有平台都保持 Bash，避免改变现有调用方语义 */
+const DEFAULT_SEND_INTERPRETER = "bash";
+const INTERPRETER_POWERSHELL = "powershell";
+
+/** 解析 sendLongCommand 的解释器；省略时始终保持 Bash 兼容默认值。 */
+export function resolveSendInterpreter(
+  interpreter?: "bash" | "powershell",
+): "bash" | "powershell" {
+  return interpreter ?? DEFAULT_SEND_INTERPRETER;
+}
+
+/** 脚本文件写入权限：PowerShell 无需可执行位，Bash 脚本需可执行位 */
+const POWERSHELL_SCRIPT_MODE = 0o644;
+const BASH_SCRIPT_MODE = 0o755;
+
+/** PowerShell -File / -Command 启动器可执行文件名与前导参数 */
+const POWERSHELL_EXECUTABLE = "powershell.exe";
+const POWERSHELL_LAUNCH_PREFIX = ["-NoLogo", "-NoProfile", "-ExecutionPolicy", "Bypass"] as const;
+
+/**
+ * 返回按解释器选择的脚本扩展名（.sh / .ps1），用于自动脚本路径的文件后缀。
+ */
+export function sendScriptExtension(interpreter: "bash" | "powershell"): string {
+  return interpreter === INTERPRETER_POWERSHELL ? ".ps1" : ".sh";
+}
+
+/**
+ * 生成脚本内容：Bash 以 shebang + \n 分隔，PowerShell 无 shebang 且以 CRLF 分隔。
+ */
+export function buildSendScriptContent(
+  interpreter: "bash" | "powershell",
+  preamble: string | undefined,
+  command: string,
+): string {
+  if (interpreter === INTERPRETER_POWERSHELL) {
+    const parts: string[] = [];
+    if (preamble) parts.push(preamble.trimEnd());
+    parts.push(command);
+    return parts.join("\r\n") + "\r\n";
+  }
+  const parts = ["#!/bin/bash"];
+  if (preamble) parts.push(preamble.trimEnd());
+  parts.push(command);
+  return parts.join("\n") + "\n";
+}
+
+/**
+ * 构建 mux pane 中执行脚本的 shell 调用：Bash 用 `bash <path>`，PowerShell 用
+ * `powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File <path>`。
+ */
+export function buildMuxInvocation(interpreter: "bash" | "powershell", scriptPath: string): string {
+  if (interpreter === INTERPRETER_POWERSHELL) {
+    return `${POWERSHELL_EXECUTABLE} ${POWERSHELL_LAUNCH_PREFIX.join(" ")} -File ${powershellEscape(scriptPath)}`;
+  }
+  return `bash ${shellEscape(scriptPath)}`;
+}
+
 /**
  * 向 surface 发送长命令（通过脚本文件避免终端自动换行问题）。
- * 返回脚本文件路径。
+ * 返回脚本文件路径。默认解释器为 Bash（所有平台）；显式 interpreter:"powershell"
+ * 时按 PowerShell 语法写 .ps1 并执行。
  */
 export function sendLongCommand(
   surface: string,
   command: string,
-  options?: { scriptPath?: string; scriptPreamble?: string },
+  options?: SendLongCommandOptions,
 ): string {
-  // Headless mode: spawn as a background child process
-  if (isHeadlessSurface(surface)) {
-    const logFile = options?.scriptPath
-      ? options.scriptPath.replace(/\.sh$/, ".log")
-      : undefined;
-    const scriptPath =
-      options?.scriptPath ??
-      join(
-        tmpdir(),
-        "pi-subagent-scripts",
-        `cmd-${Date.now()}-${Math.random().toString(16).slice(2, 8)}.sh`,
-      );
-    mkdirSync(dirname(scriptPath), { recursive: true });
-    const scriptParts = ["#!/bin/bash"];
-    if (options?.scriptPreamble) {
-      scriptParts.push(options.scriptPreamble.trimEnd());
-    }
-    scriptParts.push(command);
-    writeFileSync(scriptPath, scriptParts.join("\n") + "\n", { mode: 0o755 });
-
-    spawnHeadlessProcess(surface, "subagent", `bash ${shellEscape(scriptPath)}`, {
-      cwd: process.cwd(),
-      env: { PI_SUBAGENT_HEADLESS: "1" },
-    });
-    return scriptPath;
-  }
+  const interpreter = resolveSendInterpreter(options?.interpreter);
+  const extension = sendScriptExtension(interpreter);
 
   const scriptPath =
     options?.scriptPath ??
     join(
       tmpdir(),
       "pi-subagent-scripts",
-      `cmd-${Date.now()}-${Math.random().toString(16).slice(2, 8)}.sh`,
+      `cmd-${Date.now()}-${Math.random().toString(16).slice(2, 8)}${extension}`,
     );
   mkdirSync(dirname(scriptPath), { recursive: true });
 
-  const scriptParts = ["#!/bin/bash"];
-  if (options?.scriptPreamble) {
-    scriptParts.push(options.scriptPreamble.trimEnd());
+  const content = buildSendScriptContent(interpreter, options?.scriptPreamble, command);
+  const mode = interpreter === INTERPRETER_POWERSHELL ? POWERSHELL_SCRIPT_MODE : BASH_SCRIPT_MODE;
+  writeFileSync(scriptPath, content, { mode });
+
+  // Headless mode: spawn as a background child process
+  if (isHeadlessSurface(surface)) {
+    const headlessCommand =
+      interpreter === INTERPRETER_POWERSHELL
+        ? `& ${powershellEscape(scriptPath)}`
+        : `bash ${shellEscape(scriptPath)}`;
+    spawnHeadlessProcess(surface, "subagent", headlessCommand, {
+      cwd: process.cwd(),
+      env: { PI_SUBAGENT_HEADLESS: "1" },
+      interpreter,
+    });
+    return scriptPath;
   }
-  scriptParts.push(command);
 
-  writeFileSync(scriptPath, scriptParts.join("\n") + "\n", {
-    mode: 0o755,
-  });
-  sendCommand(surface, `bash ${shellEscape(scriptPath)}`);
+  sendCommand(surface, buildMuxInvocation(interpreter, scriptPath));
   return scriptPath;
 }
 
+/**
+ * 统一读屏 options。source 仅 herdr 后端消费（转发给 herdr pane read --source），
+ * 非 herdr 后端忽略该提示并保持各自既有读屏语义；未提供时 herdr 维持默认 recent。
+ */
+export interface ReadScreenOptions {
+  source?: "recent" | "visible" | "recent_unwrapped";
+}
+
 /**
  * 同步读取 surface 屏幕最后 N 行。
+ * options.source 仅对 herdr 后端生效（如 "recent_unwrapped"），其他后端忽略。
  */
-export function readScreen(surface: string, lines = 50): string {
+export function readScreen(surface: string, lines = 50, options?: ReadScreenOptions): string {
   if (isHeadlessSurface(surface)) {
     return readHeadlessScreen(surface, lines);
   }
 
   const backend = requireMuxBackend();
+  if (options?.source && backend === HERDR_BACKEND) {
+    return readHerdrScreen(surface, lines, options.source);
+  }
   return backendOps[backend].read(surface, lines);
 }
 
 /**
  * 异步读取 surface 屏幕最后 N 行。
+ * options.source 仅对 herdr 后端生效（如 "recent_unwrapped"），其他后端忽略。
  */
-export async function readScreenAsync(surface: string, lines = 50): Promise<string> {
+export async function readScreenAsync(
+  surface: string,
+  lines = 50,
+  options?: ReadScreenOptions,
+): Promise<string> {
   if (isHeadlessSurface(surface)) {
     return readHeadlessScreenAsync(surface, lines);
   }
 
   const backend = requireMuxBackend();
+  if (options?.source && backend === HERDR_BACKEND) {
+    return readHerdrScreen(surface, lines, options.source);
+  }
   return backendOps[backend].readAsync(surface, lines);
 }