clawt 2.16.3 → 2.16.5

package/dist/postinstall.js

@@ -68,9 +68,9 @@ var RUN_MESSAGES = {
   /** 非 TTY 环境降级输出：任务启动 */
   PROGRESS_TASK_STARTED: (index, total, branch, path) => `[${index}/${total}] ${branch} \u542F\u52A8  ${path}`,
   /** 非 TTY 环境降级输出：任务完成 */
-  PROGRESS_TASK_DONE: (index, total, branch, duration, cost, path) => `[${index}/${total}] ${branch} \u2713 \u5B8C\u6210 ${duration} ${cost}  ${path}`,
+  PROGRESS_TASK_DONE: (index, total, branch, duration, cost, detail) => `[${index}/${total}] ${branch} \u2713 \u5B8C\u6210 ${duration} ${cost}  ${detail}`,
   /** 非 TTY 环境降级输出：任务失败 */
-  PROGRESS_TASK_FAILED: (index, total, branch, duration, path) => `[${index}/${total}] ${branch} \u2717 \u5931\u8D25 ${duration}  ${path}`,
+  PROGRESS_TASK_FAILED: (index, total, branch, duration, detail) => `[${index}/${total}] ${branch} \u2717 \u5931\u8D25 ${duration}  ${detail}`,
   /** 并发限制提示 */
   CONCURRENCY_INFO: (concurrency, total) => `\u5E76\u53D1\u9650\u5236: ${concurrency}\uFF0C\u5171 ${total} \u4E2A\u4EFB\u52A1`,
   /** 并发数无效提示 */
@@ -203,7 +203,16 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** 并行执行中单个命令失败 */
   VALIDATE_PARALLEL_CMD_FAILED: (command, exitCode) => `  \u2717 ${command}\uFF08\u9000\u51FA\u7801: ${exitCode}\uFF09`,
   /** 并行执行中单个命令启动失败 */
-  VALIDATE_PARALLEL_CMD_ERROR: (command, errorMessage) => `  \u2717 ${command}\uFF08\u9519\u8BEF: ${errorMessage}\uFF09`
+  VALIDATE_PARALLEL_CMD_ERROR: (command, errorMessage) => `  \u2717 ${command}\uFF08\u9519\u8BEF: ${errorMessage}\uFF09`,
+  /** patch apply 失败后询问用户是否执行 sync */
+  VALIDATE_CONFIRM_AUTO_SYNC: (branch) => `\u662F\u5426\u7ACB\u5373\u6267\u884C sync \u540C\u6B65\u4E3B\u5206\u652F\u5230 ${branch}\uFF1F`,
+  /** 自动 sync 开始提示 */
+  VALIDATE_AUTO_SYNC_START: (branch) => `\u6B63\u5728\u81EA\u52A8\u540C\u6B65\u4E3B\u5206\u652F\u5230 ${branch} ...`,
+  /** 自动 sync 存在冲突，无法重试 */
+  VALIDATE_AUTO_SYNC_CONFLICT: (worktreePath) => `\u540C\u6B65\u5B58\u5728\u51B2\u7A81\uFF0C\u8BF7\u8FDB\u5165\u76EE\u6807 worktree \u624B\u52A8\u89E3\u51B3\u51B2\u7A81\u540E\u91CD\u8BD5
+  cd ${worktreePath}`,
+  /** 用户拒绝自动 sync */
+  VALIDATE_AUTO_SYNC_DECLINED: (branch) => `\u8BF7\u624B\u52A8\u6267\u884C clawt sync -b ${branch} \u540C\u6B65\u4E3B\u5206\u652F\u540E\u91CD\u8BD5`
 };
 
 // src/constants/messages/sync.ts

package/docs/spec.md

@@ -46,6 +46,7 @@
 | CLI 框架 | Commander.js                  |
 | 日志库   | winston (按日期滚动文件)       |
 | 交互式   | enquirer (选项选择/确认对话)   |
