pi-terminal-mux 0.3.1 → 0.4.0

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",
 });
@@ -55,7 +56,7 @@ closeSurface(surface);
 | tmux | `TMUX` + `tmux` command |
 | zellij | `ZELLIJ` / `ZELLIJ_SESSION_NAME` + `zellij` command |
 | wezterm | `WEZTERM_UNIX_SOCKET` + `wezterm` command |
-| herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` command |
+| herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` command (`tab` mode also requires `HERDR_WORKSPACE_ID`) |
 | otty | `TERM_PROGRAM=otty` + `otty` command |
 | orca | `TERM_PROGRAM=Orca` + `orca` command + reachable Orca runtime |
 
@@ -66,18 +67,26 @@ Default priority follows the table order (muxy first). Force a backend with:
 
 If the forced backend's runtime is unavailable, `getMuxBackend()` returns `null` — it never silently falls back to another backend.
 
+### Herdr surface mode
+
+Herdr keeps the backward-compatible breadth-first split mode by default. Set `PI_SUBAGENT_HERDR_MODE=tab` to create one background tab per subagent, or `split` to select the original pane layout explicitly. `createSurfaceSplit()` always remains an explicit pane split.
+
+```bash
+export PI_SUBAGENT_HERDR_MODE=tab
+```
+
 ## API overview
 
 ### Unified surface API (same semantics across backends)
 
 | Function | Description |
 |----------|-------------|
-| `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?)` | Split in an explicit direction (left/right/up/down) |
+| `createSurface(name)` | Smart placement (herdr: breadth-first splits by default, or one background tab per surface with `PI_SUBAGENT_HERDR_MODE=tab`; 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 +104,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 |
@@ -102,6 +121,7 @@ When no backend is detected, `createSurface` returns a `headless:`-prefixed surf
 | `PI_TERMINAL_MUX` / `PI_SUBAGENT_MUX` | Force a backend |
 | `PI_SUBAGENT_ZELLIJ_MIN_COLUMNS` / `PI_SUBAGENT_ZELLIJ_MIN_ROWS` | Minimum usable size for zellij splits (default 50x10; stacks instead when smaller) |
 | `PI_SUBAGENT_RENAME_TMUX_WINDOW` / `PI_SUBAGENT_RENAME_TMUX_SESSION` | Allow renameCurrentTab / renameWorkspace on tmux (user naming untouched by default) |
+| `PI_SUBAGENT_HERDR_MODE` | Herdr surface placement: `split` (default) or `tab` |
 | `PI_SUBAGENT_RENAME_HERDR_WORKSPACE` | Allow renameWorkspace on herdr |
 | `PI_EXTENSIONS_LOCALE` | Hint language (`zh-CN` / `en-US` / `auto`), provided by pi-extensions-i18n |
 

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",
 });
@@ -54,7 +55,7 @@ closeSurface(surface);
 | tmux | `TMUX` + `tmux` 命令 |
 | zellij | `ZELLIJ` / `ZELLIJ_SESSION_NAME` + `zellij` 命令 |
 | wezterm | `WEZTERM_UNIX_SOCKET` + `wezterm` 命令 |
-| herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` 命令 |
+| herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` 命令（`tab` 模式还需要 `HERDR_WORKSPACE_ID`） |
 | otty | `TERM_PROGRAM=otty` + `otty` 命令 |
 | orca | `TERM_PROGRAM=Orca` + `orca` 命令 + Orca runtime 可达 |
 
@@ -65,18 +66,26 @@ closeSurface(surface);
 
 指定的后端运行环境不满足时 `getMuxBackend()` 返回 `null`，不会悄悄降级到其他后端。
 
+### Herdr surface 模式
+
+Herdr 默认保持向后兼容的广度优先分屏模式。设置 `PI_SUBAGENT_HERDR_MODE=tab` 后，每个 subagent 会创建独立后台 Tab；设置为 `split` 可显式选择原有分屏布局。`createSurfaceSplit()` 始终保留显式 pane 分屏语义。
+
+```bash
+export PI_SUBAGENT_HERDR_MODE=tab
+```
+
 ## API 概览
 
 ### 统一 surface API（跨后端语义一致）
 
 | 函数 | 说明 |
 |------|------|
