pi-terminal-mux 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-terminal-mux
 
-Terminal multiplexer abstraction for pi extensions — one unified surface API across **muxy, cmux, tmux, zellij, wezterm, herdr and otty**, with automatic **headless fallback** (background child process + log file) when no multiplexer is detected.
+Terminal multiplexer abstraction for pi extensions — one unified surface API across **muxy, cmux, tmux, zellij, wezterm, herdr, otty and orca**, with automatic **headless fallback** (background child process + log file) when no multiplexer is detected.
 
 Any pi extension that needs terminal interaction (splitting panes, sending commands, reading screens, closing panes, waiting for process exit) should depend on this package instead of re-implementing backend detection and command assembly.
 
@@ -57,10 +57,11 @@ closeSurface(surface);
 | wezterm | `WEZTERM_UNIX_SOCKET` + `wezterm` command |
 | herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` command |
 | otty | `TERM_PROGRAM=otty` + `otty` command |
+| orca | `TERM_PROGRAM=Orca` + `orca` command + reachable Orca runtime |
 
 Default priority follows the table order (muxy first). Force a backend with:
 
-- `PI_TERMINAL_MUX` (preferred): `muxy | cmux | tmux | zellij | wezterm | herdr | otty`
+- `PI_TERMINAL_MUX` (preferred): `muxy | cmux | tmux | zellij | wezterm | herdr | otty | orca`
 - `PI_SUBAGENT_MUX`: backward-compatible alias
 
 If the forced backend's runtime is unavailable, `getMuxBackend()` returns `null` — it never silently falls back to another backend.
@@ -71,7 +72,7 @@ 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), returns a surface handle |
+| `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) |
 | `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 |
@@ -88,7 +89,7 @@ If the forced backend's runtime is unavailable, `getMuxBackend()` returns `null`
 
 ### Backend-native APIs
 
-Backend-native functions are also re-exported (e.g. `createHerdrSurface`, `splitHerdrPane`, `readHerdrScreen`, `sendOttyCommand`, `renameOttyTab`, ...). Subpath imports are available too: `pi-terminal-mux/mux`, `pi-terminal-mux/herdr`, `pi-terminal-mux/otty`.
+Backend-native functions are also re-exported (e.g. `createHerdrSurface`, `splitHerdrPane`, `readHerdrScreen`, `sendOttyCommand`, `renameOttyTab`, `createOrcaSurface`, `sendOrcaCommand`, ...). Subpath imports are available too: `pi-terminal-mux/mux`, `pi-terminal-mux/herdr`, `pi-terminal-mux/otty`, `pi-terminal-mux/orca`.
 
 ## Headless mode
 
@@ -108,7 +109,7 @@ When no backend is detected, `createSurface` returns a `headless:`-prefixed surf
 
 - **No machine coupling**: every backend is selected via runtime detection (env vars + command availability); no hardcoded local paths; missing CLIs degrade backend-by-backend down to headless.
 - **Localized user-facing text**: setup hints go through the [pi-extensions-i18n](https://www.npmjs.com/package/pi-extensions-i18n) catalog with complete `zh-CN` and `en-US` entries.
-- **Agent pane anchoring**: the agent's own pane ID on muxy/herdr/otty is captured at module load (`AGENT_MUXY_PANE_ID` etc.), immune to later focus switches.
+- **Agent pane anchoring**: the agent's own pane ID on muxy/herdr/otty/orca is captured at module load (`AGENT_MUXY_PANE_ID`, `AGENT_ORCA_TERMINAL_HANDLE` etc.), immune to later focus switches.
 
 ## License
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 终端多路复用器统一抽象层，供 pi 扩展复用。任何涉及终端交互（分屏、发命令、读屏、关屏、等待退出）的插件都应依赖本包，而不是各自重新实现 backend 探测与命令拼装。
 
-一套统一的 surface API 跨 **muxy、cmux、tmux、zellij、wezterm、herdr、otty** 七个后端，探测不到任何后端时自动降级为 **headless**（后台子进程 + 日志文件）。
+一套统一的 surface API 跨 **muxy、cmux、tmux、zellij、wezterm、herdr、otty、orca** 八个后端，探测不到任何后端时自动降级为 **headless**（后台子进程 + 日志文件）。
 
 [English README](./README.md)
 
@@ -56,10 +56,11 @@ closeSurface(surface);
 | wezterm | `WEZTERM_UNIX_SOCKET` + `wezterm` 命令 |
 | herdr | `HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr` 命令 |
 | otty | `TERM_PROGRAM=otty` + `otty` 命令 |
+| orca | `TERM_PROGRAM=Orca` + `orca` 命令 + Orca runtime 可达 |
 
 默认优先级即上表顺序（muxy 优先）。可用环境变量强制指定后端：
 
-- `PI_TERMINAL_MUX`（推荐）：`muxy | cmux | tmux | zellij | wezterm | herdr | otty`
+- `PI_TERMINAL_MUX`（推荐）：`muxy | cmux | tmux | zellij | wezterm | herdr | otty | orca`
 - `PI_SUBAGENT_MUX`：同上的向后兼容别名
 
 指定的后端运行环境不满足时 `getMuxBackend()` 返回 `null`，不会悄悄降级到其他后端。
@@ -70,7 +71,7 @@ closeSurface(surface);
 
 | 函数 | 说明 |
 |------|------|
-| `createSurface(name)` | 智能放置新 surface（cmux 首次右分屏后续开 tab、zellij tab 感知平铺/堆叠、muxy/otty 广度优先分屏），返回 surface 标识 |
+| `createSurface(name)` | 智能放置新 surface（cmux 首次右分屏后续开 tab、zellij tab 感知平铺/堆叠、muxy/otty 广度优先分屏、orca 在当前 worktree 新建 tab），返回 surface 标识 |
 | `createSurfaceSplit(name, direction, fromSurface?)` | 指定方向（left/right/up/down）分屏 |
 | `sendCommand(surface, command)` | 发送命令并回车执行 |
 | `sendLongCommand(surface, command, opts?)` | 长命令先写脚本文件再执行；`opts.scriptPreamble` 可注入 env export；返回脚本路径 |
@@ -87,7 +88,7 @@ closeSurface(surface);
 
 ### 后端原生 API
 
-各后端原生函数也从包入口透出（如 `createHerdrSurface`、`splitHerdrPane`、`readHerdrScreen`、`sendOttyCommand`、`renameOttyTab`……），子路径导入亦可：`pi-terminal-mux/mux`、`pi-terminal-mux/herdr`、`pi-terminal-mux/otty`。
+各后端原生函数也从包入口透出（如 `createHerdrSurface`、`splitHerdrPane`、`readHerdrScreen`、`sendOttyCommand`、`renameOttyTab`、`createOrcaSurface`、`sendOrcaCommand`……），子路径导入亦可：`pi-terminal-mux/mux`、`pi-terminal-mux/herdr`、`pi-terminal-mux/otty`、`pi-terminal-mux/orca`。
 
 ## Headless 模式
 
@@ -107,7 +108,7 @@ closeSurface(surface);
 
 - **不绑定具体机器**：全部后端通过运行时探测（环境变量 + 命令存在性）选择，零硬编码本机路径；外部 CLI 缺失时按后端逐个降级，最终落到 headless。
 - **用户文案国际化**：面向用户的提示走 [pi-extensions-i18n](https://www.npmjs.com/package/pi-extensions-i18n) catalog，中英文齐全。
-- **agent pane 锚定**：muxy/herdr/otty 的 agent 自身 pane ID 在模块加载时捕获（`AGENT_MUXY_PANE_ID` 等），不受用户后续焦点切换影响。
+- **agent pane 锚定**：muxy/herdr/otty/orca 的 agent 自身 pane ID 在模块加载时捕获（`AGENT_MUXY_PANE_ID`、`AGENT_ORCA_TERMINAL_HANDLE` 等），不受用户后续焦点切换影响。
 
 ## License
 

package/locales/mux.json

@@ -31,9 +31,13 @@
     "zh-CN": "请在 Otty 中运行 pi（Otty 会自动设置 TERM_PROGRAM=otty）。",
     "en-US": "Run pi inside Otty (Otty sets TERM_PROGRAM=otty automatically)."
   },
+  "setupHint.orca": {
+    "zh-CN": "请在 Orca 中运行 pi（Orca 会自动设置 TERM_PROGRAM=Orca 和 ORCA_TERMINAL_HANDLE）。",
+    "en-US": "Run pi inside Orca (Orca sets TERM_PROGRAM=Orca and ORCA_TERMINAL_HANDLE automatically)."
+  },
   "setupHint.generic": {
-    "zh-CN": "请在 Muxy、cmux（`cmux pi`）、tmux（`tmux new -A -s pi 'pi'`）、zellij（`zellij --session pi`，然后运行 `pi`）、WezTerm、herdr（运行 `herdr`，拆分 pane 后在其中运行 `pi`）或 Otty（Otty 会自动设置 TERM_PROGRAM=otty）中启动 pi。",
-    "en-US": "Start pi inside Muxy, cmux (`cmux pi`), tmux (`tmux new -A -s pi 'pi'`), zellij (`zellij --session pi`, then run `pi`), WezTerm, herdr (run `herdr`, split a pane, then run `pi` in it), or Otty (Otty sets TERM_PROGRAM=otty automatically)."
+    "zh-CN": "请在 Muxy、cmux（`cmux pi`）、tmux（`tmux new -A -s pi 'pi'`）、zellij（`zellij --session pi`，然后运行 `pi`）、WezTerm、herdr（运行 `herdr`，拆分 pane 后在其中运行 `pi`）、Otty（Otty 会自动设置 TERM_PROGRAM=otty）或 Orca（Orca 会自动设置 TERM_PROGRAM=Orca）中启动 pi。",
+    "en-US": "Start pi inside Muxy, cmux (`cmux pi`), tmux (`tmux new -A -s pi 'pi'`), zellij (`zellij --session pi`, then run `pi`), WezTerm, herdr (run `herdr`, split a pane, then run `pi` in it), Otty (Otty sets TERM_PROGRAM=otty automatically), or Orca (Orca sets TERM_PROGRAM=Orca automatically)."
   },
   "setupHint.herdrPreferred": {
     "zh-CN": "请在 herdr 中启动 pi（必须设置 HERDR_ENV=1；先运行 herdr，再在 pane 中启动 pi）。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-terminal-mux",
-  "version": "0.2.1",
+  "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",
   "type": "module",
   "main": "./index.ts",
@@ -9,7 +9,8 @@
     "./package.json": "./package.json",
     "./mux": "./src/mux.ts",
     "./herdr": "./src/herdr.ts",
-    "./otty": "./src/otty.ts"
+    "./otty": "./src/otty.ts",
+    "./orca": "./src/orca.ts"
   },
   "files": [
     "index.ts",
@@ -52,12 +53,11 @@
     "wezterm",
     "coding-agent"
   ],
-  "peerDependencies": {
-    "pi-extensions-i18n": ">=0.2.0"
+  "dependencies": {
+    "pi-extensions-i18n": "^0.3.1"
   },
   "devDependencies": {
     "@types/node": "24.12.4",
-    "pi-extensions-i18n": "^0.3.0",
     "tsx": "4.23.1",
     "typescript": "5.9.3"
   }

package/src/backends/cmux.ts

@@ -8,8 +8,12 @@
 
 import { execSync, execFileSync, spawnSync } from "node:child_process";
 import { shellEscape } from "../shell.ts";
+import { createBackendLogger } from "./shared.ts";
 import type { BackendOps } from "./types.ts";
 
+/** Cmux 后端日志（统一格式，写入 /tmp/pi-mux-cmux.log） */
+const cmuxLog = createBackendLogger("cmux", "/tmp/pi-mux-cmux.log");
+
 // ── 内部辅助 ──
 
 /** Tracked subagent pane for cmux — reused across subagent launches. */
@@ -271,7 +275,11 @@ export const ops: BackendOps = {
       try {
         const tree = execSync(`cmux tree`, { encoding: "utf8" });
         if (tree.includes(cmuxSubagentPane)) {
-          return createSurfaceInPane(name, cmuxSubagentPane);
+          const surface = createSurfaceInPane(name, cmuxSubagentPane);
+          cmuxLog(
+            `[split] mode=tab-reuse pane=${cmuxSubagentPane} new=${surface} name=${JSON.stringify(name)}`,
+          );
+          return surface;
         }
       } catch {}
       // Pane 已消失 — fall through 创建新 split
@@ -280,11 +288,18 @@ export const ops: BackendOps = {
 
     const created = createCmuxSplitSurface(name, "right", process.env.CMUX_SURFACE_ID);
     cmuxSubagentPane = created.paneRef ?? null;
+    cmuxLog(
+      `[split] mode=first dir=right from=${process.env.CMUX_SURFACE_ID ?? "<unset>"} new=${created.surface} name=${JSON.stringify(name)}`,
+    );
     return created.surface;
   },
 
   createSplit(name: string, direction: "left" | "right" | "up" | "down", fromSurface?: string): string {
-    return createCmuxSplitSurface(name, direction, fromSurface).surface;
+    const surface = createCmuxSplitSurface(name, direction, fromSurface).surface;
+    cmuxLog(
+      `[split] mode=createSurfaceSplit dir=${direction} from=${fromSurface ?? "<unset>"} new=${surface} name=${JSON.stringify(name)}`,
+    );
+    return surface;
   },
 
   send(surface: string, command: string): void {
@@ -318,6 +333,7 @@ export const ops: BackendOps = {
     execSync(`cmux close-surface --surface ${shellEscape(surface)}`, {
       encoding: "utf8",
     });
+    cmuxLog(`[close] surface=${surface}`);
   },
 
   rename(surface: string, name: string): void {

package/src/backends/herdr.ts

@@ -9,21 +9,16 @@
  *   HERDR_PANE_ID（公开 id，如 "1-1"）
  *
  * 所有 pane 操作通过 `herdr` CLI 完成，详见 SKILL.md。
+ * 日志、文件锁、BFS 分屏状态机、命令检测复用 backends/shared.ts。
  */
 
-import { execFileSync, execSync, spawnSync } from "node:child_process";
-import { appendFileSync, existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { rmSync } from "node:fs";
 import { i18n } from "../i18n.ts";
+import { createBackendLogger, withFileLock, BfsSplitStateManager, hasCommand } from "./shared.ts";
 
-// ── 日志（herdr 独立文件，便于区分后端） ──
-const HERDR_SPLIT_LOG = "/tmp/pi-herdr-split.log";
-function herdrLog(msg: string): void {
-  try {
-    appendFileSync(HERDR_SPLIT_LOG, `[${new Date().toISOString()}] ${msg}`);
-  } catch {
-    /* 写日志失败不影响主流程 */
-  }
-}
+// ── 日志（统一格式，写入 /tmp/pi-mux-herdr.log） ──
+const herdrLog = createBackendLogger("herdr", "/tmp/pi-mux-herdr.log");
 
 /**
  * 捕获于模块加载时的 agent pane id。
@@ -34,27 +29,6 @@ export const AGENT_HERDR_PANE_ID = process.env.HERDR_PANE_ID;
 export const AGENT_HERDR_WORKSPACE_ID = process.env.HERDR_WORKSPACE_ID;
 export const AGENT_HERDR_TAB_ID = process.env.HERDR_TAB_ID;
 
-// ── 命令可用性缓存 ──
-
-const commandAvailability = new Map<string, boolean>();
-
-function hasCommand(command: string): boolean {
-  if (commandAvailability.has(command)) {
-    return commandAvailability.get(command)!;
-  }
-
-  let available = false;
-  try {
-    execFileSync("which", [command], { stdio: "ignore" });
-    available = true;
-  } catch {
-    available = false;
-  }
-
-  commandAvailability.set(command, available);
-  return available;
-}
-
 /**
  * 检测 herdr backend 是否可用：
  *   1. `herdr` 命令在 PATH 中
@@ -77,12 +51,12 @@ export function isHerdrRuntimeAvailable(): boolean {
 
 /**
  * 调用 `herdr` 命令并返回 stdout。
- * 失败时 stderr 写入 log，原样抛错（调用方决定如何处理）。
+ * 失败时原样抛错（调用方决定如何处理）。
  */
 function herdrExec(args: string[]): string {
-  herdrLog(`[herdr exec] herdr ${args.map((a) => (a.includes(" ") ? JSON.stringify(a) : a)).join(" ")}\n`);
+  herdrLog(`[exec] herdr ${args.map((a) => (a.includes(" ") ? JSON.stringify(a) : a)).join(" ")}`);
   const out = execFileSync("herdr", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
-  herdrLog(`[herdr exec] -> ${JSON.stringify(out.trim().slice(0, 200))}\n`);
+  herdrLog(`[exec] -> ${JSON.stringify(out.trim().slice(0, 200))}`);
   return out;
 }
 
@@ -91,7 +65,7 @@ function herdrExec(args: string[]): string {
  * 无输出的命令，遵循 SKILL.md 中"pane send-text/send-keys/run print nothing on success"。
  */
 function herdrExecSilent(args: string[]): void {
-  herdrLog(`[herdr exec silent] herdr ${args.map((a) => (a.includes(" ") ? JSON.stringify(a) : a)).join(" ")}\n`);
+  herdrLog(`[exec silent] herdr ${args.map((a) => (a.includes(" ") ? JSON.stringify(a) : a)).join(" ")}`);
   execFileSync("herdr", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
 }
 
@@ -125,12 +99,12 @@ function extractPaneId(json: unknown): string | null {
   return null;
 }
 
-// ── mux state 缓存 ──
-//
-// herdr 没有 tmux `last_split_source` 之类的明确"上一个 split 的父 pane"语义。
-// 我们记录每个 surface 的"父 pane id"，用于 close 时清理（herdr 不需要这个，但保留
-// 以便将来扩展 — closePane 实际上只看 surface id）。
-const herdrPaneSources = new Map<string, string>();
+// ── BFS 分屏状态 marker 路径 ──
+
+/** 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`;
+}
 
 // ── 对外 API：createSurface 系列 ──
 