+| 终端宽度 | string-width (ANSI 安全的字符宽度计算) |
 | 测试     | Vitest + @vitest/coverage-v8               |
 | 构建     | tsup / tsc                    |
 | 分发     | pnpm 全局安装 (`pnpm add -g clawt`) |
@@ -338,8 +339,9 @@ clawt run -b <branchName>
 4. 通过公共函数 `executeBatchTasks`（`src/utils/task-executor.ts`）启动批量任务执行，该函数负责进度面板渲染、SIGINT 中断处理、并发控制和汇总输出。对每个 worktree 并行启动 Claude Code CLI：
    ```bash
    cd ~/.clawt/worktrees/<project>/<branchName>-<i>
-   claude -p "<tasks[i]>" --output-format json --permission-mode bypassPermissions
+   claude -p "<tasks[i]>" --output-format stream-json --verbose --permission-mode bypassPermissions
    ```
+   使用 `stream-json` 格式可实时获取 Claude Code 的流式事件（工具调用、文本输出、最终结果），用于在进度面板中显示每个任务的实时活动描述和结果预览。流式事件解析由 `src/utils/stream-parser.ts` 负责。
 5. 进入**事件监听通知**阶段（见 [5.3](#53-任务完成通知机制)）
 6. **中断处理（Ctrl+C / SIGINT）**
    - 监听 `SIGINT` 信号，用户按下 Ctrl+C 时触发
@@ -405,7 +407,7 @@ clawt run -b <branchName>
 
 **机制说明：**
 
-Claude Code CLI 以 `--output-format json` 运行时，退出后会在 stdout 输出如下 JSON：
+Claude Code CLI 以 `--output-format stream-json --verbose` 运行时，stdout 会持续输出 JSON 行（每行一个事件），包括 `system`、`assistant`（含 `tool_use` 和 `text`）、`user`（含 `tool_result`）等类型。任务结束时输出 `type: "result"` 事件：
 
 ```json
 {
@@ -423,12 +425,22 @@ Claude Code CLI 以 `--output-format json` 运行时，退出后会在 stdout
 }
 ```
 
+**流式事件解析（`src/utils/stream-parser.ts`）：**
+
+由于 stdout 的 `data` 事件可能在行中间切割，使用 `createLineBuffer()` 行缓冲器拼接完整行后，通过 `parseStreamLine()` 解析为 `StreamEvent` 对象，再由 `parseStreamEvent()` 提取活动信息（`ParsedActivity`）：
+
+- **`tool_use` 类型**：提取工具名和文件路径/命令参数，格式如 `Read index.ts`、`Bash ls -la`
+- **`text` 类型**：提取文本片段，格式如 `思考中: 让我分析一下`
+- **`result` 类型**：构造 `ClaudeCodeResult` 对象，提取耗时、费用、结果文本等
+
+活动描述文本最大长度为 `ACTIVITY_TEXT_MAX_LENGTH`（30 字符），超出后截断并追加省略号。结果预览文本最大长度为 `RESULT_PREVIEW_MAX_LENGTH`（40 字符）。
+
 **事件监听与通知流程：**
 
 1. 为每个 Claude Code 子进程维护状态（运行中 / 已完成 / 已失败）
 2. 监听每个子进程的 `close` 事件（基于 Node.js `ChildProcess` 的事件驱动机制）
-3. 当某个子进程触发 `close` 事件时，解析其 stdout 输出的 JSON
-4. 在主 worktree 的 clawt 终端实时输出通知（进度面板每个任务行末尾显示 worktree 路径，终端可点击跳转）：
+3. 当某个子进程触发 `close` 事件时，解析流式输出中最后的 `result` 事件
+4. 在主 worktree 的 clawt 终端实时输出通知。TTY 环境下使用进度面板，进度面板每个任务行第二列显示 worktree 路径（终端可点击跳转），运行中显示实时活动描述，完成/失败后显示结果预览：
 
 ```
 ✓ [完成] worktree: ~/.clawt/worktrees/main-project/feature-scheme-1
@@ -452,6 +464,39 @@ Claude Code CLI 以 `--output-format json` 运行时，退出后会在 stdout
 ════════════════════════════════════════
 ```
 
+#### 进度面板渲染机制
+
+进度面板由 `ProgressRenderer`（`src/utils/progress.ts`）负责渲染，渲染函数拆分到 `src/utils/progress-render.ts`。
+
+**TTY 模式渲染策略（备选屏幕缓冲区）：**
+
+- **进入备选屏幕**：`start()` 时通过 `ALT_SCREEN_ENTER`（`\x1B[?1049h`）进入终端备选屏幕缓冲区，隔离进度面板与主屏幕内容
+- **禁用行换行**：通过 `LINE_WRAP_DISABLE`（`\x1B[?7l`）防止超长行自动折行，配合按终端宽度截断保证每行只占一行
+- **每帧渲染**：使用 `CLEAR_SCREEN` + `CURSOR_HOME` 清屏后完全重绘，无需计算 `CURSOR_UP` 回退量，不受终端 reflow 影响
+- **防闪烁**：每帧渲染使用 Synchronized Output（`SYNC_OUTPUT_START` / `SYNC_OUTPUT_END`），终端缓冲全部输出后一次性刷新
+- **行宽截断**：通过 `truncateToTerminalWidth()`（`src/utils/progress-render.ts`）将含 ANSI 转义码的字符串截断到终端可见列数，使用 `string-width` 库正确计算中文/emoji 宽度
+- **终端 resize 响应**：监听 `process.stdout` 的 `resize` 事件，窗口宽度变化时立即触发重绘
+- **退出时恢复**：`stop()` 时恢复行换行、显示光标、退出备选屏幕，然后在主屏幕上重新输出最终面板状态（备选屏幕内容不保留）
+- **异常退出兜底**：注册 `process.on('exit')` 处理器，确保即使异常退出也能恢复终端状态
+
+**任务行格式：**
+
+```
+[1/3] /path/to/worktree  ⠹ 运行中 1m23s  Read index.ts
+[2/3] /path/to/worktree  ✓ 完成   2m05s  $0.08  任务已成功完成
+[3/3] /path/to/worktree  ● 排队中
+```
+
+- 第二列为 worktree 路径（`path.padEnd(maxPathWidth)` 对齐）
+- 运行中状态：末尾显示实时活动描述文本（如工具名+文件名、思考中+文本片段）
+- 完成/失败状态：末尾显示结果预览文本（从 `ClaudeCodeResult.result` 提取，最大 40 字符）
+
+**非 TTY 降级模式：**
+
+- 启动时输出 `[1/3] branch 启动 path`
+- 完成时输出 `[1/3] branch ✓ 完成 duration cost detail`（`detail` 优先使用结果预览，无则回退到路径）
+- 失败时输出 `[1/3] branch ✗ 失败 duration detail`
+
 ---
 
 ### 5.4 在主 Worktree 验证其他分支
@@ -576,7 +621,26 @@ git restore --staged .
 ```
 
 > 此步骤结束后，目标 worktree 的代码保持原样，主 worktree 工作目录包含目标分支的全量变更。
-> 如果 patch apply 失败（目标分支与主分支差异过大），会提示用户先执行 `clawt sync -b <branchName>` 同步主分支后重试。
+> 如果 patch apply 失败（目标分支与主分支差异过大），`migrateChangesViaPatch` 返回 `{ success: false }`，进入自动 sync 交互流程（见下文 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)）。
+
+##### patch apply 失败后的自动 sync 流程
+
+当 patch apply 失败时，validate 不再直接退出，而是通过 `handlePatchApplyFailure()` 函数进入交互流程：
+
+1. **询问用户**：提示 `是否立即执行 sync 同步主分支到 <branchName>？`
+2. **用户拒绝** → 输出提示 `请手动执行 clawt sync -b <branchName> 同步主分支后重试`，退出
+3. **用户确认** → 调用 `executeSyncForBranch(targetWorktreePath, branchName)` 自动执行 sync
+   - **sync 成功** → validate 流程结束（用户需重新执行 validate）
+   - **sync 存在冲突** → 输出提示 `同步存在冲突，请进入目标 worktree 手动解决冲突后重试`，退出
+
+> `executeSyncForBranch` 为 sync 命令抽取的核心操作函数（见 [5.12](#512-将主分支代码同步到目标-worktree)），供 validate 等命令复用。
+
+**实现要点：**
+
+- `migrateChangesViaPatch()` 返回类型从 `void` 改为 `{ success: boolean }`，patch apply 失败时返回 `{ success: false }` 而非抛出异常
+- `handleFirstValidate()` 和 `handleIncrementalValidate()` 从同步函数改为 `async` 函数，以支持交互式确认
+- `handlePatchApplyFailure()` 为新增的异步函数（`src/commands/validate.ts`），负责 patch 失败后的交互逻辑
+- 消息常量：`MESSAGES.VALIDATE_CONFIRM_AUTO_SYNC`、`MESSAGES.VALIDATE_AUTO_SYNC_START`、`MESSAGES.VALIDATE_AUTO_SYNC_CONFLICT`、`MESSAGES.VALIDATE_AUTO_SYNC_DECLINED`（`src/constants/messages/validate.ts`）
 
 ##### 步骤 4：保存快照为 git tree 对象
 
@@ -715,7 +779,7 @@ clawt validate -b feature-scheme-1 -r "pnpm test & pnpm build"
 
 ##### 步骤 3：从目标分支获取最新全量变更
 
-通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 3）。
+通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 3）。如果 patch apply 失败，同样进入自动 sync 交互流程（见首次 validate 的 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)），validate 流程提前结束。
 
 ##### 步骤 4：保存最新快照为 git tree 对象
 
@@ -1356,16 +1420,36 @@ clawt sync
         - 唯一匹配 → 直接使用
         - 多个匹配 → 通过交互式列表让用户从匹配结果中选择
      3. **无匹配** → 报错退出，并列出所有可用分支名
-3. **获取主分支名**：通过 `git rev-parse --abbrev-ref HEAD` 获取主 worktree 当前分支名（不硬编码 main/master）
-4. **自动保存未提交变更**：检查目标 worktree 是否有未提交修改
+3. 调用 `executeSyncForBranch(targetWorktreePath, branch)` 执行核心同步逻辑
+
+#### `executeSyncForBranch` — sync 核心操作函数
+
+`executeSyncForBranch(targetWorktreePath: string, branch: string): SyncResult` 是从 `handleSync` 中抽取的核心同步逻辑，不包含 worktree 解析交互，供 validate 等命令复用。
+
+**接口定义：**
+
+```typescript
+/** sync 核心操作的执行结果 */
+export interface SyncResult {
+  /** 是否同步成功 */
+  success: boolean;
+  /** 是否存在合并冲突 */
+  hasConflict: boolean;
+}
+```
+
+**执行流程：**
+
+1. **获取主分支名**：通过 `git rev-parse --abbrev-ref HEAD` 获取主 worktree 当前分支名（不硬编码 main/master）
+2. **自动保存未提交变更**：检查目标 worktree 是否有未提交修改
    - 有修改 → 自动执行 `git add . && git commit -m "<AUTO_SAVE_COMMIT_MESSAGE>"` 保存变更（commit message 由常量 `AUTO_SAVE_COMMIT_MESSAGE` 定义，值为 `chore: auto-save before sync`，同时用于 merge 命令的 squash 检测）
    - 无修改 → 跳过
-5. **在目标 worktree 中合并主分支**：
+3. **在目标 worktree 中合并主分支**：
    ```bash
    cd ~/.clawt/worktrees/<project>/<branchName>
    git merge <mainBranch>
    ```
-6. **冲突处理**：
+4. **冲突处理**：
    - **有冲突** → 输出警告，提示用户进入目标 worktree 手动解决：
      ```
      合并存在冲突，请进入目标 worktree 手动解决：
@@ -1373,9 +1457,10 @@ clawt sync
        解决冲突后执行 git add . && git merge --continue
        clawt validate -b <branch> 验证变更
      ```
+   - 返回 `{ success: false, hasConflict: true }`
    - **无冲突** → 继续
-7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 和 `.head` 文件），自动删除（代码基础已变化，旧快照无效）
-8. **输出成功提示**：
+5. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 和 `.head` 文件），自动删除（代码基础已变化，旧快照无效）
+6. **输出成功提示**并返回 `{ success: true, hasConflict: false }`：
    ```
    ✓ 已将 <mainBranch> 的最新代码同步到 <branchName>
    ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "2.16.3",
+  "version": "2.16.5",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",
@@ -19,6 +19,7 @@
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "enquirer": "^2.4.1",
+    "string-width": "^8.2.0",
     "winston": "^3.17.0",
     "winston-daily-rotate-file": "^5.0.0"
   },

