clawt 3.8.10 → 3.9.0

package/README.md

@@ -374,6 +374,10 @@ Hooks run asynchronously in the background (fire-and-forget), not blocking the m
 
 > **Priority:** `--yes` > `CI` > `CLAWT_NON_INTERACTIVE` > default interactive mode
 
+**Internally injected environment variables:**
+
+All non-interactive Claude Code sessions launched via `claude -p` (task-executor and conflict-resolver) automatically inject the environment variable `CLAUDE_CODE_ENTRYPOINT="cli"`, which enables these sessions to be resumed via `--continue`. This does not apply to interactive Claude Code sessions (e.g., `clawt resume`).
+
 ## Logs
 
 Logs are saved in `~/.clawt/logs/`, rotated by date, retained for 30 days.

package/README.zh-CN.md

@@ -374,6 +374,10 @@ hook 以 fire-and-forget 模式后台异步并行执行，不阻塞主流程。
 
 > **优先级：** `--yes` > `CI` > `CLAWT_NON_INTERACTIVE` > 默认交互模式
 
+**内部注入的环境变量：**
+
+所有通过 `claude -p` 启动的非交互式 Claude Code 子进程（task-executor 和 conflict-resolver）会自动注入环境变量 `CLAUDE_CODE_ENTRYPOINT="cli"`，使这些会话支持通过 `--continue` 恢复。不适用于交互式启动 Claude Code 的场景（如 `clawt resume`）。
+
 ## 日志
 
 日志保存在 `~/.clawt/logs/`，按日期滚动，保留 30 天。

package/dist/index.js

@@ -703,7 +703,7 @@ var EXIT_CODES = {
 };
 
 // src/constants/terminal.ts
-var VALID_TERMINAL_APPS = ["auto", "iterm2", "terminal"];
+var VALID_TERMINAL_APPS = ["auto", "iterm2", "terminal", "cmux"];
 var ITERM2_APP_PATH = "/Applications/iTerm.app";
 
 // src/constants/config.ts
