pi-terminal-mux 0.4.1 → 0.5.0

package/README.md

@@ -88,10 +88,14 @@ export PI_SUBAGENT_HERDR_MODE=tab
 | `sendEscape(surface)` | Send one ESC keypress |
 | `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 |
+| `renameSurface(surface, name)` / `renameAgent(surface, name)` | Rename a known surface or agent label |
+| `getRenameCapability(operation, backend?, env?)` | Report the actual rename target or an explicit `unsupported` / `disabled` capability without executing a command |
+| `renameCurrentTab(title)` / `renameWorkspace(title)` | Rename and return a discriminated `renamed` / `unsupported` / `disabled` / `failed` result |
 | `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 |
 | `getLastSplitSource()` / `clearLastSplitSource()` | Source pane of the most recent split (for UI display) |
 
+Rename targets differ by backend: muxy/zellij tab rename targets a pane; tmux targets a window/session when its opt-in variables are enabled; WezTerm workspace rename targets the window; cmux and Herdr provide native workspace rename; Otty and Orca have no workspace rename. Headless reports `unsupported` instead of silently succeeding.
+
 ### Detection and utilities
 
 `getMuxBackend()`, `isMuxAvailable()`, `isHeadlessMode()`, `muxSetupHint()`, `getAgentPaneId(backend?)`, `backendAgentPaneEnvVar(backend)`, `shellEscape()`, `isFishShell()`, `exitStatusVar()`, plus zellij placement planning (`selectZellijPlacement` etc.) and cmux/otty JSON parsing helpers — all pure and unit-testable.
