pi-terminal-mux 0.5.1 → 0.6.2

package/README.md

@@ -94,7 +94,7 @@ export PI_SUBAGENT_HERDR_MODE=tab
 | `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.
+Rename targets differ by backend: muxy/zellij tab rename targets a pane; tmux targets a window/session; WezTerm workspace rename targets the window; cmux and Herdr provide native workspace rename; Otty and Orca have no workspace rename. `resolveTerminalRenameTargets` is the explicit-ID path and ignores legacy opt-in variables; `getRenameCapability`, `renameCurrentTab` and `renameWorkspace` retain their legacy opt-in behavior. Headless reports `unsupported` instead of silently succeeding.
 
 ### Detection and utilities
 
@@ -124,9 +124,9 @@ These are opt-in capabilities — existing Bash callers and `pi-interactive-suba
 |----------|-------------|
 | `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_RENAME_TMUX_WINDOW` / `PI_SUBAGENT_RENAME_TMUX_SESSION` | Compatibility switches for legacy `getRenameCapability` / `renameCurrentTab` / `renameWorkspace` on tmux; ignored by explicit target resolution |
 | `PI_SUBAGENT_HERDR_MODE` | Herdr surface placement: `split` (default) or `tab` |
-| `PI_SUBAGENT_RENAME_HERDR_WORKSPACE` | Allow renameWorkspace on herdr |
+| `PI_SUBAGENT_RENAME_HERDR_WORKSPACE` | Compatibility switch for legacy `getRenameCapability` / `renameWorkspace` on herdr; ignored by explicit target resolution |
 | `PI_EXTENSIONS_LOCALE` | Hint language (`zh-CN` / `en-US` / `auto`), provided by pi-extensions-i18n |
 
 ## Design constraints
@@ -146,6 +146,6 @@ MIT
 
 `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.
+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. Explicit target resolution uses backend capability directly, independent of legacy rename opt-ins.
 
 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

@@ -93,7 +93,7 @@ export PI_SUBAGENT_HERDR_MODE=tab
 | `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`，不再静默成功。
+各后端的实际目标不同：muxy/zellij 的 tab 重命名作用于 pane；tmux 作用于 window/session；WezTerm 的 workspace 重命名作用于 window；cmux 和 Herdr 提供原生 workspace 重命名；Otty、Orca 没有 workspace 重命名。`resolveTerminalRenameTargets` 是明确 ID 路径，忽略旧环境开关；`getRenameCapability`、`renameCurrentTab`、`renameWorkspace` 保持旧开关行为。Headless 会明确返回 `unsupported`，不再静默成功。
 
 ### 探测与工具
 
@@ -123,9 +123,9 @@ export PI_SUBAGENT_HERDR_MODE=tab
 |------|------|
 | `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_RENAME_TMUX_WINDOW` / `PI_SUBAGENT_RENAME_TMUX_SESSION` | tmux 下旧 `getRenameCapability` / `renameCurrentTab` / `renameWorkspace` 的兼容开关；明确目标解析忽略 |
 | `PI_SUBAGENT_HERDR_MODE` | herdr surface 放置模式：`split`（默认）或 `tab` |
-| `PI_SUBAGENT_RENAME_HERDR_WORKSPACE` | herdr 下允许 renameWorkspace |
+| `PI_SUBAGENT_RENAME_HERDR_WORKSPACE` | herdr 下旧 `getRenameCapability` / `renameWorkspace` 的兼容开关；明确目标解析忽略 |
 | `PI_EXTENSIONS_LOCALE` | 提示文案语言（`zh-CN` / `en-US` / `auto`），由 pi-extensions-i18n 提供 |
 
 ## 设计约束
@@ -145,6 +145,6 @@ MIT
 
 `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。普通会话仍遵守各后端原有的改名开关。
+受限子进程不能改 workspace。cmux surface、muxy/zellij pane、Herdr pane 或明确新建的 Herdr tab 可以授予。tmux/WezTerm/Otty/Orca 的分屏不能证明独占 window/tab，改名会跳过，不扩大到共享父目标。普通会话必须能确定自身目标 ID；缺失时不退回当前焦点或第一个 tab。明确目标解析直接使用后端能力，独立于旧改名开关。
 
 协议 JSON 损坏或版本未知会报错，不能退回无限制范围。只有旧子代理身份标志、没有归属协议时，终端改名受限，直到启动方提供归属。此协议用于可信本地进程协作，不是安全沙箱。WezTerm/Otty 创建分屏时不会重命名共享 tab。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-terminal-mux",
-  "version": "0.5.1",
+  "version": "0.6.2",
   "description": "Terminal multiplexer abstraction for pi extensions — unified surface API across muxy, cmux, tmux, zellij, wezterm, herdr, otty and orca, with headless fallback",
   "type": "module",
   "main": "./index.ts",
@@ -54,7 +54,7 @@
     "coding-agent"
   ],
   "dependencies": {
-    "pi-extensions-i18n": "^0.4.0"
+    "pi-extensions-i18n": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "24.12.4",

package/src/rename.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { getMuxBackend, type MuxBackend } from "./detection.ts";
-import { getRenameCapability, type RenameOperation, type RenameTarget } from "./surface.ts";
+import { 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";
@@ -108,6 +108,25 @@ export interface ResolveRenameOptions {
   env?: NodeJS.ProcessEnv;
 }
 
+/** 新的明确目标路径只判断后端能力；旧公开 API 的环境开关不参与这里。 */
+function explicitRenameCapability(
+  operation: RenameOperation,
+  backend: MuxBackend | null,
+): { backend: MuxBackend; target: RenameTarget } | undefined {
+  if (!backend) return undefined;
+  if (operation === "tab") {
+    const target: Record<MuxBackend, RenameTarget> = {
+      muxy: "pane", cmux: "tab", tmux: "window", zellij: "pane", wezterm: "tab",
+      herdr: "tab", otty: "tab", orca: "terminal",
+    };
+    return { backend, target: target[backend] };
+  }
+  const target: Partial<Record<MuxBackend, RenameTarget>> = {
+    cmux: "workspace", tmux: "session", wezterm: "window", herdr: "workspace",
+  };
+  return target[backend] ? { backend, target: target[backend] } : undefined;
+}
+
 /** 返回当前进程的明确目标 ID，不以当前焦点或第一个 tab 代替未知身份。 */
 function currentTargetId(reference: { backend: MuxBackend; operation: RenameOperation; env: NodeJS.ProcessEnv }, query: RenameIdQuery): string | undefined {
   const { backend, operation, env } = reference;
@@ -154,16 +173,15 @@ export function resolveTerminalRenameTargets(options: ResolveRenameOptions, quer
       }
       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 } : {}) });
+    const capability = explicitRenameCapability(operation, backend);
+    if (!capability) {
+      outcomes.push({ status: "skipped", operation, reason: "unsupported" });
       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,
+        backend: capability.backend, operation, target: capability.target, id,
         scope: operation === "workspace" || ["tmux", "wezterm", "herdr", "otty", "orca"].includes(capability.backend) ? "shared" : "surface",
       } } : { status: "skipped", operation, reason: "missing-id" });
     } catch (error) {