package/src/commands/sync.ts

@@ -77,21 +77,22 @@ function mergeMainBranch(worktreePath: string, mainBranch: string): boolean {
   }
 }
 
+/** sync 核心操作的执行结果 */
+export interface SyncResult {
+  /** 是否同步成功 */
+  success: boolean;
+  /** 是否存在合并冲突 */
+  hasConflict: boolean;
+}
+
 /**
- * 执行 sync 命令的核心逻辑
- * 将主分支最新代码同步到目标 worktree
- * @param {SyncOptions} options - 命令选项
+ * 执行 sync 核心操作（检查未提交→自动保存→merge 主分支→清除快照）
+ * 不包含 worktree 解析交互，供 validate 等命令复用
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} branch - 分支名
+ * @returns {SyncResult} sync 执行结果
  */
-async function handleSync(options: SyncOptions): Promise<void> {
-  validateMainWorktree();
-
-  logger.info(`sync 命令执行，分支: ${options.branch ?? '(未指定)'}`);
-
-  // 解析目标 worktree（精确匹配 / 模糊匹配 / 交互选择）
-  const worktrees = getProjectWorktrees();
-  const worktree = await resolveTargetWorktree(worktrees, SYNC_RESOLVE_MESSAGES, options.branch);
-  const { path: targetWorktreePath, branch } = worktree;
-
+export function executeSyncForBranch(targetWorktreePath: string, branch: string): SyncResult {
   // 获取主分支名（不硬编码 main/master）
   const mainWorktreePath = getGitTopLevel();
   const mainBranch = getCurrentBranch(mainWorktreePath);
@@ -107,7 +108,7 @@ async function handleSync(options: SyncOptions): Promise<void> {
 
   if (hasConflict) {
     printWarning(MESSAGES.SYNC_CONFLICT(targetWorktreePath));
-    return;
+    return { success: false, hasConflict: true };
   }
 
   // 合并成功后清除该分支的 validate 快照（代码基础已变化，旧快照无效）
@@ -118,4 +119,23 @@ async function handleSync(options: SyncOptions): Promise<void> {
   }
 
   printSuccess(MESSAGES.SYNC_SUCCESS(branch, mainBranch));
+  return { success: true, hasConflict: false };
+}
+
+/**
+ * 执行 sync 命令的核心逻辑
+ * 将主分支最新代码同步到目标 worktree
+ * @param {SyncOptions} options - 命令选项
+ */
+async function handleSync(options: SyncOptions): Promise<void> {
+  validateMainWorktree();
+
+  logger.info(`sync 命令执行，分支: ${options.branch ?? '(未指定)'}`);
+
+  // 解析目标 worktree（精确匹配 / 模糊匹配 / 交互选择）
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, SYNC_RESOLVE_MESSAGES, options.branch);
+  const { path: targetWorktreePath, branch } = worktree;
+
+  executeSyncForBranch(targetWorktreePath, branch);
 }

package/src/commands/validate.ts

@@ -4,6 +4,7 @@ import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
 import type { ValidateOptions } from '../types/index.js';
+import { executeSyncForBranch } from './sync.js';
 import {
   validateMainWorktree,
   getProjectName,
@@ -33,6 +34,7 @@ import {
   writeSnapshot,
   removeSnapshot,
   confirmDestructiveAction,
+  confirmAction,
   printSuccess,
   printError,
   printWarning,
@@ -121,8 +123,9 @@ async function handleDirtyMainWorktree(mainWorktreePath: string): Promise<void>
  * @param {string} mainWorktreePath - 主 worktree 路径
  * @param {string} branchName - 分支名
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
+ * @returns {{ success: boolean }} patch 迁移结果
  */
-function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: string, branchName: string, hasUncommitted: boolean): void {
+function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: string, branchName: string, hasUncommitted: boolean): { success: boolean } {
   let didTempCommit = false;
 
   try {
@@ -143,9 +146,11 @@ function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: st
       } catch (error) {
         logger.warn(`patch apply 失败: ${error}`);
         printWarning(MESSAGES.VALIDATE_PATCH_APPLY_FAILED(branchName));
-        throw error;
+        return { success: false };
       }
     }
+
+    return { success: true };
   } finally {
     // 确保临时 commit 一定会被撤销，恢复目标 worktree 原状
     // 每个操作独立 try-catch，避免前一个失败导致后续操作不执行
@@ -164,6 +169,31 @@ function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: st
   }
 }
 