@@ -134,3 +138,14 @@ These are opt-in capabilities — existing Bash callers and `pi-interactive-suba
 ## License
 
 MIT
+
+
+## Scoped naming
+
+`createSurfaceRenameContext(surface)` describes the terminal target a launcher can grant to a child. Pass its JSON value in `PI_TERMINAL_RENAME_CONTEXT`, replacing any inherited value on **every launch and resume**. This protocol is owned by terminal-mux, not by a naming or subagent extension.
+
+`resolveTerminalRenameTargets({ tab, workspace })` returns explicit target IDs and `surface`/`shared` scope, or individual skipped/failed results. `renameTerminalTarget(reference, title)` executes against that captured identity. Callers decide when to rename and which targets to request; the library does not generate titles or change Pi sessions.
+
+A restricted child never renames a workspace. cmux surfaces, muxy/zellij panes, and Herdr panes or explicitly created Herdr tabs can be granted. tmux/WezTerm/Otty/Orca split surfaces do not prove exclusive ownership of their window/tab: naming is skipped rather than expanded to the shared parent. Ordinary sessions require their own target IDs; missing IDs never fall back to focus or the first tab. Existing backend rename opt-ins still apply to ordinary sessions.
+
+Invalid JSON or an unknown protocol version is an error, not unrestricted access. Legacy child identity variables without this protocol restrict terminal naming until the launcher supplies ownership. This is a cooperation contract for trusted local processes, not a security sandbox. WezTerm/Otty split creation does not rename a shared tab.

package/README.zh-CN.md

@@ -87,10 +87,14 @@ export PI_SUBAGENT_HERDR_MODE=tab
 | `sendEscape(surface)` | 发送一次 ESC |
 | `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)` | 命名（按后端能力降级或跳过） |
+| `renameSurface(surface, name)` / `renameAgent(surface, name)` | 重命名已知 surface 或 agent 标签 |
+| `getRenameCapability(operation, backend?, env?)` | 不执行命令，返回实际重命名目标，或明确的 `unsupported` / `disabled` 能力结果 |
+| `renameCurrentTab(title)` / `renameWorkspace(title)` | 执行重命名并返回可判别的 `renamed` / `unsupported` / `disabled` / `failed` 结果 |
 | `pollForExit(surface, signal, opts)` | 等待 surface 内进程退出：优先 `.exit` sidecar 文件，其次屏幕 sentinel（`__SUBAGENT_DONE_<code>__`），headless 走子进程 exit |
 | `getLastSplitSource()` / `clearLastSplitSource()` | 最近一次分屏的来源 pane（用于 UI 展示） |
 
+各后端的实际目标不同：muxy/zellij 的 tab 重命名作用于 pane；tmux 在开启对应变量后作用于 window/session；WezTerm 的 workspace 重命名作用于 window；cmux 和 Herdr 提供原生 workspace 重命名；Otty、Orca 没有 workspace 重命名。Headless 会明确返回 `unsupported`，不再静默成功。
+
 ### 探测与工具
 
 `getMuxBackend()`、`isMuxAvailable()`、`isHeadlessMode()`、`muxSetupHint()`、`getAgentPaneId(backend?)`、`backendAgentPaneEnvVar(backend)`、`shellEscape()`、`isFishShell()`、`exitStatusVar()`，以及 zellij 放置规划（`selectZellijPlacement` 等）与 cmux/otty JSON 解析等纯函数，均可直接引用做单元测试。
@@ -133,3 +137,14 @@ export PI_SUBAGENT_HERDR_MODE=tab
 ## License
 
 MIT
+
+
+## 按归属改名
+
+`createSurfaceRenameContext(surface)` 描述启动方可授予子进程的终端改名目标。把返回值序列化为 JSON 放入 `PI_TERMINAL_RENAME_CONTEXT`，**每次启动和恢复都替换继承值**。协议属于 terminal-mux，不属于命名或子代理插件。
+
+`resolveTerminalRenameTargets({ tab, workspace })` 返回明确的目标 ID、`surface`/`shared` 范围，或逐目标跳过/失败结果。`renameTerminalTarget(reference, title)` 对捕获的身份执行改名。调用方决定何时改、改哪些目标；库不生成标题，也不修改 Pi session。
+
+受限子进程不能改 workspace。cmux surface、muxy/zellij pane、Herdr pane 或明确新建的 Herdr tab 可以授予。tmux/WezTerm/Otty/Orca 的分屏不能证明独占 window/tab，改名会跳过，不扩大到共享父目标。普通会话必须能确定自身目标 ID；缺失时不退回当前焦点或第一个 tab。普通会话仍遵守各后端原有的改名开关。
+
+协议 JSON 损坏或版本未知会报错，不能退回无限制范围。只有旧子代理身份标志、没有归属协议时，终端改名受限，直到启动方提供归属。此协议用于可信本地进程协作，不是安全沙箱。WezTerm/Otty 创建分屏时不会重命名共享 tab。

package/locales/mux.json

@@ -50,5 +50,17 @@
   "error.invalidHerdrMode": {
     "zh-CN": "不支持的 Herdr surface 模式：{value}。可选值：split、tab。",
     "en-US": "Unsupported Herdr surface mode: {value}. Choose split or tab."
+  },
+  "error.renameIncomplete": {
+    "zh-CN": "{backend} 未完成终端改名。",
+    "en-US": "{backend} did not complete terminal renaming."
+  },
+  "rename.invalidContext": {
+    "zh-CN": "终端改名归属信息无效；未修改终端名称。",
+    "en-US": "Invalid terminal rename ownership context; terminal names were not changed."
+  },
+  "rename.missingId": {
+    "zh-CN": "无法确定终端改名目标 ID。",
+    "en-US": "Cannot determine the terminal rename target ID."
   }
 }

package/package.json

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

@@ -20,6 +20,10 @@ 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_TAB_LIST_COMMAND = ["tab", "list"] as const;
+const HERDR_TAB_RENAME_COMMAND = ["tab", "rename"] as const;
+const HERDR_WORKSPACE_RENAME_COMMAND = ["workspace", "rename"] as const;
+const HERDR_WORKSPACE_FLAG = "--workspace";
 const HERDR_PANE_SPLIT_COMMAND = ["pane", "split"] as const;
 const HERDR_PANE_CLOSE_COMMAND = ["pane", "close"] as const;
 const HERDR_SPLIT_DIRECTION_FLAG = "--direction";
@@ -155,6 +159,11 @@ function extractCreatedHerdrTab(json: unknown): CreatedHerdrTab | null {
 /** 记录由本进程创建的 tab surface，使 rename / close 操作作用于整个 tab。 */
 const createdHerdrTabIds = new Map<string, string>();
 
+/** 仅返回本进程实际创建的独占 tab，供启动方声明改名归属。 */
+export function getCreatedHerdrTabId(surface: string): string | undefined {
+  return createdHerdrTabIds.get(surface);
+}
+
 // ── 对外 API：createSurface 系列 ──
 
 /** 使用原有 BFS 策略创建 subagent 分屏。 */
@@ -358,24 +367,28 @@ function herdrSurfaceLabel(name: string): string {
  * 用 herdr CLI 重命名 pane 对应的 tab。
  * tab label 格式: workspace_label[name]
  */
-export function renameHerdrTab(paneId: string, name: string): void {
+export function renameHerdrTab(paneId: string, name: string): boolean {
   const ws = parseWorkspaceIdFromPaneId(paneId);
-  if (!ws) return;
+  if (!ws) return false;
   try {
     const tabLabel = herdrSurfaceLabel(name);
-    const tabsJson = herdrExec(["tab", "list", "--workspace", ws]);
+    if (paneId === AGENT_HERDR_PANE_ID && AGENT_HERDR_TAB_ID) {
+      herdrExecSilent([...HERDR_TAB_RENAME_COMMAND, AGENT_HERDR_TAB_ID, tabLabel]);
+      return true;
+    }
+
+    const tabsJson = herdrExec([...HERDR_TAB_LIST_COMMAND, HERDR_WORKSPACE_FLAG, ws]);
     const parsed = parseHerdrJson(tabsJson);
-    if (!parsed || typeof parsed !== "object") return;
+    if (!parsed || typeof parsed !== "object") return false;
     const result = (parsed as Record<string, unknown>).result as Record<string, unknown> | undefined;
     const tabs = (result?.tabs as Array<Record<string, unknown>>) ?? [];
-    if (tabs.length > 0) {
-      const firstTab = tabs[0];
-      if (firstTab && typeof firstTab.tab_id === "string") {
-        herdrExecSilent(["tab", "rename", firstTab.tab_id, tabLabel]);
-      }
-    }
+    const firstTab = tabs[0];
+    if (!firstTab || typeof firstTab.tab_id !== "string") return false;
+    herdrExecSilent([...HERDR_TAB_RENAME_COMMAND, firstTab.tab_id, tabLabel]);
+    return true;
   } catch (e) {
     herdrLog(`[rename tab] pane=${paneId} name=${JSON.stringify(name)} failed: ${(e as Error).message}`);
+    return false;
   }
 }
 
@@ -383,13 +396,15 @@ export function renameHerdrTab(paneId: string, name: string): void {
  * 重命名 workspace。herdr 中 workspace rename 命令是 `herdr workspace rename <id> <label>`。
  * 仅当环境变量 PI_SUBAGENT_RENAME_HERDR_WORKSPACE=1 时启用（保守策略，避免影响用户命名）。
  */
-export function renameHerdrWorkspace(title: string): void {
-  if (process.env.PI_SUBAGENT_RENAME_HERDR_WORKSPACE !== "1") return;
-  if (!AGENT_HERDR_WORKSPACE_ID) return;
+export function renameHerdrWorkspace(title: string): boolean {
+  if (process.env.PI_SUBAGENT_RENAME_HERDR_WORKSPACE !== "1") return false;
+  if (!AGENT_HERDR_WORKSPACE_ID) return false;
   try {
-    herdrExecSilent(["workspace", "rename", AGENT_HERDR_WORKSPACE_ID, title]);
+    herdrExecSilent([...HERDR_WORKSPACE_RENAME_COMMAND, AGENT_HERDR_WORKSPACE_ID, title]);
+    return true;
   } catch (e) {
     herdrLog(`[rename workspace] title=${JSON.stringify(title)} failed: ${(e as Error).message}`);
+    return false;
   }
 }
 

package/src/backends/orca.ts

@@ -211,8 +211,8 @@ function orcaExec(args: string[]): string {
   return result.stdout;
 }
 
-/** 调用 `orca` 命令，失败只记 log 不抛错。用于 send/rename/close 这类 best-effort 操作。 */
-function orcaExecSilent(args: string[]): void {
+/** 调用 `orca` 命令，失败只记 log 不抛错，并返回执行是否成功。 */
+function orcaExecSilent(args: string[]): boolean {
   const cmdline = `orca ${args
     .map((a) => (a.includes(" ") || a.includes('"') ? JSON.stringify(a) : a))
     .join(" ")}`;
@@ -228,7 +228,9 @@ function orcaExecSilent(args: string[]): void {
         (result.stderr ?? "").trim().slice(0, 200),
       )}`,
     );