-| `createSurface(name)` | 智能放置新 surface（cmux 首次右分屏后续开 tab、zellij tab 感知平铺/堆叠、muxy/otty/orca 广度优先分屏；orca 缺少 agent handle 时新建 tab），返回 surface 标识 |
-| `createSurfaceSplit(name, direction, fromSurface?)` | 指定方向（left/right/up/down）分屏 |
+| `createSurface(name)` | 智能放置新 surface（herdr 默认广度优先分屏，设置 `PI_SUBAGENT_HERDR_MODE=tab` 后每个 surface 创建独立后台 Tab；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 +103,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 运行时。
+
 ## 环境变量
 
 | 变量 | 说明 |
@@ -101,6 +120,7 @@ closeSurface(surface);
 | `PI_TERMINAL_MUX` / `PI_SUBAGENT_MUX` | 强制指定后端 |
 | `PI_SUBAGENT_ZELLIJ_MIN_COLUMNS` / `PI_SUBAGENT_ZELLIJ_MIN_ROWS` | zellij 分屏最小可用尺寸（默认 50×10，不满足时改堆叠） |
 | `PI_SUBAGENT_RENAME_TMUX_WINDOW` / `PI_SUBAGENT_RENAME_TMUX_SESSION` | tmux 下允许 renameCurrentTab / renameWorkspace（默认不动用户命名） |
+| `PI_SUBAGENT_HERDR_MODE` | herdr surface 放置模式：`split`（默认）或 `tab` |
 | `PI_SUBAGENT_RENAME_HERDR_WORKSPACE` | herdr 下允许 renameWorkspace |
 | `PI_EXTENSIONS_LOCALE` | 提示文案语言（`zh-CN` / `en-US` / `auto`），由 pi-extensions-i18n 提供 |
 

package/locales/mux.json

@@ -46,5 +46,9 @@
   "setupHint.ottySendKeys": {
     "zh-CN": "Otty 的 `ipc-allow-send-keys` 未启用。如需让 pi 驱动子 agent 分屏，请在 ~/.config/otty/config.toml 中添加 `ipc-allow-send-keys = true` 并重新加载 Otty。",
     "en-US": "Otty's `ipc-allow-send-keys` is disabled. To let pi drive subagent panes, add `ipc-allow-send-keys = true` to ~/.config/otty/config.toml and reload Otty."
+  },
+  "error.invalidHerdrMode": {
+    "zh-CN": "不支持的 Herdr surface 模式：{value}。可选值：split、tab。",
+    "en-US": "Unsupported Herdr surface mode: {value}. Choose split or tab."
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-terminal-mux",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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",

package/src/backends/herdr.ts

@@ -8,7 +8,7 @@
  *   HERDR_TAB_ID（公开 id，如 "1:1"）
  *   HERDR_PANE_ID（公开 id，如 "1-1"）
  *
- * 所有 pane 操作通过 `herdr` CLI 完成，详见 SKILL.md。
+ * 所有 tab / pane 操作通过 `herdr` CLI 完成，详见 SKILL.md。
  * 日志、文件锁、BFS 分屏状态机、命令检测复用 backends/shared.ts。
  */
 
@@ -19,6 +19,32 @@ import { createBackendLogger, withFileLock, BfsSplitStateManager, hasCommand } f
 
 // ── 日志（统一格式，写入 /tmp/pi-mux-herdr.log） ──
 const herdrLog = createBackendLogger("herdr", "/tmp/pi-mux-herdr.log");
+const HERDR_TAB_CLOSE_COMMAND = ["tab", "close"] as const;
+const HERDR_PANE_SPLIT_COMMAND = ["pane", "split"] as const;
+const HERDR_PANE_CLOSE_COMMAND = ["pane", "close"] as const;
+const HERDR_SPLIT_DIRECTION_FLAG = "--direction";
+const HERDR_NO_FOCUS_FLAG = "--no-focus";
+const HERDR_SPLIT_RIGHT = "right";
+const HERDR_SPLIT_DOWN = "down";
+const HERDR_SPLIT_UP = "up";
+const HERDR_MARKER_PATH_PREFIX = "/tmp/herdr-subagent-pane-";
+const HERDR_MARKER_DEFAULT_ID = "default";
+const HERDR_LOCK_SUFFIX = ".lock";
+export const HERDR_SURFACE_MODE_SPLIT = "split";
+export const HERDR_SURFACE_MODE_TAB = "tab";
+const DEFAULT_HERDR_SURFACE_MODE = HERDR_SURFACE_MODE_SPLIT;
+
+export type HerdrSurfaceMode =
+  | typeof HERDR_SURFACE_MODE_SPLIT
+  | typeof HERDR_SURFACE_MODE_TAB;
+
+/** 解析 Herdr surface 放置模式；未配置时保持旧版 split，非法显式值直接报错。 */
+export function resolveHerdrSurfaceMode(value = process.env.PI_SUBAGENT_HERDR_MODE): HerdrSurfaceMode {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized || normalized === HERDR_SURFACE_MODE_SPLIT) return DEFAULT_HERDR_SURFACE_MODE;
+  if (normalized === HERDR_SURFACE_MODE_TAB) return HERDR_SURFACE_MODE_TAB;
+  throw new Error(i18n.t("error.invalidHerdrMode", { value }));
+}
 
 /**
  * 捕获于模块加载时的 agent pane id。
@@ -33,18 +59,20 @@ export const AGENT_HERDR_TAB_ID = process.env.HERDR_TAB_ID;
  * 检测 herdr backend 是否可用：
  *   1. `herdr` 命令在 PATH 中
  *   2. 当前进程在 herdr pane 内运行（HERDR_ENV=1）
- *   3. HERDR_PANE_ID 已注入
+ *   3. HERDR_PANE_ID 已注入；tab 模式还要求 HERDR_WORKSPACE_ID
  *
  * 注意：即使 socket 暂时不通，只要命令存在且 env 注入，就认为"runtime available"。
- * 子 agent 创建时会用 `herdr pane split` 触发 socket 调用，那时报错即可。
+ * 子 agent 创建时再通过对应的 pane split / tab create 命令触发 socket 调用。
  */
 export function isHerdrRuntimeAvailable(): boolean {
-  return (
-    !!process.env.HERDR_ENV &&
-    process.env.HERDR_ENV === "1" &&
-    !!process.env.HERDR_PANE_ID &&
-    hasCommand("herdr")
-  );
+  if (
+    process.env.HERDR_ENV !== "1" ||
+    !process.env.HERDR_PANE_ID ||
+    !hasCommand("herdr")
+  ) {
+    return false;
+  }
+  return resolveHerdrSurfaceMode() === HERDR_SURFACE_MODE_SPLIT || !!process.env.HERDR_WORKSPACE_ID;
 }
 
 // ── herdr CLI 调用的薄封装 ──