+/**
+ * patch apply 失败后的交互处理：询问用户是否自动执行 sync
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} branchName - 分支名
+ */
+async function handlePatchApplyFailure(targetWorktreePath: string, branchName: string): Promise<void> {
+  // 询问用户是否自动执行 sync
+  const confirmed = await confirmAction(MESSAGES.VALIDATE_CONFIRM_AUTO_SYNC(branchName));
+
+  if (!confirmed) {
+    // 用户拒绝自动 sync
+    printWarning(MESSAGES.VALIDATE_AUTO_SYNC_DECLINED(branchName));
+    return;
+  }
+
+  // 用户确认，执行 sync
+  printInfo(MESSAGES.VALIDATE_AUTO_SYNC_START(branchName));
+  const syncResult = executeSyncForBranch(targetWorktreePath, branchName);
+
+  if (syncResult.hasConflict) {
+    // sync 存在冲突，提示用户手动解决
+    printWarning(MESSAGES.VALIDATE_AUTO_SYNC_CONFLICT(targetWorktreePath));
+  }
+}
+
 /**
  * 保存当前主 worktree 工作目录变更为 git tree 对象快照
  * 操作序列：git add . → git write-tree → git restore --staged .
@@ -231,9 +261,15 @@ async function handleValidateClean(options: ValidateOptions): Promise<void> {
  * @param {string} branchName - 分支名
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
-function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): void {
+async function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): Promise<void> {
   // 通过 patch 迁移目标分支全量变更到主 worktree
-  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+  const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+
+  if (!result.success) {
+    // patch 失败，询问用户是否自动 sync
+    await handlePatchApplyFailure(targetWorktreePath, branchName);
+    return;
+  }
 
   // 保存快照为 git tree 对象
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
@@ -250,7 +286,7 @@ function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: strin
  * @param {string} branchName - 分支名
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
-function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): void {
+async function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): Promise<void> {
   // 步骤 1：读取旧快照（tree hash + 当时的 HEAD commit hash）
   const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash } = readSnapshot(projectName, branchName);
 
@@ -262,7 +298,13 @@ function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath:
   }
 
   // 步骤 3：通过 patch 从目标分支获取最新全量变更
-  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+  const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+
+  if (!result.success) {
+    // patch 失败，询问用户是否自动 sync
+    await handlePatchApplyFailure(targetWorktreePath, branchName);
+    return;
+  }
 
   // 步骤 4：保存最新快照为 git tree 对象（同时记录当前 HEAD）
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
@@ -441,14 +483,14 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
-    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
+    await handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   } else {
     // 首次模式：先确保主 worktree 干净
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
 
-    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
+    await handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   }
 
   // validate 成功后执行用户指定的命令

package/src/constants/index.ts

@@ -10,11 +10,21 @@ export { DEBUG_LOG_PREFIX, DEBUG_TIMESTAMP_FORMAT } from './logger.js';
 export {
   SPINNER_FRAMES,
   SPINNER_INTERVAL_MS,
-  CURSOR_UP,
-  CLEAR_LINE,
   CURSOR_HIDE,
   CURSOR_SHOW,
   TASK_STATUS_ICONS,
   TASK_STATUS_LABELS,
+  ACTIVITY_TEXT_MAX_LENGTH,
+  TEXT_ACTIVITY_PREFIX,
+  RESULT_PREVIEW_MAX_LENGTH,
+  DEFAULT_TERMINAL_COLUMNS,
+  LINE_WRAP_DISABLE,
+  LINE_WRAP_ENABLE,
+  SYNC_OUTPUT_START,
+  SYNC_OUTPUT_END,
+  ALT_SCREEN_ENTER,
+  ALT_SCREEN_LEAVE,
+  CLEAR_SCREEN,
+  CURSOR_HOME,
 } from './progress.js';
 export { SELECT_ALL_NAME, SELECT_ALL_LABEL } from './prompt.js';

package/src/constants/messages/run.ts

@@ -17,11 +17,11 @@ export const RUN_MESSAGES = {
   PROGRESS_TASK_STARTED: (index: number, total: number, branch: string, path: string) =>
     `[${index}/${total}] ${branch} 启动  ${path}`,
   /** 非 TTY 环境降级输出：任务完成 */