@@ -732,7 +732,7 @@ var CONFIG_DEFINITIONS = {
   },
   terminalApp: {
     defaultValue: "auto",
-    description: "\u6279\u91CF resume \u4F7F\u7528\u7684\u7EC8\u7AEF\u5E94\u7528\uFF1Aauto\uFF08\u81EA\u52A8\u68C0\u6D4B\uFF09\u3001iterm2\u3001terminal\uFF08macOS\uFF09",
+    description: "\u6279\u91CF resume \u4F7F\u7528\u7684\u7EC8\u7AEF\u5E94\u7528\uFF1Aauto\uFF08\u81EA\u52A8\u68C0\u6D4B\uFF09\u3001iterm2\u3001terminal\u3001cmux\uFF08macOS\uFF09",
     allowedValues: VALID_TERMINAL_APPS
   },
   resumeInPlace: {
@@ -2015,14 +2015,20 @@ import { existsSync as existsSync6 } from "fs";
 function isITerm2Installed() {
   return existsSync6(ITERM2_APP_PATH);
 }
+function isCmuxEnvironment() {
+  return !!process.env.CMUX_WORKSPACE_ID;
+}
 function detectTerminalApp() {
   const configured = getConfigValue("terminalApp");
-  if (configured === "iterm2" || configured === "terminal") {
+  if (configured === "iterm2" || configured === "terminal" || configured === "cmux") {
     return configured;
   }
   if (!VALID_TERMINAL_APPS.includes(configured)) {
     logger.warn(`terminalApp \u914D\u7F6E\u503C "${configured}" \u65E0\u6548\uFF0C\u6709\u6548\u503C: ${VALID_TERMINAL_APPS.join(", ")}\uFF0C\u5C06\u4F7F\u7528\u81EA\u52A8\u68C0\u6D4B`);
   }
+  if (isCmuxEnvironment()) {
+    return "cmux";
+  }
   if (isITerm2Installed()) {
     return "iterm2";
   }
@@ -2060,14 +2066,52 @@ tell application "iTerm"
 end tell
   `.trim();
 }
-function openCommandInNewTerminalTab(command, tabTitle) {
-  if (process.platform !== "darwin") {
-    throw new ClawtError("\u6279\u91CF resume \u76EE\u524D\u4EC5\u652F\u6301 macOS \u5E73\u53F0\uFF08\u901A\u8FC7 AppleScript \u6253\u5F00\u7EC8\u7AEF Tab\uFF09");
+function openCommandInCmuxSurface(command, title) {
+  if (!isCmuxEnvironment()) {
+    throw new ClawtError(
+      "\u5F53\u524D\u4E0D\u5728 cmux \u73AF\u5883\u4E2D\uFF0C\u65E0\u6CD5\u521B\u5EFA surface\n\u8BF7\u786E\u4FDD\u5728 cmux \u7EC8\u7AEF\u4E2D\u6267\u884C clawt resume \u547D\u4EE4\uFF0C\u6216\u4FEE\u6539 terminalApp \u914D\u7F6E"
+    );
   }
-  const terminalApp = detectTerminalApp();
-  const script = terminalApp === "iterm2" ? buildITermAppleScript(command, tabTitle) : buildTerminalAppleScript(command, tabTitle);
-  logger.debug(`\u6253\u5F00\u7EC8\u7AEF Tab [${terminalApp}]: ${tabTitle}`);
+  logger.debug(`\u5728 cmux \u4E2D\u521B\u5EFA\u65B0 surface: ${title}`);
   logger.debug(`\u6267\u884C\u547D\u4EE4: ${command}`);
+  try {
+    const newSurfaceResult = execFileSync3("cmux", [
+      "new-split",
+      "right"
+      // 在右侧创建新 surface
+    ], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5e3
+      // 5秒超时
+    });
+    logger.debug(`new-split \u8F93\u51FA: ${newSurfaceResult}`);
+    const match = newSurfaceResult.match(/(?:OK\s+)?(surface:\d+)/i);
+    if (!match) {
+      throw new Error(`\u65E0\u6CD5\u89E3\u6790 cmux new-split \u8F93\u51FA: ${newSurfaceResult}`);
+    }
+    const surfaceRef = match[1];
+    logger.debug(`\u5DF2\u521B\u5EFA surface: ${surfaceRef}`);
+    execFileSync3("cmux", [
+      "send",
+      "--surface",
+      surfaceRef,
+      `${command}\\n`
+      // 追加换行符以自动执行命令
+    ], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5e3
+    });
+    logger.debug(`\u5DF2\u5411 ${surfaceRef} \u53D1\u9001\u547D\u4EE4`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ClawtError(`\u5728 cmux \u4E2D\u521B\u5EFA surface \u5931\u8D25: ${message}`);
+  }
+}
+function executeAppleScript(script, terminalApp) {
+  logger.debug(`\u6253\u5F00\u7EC8\u7AEF Tab [${terminalApp}]`);
+  logger.debug(`\u6267\u884C AppleScript`);
   try {
     execFileSync3("osascript", ["-e", script], {
       encoding: "utf-8",
@@ -2079,6 +2123,27 @@ function openCommandInNewTerminalTab(command, tabTitle) {
     throw new ClawtError(`\u6253\u5F00\u7EC8\u7AEF Tab \u5931\u8D25: ${message}${accessibilityHint}`);
   }
 }
+function openCommandInNewTerminalTab(command, tabTitle) {
+  if (process.platform !== "darwin") {
+    throw new ClawtError("\u6279\u91CF resume \u76EE\u524D\u4EC5\u652F\u6301 macOS \u5E73\u53F0");
+  }
+  const terminalApp = detectTerminalApp();
+  switch (terminalApp) {
+    case "cmux":
+      openCommandInCmuxSurface(command, tabTitle);
+      break;
+    case "iterm2":
+      const itermScript = buildITermAppleScript(command, tabTitle);
+      executeAppleScript(itermScript, "iterm2");
+      break;
+    case "terminal":
+      const terminalScript = buildTerminalAppleScript(command, tabTitle);
+      executeAppleScript(terminalScript, "terminal");
+      break;
+    default:
+      throw new ClawtError(`\u4E0D\u652F\u6301\u7684\u7EC8\u7AEF\u7C7B\u578B: ${terminalApp}`);
+  }
+}
 
 // src/utils/claude.ts
 function encodeClaudeProjectPath(absolutePath) {

package/dist/postinstall.js

@@ -641,7 +641,7 @@ var MESSAGES = {
 };
 
 // src/constants/terminal.ts
-var VALID_TERMINAL_APPS = ["auto", "iterm2", "terminal"];
+var VALID_TERMINAL_APPS = ["auto", "iterm2", "terminal", "cmux"];
 
 // src/constants/config.ts
 var CONFIG_DEFINITIONS = {
@@ -667,7 +667,7 @@ var CONFIG_DEFINITIONS = {
   },
   terminalApp: {
     defaultValue: "auto",
-    description: "\u6279\u91CF resume \u4F7F\u7528\u7684\u7EC8\u7AEF\u5E94\u7528\uFF1Aauto\uFF08\u81EA\u52A8\u68C0\u6D4B\uFF09\u3001iterm2\u3001terminal\uFF08macOS\uFF09",
+    description: "\u6279\u91CF resume \u4F7F\u7528\u7684\u7EC8\u7AEF\u5E94\u7528\uFF1Aauto\uFF08\u81EA\u52A8\u68C0\u6D4B\uFF09\u3001iterm2\u3001terminal\u3001cmux\uFF08macOS\uFF09",
     allowedValues: VALID_TERMINAL_APPS
   },
   resumeInPlace: {

package/docs/merge.md

@@ -104,7 +104,7 @@ clawt merge [-m <commitMessage>]
    | `auto` | — | 直接调用 AI 解决，不询问 |
    | `manual` | — | 输出冲突提示信息，用户手动解决 |
 
-   AI 解决冲突时，调用 Claude Code CLI 在主 worktree 中分析并解决冲突文件，超时时间由配置项 `conflictResolveTimeoutMs` 控制（默认 15 分钟）。AI 解决成功后自动执行 `git add . && git merge --continue` 完成合并。
+   AI 解决冲突时，调用 Claude Code CLI 在主 worktree 中分析并解决冲突文件，超时时间由配置项 `conflictResolveTimeoutMs` 控制（默认 15 分钟）。冲突解决子进程通过 `getEnvWithoutNestedSessionFlag()` 启动，会自动注入环境变量 `CLAUDE_CODE_ENTRYPOINT="cli"` 使会话支持 `--continue` 恢复。AI 解决成功后自动执行 `git add . && git merge --continue` 完成合并。
 10. **推送（受 `autoPullPush` 配置控制）**
    - `autoPullPush` 为 `false` → 输出提示 `已跳过自动 pull/push，请手动执行 git pull && git push`
    - `autoPullPush` 为 `true` → 执行 `git pull` + `git push`：

package/docs/resume.md

@@ -88,13 +88,19 @@ clawt resume -f tasks.md -c 2
 
 | 配置值     | 行为                                                         |
 | ---------- | ------------------------------------------------------------ |
-| `auto`     | 自动检测：优先检测 iTerm2 是否已安装（`/Applications/iTerm.app`），已安装则使用 iTerm2，否则降级到 Terminal.app |
-| `iterm2`   | 强制使用 iTerm2                                               |
-| `terminal` | 强制使用 Terminal.app                                         |
+| `auto`     | 自动检测：优先检测 cmux 环境（通过 `CMUX_PANEL_ID` 环境变量），在 cmux 环境时在当前 pane 创建新 surface；否则检测 iTerm2 是否已安装，已安装则使用 iTerm2，否则降级到 Terminal.app |
+| `cmux`     | 在当前 cmux pane 中创建新 surface 执行命令                    |
+| `iterm2`   | 强制使用 iTerm2 创建新 Tab                                    |
+| `terminal` | 强制使用 Terminal.app 创建新 Tab                              |
 
-**平台限制：** 批量恢复目前仅支持 macOS 平台（通过 AppleScript 打开终端 Tab）。非 macOS 平台会抛出错误。
+**平台限制：** 批量恢复目前仅支持 macOS 平台。非 macOS 平台会抛出错误。
 
-**权限要求：** Terminal.app 通过 System Events 模拟键盘操作（`Cmd+T`）新建 Tab，需要在「系统设置 → 隐私与安全性 → 辅助功能」中授权终端应用。iTerm2 使用原生 AppleScript 接口，无需辅助功能权限。
+**cmux 集成说明：**
+- cmux 终端通过 `cmux new-surface --type terminal --pane <pane-id>` 创建新 surface
+- 创建后通过 `cmux send --surface <surface-id> <command>` 发送启动命令
+- 环境变量 `CMUX_PANEL_ID` 用于识别当前 pane，`CMUX_SURFACE_ID` 作为回退
+
+**权限要求：** Terminal.app 通过 System Events 模拟键盘操作（`Cmd+T`）新建 Tab，需要在「系统设置 → 隐私与安全性 → 辅助功能」中授权终端应用。iTerm2 使用原生 AppleScript 接口，无需辅助功能权限。cmux 通过 CLI 命令操作，无需特殊权限。
 
 启动命令通过配置项 `claudeCodeCommand`（默认值 `claude`）指定，与 `clawt run` 不传 `--tasks` 时的交互式界面行为一致。
 

package/docs/run.md

@@ -89,6 +89,7 @@ clawt run -b <branchName>
    claude -p "<tasks[i]>" --output-format stream-json --verbose --permission-mode bypassPermissions --append-system-prompt "<系统提示>"
    ```
    其中 `--append-system-prompt` 使用统一的 `APPEND_SYSTEM_PROMPT` 常量（定义在 `src/constants/config.ts`）。
+   子进程通过 `spawnProcess()`（`src/utils/shell.ts`）启动，会自动注入环境变量 `CLAUDE_CODE_ENTRYPOINT="cli"`（通过 `getEnvWithoutNestedSessionFlag()` 函数），使会话支持通过 `--continue` 恢复。
    使用 `stream-json` 格式可实时获取 Claude Code 的流式事件（工具调用、文本输出、最终结果），用于在进度面板中显示每个任务的实时活动描述和结果预览。流式事件解析由 `src/utils/stream-parser.ts` 负责。
 6. 进入**事件监听通知**阶段（见 [5.3](#53-任务完成通知机制)）
 7. **中断处理（Ctrl+C / SIGINT）**

package/docs/spec.md

@@ -316,6 +316,12 @@ async function interactiveConfigEditor<T extends object>(
 
 > **非交互模式判断优先级：** CLI `--yes` 选项 > `CI` 环境变量 > `CLAWT_NON_INTERACTIVE` 环境变量 > 默认交互模式。实现见 `src/utils/interactive.ts`。
 
+**Clawt 内部注入的环境变量：**
+
+| 环境变量 | 值 | 说明 |
+| -------- | --- | ---- |
+| `CLAUDE_CODE_ENTRYPOINT` | `cli` | 所有通过 `claude -p` 启动的非交互式 Claude Code 子进程（task-executor 和 conflict-resolver）会自动注入此环境变量，使这些会话支持通过 `--continue` 恢复。常量定义在 `src/constants/config.ts` 的 `CLAUDE_CODE_ENTRYPOINT_VALUE`，注入逻辑在 `src/utils/shell.ts` 的 `getEnvWithoutNestedSessionFlag()` 函数中实现。不适用于交互式启动 Claude Code 的场景（如 `clawt resume`）。 |
+
 所有命令执行前，都必须先执行**主 worktree 校验**（见 [2.1](#21-主-worktree-的定义与定位规则)）。
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "3.8.10",
+  "version": "3.9.0",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/constants/config.ts

@@ -5,7 +5,10 @@ import { VALID_TERMINAL_APPS } from './terminal.js';
 export const APPEND_SYSTEM_PROMPT =
   'Currently, you are in the git worktree directory.';
 
-/** 通过 clawt 启动的 Claude Code 非交互式会话（claude -p）的 entrypoint 标识 */
+/**
+ * 通过 clawt 启动的 Claude Code 非交互式会话（claude -p）的 entrypoint 标识
+ * 设置为 'cli' 使 claude -p 启动的会话可以通过 --continue 恢复
+ */
 export const CLAUDE_CODE_ENTRYPOINT_VALUE = 'cli';
 
 /**
@@ -35,7 +38,7 @@ export const CONFIG_DEFINITIONS: ConfigDefinitions = {
   },
   terminalApp: {
     defaultValue: 'auto',
-    description: '批量 resume 使用的终端应用：auto（自动检测）、iterm2、terminal（macOS）',
+    description: '批量 resume 使用的终端应用：auto（自动检测）、iterm2、terminal、cmux（macOS）',
     allowedValues: VALID_TERMINAL_APPS,
   },
   resumeInPlace: {

package/src/constants/terminal.ts

@@ -13,7 +13,7 @@ export const DISABLE_BRACKETED_PASTE = '\x1b[?2004l';
 export const PASTE_THRESHOLD_MS = 10;
 
 /** 配置项 terminalApp 允许的有效值 */
-export const VALID_TERMINAL_APPS: readonly string[] = ['auto', 'iterm2', 'terminal'];
+export const VALID_TERMINAL_APPS: readonly string[] = ['auto', 'iterm2', 'terminal', 'cmux'];
 
 /** iTerm2 应用路径，用于 auto 模式检测是否已安装 */
 export const ITERM2_APP_PATH = '/Applications/iTerm.app';

package/src/types/config.ts

@@ -10,7 +10,7 @@ export interface ClawtConfig {
   confirmDestructiveOps: boolean;
   /** run 命令默认最大并发数，0 表示不限制 */
   maxConcurrency: number;
-  /** 批量 resume 使用的终端应用：'auto'（自动检测）、'iterm2'、'terminal'（macOS） */
+  /** 批量 resume 使用的终端应用：'auto'（自动检测）、'iterm2'、'terminal'、'cmux'（macOS） */
   terminalApp: string;
   /** resume 单选时是否在当前终端就地打开，false 则通过 terminalApp 在新 Tab 中打开 */
   resumeInPlace: boolean;

package/src/utils/shell.ts

@@ -6,7 +6,9 @@ import { throwIfGitIndexLockError } from './git-lock.js';
 
 /**
  * 获取移除了 CLAUDECODE 嵌套会话标记的环境变量副本，并注入 CLAUDE_CODE_ENTRYPOINT 标识
- * 仅用于 claude -p 等非交互式子进程，避免被 Claude Code 误判为嵌套会话而拒绝启动
+ * 仅用于 claude -p 等非交互式子进程：
+ * - 移除 CLAUDECODE：避免被 Claude Code 误判为嵌套会话而拒绝启动
+ * - 注入 CLAUDE_CODE_ENTRYPOINT="cli"：使 claude -p 会话支持 --continue 恢复
  * 不适用于交互式启动 Claude Code（如 clawt resume），交互式场景应保留原始环境变量
  * @returns {NodeJS.ProcessEnv} 移除 CLAUDECODE 并注入 CLAUDE_CODE_ENTRYPOINT 后的环境变量
  */

package/src/utils/terminal.ts

@@ -6,7 +6,7 @@ import { VALID_TERMINAL_APPS, ITERM2_APP_PATH } from '../constants/index.js';
 import { getConfigValue } from './config.js';
 
 /** 终端应用类型 */
-type TerminalApp = 'iterm2' | 'terminal';
+type TerminalApp = 'iterm2' | 'terminal' | 'cmux';
 
 /**
  * 检测系统是否安装了 iTerm2
@@ -17,17 +17,28 @@ function isITerm2Installed(): boolean {
   return existsSync(ITERM2_APP_PATH);
 }
 
+/**
+ * 检测当前是否在 cmux 环境中运行
+ * 通过检查环境变量 CMUX_WORKSPACE_ID 是否存在来判断
+ * @returns {boolean} 是否在 cmux 环境中
+ */
+export function isCmuxEnvironment(): boolean {
+  return !!process.env.CMUX_WORKSPACE_ID;
+}
+
 /**
  * 检测当前使用的终端应用
- * 优先读取配置项 terminalApp；值为 'auto' 时优先检测 iTerm2 是否已安装，
- * 已安装则使用 iTerm2，否则降级到 Terminal.app
- * @returns {TerminalApp} 终端类型：'iterm2' 或 'terminal'
+ * 优先读取配置项 terminalApp；值为 'auto' 时按以下顺序检测：
+ * 1. cmux 环境（通过 CMUX_WORKSPACE_ID 环境变量）
+ * 2. iTerm2 是否已安装
+ * 3. 降级到 Terminal.app
+ * @returns {TerminalApp} 终端类型：'iterm2'、'terminal' 或 'cmux'
  */
 export function detectTerminalApp(): TerminalApp {
   const configured = getConfigValue('terminalApp');
 
   // 配置了明确的终端类型，直接使用
-  if (configured === 'iterm2' || configured === 'terminal') {
+  if (configured === 'iterm2' || configured === 'terminal' || configured === 'cmux') {
     return configured;
   }
 
@@ -36,10 +47,15 @@ export function detectTerminalApp(): TerminalApp {
     logger.warn(`terminalApp 配置值 "${configured}" 无效，有效值: ${VALID_TERMINAL_APPS.join(', ')}，将使用自动检测`);
   }
 
-  // auto 模式：优先检测 iTerm2 是否已安装
+  // auto 模式：优先检测 cmux 环境
+  if (isCmuxEnvironment()) {
+    return 'cmux';
+  }
+
   if (isITerm2Installed()) {
     return 'iterm2';
   }
+
   return 'terminal';
 }
 
@@ -99,25 +115,78 @@ end tell
 }
 
 /**
- * 在新终端 Tab 中执行命令
- * 自动检测终端类型（iTerm2 / Terminal.app），通过 AppleScript 打开新 Tab
+ * 在当前 cmux workspace 中分割创建新 surface 并执行命令
  * @param {string} command - 要执行的 shell 命令
- * @param {string} tabTitle - Tab 标题
- * @throws {ClawtError} 非 macOS 平台或 AppleScript 执行失败时抛出
+ * @param {string} title - surface 标题（用于日志）
+ * @throws {ClawtError} 不在 cmux 环境中或 CLI 执行失败时抛出
  */
-export function openCommandInNewTerminalTab(command: string, tabTitle: string): void {
-  if (process.platform !== 'darwin') {
-    throw new ClawtError('批量 resume 目前仅支持 macOS 平台（通过 AppleScript 打开终端 Tab）');
+function openCommandInCmuxSurface(command: string, title: string): void {
+  // 环境检查：只需要检查 WORKSPACE_ID
+  if (!isCmuxEnvironment()) {
+    throw new ClawtError(
+      '当前不在 cmux 环境中，无法创建 surface\n' +
+      '请确保在 cmux 终端中执行 clawt resume 命令，或修改 terminalApp 配置'
+    );
   }
 
-  const terminalApp = detectTerminalApp();
-  const script = terminalApp === 'iterm2'
-    ? buildITermAppleScript(command, tabTitle)
-    : buildTerminalAppleScript(command, tabTitle);
-
-  logger.debug(`打开终端 Tab [${terminalApp}]: ${tabTitle}`);
+  logger.debug(`在 cmux 中创建新 surface: ${title}`);
   logger.debug(`执行命令: ${command}`);
 
+  try {
+    // 步骤 1：分割创建新 surface（利用默认值机制）
+    const newSurfaceResult = execFileSync('cmux', [
+      'new-split',
+      'right',  // 在右侧创建新 surface
+    ], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,  // 5秒超时
+    });
+
+    logger.debug(`new-split 输出: ${newSurfaceResult}`);
+
+    // 步骤 2：解析输出获取新 surface ID
+    // 输出格式可能是：
+    // - "surface:24"（简短引用）
+    // - "OK surface:24 pane:14 workspace:5"（带 OK 前缀）
+    // 需要灵活匹配
+    const match = newSurfaceResult.match(/(?:OK\s+)?(surface:\d+)/i);
+    if (!match) {
+      throw new Error(`无法解析 cmux new-split 输出: ${newSurfaceResult}`);
+    }
+    const surfaceRef = match[1];
+
+    logger.debug(`已创建 surface: ${surfaceRef}`);
+
+    // 步骤 3：向新 surface 发送命令（追加 \n 自动执行）
+    execFileSync('cmux', [
+      'send',
+      '--surface', surfaceRef,
+      `${command}\\n`,  // 追加换行符以自动执行命令
+    ], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    });
+
+    logger.debug(`已向 ${surfaceRef} 发送命令`);
+
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ClawtError(`在 cmux 中创建 surface 失败: ${message}`);
+  }
+}
+
+/**
+ * 执行 AppleScript 脚本
+ * @param {string} script - AppleScript 内容
+ * @param {TerminalApp} terminalApp - 终端类型（'iterm2' 或 'terminal'）
+ * @throws {ClawtError} AppleScript 执行失败时抛出
+ */
+function executeAppleScript(script: string, terminalApp: 'iterm2' | 'terminal'): void {
+  logger.debug(`打开终端 Tab [${terminalApp}]`);
+  logger.debug(`执行 AppleScript`);
+
   try {
     execFileSync('osascript', ['-e', script], {
       encoding: 'utf-8',
@@ -125,10 +194,42 @@ export function openCommandInNewTerminalTab(command: string, tabTitle: string):
     });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    // Terminal.app 通过 System Events 模拟键盘操作需要辅助功能权限
     const accessibilityHint = terminalApp === 'terminal'
       ? '\n提示：Terminal.app 需要辅助功能权限，请在「系统设置 → 隐私与安全性 → 辅助功能」中授权终端应用'
       : '';
     throw new ClawtError(`打开终端 Tab 失败: ${message}${accessibilityHint}`);
   }
 }
+
+/**
+ * 在新终端 Tab 或 cmux Surface 中执行命令
+ * 自动检测终端类型（cmux / iTerm2 / Terminal.app）
+ * - cmux：在当前 pane 创建新 surface
+ * - iTerm2 / Terminal.app：通过 AppleScript 打开新 Tab
+ * @param {string} command - 要执行的 shell 命令
+ * @param {string} tabTitle - Tab 或 surface 标题
+ * @throws {ClawtError} 非 macOS 平台或终端打开失败时抛出
+ */
+export function openCommandInNewTerminalTab(command: string, tabTitle: string): void {
+  if (process.platform !== 'darwin') {
+    throw new ClawtError('批量 resume 目前仅支持 macOS 平台');
+  }
+
+  const terminalApp = detectTerminalApp();
+
+  switch (terminalApp) {
+    case 'cmux':
+      openCommandInCmuxSurface(command, tabTitle);
+      break;
+    case 'iterm2':
+      const itermScript = buildITermAppleScript(command, tabTitle);
+      executeAppleScript(itermScript, 'iterm2');
+      break;
+    case 'terminal':
+      const terminalScript = buildTerminalAppleScript(command, tabTitle);
+      executeAppleScript(terminalScript, 'terminal');
+      break;
+    default:
+      throw new ClawtError(`不支持的终端类型: ${terminalApp}`);
+  }
+}

package/tests/unit/utils/terminal-cmux.test.ts

@@ -0,0 +1,288 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// mock node:child_process
+vi.mock('node:child_process', () => ({
+  execFileSync: vi.fn(),
+}));
+
+// mock node:fs
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+}));
+
+// mock logger
+vi.mock('../../../src/logger/index.js', () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+// mock config
+vi.mock('../../../src/utils/config.js', () => ({
+  getConfigValue: vi.fn(),
+}));
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import {
+  isCmuxEnvironment,
+  detectTerminalApp,
+  openCommandInNewTerminalTab,
+} from '../../../src/utils/terminal.js';
+import { getConfigValue } from '../../../src/utils/config.js';
+
+const mockedExecFileSync = vi.mocked(execFileSync);
+const mockedExistsSync = vi.mocked(existsSync);
+const mockedGetConfigValue = vi.mocked(getConfigValue);
+
+describe('cmux 环境检测', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    // 每个测试前重置环境变量
+    vi.resetModules();
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    // 测试后恢复原始环境变量
+    process.env = originalEnv;
+  });
+
+  describe('isCmuxEnvironment', () => {
+    it('CMUX_WORKSPACE_ID 存在时返回 true', () => {
+      process.env.CMUX_WORKSPACE_ID = '6E83B1B3-5617-43F0-82FB-75F55E9F3F28';
+      expect(isCmuxEnvironment()).toBe(true);
+    });
+
+    it('CMUX_WORKSPACE_ID 不存在时返回 false', () => {
+      delete process.env.CMUX_WORKSPACE_ID;
+      expect(isCmuxEnvironment()).toBe(false);
+    });
+  });
+});
+
+describe('终端检测优先级', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('明确配置 cmux 时返回 cmux', () => {
+    mockedGetConfigValue.mockReturnValue('cmux');
+    expect(detectTerminalApp()).toBe('cmux');
+  });
+
+  it('明确配置 iterm2 时返回 iterm2', () => {
+    mockedGetConfigValue.mockReturnValue('iterm2');
+    expect(detectTerminalApp()).toBe('iterm2');
+  });
+
+  it('明确配置 terminal 时返回 terminal', () => {
+    mockedGetConfigValue.mockReturnValue('terminal');
+    expect(detectTerminalApp()).toBe('terminal');
+  });
+
+  it('auto 模式下 cmux 环境优先级最高', () => {
+    mockedGetConfigValue.mockReturnValue('auto');
+    process.env.CMUX_WORKSPACE_ID = '6E83B1B3-5617-43F0-82FB-75F55E9F3F28'; // 在 cmux 环境中
+
+    expect(detectTerminalApp()).toBe('cmux');
+  });
+
+  it('auto 模式下非 cmux 环境降级到 iTerm2', () => {
+    mockedGetConfigValue.mockReturnValue('auto');
+    mockedExistsSync.mockReturnValue(true); // iTerm2 已安装
+    delete process.env.CMUX_WORKSPACE_ID; // 不在 cmux 环境中
+
+    expect(detectTerminalApp()).toBe('iterm2');
+  });
+
+  it('auto 模式下无 iTerm2 时降级到 terminal', () => {
+    mockedGetConfigValue.mockReturnValue('auto');
+    mockedExistsSync.mockReturnValue(false); // iTerm2 未安装
+    delete process.env.CMUX_WORKSPACE_ID; // 不在 cmux 环境中
+
+    expect(detectTerminalApp()).toBe('terminal');
+  });
+});
+
+describe('cmux surface 创建', () => {
+  const originalEnv = process.env;
+  const originalPlatform = process.platform;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    Object.defineProperty(process, 'platform', { value: originalPlatform });
+  });
+
+  it('成功创建 surface 并发送命令（简短格式输出）', () => {
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    process.env.CMUX_WORKSPACE_ID = '6E83B1B3-5617-43F0-82FB-75F55E9F3F28';
+
+    mockedGetConfigValue.mockReturnValue('cmux');
+    mockedExecFileSync
+      .mockReturnValueOnce('surface:24') // new-split 返回简短格式
+      .mockReturnValueOnce(''); // send 返回
+
+    expect(() => openCommandInNewTerminalTab('claude', 'test-title')).not.toThrow();
+
+    // 验证 new-split 调用
+    expect(mockedExecFileSync).toHaveBeenNthCalledWith(
+      1,
+      'cmux',
+      ['new-split', 'right'],
+      expect.objectContaining({ timeout: 5000 })
+    );
+
+    // 验证 send 调用（包含 \n 以自动执行）
+    expect(mockedExecFileSync).toHaveBeenNthCalledWith(
+      2,
+      'cmux',
+      ['send', '--surface', 'surface:24', 'claude\\n'],
+      expect.objectContaining({ timeout: 5000 })
+    );
+  });
+
+  it('成功创建 surface 并发送命令（带 OK 前缀输出）', () => {
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    process.env.CMUX_WORKSPACE_ID = '6E83B1B3-5617-43F0-82FB-75F55E9F3F28';
+
+    mockedGetConfigValue.mockReturnValue('cmux');
+    mockedExecFileSync
+      .mockReturnValueOnce('OK surface:24 pane:14 workspace:5') // new-split 返回带前缀格式
+      .mockReturnValueOnce(''); // send 返回
+
+    expect(() => openCommandInNewTerminalTab('claude', 'test-title')).not.toThrow();
+
+    // 验证解析正确（包含 \n 以自动执行）
+    expect(mockedExecFileSync).toHaveBeenNthCalledWith(
+      2,
+      'cmux',
+      ['send', '--surface', 'surface:24', 'claude\\n'],
+      expect.objectContaining({ timeout: 5000 })
+    );
+  });
+
+  it('不在 cmux 环境中时抛出友好错误', () => {
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    delete process.env.CMUX_WORKSPACE_ID;
+
+    mockedGetConfigValue.mockReturnValue('cmux');
+
+    expect(() => openCommandInNewTerminalTab('claude', 'test-title')).toThrow(
+      /当前不在 cmux 环境中/
+    );
+  });
+
+  it('new-split 输出格式无法解析时抛出错误', () => {
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    process.env.CMUX_WORKSPACE_ID = '6E83B1B3-5617-43F0-82FB-75F55E9F3F28';
+
+    mockedGetConfigValue.mockReturnValue('cmux');
+    mockedExecFileSync.mockReturnValueOnce('invalid output format');
+
+    expect(() => openCommandInNewTerminalTab('claude', 'test-title')).toThrow(
+      /无法解析 cmux new-split 输出/
+    );
+  });
+
+  it('cmux CLI 执行失败时捕获并抛出错误', () => {
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    process.env.CMUX_WORKSPACE_ID = '6E83B1B3-5617-43F0-82FB-75F55E9F3F28';
+
+    mockedGetConfigValue.mockReturnValue('cmux');
+    mockedExecFileSync.mockImplementation(() => {
+      const error = new Error('spawn cmux ENOENT');
+      throw error;
+    });
+
+    expect(() => openCommandInNewTerminalTab('claude', 'test-title')).toThrow(
+      /在 cmux 中创建 surface 失败/
+    );
+  });
+
+  it('非 macOS 平台抛出错误', () => {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+
+    expect(() => openCommandInNewTerminalTab('claude', 'test-title')).toThrow(
+      /仅支持 macOS 平台/
+    );
+  });
+});
+
+describe('向后兼容性', () => {
+  const originalEnv = process.env;
+  const originalPlatform = process.platform;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    Object.defineProperty(process, 'platform', { value: originalPlatform });
+  });
+
+  it('iTerm2 用户不受影响', () => {
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    delete process.env.CMUX_WORKSPACE_ID;
+
+    mockedGetConfigValue.mockReturnValue('iterm2');
+    mockedExecFileSync.mockReturnValue('');
+
+    expect(() => openCommandInNewTerminalTab('claude', 'test-title')).not.toThrow();
+
+    // 验证使用 osascript 执行 AppleScript
+    expect(mockedExecFileSync).toHaveBeenCalledWith(
+      'osascript',
+      expect.arrayContaining([expect.stringContaining('-e')]),
+      expect.any(Object)
+    );
+  });
+
+  it('Terminal.app 用户不受影响', () => {
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    delete process.env.CMUX_WORKSPACE_ID;
+
+    mockedGetConfigValue.mockReturnValue('terminal');
+    mockedExecFileSync.mockReturnValue('');
+
+    expect(() => openCommandInNewTerminalTab('claude', 'test-title')).not.toThrow();
+
+    // 验证使用 osascript 执行 AppleScript
+    expect(mockedExecFileSync).toHaveBeenCalledWith(
+      'osascript',
+      expect.arrayContaining([expect.stringContaining('-e')]),
+      expect.any(Object)
+    );
+  });
+
+  it('auto 模式下原有行为不变（无 cmux 环境时）', () => {
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    delete process.env.CMUX_WORKSPACE_ID;
+
+    mockedGetConfigValue.mockReturnValue('auto');
+    mockedExistsSync.mockReturnValue(true); // iTerm2 已安装
+    mockedExecFileSync.mockReturnValue('');
+
+    expect(() => openCommandInNewTerminalTab('claude', 'test-title')).not.toThrow();
+
+    // 验证使用 iTerm2
+    expect(mockedExecFileSync).toHaveBeenCalledWith(
+      'osascript',
+      expect.arrayContaining([expect.stringContaining('-e')]),
+      expect.any(Object)
+    );
+  });
+});