clawt 2.16.4 → 2.16.5

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 验证其他分支

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "2.16.4",
+  "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/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/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';

package/src/utils/progress-render.ts

@@ -1,7 +1,63 @@
 import chalk from 'chalk';
+import stringWidth from 'string-width';
 import { TASK_STATUS_ICONS, TASK_STATUS_LABELS } from '../constants/index.js';
 import { formatDuration } from './formatter.js';
 
+/** ANSI 颜色/样式转义序列的匹配正则 */
+const ANSI_ESCAPE_RE = /\x1B\[[0-9;]*m/g;
+
+/** ANSI 样式重置序列，用于截断后关闭未闭合的颜色 */
+const ANSI_RESET = '\x1B[0m';
+
+/**
+ * 将含 ANSI 转义码的字符串截断到指定可见宽度
+ *
+ * 逐字符遍历原始字符串，跳过 ANSI 序列不计入可见宽度，
+ * 在可见宽度达到上限时截断并追加样式重置序列防止颜色泄漏。
+ * @param {string} text - 可能含 ANSI 颜色码的字符串
+ * @param {number} maxWidth - 终端可见列数上限
+ * @returns {string} 截断后的字符串（不超过 maxWidth 可见列）
+ */
+export function truncateToTerminalWidth(text: string, maxWidth: number): string {
+  // 快速路径：实际可见宽度未超限时直接返回
+  if (stringWidth(text) <= maxWidth) {
+    return text;
+  }
+
+  let visibleWidth = 0;
+  let result = '';
+  let i = 0;
+
+  while (i < text.length) {
+    // 检查当前位置是否是 ANSI 转义序列的起始
+    if (text[i] === '\x1B' && text[i + 1] === '[') {
+      // 匹配完整的 ANSI 序列（格式: ESC [ <数字;...> m）
+      const match = text.slice(i).match(/^\x1B\[[0-9;]*m/);
+      if (match) {
+        // ANSI 序列不占可见宽度，直接保留
+        result += match[0];
+        i += match[0].length;
+        continue;
+      }
+    }
+
+    // 计算当前字符的可见宽度（中文/emoji 为 2，ASCII 为 1）
+    const charWidth = stringWidth(text[i]);
+
+    // 加上当前字符后是否会超出上限
+    if (visibleWidth + charWidth > maxWidth) {
+      break;
+    }
+
+    result += text[i];
+    visibleWidth += charWidth;
+    i++;
+  }
+
+  // 追加样式重置，防止截断后颜色泄漏到下一行
+  return result + ANSI_RESET;
+}
+
 /** 单个任务的进度状态 */
 export interface TaskProgress {
   /** 任务序号（从 1 开始） */
@@ -22,47 +78,55 @@ export interface TaskProgress {
   durationMs: number | null;
   /** 费用（美元），完成后由 ClaudeCodeResult 填入 */
   costUsd: number | null;
+  /** 当前活动描述文本（仅 running 状态有效） */
+  activity: string | null;
+  /** 结果预览文本（完成/失败后显示） */
+  resultPreview: string | null;
 }
 
 /**
- * 计算分支名的最大显示宽度，用于对齐
+ * 计算路径的最大显示宽度，用于对齐
  * @param {TaskProgress[]} tasks - 任务列表
- * @returns {number} 最大分支名长度
+ * @returns {number} 最大路径长度
  */
-export function getMaxBranchWidth(tasks: TaskProgress[]): number {
-  return Math.max(...tasks.map((t) => t.branch.length));
+export function getMaxPathWidth(tasks: TaskProgress[]): number {
+  return Math.max(...tasks.map((t) => t.path.length));
 }
 
 /**
  * 渲染单个任务行（TTY 模式）
- * 格式: [1/3] feat-1  ⠹ 运行中 1m23s
- * 完成/失败后追加 worktree 路径，终端可点击跳转
+ * 格式: [1/3] /path/to/worktree  ⠹ 运行中 1m23s
+ * 完成/失败后末尾追加结果预览文本
  * @param {TaskProgress} task - 任务进度
  * @param {number} total - 总任务数
- * @param {number} maxBranchWidth - 分支名最大宽度（用于对齐）
+ * @param {number} maxPathWidth - 路径最大宽度（用于对齐）
  * @param {string} spinnerChar - 当前 spinner 帧字符
  * @returns {string} 渲染后的单行字符串（含 chalk 颜色）
  */
-export function renderTaskLine(task: TaskProgress, total: number, maxBranchWidth: number, spinnerChar: string): string {
+export function renderTaskLine(task: TaskProgress, total: number, maxPathWidth: number, spinnerChar: string): string {
   const indexStr = `[${task.index}/${total}]`;
-  const branchStr = task.branch.padEnd(maxBranchWidth);
+  const pathStr = task.path.padEnd(maxPathWidth);
 
   switch (task.status) {
     case 'pending': {
-      return `${indexStr} ${branchStr}  ${chalk.gray(TASK_STATUS_ICONS.PENDING)} ${chalk.gray(TASK_STATUS_LABELS.PENDING)}  ${chalk.dim(task.path)}`;
+      return `${indexStr} ${pathStr}  ${chalk.gray(TASK_STATUS_ICONS.PENDING)} ${chalk.gray(TASK_STATUS_LABELS.PENDING)}`;
     }
     case 'running': {
       const elapsed = formatDuration(Date.now() - task.startedAt);
-      return `${indexStr} ${branchStr}  ${chalk.cyan(spinnerChar)} ${chalk.cyan(TASK_STATUS_LABELS.RUNNING)} ${chalk.gray(elapsed)}  ${chalk.dim(task.path)}`;
+      // 仅显示活动信息，不显示路径（路径已在第二列显示）
+      const detail = task.activity ? `  ${chalk.dim(task.activity)}` : '';
+      return `${indexStr} ${pathStr}  ${chalk.cyan(spinnerChar)} ${chalk.cyan(TASK_STATUS_LABELS.RUNNING)} ${chalk.gray(elapsed)}${detail}`;
     }
     case 'done': {
       const duration = task.durationMs != null ? formatDuration(task.durationMs) : 'N/A';
       const cost = task.costUsd != null ? `$${task.costUsd.toFixed(2)}` : '';
-      return `${indexStr} ${branchStr}  ${chalk.green(TASK_STATUS_ICONS.DONE)} ${chalk.green(TASK_STATUS_LABELS.DONE)}   ${chalk.gray(duration)}  ${chalk.yellow(cost)}  ${chalk.dim(task.path)}`;
+      const preview = task.resultPreview ? `  ${chalk.dim(task.resultPreview)}` : '';
+      return `${indexStr} ${pathStr}  ${chalk.green(TASK_STATUS_ICONS.DONE)} ${chalk.green(TASK_STATUS_LABELS.DONE)}   ${chalk.gray(duration)}  ${chalk.yellow(cost)}${preview}`;
     }
     case 'failed': {
       const duration = task.durationMs != null ? formatDuration(task.durationMs) : 'N/A';
-      return `${indexStr} ${branchStr}  ${chalk.red(TASK_STATUS_ICONS.FAILED)} ${chalk.red(TASK_STATUS_LABELS.FAILED)}   ${chalk.gray(duration)}  ${chalk.dim(task.path)}`;
+      const preview = task.resultPreview ? `  ${chalk.dim(task.resultPreview)}` : '';
+      return `${indexStr} ${pathStr}  ${chalk.red(TASK_STATUS_ICONS.FAILED)} ${chalk.red(TASK_STATUS_LABELS.FAILED)}   ${chalk.gray(duration)}${preview}`;
     }
   }
 }

package/src/utils/progress.ts

@@ -1,15 +1,22 @@
 import {
   SPINNER_FRAMES,
   SPINNER_INTERVAL_MS,
-  CURSOR_UP,
-  CLEAR_LINE,
   CURSOR_HIDE,
   CURSOR_SHOW,
+  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,
   MESSAGES,
 } from '../constants/index.js';
 import { formatDuration } from './formatter.js';
 import type { TaskProgress } from './progress-render.js';
-import { getMaxBranchWidth, renderTaskLine, renderSummaryLine } from './progress-render.js';
+import { getMaxPathWidth, renderTaskLine, renderSummaryLine, truncateToTerminalWidth } from './progress-render.js';
 
 /**
  * 任务进度面板渲染器
@@ -29,10 +36,12 @@ export class ProgressRenderer {
   private timer: ReturnType<typeof setInterval> | null;
   /** 是否为 TTY 环境 */
   private isTTY: boolean;
-  /** 已渲染的行数（用于回退光标） */
-  private renderedLineCount: number;
+  /** resize 事件处理器引用（用于 stop 时移除监听） */
+  private resizeHandler: (() => void) | null;
   /** 是否已停止 */
   private stopped: boolean;
+  /** exit 兜底处理器（确保异常退出时终端状态被恢复） */
+  private exitHandler: (() => void) | null;
   /** 是否存在排队任务（启用汇总行渲染） */
   private hasPendingTasks: boolean;
 
@@ -48,8 +57,9 @@ export class ProgressRenderer {
     this.frameIndex = 0;
     this.timer = null;
     this.isTTY = !!process.stdout.isTTY;
-    this.renderedLineCount = 0;
+    this.resizeHandler = null;
     this.stopped = false;
+    this.exitHandler = null;
     this.hasPendingTasks = !allRunning;
 
     this.tasks = branches.map((branch, i) => ({
@@ -62,6 +72,8 @@ export class ProgressRenderer {
       lastActiveAt: allRunning ? now : 0,
       durationMs: null,
       costUsd: null,
+      activity: null,
+      resultPreview: null,
     }));
   }
 
@@ -83,8 +95,10 @@ export class ProgressRenderer {
       return;
     }
 
-    // TTY 模式：隐藏光标，启动定时刷新
+    // TTY 模式：进入备选屏幕缓冲区，隐藏光标，禁用终端自动行换行
+    process.stdout.write(ALT_SCREEN_ENTER);
     process.stdout.write(CURSOR_HIDE);
+    process.stdout.write(LINE_WRAP_DISABLE);
     this.render();
     this.timer = setInterval(() => {
       this.frameIndex = (this.frameIndex + 1) % SPINNER_FRAMES.length;
@@ -95,6 +109,22 @@ export class ProgressRenderer {
     if (this.timer.unref) {
       this.timer.unref();
     }
+
+    // 监听终端宽度变化，立即触发重绘
+    this.resizeHandler = () => {
+      if (!this.stopped) {
+        this.render();
+      }
+    };
+    process.stdout.on('resize', this.resizeHandler);
+
+    // 注册 exit 兜底，确保异常退出时终端状态被恢复
+    this.exitHandler = () => {
+      process.stdout.write(LINE_WRAP_ENABLE);
+      process.stdout.write(CURSOR_SHOW);
+      process.stdout.write(ALT_SCREEN_LEAVE);
+    };
+    process.on('exit', this.exitHandler);
   }
 
   /**
@@ -106,6 +136,18 @@ export class ProgressRenderer {
     this.tasks[index].lastActiveAt = Date.now();
   }
 
+  /**
+   * 更新指定任务的活动描述文本
+   * 同时更新 lastActiveAt 时间戳
+   * @param {number} index - 任务索引（从 0 开始）
+   * @param {string} text - 活动描述文本
+   */
+  updateActivityText(index: number, text: string): void {
+    const task = this.tasks[index];
+    task.activity = text;
+    task.lastActiveAt = Date.now();
+  }
+
   /**
    * 标记指定任务为运行中状态
    * 将 pending 任务标记为 running 并设置启动时间戳
@@ -129,19 +171,21 @@ export class ProgressRenderer {
    * @param {number} index - 任务索引（从 0 开始）
    * @param {number} durationMs - 耗时（毫秒）
    * @param {number} costUsd - 费用（美元）
+   * @param {string} [resultPreview] - 结果预览文本（可选）
    */
-  markDone(index: number, durationMs: number, costUsd: number): void {
+  markDone(index: number, durationMs: number, costUsd: number, resultPreview?: string): void {
     const task = this.tasks[index];
     task.status = 'done';
     task.finishedAt = Date.now();
     task.durationMs = durationMs;
     task.costUsd = costUsd;
+    task.resultPreview = resultPreview ?? null;
 
     if (!this.isTTY) {
       // 非 TTY 降级：直接输出完成信息
       const duration = formatDuration(durationMs);
       const cost = `$${costUsd.toFixed(2)}`;
-      console.log(MESSAGES.PROGRESS_TASK_DONE(task.index, this.total, task.branch, duration, cost, task.path));
+      console.log(MESSAGES.PROGRESS_TASK_DONE(task.index, this.total, task.branch, duration, cost, task.resultPreview ?? task.path));
     }
   }
 
@@ -149,17 +193,19 @@ export class ProgressRenderer {
    * 标记指定任务为失败状态
    * @param {number} index - 任务索引（从 0 开始）
    * @param {number} durationMs - 耗时（毫秒）
+   * @param {string} [resultPreview] - 结果预览文本（可选）
    */
-  markFailed(index: number, durationMs: number): void {
+  markFailed(index: number, durationMs: number, resultPreview?: string): void {
     const task = this.tasks[index];
     task.status = 'failed';
     task.finishedAt = Date.now();
     task.durationMs = durationMs;
+    task.resultPreview = resultPreview ?? null;
 
     if (!this.isTTY) {
       // 非 TTY 降级：直接输出失败信息
       const duration = formatDuration(durationMs);
-      console.log(MESSAGES.PROGRESS_TASK_FAILED(task.index, this.total, task.branch, duration, task.path));
+      console.log(MESSAGES.PROGRESS_TASK_FAILED(task.index, this.total, task.branch, duration, task.resultPreview ?? task.path));
     }
   }
 
@@ -176,38 +222,78 @@ export class ProgressRenderer {
       this.timer = null;
     }
 
+    // 移除终端 resize 监听
+    if (this.resizeHandler) {
+      process.stdout.removeListener('resize', this.resizeHandler);
+      this.resizeHandler = null;
+    }
+
     if (this.isTTY) {
-      // 最后渲染一次，确保最终状态显示正确
+      // 最后在备选屏幕渲染一次，确保最终状态显示正确
       this.render();
+      // 恢复终端自动行换行
+      process.stdout.write(LINE_WRAP_ENABLE);
       // 恢复光标显示
       process.stdout.write(CURSOR_SHOW);
+      // 退出备选屏幕缓冲区，恢复主屏幕内容
+      process.stdout.write(ALT_SCREEN_LEAVE);
+
+      // 在主屏幕上输出最终面板状态（备选屏幕内容不保留，需要重新输出）
+      const cols = process.stdout.columns || DEFAULT_TERMINAL_COLUMNS;
+      const finalLines = this.buildLines(cols);
+      for (const line of finalLines) {
+        process.stdout.write(`${line}\n`);
+      }
+    }
+
+    // 移除 exit 兜底
+    if (this.exitHandler) {
+      process.removeListener('exit', this.exitHandler);
+      this.exitHandler = null;
     }
   }
 
   /**
-   * 执行一次完整的面板渲染
-   * 先回退光标到面板起始位置，再逐行输出
+   * 构建当前帧的面板行内容
+   * @param {number} cols - 终端列数
+   * @returns {string[]} 截断后的面板行数组
    */
-  private render(): void {
-    const maxBranchWidth = getMaxBranchWidth(this.tasks);
+  private buildLines(cols: number): string[] {
+    const maxPathWidth = getMaxPathWidth(this.tasks);
     const spinnerChar = SPINNER_FRAMES[this.frameIndex];
-    const lines = this.tasks.map((task) => renderTaskLine(task, this.total, maxBranchWidth, spinnerChar));
+    const lines = this.tasks.map((task) => renderTaskLine(task, this.total, maxPathWidth, spinnerChar));
 
     // 存在排队任务时追加汇总行
     if (this.hasPendingTasks) {
       lines.push(renderSummaryLine(this.tasks, this.total));
     }
 
-    // 回退光标到面板起始位置
-    if (this.renderedLineCount > 0) {
-      process.stdout.write(CURSOR_UP(this.renderedLineCount));
-    }
+    return lines.map((line) => truncateToTerminalWidth(line, cols));
+  }
+
+  /**
+   * 执行一次完整的面板渲染
+   * 在备选屏幕缓冲区中，每次清屏+归位后完全重绘
+   * 无需计算 CURSOR_UP 回退量，不受终端 reflow 影响
+   * 使用 Synchronized Output 防止多行写入时的闪烁
+   */
+  private render(): void {
+    const cols = process.stdout.columns || DEFAULT_TERMINAL_COLUMNS;
+    const lines = this.buildLines(cols);
+
+    // 开启同步输出（终端缓冲输出，关闭时一次性刷新，防止闪烁）
+    process.stdout.write(SYNC_OUTPUT_START);
+
+    // 备选屏幕无滚动缓冲区，直接清屏+归位即可，无需计算回退量
+    process.stdout.write(CLEAR_SCREEN);
+    process.stdout.write(CURSOR_HOME);
 
-    // 逐行输出，每行末尾清除残留字符
+    // 逐行输出，按终端宽度截断
     for (const line of lines) {
-      process.stdout.write(`${line}${CLEAR_LINE}\n`);
+      process.stdout.write(`${line}\n`);
     }
 
-    this.renderedLineCount = lines.length;
+    // 关闭同步输出
+    process.stdout.write(SYNC_OUTPUT_END);
   }
 }