-  PROGRESS_TASK_DONE: (index: number, total: number, branch: string, duration: string, cost: string, path: string) =>
-    `[${index}/${total}] ${branch} ✓ 完成 ${duration} ${cost}  ${path}`,
+  PROGRESS_TASK_DONE: (index: number, total: number, branch: string, duration: string, cost: string, detail: string) =>
+    `[${index}/${total}] ${branch} ✓ 完成 ${duration} ${cost}  ${detail}`,
   /** 非 TTY 环境降级输出：任务失败 */
-  PROGRESS_TASK_FAILED: (index: number, total: number, branch: string, duration: string, path: string) =>
-    `[${index}/${total}] ${branch} ✗ 失败 ${duration}  ${path}`,
+  PROGRESS_TASK_FAILED: (index: number, total: number, branch: string, duration: string, detail: string) =>
+    `[${index}/${total}] ${branch} ✗ 失败 ${duration}  ${detail}`,
   /** 并发限制提示 */
   CONCURRENCY_INFO: (concurrency: number, total: number) =>
     `并发限制: ${concurrency}，共 ${total} 个任务`,

package/src/constants/messages/validate.ts

@@ -53,4 +53,16 @@ export const VALIDATE_MESSAGES = {
   /** 并行执行中单个命令启动失败 */
   VALIDATE_PARALLEL_CMD_ERROR: (command: string, errorMessage: string) =>
     `  ✗ ${command}（错误: ${errorMessage}）`,
+  /** patch apply 失败后询问用户是否执行 sync */
+  VALIDATE_CONFIRM_AUTO_SYNC: (branch: string) =>
+    `是否立即执行 sync 同步主分支到 ${branch}？`,
+  /** 自动 sync 开始提示 */
+  VALIDATE_AUTO_SYNC_START: (branch: string) =>
+    `正在自动同步主分支到 ${branch} ...`,
+  /** 自动 sync 存在冲突，无法重试 */
+  VALIDATE_AUTO_SYNC_CONFLICT: (worktreePath: string) =>
+    `同步存在冲突，请进入目标 worktree 手动解决冲突后重试\n  cd ${worktreePath}`,
+  /** 用户拒绝自动 sync */
+  VALIDATE_AUTO_SYNC_DECLINED: (branch: string) =>
+    `请手动执行 clawt sync -b ${branch} 同步主分支后重试`,
 } as const;