+    return false;
   }
+  return true;
 }
 
 // ── 对外 API ──
@@ -424,8 +426,8 @@ export function closeOrcaSurface(handle: string): void {
  * 注意：rename 作用于 tab 标题，split pane 与源 pane 共享 tab ——
  * 调用方需确认 target 是独立 tab（create() 产物或 agent 自己的 terminal）。
  */
-export function renameOrcaTerminal(handle: string, name: string): void {
-  orcaExecSilent(["terminal", "rename", "--terminal", handle, "--title", name]);
+export function renameOrcaTerminal(handle: string, name: string): boolean {
+  return orcaExecSilent(["terminal", "rename", "--terminal", handle, "--title", name]);
 }
 
 // ── BackendOps 适配器（薄包装以上原生函数，行为语义见各函数注释） ──

package/src/backends/otty.ts

@@ -194,7 +194,7 @@ function ottyExec(args: string[]): string {
  * 调用 `otty` 命令，丢弃 stdout。用于 sendCommand / sendKeys / closePane 这类
  * 无输出的命令。
  */
-function ottyExecSilent(args: string[]): void {
+function ottyExecSilent(args: string[]): boolean {
   const cmdline = `otty ${args
     .map((a) => (a.includes(" ") || a.includes('"') ? JSON.stringify(a) : a))
     .join(" ")}`;
@@ -209,7 +209,9 @@ function ottyExecSilent(args: string[]): void {
         (result.stderr ?? "").trim().slice(0, 200),
       )}`,
     );
+    return false;
   }
+  return true;
 }
 
 // ── Pane 数据结构 ──
@@ -368,7 +370,7 @@ export function createOttySurface(name: string): string {
         return "";
       }
       state.add(newId);
-      renameOttyTab(newId, name);
+      // 新 pane 不代表独占 tab，保留创建时的 pane 标题。
       ottyLog(`[create] mode=first dir=right from=${agentId} new=${newId} name=${JSON.stringify(name)}`);
       return newId;
     }
@@ -436,7 +438,7 @@ export function createOttySurface(name: string): string {
     // split 源是 agent pane（不在状态机里），只需 add。
     if (!recovered) state.advance();
     state.add(newId);
-    renameOttyTab(newId, name);
+    // 新 pane 不代表独占 tab，保留创建时的 pane 标题。
     ottyLog(`[create] mode=next dir=${direction} from=${target} new=${newId} name=${JSON.stringify(name)}`);
     return newId;
   });
@@ -565,16 +567,21 @@ export function closeOttySurface(paneId: string): void {
  * 重命名 pane 对应的 tab。
  * Otty 没有"pane -> tab id"的直接命令，所以用 `panes --json` 反查 tab_id。
  */
-export function renameOttyTab(paneId: string, name: string): void {
+export function renameOttyTab(paneId: string, name: string): boolean {
   const tabId = getTabIdForPane(paneId);
   if (!tabId) {
     ottyLog(`[rename] pane=${paneId} no tab id found`);
-    return;
+    return false;
   }
   try {
-    ottyExecSilent(["tab", "rename", "--tab", tabId, name]);
+    if (!ottyExecSilent(["tab", "rename", "--tab", tabId, name])) {
+      ottyLog(`[rename] pane=${paneId} tab=${tabId} name=${JSON.stringify(name)} failed`);
+      return false;
+    }
+    return true;
   } catch (e) {
     ottyLog(`[rename] pane=${paneId} tab=${tabId} name=${JSON.stringify(name)} failed: ${(e as Error).message}`);
+    return false;
   }
 }
 

package/src/backends/wezterm.ts

@@ -68,13 +68,7 @@ export const ops: BackendOps = {
       throw new Error(`Unexpected wezterm split-pane output: ${rawId || "(empty)"}`);
     }
     const paneId = rawId;
-    try {
-      execFileSync("wezterm", ["cli", "set-tab-title", "--pane-id", paneId, name], {
-        encoding: "utf8",
-      });
-    } catch {
-      // Optional — tab title is cosmetic.
-    }
+    // 分屏与父 pane 共享 tab，不能用子任务名称覆盖共享标题。
     if (options?.activate) {
       execFileSync("wezterm", weztermActivateArgs(paneId), { encoding: "utf8" });
     }

package/src/index.ts

@@ -10,7 +10,7 @@
  *   - sendCommand / sendLongCommand / sendEscape
  *   - readScreen / readScreenAsync
  *   - closeSurface
- *   - renameCurrentTab / renameAgent / renameWorkspace
+ *   - renameCurrentTab / renameAgent / renameWorkspace / getRenameCapability
  *   - pollForExit                      等待 surface 内进程退出（.exit sidecar / sentinel）
  *
  * 后端探测：

package/src/mux.ts

@@ -51,6 +51,7 @@ export {
   closeSurface,
   renameSurface,
   renameAgent,
+  getRenameCapability,
   renameCurrentTab,
   renameWorkspace,
   pollForExit,
@@ -62,6 +63,11 @@ export type {
   CreateSurfaceSplitOptions,
   SendLongCommandOptions,
   ReadScreenOptions,
+  RenameOperation,
+  RenameTarget,
+  RenameBackend,
+  RenameCapability,
+  RenameResult,
 } from "./surface.ts";
 
 // ── Cmux 公开解析函数 ──
@@ -89,3 +95,19 @@ export {
   renameHerdrTab,
   renameHerdrWorkspace,
 } from "./backends/herdr.ts";
+
+// ── 精确目标和跨进程改名归属 ──
+export {
+  TERMINAL_RENAME_CONTEXT_ENV,
+  createSurfaceRenameContext,
+  readSurfaceRenameContext,
+  resolveTerminalRenameTargets,
+  renameTerminalTarget,
+} from "./rename.ts";
+export type {
+  SurfaceRenameContext,
+  TerminalRenameTarget,
+  TerminalRenameOutcome,
+  ResolveRenameOptions,
+  RenameCommandRunner,
+} from "./rename.ts";

package/src/rename.ts

@@ -0,0 +1,212 @@
+import { execFileSync } from "node:child_process";
+import { getMuxBackend, type MuxBackend } from "./detection.ts";
+import { getRenameCapability, type RenameOperation, type RenameTarget } from "./surface.ts";
+import { getCreatedHerdrTabId } from "./backends/herdr.ts";
+import { AGENT_OTTY_PANE_ID, getTabIdForPane } from "./backends/otty.ts";
+import { renameOrcaTerminal } from "./backends/orca.ts";
+import { i18n } from "./i18n.ts";
+
+export const TERMINAL_RENAME_CONTEXT_ENV = "PI_TERMINAL_RENAME_CONTEXT";
+const CONTEXT_VERSION = 1;
+const COMMAND_TIMEOUT_MS = 5_000;
+const RENAME_COMMANDS = {
+  cmuxTab: ["rename-tab", "--surface"],
+  cmuxWorkspace: ["workspace-action", "--workspace"],
+  cmuxWorkspaceAction: ["--action", "rename", "--title"],
+  muxy: ["rename-pane", "--pane"],
+  tmuxTab: ["rename-window", "-t"],
+  tmuxWorkspace: ["rename-session", "-t"],
+  tmuxLookup: ["display-message", "-p", "-t"],
+  tmuxWindowId: "#{window_id}",
+  tmuxSessionId: "#{session_id}",
+  zellij: ["action", "rename-pane"],
+  paneId: "--pane-id",
+  weztermTab: ["cli", "set-tab-title", "--pane-id"],
+  weztermWorkspace: ["cli", "set-window-title", "--pane-id"],
+  herdr: "rename",
+  otty: ["tab", "rename", "--tab"],
+} as const;
+const BACKENDS = ["cmux", "muxy", "tmux", "zellij", "wezterm", "herdr", "otty", "orca"] as const;
+
+export interface TerminalRenameTarget {
+  backend: MuxBackend;
+  operation: RenameOperation;
+  target: RenameTarget;
+  id: string;
+  scope: "surface" | "shared";
+}
+
+/** 启动方授予的单个 surface 改名范围；不是操作系统安全边界。 */
+export interface SurfaceRenameContext {
+  version: 1;
+  backend: MuxBackend | null;
+  surface: string;
+  ownedTarget: { target: "pane" | "tab" | "terminal"; id: string } | null;
+}
+
+export type TerminalRenameOutcome =
+  | { status: "ready" | "renamed"; reference: TerminalRenameTarget }
+  | { status: "skipped"; operation: RenameOperation; reason: "unsupported" | "disabled" | "shared" | "unverified" | "missing-id"; setting?: string }
+  | { status: "failed"; operation: RenameOperation; error: string };
+
+/** 只把可确认独占的 surface 授给子进程，绝不把 pane 扩大为共享窗口。 */
+export function createSurfaceRenameContext(surface: string, backend = getMuxBackend()): SurfaceRenameContext {
+  let ownedTarget: SurfaceRenameContext["ownedTarget"] = null;
+  if (surface.startsWith("headless:")) backend = null;
+  if (surface) {
+    if (backend === "cmux") ownedTarget = { target: "tab", id: surface };
+    if (backend === "muxy" || backend === "zellij") ownedTarget = { target: "pane", id: surface };
+    if (backend === "herdr") {
+      const tabId = getCreatedHerdrTabId(surface);
+      ownedTarget = tabId ? { target: "tab", id: tabId } : { target: "pane", id: surface };
+    }
+  }
+  return { version: CONTEXT_VERSION, backend, surface, ownedTarget };
+}
+
+/** 校验跨进程协议；损坏或未知版本不退回主会话权限。 */
+export function readSurfaceRenameContext(env: NodeJS.ProcessEnv = process.env): SurfaceRenameContext | undefined {
+  const raw = env[TERMINAL_RENAME_CONTEXT_ENV];
+  if (raw === undefined) {
+    // 旧启动方没有归属信息时，只读其身份标志以收紧范围，不能猜测独占 tab。
+    if (env.PI_SUBAGENT_ID || env.PI_SUBAGENT_SURFACE) {
+      return { version: CONTEXT_VERSION, backend: null, surface: "", ownedTarget: null };
+    }
+    return undefined;
+  }
+  let value: unknown;
+  try { value = JSON.parse(raw); } catch { throw new Error(i18n.t("rename.invalidContext")); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(i18n.t("rename.invalidContext"));
+  const context = value as Record<string, unknown>;
+  const validBackend = context.backend === null || BACKENDS.some((backend) => backend === context.backend);
+  if (context.version !== CONTEXT_VERSION || !validBackend || typeof context.surface !== "string" ||
+      Object.keys(context).some((key) => !["version", "backend", "surface", "ownedTarget"].includes(key))) {
+    throw new Error(i18n.t("rename.invalidContext"));
+  }
+  if (context.ownedTarget !== null) {
+    if (!context.ownedTarget || typeof context.ownedTarget !== "object" || Array.isArray(context.ownedTarget)) {
+      throw new Error(i18n.t("rename.invalidContext"));
+    }
+    const owned = context.ownedTarget as Record<string, unknown>;
+    const targetByBackend: Partial<Record<MuxBackend, readonly string[]>> = {
+      cmux: ["tab"], muxy: ["pane"], zellij: ["pane"], herdr: ["pane", "tab"],
+    };
+    if (!context.surface || typeof owned.id !== "string" || !owned.id.trim() ||
+        Object.keys(owned).some((key) => !["target", "id"].includes(key)) ||
+        !targetByBackend[context.backend as MuxBackend]?.includes(owned.target as string) ||
+        (!(context.backend === "herdr" && owned.target === "tab") && owned.id !== context.surface)) {
+      throw new Error(i18n.t("rename.invalidContext"));
+    }
+  }
+  return context as unknown as SurfaceRenameContext;
+}
+
+export interface ResolveRenameOptions {
+  tab: boolean;
+  workspace: boolean;
+  backend?: MuxBackend | null;
+  env?: NodeJS.ProcessEnv;
+}
+
+/** 返回当前进程的明确目标 ID，不以当前焦点或第一个 tab 代替未知身份。 */
+function currentTargetId(reference: { backend: MuxBackend; operation: RenameOperation; env: NodeJS.ProcessEnv }, query: RenameIdQuery): string | undefined {
+  const { backend, operation, env } = reference;
+  const surfaceKeys: Record<MuxBackend, string> = {
+    cmux: "CMUX_SURFACE_ID", muxy: "MUXY_PANE_ID", tmux: "TMUX_PANE", zellij: "ZELLIJ_PANE_ID",
+    wezterm: "WEZTERM_PANE", herdr: "HERDR_TAB_ID", otty: "OTTY_PANE_ID", orca: "ORCA_TERMINAL_HANDLE",
+  };
+  if (backend === "tmux") {
+    const pane = env.TMUX_PANE;
+    return pane ? query("tmux", [...RENAME_COMMANDS.tmuxLookup, pane,
+      operation === "tab" ? RENAME_COMMANDS.tmuxWindowId : RENAME_COMMANDS.tmuxSessionId]).trim() : undefined;
+  }
+  if (backend === "otty") {
+    const pane = env.OTTY_PANE_ID ?? AGENT_OTTY_PANE_ID;
+    return pane ? getTabIdForPane(pane) ?? undefined : undefined;
+  }
+  if (operation === "workspace" && backend === "cmux") return env.CMUX_WORKSPACE_ID;
+  if (operation === "workspace" && backend === "herdr") return env.HERDR_WORKSPACE_ID;
+  return env[surfaceKeys[backend]];
+}
+
+export type RenameIdQuery = (command: string, args: string[]) => string;
+
+/** 查询父 window/session 的明确身份，限制外部命令等待时间。 */
+function queryRenameId(command: string, args: string[]): string {
+  return execFileSync(command, args, { encoding: "utf8", timeout: COMMAND_TIMEOUT_MS });
+}
+
+/** 解析一次批量改名的目标；各目标的失败、关闭或跳过分别保留。 */
+export function resolveTerminalRenameTargets(options: ResolveRenameOptions, query: RenameIdQuery = queryRenameId): TerminalRenameOutcome[] {
+  const env = options.env ?? process.env;
+  const context = readSurfaceRenameContext(env);
+  const backend = options.backend === undefined ? getMuxBackend() : options.backend;
+  const outcomes: TerminalRenameOutcome[] = [];
+  for (const operation of ["workspace", "tab"] as const) {
+    if (!options[operation]) continue;
+    if (context) {
+      if (operation === "workspace") {
+        outcomes.push({ status: "skipped", operation, reason: "shared" });
+      } else if (!context.ownedTarget || !backend || context.backend !== backend) {
+        outcomes.push({ status: "skipped", operation, reason: "unverified" });
+      } else {
+        outcomes.push({ status: "ready", reference: { backend, operation, ...context.ownedTarget, scope: "surface" } });
+      }
+      continue;
+    }
+    const capability = getRenameCapability(operation, backend, env);
+    if (capability.status !== "supported") {
+      outcomes.push({ status: "skipped", operation, reason: capability.status,
+        ...(capability.status === "disabled" ? { setting: capability.setting } : {}) });
+      continue;
+    }
+    try {
+      const id = currentTargetId({ backend: capability.backend, operation, env }, query);
+      outcomes.push(id?.trim() ? { status: "ready", reference: {
+        backend: capability.backend, operation, target: capability.backend === "orca" ? "tab" : capability.target, id,
+        scope: operation === "workspace" || ["tmux", "wezterm", "herdr", "otty", "orca"].includes(capability.backend) ? "shared" : "surface",
+      } } : { status: "skipped", operation, reason: "missing-id" });
+    } catch (error) {
+      outcomes.push({ status: "failed", operation, error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return outcomes;
+}
+
+export type RenameCommandRunner = (command: string, args: string[]) => void;
+
+/** 改名命令设置超时，异常留给调用方转成逐目标结果。 */
+function runRenameCommand(command: string, args: string[]): void {
+  execFileSync(command, args, { encoding: "utf8", timeout: COMMAND_TIMEOUT_MS });
+}
+
+/** 用解析时捕获的身份执行改名，不再查询当前焦点。 */
+export function renameTerminalTarget(
+  reference: TerminalRenameTarget,
+  title: string,
+  dependencies: { run: RenameCommandRunner; renameOrca: typeof renameOrcaTerminal } = { run: runRenameCommand, renameOrca: renameOrcaTerminal },
+): TerminalRenameOutcome {
+  const { backend, operation, target, id } = reference;
+  const { run, renameOrca } = dependencies;
+  try {
+    if (!id.trim()) throw new Error(i18n.t("rename.missingId"));
+    switch (backend) {
+      case "cmux":
+        run("cmux", operation === "tab" ? [...RENAME_COMMANDS.cmuxTab, id, title]
+          : [...RENAME_COMMANDS.cmuxWorkspace, id, ...RENAME_COMMANDS.cmuxWorkspaceAction, title]);
+        break;
+      case "muxy": run("muxy", [...RENAME_COMMANDS.muxy, id, title]); break;
+      case "tmux": run("tmux", [...(operation === "tab" ? RENAME_COMMANDS.tmuxTab : RENAME_COMMANDS.tmuxWorkspace), id, title]); break;
+      case "zellij": run("zellij", [...RENAME_COMMANDS.zellij, title, RENAME_COMMANDS.paneId, id]); break;
+      case "wezterm": run("wezterm", [...(operation === "tab" ? RENAME_COMMANDS.weztermTab : RENAME_COMMANDS.weztermWorkspace), id, title]); break;
+      case "herdr": run("herdr", [target, RENAME_COMMANDS.herdr, id, title]); break;
+      case "otty": run("otty", [...RENAME_COMMANDS.otty, id, title]); break;
+      case "orca":
+        if (!renameOrca(id, title)) throw new Error(i18n.t("error.renameIncomplete", { backend }));
+        break;
+    }
+    return { status: "renamed", reference };
+  } catch (error) {
+    return { status: "failed", operation, error: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/surface.ts

@@ -55,6 +55,10 @@ import { renameOrcaTerminal } from "./backends/orca.ts";
 const execFileAsync = promisify(execFile);
 const ORCA_BACKEND: MuxBackend = "orca";
 const HERDR_BACKEND: MuxBackend = "herdr";
+const TMUX_WINDOW_RENAME_SETTING = "PI_SUBAGENT_RENAME_TMUX_WINDOW";
+const TMUX_SESSION_RENAME_SETTING = "PI_SUBAGENT_RENAME_TMUX_SESSION";
+const HERDR_WORKSPACE_RENAME_SETTING = "PI_SUBAGENT_RENAME_HERDR_WORKSPACE";
+const ENABLED_SETTING_VALUE = "1";
 
 // ── 全键注册表 ──
 
@@ -406,139 +410,163 @@ export function renameAgent(surface: string, name: string): void {
   }
 }
 
-/**
- * 重命名当前 tab / window。
- */
-export function renameCurrentTab(title: string): void {
-  if (isHeadlessMode()) return;
-
-  const backend = requireMuxBackend();
-
-  if (backend === "cmux") {
-    const surfaceId = process.env.CMUX_SURFACE_ID;
-    if (!surfaceId) throw new Error("CMUX_SURFACE_ID not set");
-    execSync(`cmux rename-tab --surface ${shellEscape(surfaceId)} ${shellEscape(title)}`, {
-      encoding: "utf8",
-    });
-    return;
-  }
-
-  if (backend === "muxy") {
-    const paneId = AGENT_MUXY_PANE_ID;
-    if (!paneId) throw new Error("MUXY_PANE_ID not set");
-    execFileSync("muxy", ["rename-pane", "--pane", paneId, title], { encoding: "utf8" });
-    return;
-  }
-
-  if (backend === "tmux") {
-    if (process.env.PI_SUBAGENT_RENAME_TMUX_WINDOW !== "1") {
-      return;
+export type RenameOperation = "tab" | "workspace";
+export type RenameTarget = "tab" | "window" | "pane" | "workspace" | "session" | "terminal";
+export type RenameBackend = MuxBackend | "headless";
+
+export type RenameCapability =
+  | { status: "supported"; backend: MuxBackend; operation: RenameOperation; target: RenameTarget }
+  | { status: "unsupported"; backend: RenameBackend; operation: RenameOperation }
+  | { status: "disabled"; backend: MuxBackend; operation: RenameOperation; setting: string };
+
+export type RenameResult =
+  | { status: "renamed"; backend: MuxBackend; operation: RenameOperation; target: RenameTarget }
+  | { status: "unsupported"; backend: RenameBackend; operation: RenameOperation }
+  | { status: "disabled"; backend: MuxBackend; operation: RenameOperation; setting: string }
+  | { status: "failed"; backend: MuxBackend; operation: RenameOperation; target: RenameTarget; error: string };
+
+/** 返回指定后端的真实重命名语义，不执行终端命令。 */
+export function getRenameCapability(
+  operation: RenameOperation,
+  backend: MuxBackend | null = getMuxBackend(),
+  env: NodeJS.ProcessEnv = process.env,
+): RenameCapability {
+  if (!backend) return { status: "unsupported", backend: "headless", operation };
+
+  if (operation === "tab") {
+    if (backend === "tmux" && env[TMUX_WINDOW_RENAME_SETTING] !== ENABLED_SETTING_VALUE) {
+      return { status: "disabled", backend, operation, setting: TMUX_WINDOW_RENAME_SETTING };
     }
-    const paneId = process.env.TMUX_PANE;
-    if (!paneId) throw new Error("TMUX_PANE not set");
-    const windowId = execFileSync("tmux", ["display-message", "-p", "-t", paneId, "#{window_id}"], {
-      encoding: "utf8",
-    }).trim();
-    execFileSync("tmux", ["rename-window", "-t", windowId, title], { encoding: "utf8" });
-    return;
+    const target: Record<MuxBackend, RenameTarget> = {
+      muxy: "pane",
+      cmux: "tab",
+      tmux: "window",
+      zellij: "pane",
+      wezterm: "tab",
+      herdr: "tab",
+      otty: "tab",
+      orca: "terminal",
+    };
+    return { status: "supported", backend, operation, target: target[backend] };
   }
 
-  if (backend === "wezterm") {
-    const paneId = process.env.WEZTERM_PANE;
-    const args = ["cli", "set-tab-title"];
-    if (paneId) args.push("--pane-id", paneId);
-    args.push(title);
-    execFileSync("wezterm", args, { encoding: "utf8" });
-    return;
-  }
-
-  if (backend === "herdr") {
-    renameHerdrTab(AGENT_HERDR_PANE_ID ?? "", title);
-    return;
-  }
-
-  if (backend === "otty") {
-    renameOttyTab(AGENT_OTTY_PANE_ID ?? "", title);
-    return;
+  if (backend === "tmux" && env[TMUX_SESSION_RENAME_SETTING] !== ENABLED_SETTING_VALUE) {
+    return { status: "disabled", backend, operation, setting: TMUX_SESSION_RENAME_SETTING };
   }
-
-  if (backend === "orca") {
-    if (!AGENT_ORCA_TERMINAL_HANDLE) throw new Error("ORCA_TERMINAL_HANDLE not set");
-    renameOrcaTerminal(AGENT_ORCA_TERMINAL_HANDLE, title);
-    return;
-  }
-
-  // zellij: rename the agent's own pane
-  const paneId = process.env.ZELLIJ_PANE_ID;
-  if (paneId) {
-    execFileSync("zellij", ["action", "rename-pane", title, "--pane-id", paneId], { encoding: "utf8" });
-  } else {
-    execFileSync("zellij", ["action", "rename-pane", title], { encoding: "utf8" });
+  if (backend === "herdr" && env[HERDR_WORKSPACE_RENAME_SETTING] !== ENABLED_SETTING_VALUE) {
+    return { status: "disabled", backend, operation, setting: HERDR_WORKSPACE_RENAME_SETTING };
   }
+  if (backend === "cmux") return { status: "supported", backend, operation, target: "workspace" };
+  if (backend === "tmux") return { status: "supported", backend, operation, target: "session" };
+  if (backend === "wezterm") return { status: "supported", backend, operation, target: "window" };
+  if (backend === "herdr") return { status: "supported", backend, operation, target: "workspace" };
+  return { status: "unsupported", backend, operation };
 }
 
-/**
- * 重命名当前 workspace / session。
- */
-export function renameWorkspace(title: string): void {
-  if (isHeadlessMode()) return;
-
-  const backend = requireMuxBackend();
-
-  if (backend === "cmux") {
-    execSync(`cmux workspace-action --action rename --title ${shellEscape(title)}`, {
-      encoding: "utf8",
-    });
-    return;
-  }
-
-  if (backend === "muxy") {
-    return;
-  }
+/** 将终端命令异常封装为可判别的失败结果。 */
+function failedRenameResult(
+  capability: Extract<RenameCapability, { status: "supported" }>,
+  error: unknown,
+): RenameResult {
+  return {
+    status: "failed",
+    backend: capability.backend,
+    operation: capability.operation,
+    target: capability.target,
+    error: error instanceof Error ? error.message : String(error),
+  };
+}
 
-  if (backend === "tmux") {
-    if (process.env.PI_SUBAGENT_RENAME_TMUX_SESSION !== "1") {
-      return;
+/** 重命名当前 tab/window/pane，并返回实际目标与执行结果。 */
+export function renameCurrentTab(title: string): RenameResult {
+  const capability = getRenameCapability("tab");
+  if (capability.status !== "supported") return capability;
+
+  try {
+    const backend = capability.backend;
+    if (backend === "cmux") {
+      const surfaceId = process.env.CMUX_SURFACE_ID;
+      if (!surfaceId) throw new Error("CMUX_SURFACE_ID not set");
+      execSync(`cmux rename-tab --surface ${shellEscape(surfaceId)} ${shellEscape(title)}`, {
+        encoding: "utf8",
+      });
+    } else if (backend === "muxy") {
+      const paneId = AGENT_MUXY_PANE_ID;
+      if (!paneId) throw new Error("MUXY_PANE_ID not set");
+      execFileSync("muxy", ["rename-pane", "--pane", paneId, title], { encoding: "utf8" });
+    } else if (backend === "tmux") {
+      const paneId = process.env.TMUX_PANE;
+      if (!paneId) throw new Error("TMUX_PANE not set");
+      const windowId = execFileSync("tmux", ["display-message", "-p", "-t", paneId, "#{window_id}"], {
+        encoding: "utf8",
+      }).trim();
+      execFileSync("tmux", ["rename-window", "-t", windowId, title], { encoding: "utf8" });
+    } else if (backend === "wezterm") {
+      const paneId = process.env.WEZTERM_PANE;
+      const args = ["cli", "set-tab-title"];
+      if (paneId) args.push("--pane-id", paneId);
+      args.push(title);
+      execFileSync("wezterm", args, { encoding: "utf8" });
+    } else if (backend === "herdr") {
+      if (!renameHerdrTab(AGENT_HERDR_PANE_ID ?? "", title)) {
+        throw new Error(i18n.t("error.renameIncomplete", { backend: "Herdr" }));
+      }
+    } else if (backend === "otty") {
+      if (!renameOttyTab(AGENT_OTTY_PANE_ID ?? "", title)) {
+        throw new Error(i18n.t("error.renameIncomplete", { backend: "Otty" }));
+      }
+    } else if (backend === "orca") {
+      if (!AGENT_ORCA_TERMINAL_HANDLE) throw new Error("ORCA_TERMINAL_HANDLE not set");
+      if (!renameOrcaTerminal(AGENT_ORCA_TERMINAL_HANDLE, title)) {
+        throw new Error(i18n.t("error.renameIncomplete", { backend: "Orca" }));
+      }
+    } else {
+      const paneId = process.env.ZELLIJ_PANE_ID;
+      const args = ["action", "rename-pane", title];
+      if (paneId) args.push("--pane-id", paneId);
+      execFileSync("zellij", args, { encoding: "utf8" });
     }
-    const paneId = process.env.TMUX_PANE;
-    if (!paneId) throw new Error("TMUX_PANE not set");
-    const sessionId = execFileSync(
-      "tmux",
-      ["display-message", "-p", "-t", paneId, "#{session_id}"],
-      { encoding: "utf8" },
-    ).trim();
-    execFileSync("tmux", ["rename-session", "-t", sessionId, title], { encoding: "utf8" });
-    return;
+    return { status: "renamed", backend, operation: capability.operation, target: capability.target };
+  } catch (error) {
+    return failedRenameResult(capability, error);
   }
+}
 
-  if (backend === "wezterm") {
-    const paneId = process.env.WEZTERM_PANE;
-    const args = ["cli", "set-window-title"];
-    if (paneId) args.push("--pane-id", paneId);
-    args.push(title);
-    try {
+/** 重命名当前 workspace/session/window，并明确报告不支持或未启用。 */
+export function renameWorkspace(title: string): RenameResult {
+  const capability = getRenameCapability("workspace");
+  if (capability.status !== "supported") return capability;
+
+  try {
+    const backend = capability.backend;
+    if (backend === "cmux") {
+      execSync(`cmux workspace-action --action rename --title ${shellEscape(title)}`, {
+        encoding: "utf8",
+      });
+    } else if (backend === "tmux") {
+      const paneId = process.env.TMUX_PANE;
+      if (!paneId) throw new Error("TMUX_PANE not set");
+      const sessionId = execFileSync(
+        "tmux",
+        ["display-message", "-p", "-t", paneId, "#{session_id}"],
+        { encoding: "utf8" },
+      ).trim();
+      execFileSync("tmux", ["rename-session", "-t", sessionId, title], { encoding: "utf8" });
+    } else if (backend === "wezterm") {
+      const paneId = process.env.WEZTERM_PANE;
+      const args = ["cli", "set-window-title"];
+      if (paneId) args.push("--pane-id", paneId);
+      args.push(title);
       execFileSync("wezterm", args, { encoding: "utf8" });
-    } catch {
-      // Optional.
+    } else if (backend === "herdr") {
+      if (!renameHerdrWorkspace(title)) {
+        throw new Error(i18n.t("error.renameIncomplete", { backend: "Herdr" }));
+      }
     }
-    return;
-  }
-
-  if (backend === "herdr") {
-    renameHerdrWorkspace(title);
-    return;
+    return { status: "renamed", backend, operation: capability.operation, target: capability.target };
+  } catch (error) {
+    return failedRenameResult(capability, error);
   }
-
-  if (backend === "otty") {
-    return;
-  }
-
-  if (backend === "orca") {
-    // orca: 无独立 workspace 概念（worktree 由 Orca 管理），跳过
-    return;
-  }
-
-  // zellij: skip session rename
 }
 
 export { renameHerdrTab, renameHerdrWorkspace };