@@ -103,19 +131,34 @@ function extractPaneId(json: unknown): string | null {
 
 /** herdr BFS 分屏状态 marker 文件路径（按 agent pane id 区分） */
 function herdrMarkerPath(): string {
-  return `/tmp/herdr-subagent-pane-${(AGENT_HERDR_PANE_ID ?? "default").replace(/[^a-zA-Z0-9_-]/g, "_")}.json`;
+  const paneId = (AGENT_HERDR_PANE_ID ?? HERDR_MARKER_DEFAULT_ID).replace(/[^a-zA-Z0-9_-]/g, "_");
+  return `${HERDR_MARKER_PATH_PREFIX}${paneId}.json`;
 }
 
+interface CreatedHerdrTab {
+  tabId: string;
+  paneId: string;
+}
+
+/** 从 `herdr tab create` 响应提取新 tab 与 root pane 的公开 id。 */
+function extractCreatedHerdrTab(json: unknown): CreatedHerdrTab | null {
+  if (!json || typeof json !== "object") return null;
+  const result = (json as Record<string, unknown>).result;
+  if (!result || typeof result !== "object") return null;
+  const record = result as Record<string, unknown>;
+  const tab = record.tab as Record<string, unknown> | undefined;
+  const rootPane = record.root_pane as Record<string, unknown> | undefined;
+  if (typeof tab?.tab_id !== "string" || typeof rootPane?.pane_id !== "string") return null;
+  return { tabId: tab.tab_id, paneId: rootPane.pane_id };
+}
+
+/** 记录由本进程创建的 tab surface，使 rename / close 操作作用于整个 tab。 */
+const createdHerdrTabIds = new Map<string, string>();
+
 // ── 对外 API：createSurface 系列 ──
 
-/**
- * 创建一个新的 subagent pane。
- *
- * 实现：split 当前 agent pane 右侧（--no-focus 保持 agent 焦点不变）。
- * 后续 subagent 按 breadth-first 模式轮转 right/down/right/down…（与 cmux/muxy 行为一致）。
- * 锁与 BFS 状态机复用 shared.ts。
- */
-export function createHerdrSurface(name: string): string {
+/** 使用原有 BFS 策略创建 subagent 分屏。 */
+function createHerdrSplitSurface(name: string): string {
   if (!AGENT_HERDR_PANE_ID) {
     throw new Error(
       "HERDR_PANE_ID not set; cannot determine parent pane for subagent split. " +
@@ -124,20 +167,18 @@ export function createHerdrSurface(name: string): string {
   }
 
   const markerFile = herdrMarkerPath();
-  const lockPath = `${markerFile}.lock`;
+  const lockPath = `${markerFile}${HERDR_LOCK_SUFFIX}`;
 
   return withFileLock(lockPath, {}, () => {
     const state = new BfsSplitStateManager(markerFile);
 
-    // 首次 split
     if (state.panes().length === 0) {
       const output = herdrExec([
-        "pane",
-        "split",
-        AGENT_HERDR_PANE_ID!,
-        "--direction",
-        "right",
-        "--no-focus",
+        ...HERDR_PANE_SPLIT_COMMAND,
+        AGENT_HERDR_PANE_ID,
+        HERDR_SPLIT_DIRECTION_FLAG,
+        HERDR_SPLIT_RIGHT,
+        HERDR_NO_FOCUS_FLAG,
       ]);
       const newPaneId = extractPaneId(parseHerdrJson(output));
       if (newPaneId) {
@@ -152,22 +193,31 @@ export function createHerdrSurface(name: string): string {
       return "";
     }
 
-    // 后续：BFS 分屏
     const next = state.next();
     if (!next) return "";
 
     let { source } = next;
     const { direction } = next;
-
-    // 若 source 过期（pane 被关闭 / session 重启），重置状态从 agent pane 重新分屏
     let output: string;
     try {
-      output = herdrExec(["pane", "split", source, "--direction", direction, "--no-focus"]);
+      output = herdrExec([
+        ...HERDR_PANE_SPLIT_COMMAND,
+        source,
+        HERDR_SPLIT_DIRECTION_FLAG,
+        direction,
+        HERDR_NO_FOCUS_FLAG,
+      ]);
     } catch {
       try { rmSync(markerFile); } catch { /* ignore */ }
       herdrLog(`[split] pane ${source} gone, resetting from agent pane ${AGENT_HERDR_PANE_ID}`);
-      source = AGENT_HERDR_PANE_ID!;
-      output = herdrExec(["pane", "split", source, "--direction", "right", "--no-focus"]);
+      source = AGENT_HERDR_PANE_ID;
+      output = herdrExec([
+        ...HERDR_PANE_SPLIT_COMMAND,
+        source,
+        HERDR_SPLIT_DIRECTION_FLAG,
+        HERDR_SPLIT_RIGHT,
+        HERDR_NO_FOCUS_FLAG,
+      ]);
     }
 
     const newPaneId = extractPaneId(parseHerdrJson(output));
@@ -185,6 +235,46 @@ export function createHerdrSurface(name: string): string {
   });
 }
 
+/** 在当前 workspace 中创建独立后台 tab，并返回 root pane id。 */
+function createHerdrTabSurface(name: string): string {
+  if (!AGENT_HERDR_WORKSPACE_ID) {
+    throw new Error(
+      "HERDR_WORKSPACE_ID not set; cannot determine workspace for subagent tab. " +
+        "Start pi inside herdr so HERDR_WORKSPACE_ID is injected at launch.",
+    );
+  }
+
+  const tabLabel = herdrSurfaceLabel(name);
+  const output = herdrExec([
+    "tab",
+    "create",
+    "--workspace",
+    AGENT_HERDR_WORKSPACE_ID,
+    "--cwd",
+    process.cwd(),
+    "--label",
+    tabLabel,
+    "--no-focus",
+  ]);
+  const createdTab = extractCreatedHerdrTab(parseHerdrJson(output));
+  if (!createdTab) {
+    throw new Error(`Unexpected herdr tab create output: ${output.trim() || "(empty)"}`);
+  }
+
+  createdHerdrTabIds.set(createdTab.paneId, createdTab.tabId);
+  herdrLog(
+    `[tab create] workspace=${AGENT_HERDR_WORKSPACE_ID} tab=${createdTab.tabId} pane=${createdTab.paneId} name=${JSON.stringify(name)}`,
+  );
+  return createdTab.paneId;
+}
+
+/** 按 PI_SUBAGENT_HERDR_MODE 选择兼容分屏或独立 tab；默认保持 split。 */
+export function createHerdrSurface(name: string): string {
+  return resolveHerdrSurfaceMode() === HERDR_SURFACE_MODE_TAB
+    ? createHerdrTabSurface(name)
+    : createHerdrSplitSurface(name);
+}
+
 /**
  * 从指定 pane 直接分屏（不走广度优先状态机），供 createSurfaceSplit 使用。
  * herdr 文档仅明确 right/down，left/up 分别归一到 right/down。
@@ -195,8 +285,16 @@ export function splitHerdrPane(
   direction: "left" | "right" | "up" | "down",
   name?: string,
 ): string {
-  const dir = direction === "down" || direction === "up" ? "down" : "right";
-  const output = herdrExec(["pane", "split", fromPane, "--direction", dir, "--no-focus"]);
+  const dir = direction === HERDR_SPLIT_DOWN || direction === HERDR_SPLIT_UP
+    ? HERDR_SPLIT_DOWN
+    : HERDR_SPLIT_RIGHT;
+  const output = herdrExec([
+    ...HERDR_PANE_SPLIT_COMMAND,
+    fromPane,
+    HERDR_SPLIT_DIRECTION_FLAG,
+    dir,
+    HERDR_NO_FOCUS_FLAG,
+  ]);
   const newPaneId = extractPaneId(parseHerdrJson(output));
   if (!newPaneId) {
     throw new Error(`Unexpected herdr pane split output: ${output.trim() || "(empty)"}`);
@@ -250,6 +348,12 @@ function getWorkspaceLabel(): string | null {
   }
 }
 
+/** 生成 herdr pane / tab 的统一显示标签。 */
+function herdrSurfaceLabel(name: string): string {
+  const workspaceLabel = getWorkspaceLabel();
+  return workspaceLabel ? `${workspaceLabel}[${name}]` : name;
+}
+
 /**
  * 用 herdr CLI 重命名 pane 对应的 tab。
  * tab label 格式: workspace_label[name]
@@ -258,8 +362,7 @@ export function renameHerdrTab(paneId: string, name: string): void {
   const ws = parseWorkspaceIdFromPaneId(paneId);
   if (!ws) return;
   try {
-    const wsLabel = getWorkspaceLabel();
-    const tabLabel = wsLabel ? `${wsLabel}[${name}]` : name;
+    const tabLabel = herdrSurfaceLabel(name);
     const tabsJson = herdrExec(["tab", "list", "--workspace", ws]);
     const parsed = parseHerdrJson(tabsJson);
     if (!parsed || typeof parsed !== "object") return;
@@ -308,6 +411,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,18 +430,23 @@ 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)]);
 }
 
 /**
- * 关闭 pane。
- * `herdr pane close <id>` 是 herdr CLI 子命令。
+ * 关闭 surface。本进程创建的 tab surface 关闭整个 tab；其他 pane id 仍按 pane 关闭。
  */
 export function closeHerdrSurface(paneId: string): void {
-  herdrExecSilent(["pane", "close", paneId]);
+  const tabId = createdHerdrTabIds.get(paneId);
+  if (tabId) {
+    herdrExecSilent([...HERDR_TAB_CLOSE_COMMAND, tabId]);
+    createdHerdrTabIds.delete(paneId);
+    herdrLog(`[close] tab=${tabId} pane=${paneId}`);
+    return;
+  }
+
+  herdrExecSilent([...HERDR_PANE_CLOSE_COMMAND, paneId]);
 
-  // 从 BFS 状态移除已关闭的 subagent，避免僵尸 ID 累积
   const state = new BfsSplitStateManager(herdrMarkerPath());
   const beforePanes = state.panes();
   state.remove(paneId);
@@ -402,6 +517,18 @@ export const ops: BackendOps = {
     closeHerdrSurface(surface);
   },
   rename(surface: string, name: string): void {
-    renameHerdrPane(surface, name);
+    const tabId = createdHerdrTabIds.get(surface);
+    if (!tabId) {
+      renameHerdrPane(surface, name);
+      return;
+    }
+    try {
+      const tabLabel = herdrSurfaceLabel(name);
+      herdrExecSilent(["tab", "rename", tabId, tabLabel]);
+    } catch (error) {
+      herdrLog(
+        `[rename tab] tab=${tabId} pane=${surface} name=${JSON.stringify(name)} failed: ${(error as Error).message}`,
+      );
+    }
   },
 };

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";
 
@@ -54,6 +54,7 @@ import { renameOrcaTerminal } from "./backends/orca.ts";
 
 const execFileAsync = promisify(execFile);
 const ORCA_BACKEND: MuxBackend = "orca";
+const HERDR_BACKEND: MuxBackend = "herdr";
 
 // ── 全键注册表 ──
 
@@ -128,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();
 
@@ -170,7 +186,7 @@ export function createSurfaceSplit(
     lastSplitSource = source ?? null;
   }
 
-  return backendOps[backend].createSplit(name, direction, fromSurface);
+  return backendOps[backend].createSplit(name, direction, fromSurface, options);
 }
 
 /**
@@ -196,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);
 }