@kevinhao/pi-terminal-mux 0.6.5 → 0.7.0

package/README.md

@@ -63,7 +63,7 @@ Automatic detection prefers tmux, then Orca. Force a backend with `PI_TERMINAL_M
 
 | Function | Behavior |
 |----------|----------|
-| `createSurface(name, options?)` | tmux right-split; Orca breadth-first splits from the caller, or a new tab without a caller handle; headless fallback. `options.command` starts work during creation |
+| `createSurface(name, options?)` | tmux and Orca both breadth-first split from the caller's pane into a grid; Orca opens a new tab without a caller handle; headless fallback. `options.command` starts work during creation |
 | `createSurfaceSplit(name, direction, fromSurface?, options?)` | Explicit split; `direction` is left/right/up/down, `options.command` is optional. Requires tmux or Orca; headless has no pane layout |
 | `sendCommand(surface, command)` | Send input followed by Enter to an existing terminal |
 | `sendLongCommand(surface, command, options?)` | Write a script, then execute it. Supports `scriptPath`, `scriptPreamble`, and `interpreter: "bash" | "powershell"` |

package/README.zh-CN.md

@@ -63,7 +63,7 @@ const scriptPath = sendLongCommand(surface, "pi --session /tmp/child.jsonl", {
 
 | 函数 | 行为 |
 |------|------|
-| `createSurface(name, options?)` | tmux 向右分屏；Orca 从调用方做 BFS 分屏，没有调用方 handle 时新建 tab；无后端时 headless。`options.command` 在创建时启动任务 |
+| `createSurface(name, options?)` | tmux 与 Orca 一致：从调用方 pane 出发做 BFS 网格分屏；Orca 没有调用方 handle 时新建 tab；无后端时 headless。`options.command` 在创建时启动任务 |
 | `createSurfaceSplit(name, direction, fromSurface?, options?)` | 指定方向 left/right/up/down 分屏；可传 `options.command`。要求 tmux 或 Orca，headless 没有布局 |
 | `sendCommand(surface, command)` | 向现有终端发送文本并回车 |
 | `sendLongCommand(surface, command, options?)` | 先写脚本再执行；支持 `scriptPath`、`scriptPreamble` 和 `interpreter: "bash" | "powershell"` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kevinhao/pi-terminal-mux",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Terminal surface API for tmux and Orca, with native startup commands and headless fallback",
   "type": "module",
   "main": "./index.ts",

package/src/backends/orca.ts

@@ -32,8 +32,8 @@
 
 import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
-import { BfsSplitStateManager, createBackendLogger, hasCommand, withFileLock } from "./shared.ts";
-import type { BackendOps, CreateSurfaceOptions } from "./types.ts";
+import { BfsSplitStateManager, createBackendLogger, createBfsSurface, hasCommand } from "./shared.ts";
+import type { BackendOps, CreateSurfaceOptions, SurfaceState } from "./types.ts";
 
 const ORCA_RUNTIME_CHECK_TIMEOUT_MS = 1_500;
 const ORCA_COMMAND_TIMEOUT_MS = 10_000;
@@ -244,30 +244,12 @@ export function createOrcaSurface(name: string, options?: CreateSurfaceOptions):
   const agentHandle = AGENT_ORCA_TERMINAL_HANDLE;
   if (!agentHandle) return createOrcaTab(name, options);
 
-  const markerFile = orcaStateFile();
-  const lockPath = `${markerFile}.lock`;
   try {
-    return withFileLock(lockPath, { timeoutMs: 3_000 }, () => {
-      let state = new BfsSplitStateManager(markerFile);
-      if (state.panes().length === 0) {
-        const handle = splitOrcaTerminal("right", agentHandle, options);
-        state.add(handle);
-        return handle;
-      }
-      const next = state.next();
-      if (!next) throw new Error("Cannot determine the next Orca split source.");
-      // Resolve stale placement before submitting work. Never retry an ambiguous create failure.
-      if (queryOrcaTerminalState(next.source).kind === "absent") {
-        for (const pane of state.panes()) state.remove(pane);
-        state = new BfsSplitStateManager(markerFile);
-        const handle = splitOrcaTerminal("right", agentHandle, options);
-        state.add(handle);
-        return handle;
-      }
-      const handle = splitOrcaTerminal(next.direction, next.source, options);
-      state.advance();
-      state.add(handle);
-      return handle;
+    return createBfsSurface({
+      statePath: orcaStateFile(),
+      base: agentHandle,
+      split: (direction, source) => splitOrcaTerminal(direction, source, options),
+      isAbsent: (handle) => queryOrcaTerminalState(handle).kind === "absent",
     });
   } catch (error) {
     orcaLog(`[create] failed: ${(error as Error).message}`);
@@ -490,4 +472,8 @@ export const ops: BackendOps = {
   rename(surface: string, name: string): void {
     renameOrcaTerminal(surface, name);
   },
+  /** 查询 terminal 是否存在；查询失败归一为 unknown */
+  state(surface: string): SurfaceState {
+    return queryOrcaTerminalState(surface).kind;
+  },
 };

package/src/backends/shared.ts

@@ -208,6 +208,53 @@ export class BfsSplitStateManager {
   }
 }
 
+// ── BFS 分屏创建（tmux / Orca 共用） ──
+
+export interface BfsSplitOptions {
+  /** BFS 状态 marker 文件路径 */
+  statePath: string;
+  /** 第一个 pane 的分屏源（agent 自己的 pane） */
+  base: string;
+  /** 执行一次分屏，返回新 pane ID */
+  split: (direction: BfsNext["direction"], source: string) => string;
+  /** 该 pane 是否已消失，用于丢弃僵尸状态 */
+  isAbsent: (pane: string) => boolean;
+}
+
+/**
+ * 按 BFS 网格从 base 分屏：首次向右，之后按轮次交替 right/down，
+ * 让多个 subagent 铺成二维网格而不是一路向右切窄。
+ *
+ * 状态存于 statePath（跨进程），用文件锁串行化并发创建。
+ * 下一个分屏源已消失时清空状态，重新从 base 向右开始。
+ */
+export function createBfsSurface(options: BfsSplitOptions): string {
+  const { statePath, base, split, isAbsent } = options;
+  return withFileLock(`${statePath}.lock`, { timeoutMs: 3_000 }, () => {
+    let state = new BfsSplitStateManager(statePath);
+    const first = (): string => {
+      const pane = split("right", base);
+      state.add(pane);
+      return pane;
+    };
+
+    if (state.panes().length === 0) return first();
+
+    const next = state.next();
+    if (!next) throw new Error("Cannot determine the next split source.");
+    if (isAbsent(next.source)) {
+      for (const pane of state.panes()) state.remove(pane);
+      state = new BfsSplitStateManager(statePath);
+      return first();
+    }
+
+    const pane = split(next.direction, next.source);
+    state.advance();
+    state.add(pane);
+    return pane;
+  });
+}
+
 // ── 命令可用性检测 ──
 
 const commandAvailability = new Map<string, boolean>();

package/src/backends/tmux.ts

@@ -3,21 +3,52 @@
  *
  * Tmux 特定的 surface 操作：split-window / send-keys / capture-pane / kill-pane。
  * Tmux 没有 pane 级命名，rename 退化为 window 命名。
+ *
+ * create() 与 Orca 保持一致：从 agent pane（TMUX_PANE）出发按 BFS 网格分屏，
+ * 首次向右，之后按轮次交替 right/down，让 subagent 铺成二维网格。
+ * 状态 marker 按 agent pane 隔离，放在系统临时目录。
  */
 
-import { execFileSync, execFile } from "node:child_process";
+import { execFileSync, execFile, spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
 import { promisify } from "node:util";
-import { createBackendLogger } from "./shared.ts";
-import type { BackendOps, CreateSurfaceOptions } from "./types.ts";
+import { BfsSplitStateManager, createBackendLogger, createBfsSurface } from "./shared.ts";
+import type { BackendOps, CreateSurfaceOptions, SurfaceState } from "./types.ts";
 
 const execFileAsync = promisify(execFile);
 
 /** Tmux 后端日志（统一格式，写入 /tmp/pi-mux-tmux.log） */
 const tmuxLog = createBackendLogger("tmux", "/tmp/pi-mux-tmux.log");
 
+/** BFS 分屏状态 marker 路径：按 agent pane 隔离不同 tmux 会话/窗口 */
+function tmuxStateFile(): string {
+  const base = process.env.TMUX_PANE ?? "default";
+  return `${tmpdir()}/tmux-subagent-pane-${base.replace(/[^a-zA-Z0-9_-]/g, "_")}.json`;
+}
+
+/** 从 BFS marker 中移除已关闭的 pane，避免后续 create 使用僵尸 pane */
+function cleanupStateForSurface(pane: string): void {
+  try {
+    new BfsSplitStateManager(tmuxStateFile()).remove(pane);
+  } catch (e) {
+    tmuxLog(`[state] cleanup failed for ${pane}: ${(e as Error).message}`);
+  }
+}
+
+function isPaneAbsent(pane: string): boolean {
+  return ops.state(pane) === "absent";
+}
+
 export const ops: BackendOps = {
   create(name: string, options?: CreateSurfaceOptions): string {
-    return ops.createSplit(name, "right", process.env.TMUX_PANE, options);
+    const base = process.env.TMUX_PANE;
+    if (!base) return ops.createSplit(name, "right", undefined, options);
+    return createBfsSurface({
+      statePath: tmuxStateFile(),
+      base,
+      split: (direction, source) => ops.createSplit(name, direction, source, options),
+      isAbsent: isPaneAbsent,
+    });
   },
 
   createSplit(name: string, direction: "left" | "right" | "up" | "down", fromSurface?: string, options?: CreateSurfaceOptions): string {
@@ -76,6 +107,7 @@ export const ops: BackendOps = {
   close(surface: string): void {
     execFileSync("tmux", ["kill-pane", "-t", surface], { encoding: "utf8" });
     tmuxLog(`[close] surface=${surface}`);
+    cleanupStateForSurface(surface);
   },
 
   rename(surface: string, name: string): void {
@@ -85,4 +117,11 @@ export const ops: BackendOps = {
     }).trim();
     execFileSync("tmux", ["rename-window", "-t", windowId, name], { encoding: "utf8" });
   },
+
+  state(surface: string): SurfaceState {
+    const result = spawnSync("tmux", ["list-panes", "-a", "-F", "#{pane_id}"], { encoding: "utf8", timeout: 5000 });
+    if (result.status === 0) return result.stdout.split(/\s+/).includes(surface) ? "present" : "absent";
+    if (/no server running|error connecting.*No such file|failed to connect.*No such file/.test(result.stderr ?? "")) return "absent";
+    return "unknown";
+  },
 };

package/src/backends/types.ts

@@ -17,4 +17,8 @@ export interface BackendOps {
   readAsync(surface: string, lines?: number): Promise<string>;
   close(surface: string): void;
   rename(surface: string, name: string): void;
+  /** Absence must come from a successful inventory, never from a failed read. */
+  state(surface: string): SurfaceState;
 }
+
+export type SurfaceState = "present" | "absent" | "unknown";

package/src/headless.ts

@@ -19,6 +19,7 @@ import type { WriteStream } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { isMuxAvailable } from "./detection.ts";
+import type { SurfaceState } from "./backends/types.ts";
 
 // ── 常量 ──
 
@@ -144,6 +145,14 @@ export function spawnHeadlessProcess(
 /**
  * 关闭 headless surface：先 SIGTERM，HEADLESS_KILL_TIMEOUT_MS 后若仍存活则 SIGKILL。
  */
+/** Headless surfaces have no inventory; the managed child process is the authority. */
+export function headlessSurfaceState(surface: string): SurfaceState {
+  if (!isHeadlessSurface(surface)) return "unknown";
+  const proc = headlessProcesses.get(surface);
+  if (!proc) return "absent";
+  return proc.child.exitCode === null && proc.child.signalCode === null ? "present" : "absent";
+}
+
 export function closeHeadlessSurface(surface: string): void {
   const proc = headlessProcesses.get(surface);
   if (!proc) return;

package/src/mux.ts

@@ -34,6 +34,7 @@ export {
   readScreen,
   readScreenAsync,
   closeSurface,
+  surfaceState,
   renameSurface,
   getRenameCapability,
   renameCurrentTab,
@@ -53,6 +54,7 @@ export type {
   RenameCapability,
   RenameResult,
 } from "./surface.ts";
+export type { SurfaceState } from "./backends/types.ts";
 
 export {
   TERMINAL_RENAME_CONTEXT_ENV,

package/src/surface.ts

@@ -11,10 +11,10 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
 import { getMuxBackend, muxLog, muxSetupHint } from "./detection.ts";
-import { isHeadlessSurface, createHeadlessSurface, closeHeadlessSurface, sendHeadlessEscape, readHeadlessScreen, readHeadlessScreenAsync, spawnHeadlessProcess, getHeadlessProcessExit, drainHeadlessProcess } from "./headless.ts";
+import { isHeadlessSurface, createHeadlessSurface, closeHeadlessSurface, sendHeadlessEscape, readHeadlessScreen, readHeadlessScreenAsync, spawnHeadlessProcess, getHeadlessProcessExit, drainHeadlessProcess, headlessSurfaceState } from "./headless.ts";
 import { shellEscape, powershellEscape } from "./shell.ts";
 import type { MuxBackend } from "./detection.ts";
-import type { BackendOps, CreateSurfaceOptions } from "./backends/types.ts";
+import type { BackendOps, CreateSurfaceOptions, SurfaceState } from "./backends/types.ts";
 import { ops as tmuxOps } from "./backends/tmux.ts";
 import { ops as orcaOps, AGENT_ORCA_TERMINAL_HANDLE, renameOrcaTerminal } from "./backends/orca.ts";
 
@@ -257,6 +257,20 @@ export function closeSurface(surface: string): void {
   backendOps[backend].close(surface);
 }
 
+/**
+ * Query whether a surface still exists.
+ *
+ * A failed screen read must not be reported as absence, so this asks the backend
+ * for its inventory. Headless surfaces are tracked by their managed child process.
+ */
+export function surfaceState(surface: string): SurfaceState {
+  if (!surface) return "unknown";
+  if (isHeadlessSurface(surface)) return headlessSurfaceState(surface);
+  const backend = getMuxBackend();
+  if (!backend) return "unknown";
+  return backendOps[backend].state(surface);
+}
+
 /**
  * 重命名指定 surface。
  */