@@ -139,6 +113,7 @@ const herdrPaneSources = new Map<string, string>();
  *
  * 实现：split 当前 agent pane 右侧（--no-focus 保持 agent 焦点不变）。
  * 后续 subagent 按 breadth-first 模式轮转 right/down/right/down…（与 cmux/muxy 行为一致）。
+ * 锁与 BFS 状态机复用 shared.ts。
  */
 export function createHerdrSurface(name: string): string {
   if (!AGENT_HERDR_PANE_ID) {
@@ -148,142 +123,66 @@ export function createHerdrSurface(name: string): string {
     );
   }
 
-  // 与 muxy 同样的广度优先分屏策略：
-  //   第一轮：从 agent pane 向右分，pos=0, base=1
-  //   第二轮：从第一个 pane 向下分，pos=0, base=1
-  //   第三轮：从第一个 pane 向右、第二个 pane 向右，pos=0, base=2
-  //   ……
-  // 状态文件：/tmp/herdr-subagent-pane-<agent_pane_id>.json
-  const markerFile = `/tmp/herdr-subagent-pane-${AGENT_HERDR_PANE_ID.replace(/[^a-zA-Z0-9_-]/g, "_")}.json`;
-  const lockFile = `${markerFile}.lock`;
-
-  // 全局锁：所有分屏操作串行化
-  const acquired = (() => {
-    for (let i = 0; i < 60; i++) {
-      if (!existsSync(lockFile)) {
-        try {
-          writeFileSync(lockFile, `${process.pid}`, { flag: "wx" });
-          return true;
-        } catch {
-          // 竞争失败，继续等待
-        }
-      }
-      spawnSync("sleep", ["0.05"]);
-    }
-    return false;
-  })();
+  const markerFile = herdrMarkerPath();
+  const lockPath = `${markerFile}.lock`;
 
-  if (!acquired) {
-    herdrLog(`[herdr split] failed to acquire lock ${lockFile}\n`);
-    return "";
-  }
-
-  try {
-    let state: { panes: string[]; pos: number; base: number; dir: "right" | "down" } = {
-      panes: [],
-      pos: 0,
-      base: 0,
-      dir: "right",
-    };
-    try {
-      state = JSON.parse(readFileSync(markerFile, "utf8"));
-    } catch {
-      /* 文件不存在或损坏，用初始状态 */
-    }
+  return withFileLock(lockPath, {}, () => {
+    const state = new BfsSplitStateManager(markerFile);
 
     // 首次 split
-    if (state.panes.length === 0) {
+    if (state.panes().length === 0) {
       const output = herdrExec([
         "pane",
         "split",
-        AGENT_HERDR_PANE_ID,
+        AGENT_HERDR_PANE_ID!,
         "--direction",
         "right",
         "--no-focus",
       ]);
-      const json = parseHerdrJson(output);
-      const newPaneId = extractPaneId(json);
+      const newPaneId = extractPaneId(parseHerdrJson(output));
       if (newPaneId) {
-        state.panes = [newPaneId];
-        state.pos = 0;
-        state.base = 1;
-        state.dir = "down";
-        writeFileSync(markerFile, JSON.stringify(state));
-        herdrPaneSources.set(newPaneId, AGENT_HERDR_PANE_ID);
+        state.add(newPaneId);
         renameHerdrPane(newPaneId, name);
         herdrLog(
-          `[herdr split] mode=first dir=right from=${AGENT_HERDR_PANE_ID} new=${newPaneId} name=${JSON.stringify(name)}\n`,
+          `[split] mode=first dir=right from=${AGENT_HERDR_PANE_ID} new=${newPaneId} name=${JSON.stringify(name)}`,
         );
         return newPaneId;
       }
-      herdrLog(`[herdr split] first split returned no pane id, output=${JSON.stringify(output)}\n`);
+      herdrLog(`[split] first split returned no pane id, output=${JSON.stringify(output)}`);
       return "";
     }
 
-    // 本轮结束？翻转方向
-    if (state.pos >= state.base) {
-      state.pos = 0;
-      state.base = state.panes.length;
-      state.dir = state.dir === "right" ? "down" : "right";
-    }
+    // 后续：BFS 分屏
+    const next = state.next();
+    if (!next) return "";
 
-    let targetPane = state.panes[state.pos];
-    if (!targetPane) {
-      herdrLog(`[herdr split] state.panes[${state.pos}] is undefined\n`);
-      return "";
-    }
+    let { source } = next;
+    const { direction } = next;
 
-    // 若 targetPane 过期（pane 被关闭 / session 重启），自动重置状态从 agent pane 重新分屏
+    // 若 source 过期（pane 被关闭 / session 重启），重置状态从 agent pane 重新分屏
     let output: string;
-    let sourcePane = targetPane;
     try {
-      output = herdrExec([
-        "pane",
-        "split",
-        targetPane,
-        "--direction",
-        state.dir,
-        "--no-focus",
-      ]);
+      output = herdrExec(["pane", "split", source, "--direction", direction, "--no-focus"]);
     } catch {
       try { rmSync(markerFile); } catch { /* ignore */ }
-      herdrLog(
-        `[herdr split] pane ${targetPane} gone, resetting from agent pane ${AGENT_HERDR_PANE_ID}\n`,
-      );
-      state = { panes: [], pos: 0, base: 0, dir: "right" };
-      targetPane = AGENT_HERDR_PANE_ID;
-      sourcePane = AGENT_HERDR_PANE_ID;
-      output = herdrExec([
-        "pane",
-        "split",
-        AGENT_HERDR_PANE_ID,
-        "--direction",
-        "right",
-        "--no-focus",
-      ]);
+      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"]);
     }
-    const json = parseHerdrJson(output);
-    const newPaneId = extractPaneId(json);
+
+    const newPaneId = extractPaneId(parseHerdrJson(output));
     if (newPaneId) {
-      state.panes.push(newPaneId);
-      state.pos++;
-      writeFileSync(markerFile, JSON.stringify(state));
-      herdrPaneSources.set(newPaneId, sourcePane);
+      state.advance();
+      state.add(newPaneId);
       renameHerdrPane(newPaneId, name);
       herdrLog(
-        `[herdr split] mode=next pos=${state.pos - 1} base=${state.base} dir=${state.dir} from=${targetPane} new=${newPaneId} name=${JSON.stringify(name)}\n`,
+        `[split] mode=next dir=${direction} from=${source} new=${newPaneId} name=${JSON.stringify(name)}`,
       );
       return newPaneId;
     }
-    herdrLog(`[herdr split] next split returned no pane id, output=${JSON.stringify(output)}\n`);
+    herdrLog(`[split] next split returned no pane id, output=${JSON.stringify(output)}`);
     return "";
-  } finally {
-    try {
-      rmSync(lockFile);
-    } catch {
-      /* ignore */
-    }
-  }
+  });
 }
 
 /**
@@ -302,11 +201,8 @@ export function splitHerdrPane(
   if (!newPaneId) {
     throw new Error(`Unexpected herdr pane split output: ${output.trim() || "(empty)"}`);
   }
-  herdrPaneSources.set(newPaneId, fromPane);
   if (name) renameHerdrPane(newPaneId, name);
-  herdrLog(
-    `[herdr split] mode=direct dir=${dir} from=${fromPane} new=${newPaneId} name=${JSON.stringify(name ?? "")}\n`,
-  );
+  herdrLog(`[split] mode=direct dir=${dir} from=${fromPane} new=${newPaneId} name=${JSON.stringify(name ?? "")}`);
   return newPaneId;
 }
 
@@ -320,7 +216,7 @@ export function renameHerdrPane(paneId: string, name: string): void {
     const paneLabel = wsLabel ? `${wsLabel}[${name}]` : name;
     herdrExecSilent(["pane", "rename", paneId, paneLabel]);
   } catch (e) {
-    herdrLog(`[herdr rename pane] pane=${paneId} name=${JSON.stringify(name)} failed: ${(e as Error).message}\n`);
+    herdrLog(`[rename pane] pane=${paneId} name=${JSON.stringify(name)} failed: ${(e as Error).message}`);
   }
 }
 
@@ -333,7 +229,7 @@ export function renameHerdrAgent(paneId: string, name: string): void {
   try {
     herdrExecSilent(["agent", "rename", paneId, name]);
   } catch (e) {
-    herdrLog(`[herdr rename agent] pane=${paneId} name=${JSON.stringify(name)} failed: ${(e as Error).message}\n`);
+    herdrLog(`[rename agent] pane=${paneId} name=${JSON.stringify(name)} failed: ${(e as Error).message}`);
   }
 }
 
@@ -376,7 +272,7 @@ export function renameHerdrTab(paneId: string, name: string): void {
       }
     }
   } catch (e) {
-    herdrLog(`[herdr rename tab] pane=${paneId} name=${JSON.stringify(name)} failed: ${(e as Error).message}\n`);
+    herdrLog(`[rename tab] pane=${paneId} name=${JSON.stringify(name)} failed: ${(e as Error).message}`);
   }
 }
 
@@ -390,7 +286,7 @@ export function renameHerdrWorkspace(title: string): void {
   try {
     herdrExecSilent(["workspace", "rename", AGENT_HERDR_WORKSPACE_ID, title]);
   } catch (e) {
-    herdrLog(`[herdr rename workspace] title=${JSON.stringify(title)} failed: ${(e as Error).message}\n`);
+    herdrLog(`[rename workspace] title=${JSON.stringify(title)} failed: ${(e as Error).message}`);
   }
 }
 
@@ -435,38 +331,16 @@ export function readHerdrScreen(paneId: string, lines = 50, source: "visible" |
 export function closeHerdrSurface(paneId: string): void {
   herdrExecSilent(["pane", "close", paneId]);
 
-  // 清理 mux state marker（与 muxy 的 close 逻辑一致）
-  const markerFile = `/tmp/herdr-subagent-pane-${(AGENT_HERDR_PANE_ID ?? "default").replace(/[^a-zA-Z0-9_-]/g, "_")}.json`;
-  try {
-    const parsed = JSON.parse(readFileSync(markerFile, "utf8"));
-    if (parsed && Array.isArray(parsed.panes)) {
-      const idx = parsed.panes.indexOf(paneId);
-      if (idx >= 0) {
-        const beforePanes = [...parsed.panes];
-        const beforePos = parsed.pos;
-        parsed.panes.splice(idx, 1);
-        if (typeof parsed.pos === "number" && idx < parsed.pos) {
-          parsed.pos = Math.max(0, parsed.pos - 1);
-        }
-        if (parsed.panes.length === 0) {
-          rmSync(markerFile);
-          herdrLog(
-            `[herdr close] pane=${paneId} panes=${JSON.stringify(beforePanes)} -> [] pos=${beforePos} -> <marker-removed>\n`,
-          );
-        } else {
-          writeFileSync(markerFile, JSON.stringify(parsed));
-          herdrLog(
-            `[herdr close] pane=${paneId} panes=${JSON.stringify(beforePanes)} -> ${JSON.stringify(parsed.panes)} pos=${beforePos} -> ${parsed.pos}\n`,
-          );
-        }
-      } else {
-        herdrLog(`[herdr close] pane=${paneId} (not in marker state.panes)\n`);
-      }
-    }
-  } catch {
-    herdrLog(`[herdr close] pane=${paneId} (no marker, nothing to clean)\n`);
+  // 从 BFS 状态移除已关闭的 subagent，避免僵尸 ID 累积
+  const state = new BfsSplitStateManager(herdrMarkerPath());
+  const beforePanes = state.panes();
+  state.remove(paneId);
+  const afterPanes = state.panes();
+  if (beforePanes.length !== afterPanes.length) {
+    herdrLog(`[close] pane=${paneId} panes=${JSON.stringify(beforePanes)} -> ${JSON.stringify(afterPanes)}`);
+  } else {
+    herdrLog(`[close] pane=${paneId} (not in marker state.panes)`);
   }
-  herdrPaneSources.delete(paneId);
 }
 
 // ── 辅助：从 pane id 解析 workspace id ──
@@ -530,4 +404,4 @@ export const ops: BackendOps = {
   rename(surface: string, name: string): void {
     renameHerdrPane(surface, name);
   },
-};
+};