package/src/constants/progress.ts

@@ -4,12 +4,6 @@ export const SPINNER_FRAMES: readonly string[] = ['⠋', '⠙', '⠹', '⠸', '
 /** spinner 刷新间隔（毫秒） */
 export const SPINNER_INTERVAL_MS = 100;
 
-/** ANSI 转义：光标上移 n 行 */
-export const CURSOR_UP = (n: number): string => `\x1B[${n}A`;
-
-/** ANSI 转义：清除从光标到行尾 */
-export const CLEAR_LINE = '\x1B[0K';
-
 /** ANSI 转义：隐藏光标 */
 export const CURSOR_HIDE = '\x1B[?25l';
 
@@ -37,3 +31,39 @@ export const TASK_STATUS_LABELS = {
   /** 失败 */
   FAILED: '失败',
 } as const;
+
+/** 活动描述文本的最大字符数 */
+export const ACTIVITY_TEXT_MAX_LENGTH = 30;
+
+/** 文本类型活动的前缀 */
+export const TEXT_ACTIVITY_PREFIX = '思考中';
+
+/** 结果预览文本的最大字符数 */
+export const RESULT_PREVIEW_MAX_LENGTH = 40;
+
+/** 终端宽度的默认值（无法获取时的回退值） */
+export const DEFAULT_TERMINAL_COLUMNS = 80;
+
+/** ANSI 转义：禁用终端自动行换行（超出宽度的内容被截断而非折行） */
+export const LINE_WRAP_DISABLE = '\x1B[?7l';
+
+/** ANSI 转义：恢复终端自动行换行 */
+export const LINE_WRAP_ENABLE = '\x1B[?7h';
+
+/** ANSI 转义：开启同步输出模式（终端缓冲所有输出直到关闭，防止渲染闪烁） */
+export const SYNC_OUTPUT_START = '\x1B[?2026h';
+
+/** ANSI 转义：关闭同步输出模式（终端一次性刷新缓冲区内容） */
+export const SYNC_OUTPUT_END = '\x1B[?2026l';
+
+/** ANSI 转义：进入备选屏幕缓冲区（同时保存光标位置） */
+export const ALT_SCREEN_ENTER = '\x1B[?1049h';
+
+/** ANSI 转义：离开备选屏幕缓冲区（同时恢复光标位置） */
+export const ALT_SCREEN_LEAVE = '\x1B[?1049l';
+
+/** ANSI 转义：清除整个屏幕 */
+export const CLEAR_SCREEN = '\x1B[2J';
+
+/** ANSI 转义：光标移到屏幕左上角 (1,1) */
+export const CURSOR_HOME = '\x1B[H';

package/src/utils/index.ts

@@ -61,6 +61,8 @@ export type { WorktreeResolveMessages, WorktreeMultiResolveMessages } from './wo
 export { ProgressRenderer } from './progress.js';
 export { parseTaskFile, loadTaskFile, parseTasksFromOptions } from './task-file.js';
 export { executeBatchTasks } from './task-executor.js';
+export { createLineBuffer, parseStreamLine, parseStreamEvent, formatActivityText, truncateText } from './stream-parser.js';
+export type { ParsedActivity, StreamEvent, LineBuffer } from './stream-parser.js';
 export { detectTerminalApp, openCommandInNewTerminalTab } from './terminal.js';
 export { truncateTaskDesc, printDryRunPreview } from './dry-run.js';
 export { applyAliases } from './alias.js';