@zhushanwen/pi-subagent-workflow 8.7.0 → 8.8.1

package/src/interface/format.ts

@@ -1,4 +1,4 @@
-// src/tui/format.ts
+// src/interface/format.ts
 //
 // 纯格式化函数.零 Pi 依赖、零 runtime 依赖,可单测.
 //
@@ -6,16 +6,28 @@
 //   `·` 同级并列字段/thinking 图标;`()` 元数据分组;`›` 工具;`>` 输出;`·` thinking.
 //   禁用 `│` 做 stats 分隔、`├─`/`└─` 做 eventLog 前缀.
 //
-// 截断(tui-format.md §5):truncLine 是 ANSI 安全的——追踪 active SGR,省略号前重应用,
-// 否则背景色在省略号处断裂(contentBox 的 applyBg 被 `\x1b[0m` 抹掉).
-// 移植自 pi-subagents render.ts:44-89.
+// 截断/填充/换行（truncLine / padToVisible / segFillColored / wrapText）已迁
+// ./tui-kit.ts（post-convergence C4 零依赖叶），本文件 re-export 维持既有导入面.
 
 import os from "node:os";
 
-import { visibleWidth } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
-import type { AgentEventLogEntry, DisplayItem, ExecutionStatus } from "@zhushanwen/subagent-core/execution/types.ts";
-import { DEFAULT_AGENT_NAME } from "@zhushanwen/subagent-core/execution/types.ts";
+import type { AgentEventLogEntry, DisplayItem, ExecutionStatus } from "@zhushanwen/subagent-core";
+import { DEFAULT_AGENT_NAME } from "@zhushanwen/subagent-core";
+import type {
+  DoneReason,
+  ExecutionTraceNode,
+  RunStatus,
+  ToolCallEntry,
+} from "@zhushanwen/subagent-core";
+import { displayAgentName } from "@zhushanwen/subagent-core";
+
+import { padToVisible, segFillColored, truncLine, wrapText } from "./tui-kit.ts";
+
+// ANSI 可见宽度布局家族单定义在 ./tui-kit.ts（零依赖叶）；此处 re-export 保持
+// 既有消费方（tool-render / bg-notify-render / 测试等）导入面零改动。
+export { padToVisible, segFillColored, truncLine, wrapText };
 
 /**
  * ThemeLike:TUI 语义 token 着色接口(duck-typed,兼容 Pi Theme).
@@ -37,9 +49,6 @@ export interface ThemeLike {
 /** spinner 帧序列(Braille),seed-frame 驱动,不用 setInterval. */
 const RUNNING_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
-/** grapheme 切分器(Unicode/emoji 安全).模块级共享,勿热路径 new. */
-const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
-
 // formatTokens 阈值(三段式,与 demo 一致)
 /** < 此值显示原值. */
 const TOKEN_PLAIN_MAX = 1000;
@@ -119,49 +128,6 @@ export function shortId(id: string): string {
   return segments.slice(0, SHORT_ID_BG_SEGMENTS).join("-");
 }
 
-/**
- * 把文本 pad 到指定**可见**宽度(grapheme/emoji/CJK 安全).
- *
- * 用 visibleWidth 而非 `.length`——避免 ANSI 转义、emoji、宽字符(CJK 占 2 列)
- * 把列对齐算错(dev guide §2.4 警告的坑).
- *
- *   - 已 ≥ width → 原样返回(调用方负责先 truncLine 截断)
- *   - < width → 末尾补空格到可见宽度对齐
- *
- * 与 truncLine 配对:左/右列对齐时先 `truncLine(s, colWidth)` 再 `padToVisible(s, colWidth)`.
- */
-export function padToVisible(text: string, width: number): string {
-  const w = visibleWidth(text);
-  if (w >= width) return text;
-  return text + " ".repeat(width - w);
-}
-
-/**
- * 分段着色版 segFill:title 和 fill 都已着色(含 ANSI),拼接时各自 ANSI 延续.
- *
- * 解决 ANSI 嵌套失色问题:若用 `t.fg("c1", fill(title, "─", n))`,
- * title 内的 `\x1b[0m` 会重置外层 c1,导致 title 之后的 `─` 失去 c1.
- * 本函数改成 `title + fill.repeat(后)`,fill 整段保持着自己的 ANSI,不依赖外层包裹 → 全线着色一致.
- *
- *   segFillColored(t.fg("accent"," Subagents "), t.fg("borderMuted","─"), 20)
- *   → accent(" Subagents ") + borderMuted(─×N),无嵌套
- *
- * 注意:fill 必须是「单字符着色」(如 `t.fg("borderMuted","─")`),visibleWidth=1.
- * 调用方负责 title/fill 着色;本函数不接 theme.标题在前、填充在后.
- */
-export function segFillColored(titleStyled: string | undefined, fillStyled: string, width: number): string {
-  if (width <= 0) return "";
-  const fillW = visibleWidth(fillStyled);
-  if (!titleStyled || fillW === 0) {
-    // 纯填充线:fillStyled.visibleWidth 应为 1,按 width 次重复
-    return fillStyled.repeat(width);
-  }
-  const tw = visibleWidth(titleStyled);
-  if (tw >= width) return truncLine(titleStyled, width);
-  const fillCount = width - tw;
-  return titleStyled + fillStyled.repeat(fillCount);
-}
-
 // ============================================================
 // 状态图标
 // ============================================================
@@ -217,9 +183,8 @@ export function sanitizeLabel(label: string): string {
 /**
  * 取文本首个非空行(多行压成首行).
  *
- * 仅做"取首行"——不 sanitize.三处调用方的 sanitize 末步不同
- * (tool-render 调 sanitizeLabel、bg-notify-render 压 \r\t、list-view 不处理),
- * 故共享此基础函数,各自按需 wrap.
+ * 仅做"取首行"——不 sanitize.需要压平残余 \r/\t 的调用方用 firstLineSanitized
+ * (下方);list-component 直接消费本函数(标题/错误行由外层 truncLine 再压平).
  *
  *   firstLine("a\nb\nc") → "a"
  *   firstLine("\n\nb") → "b"
@@ -230,6 +195,18 @@ export function firstLine(text?: string): string {
   return text.split("\n").find((l) => l.trim())?.trim() ?? "";
 }
 
+/**
+ * firstLine + sanitize 组合:取首个非空行后压平残余 \r/\t.
+ *
+ * tool-render(content 错误回显)与 bg-notify-render(结果/错误正文)共用,
+ * 取代两侧各自维护的 wrapper.tool-render 旧版走 sanitizeLabel(\t→两空格)、
+ * bg-notify-render 旧版压 \r\t 为单空格——差异无测试钉住,统一取
+ * sanitizeLabel 口径(与 eventLog 行处理一致).
+ */
+export function firstLineSanitized(text?: string): string {
+  return sanitizeLabel(firstLine(text));
+}
+
 /**
  * 从 renderCall/execute 的 unknown args 安全提取 agent 名.
  * 类型守卫窄化(替代 `as { agent?: string }` 全可选断言).
@@ -292,78 +269,120 @@ export function formatEventLine(entry: AgentEventLogEntry, theme: ThemeLike): st
   }
 }
 
+// ── formatToolCall 表驱动分发（形态 2）────────────────────────
+// 每个 toolName 的 case 体提为独立格式化函数，主函数留查表 + 落空语义
+// （落空 = 原 default 分支逐字节一致；查表用 Map 避免原型链键误命中，
+// 如 toolName === "constructor" 时普通对象下标会取到 Object.prototype）。
+
+/** formatToolCall 单工具格式化器签名（同步——保持原 switch case 同步语义）。 */
+type ToolCallFormatter = (args: Record<string, unknown>, theme: ThemeLike) => string;
+
+/** 显示层路径缩写：~ 替换 home 前缀（仅显示层，不读取 pi 目录，TC9 合法命中）。 */
+function shortenHomePath(p: string): string {
+  const home = os.homedir();
+  return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+}
+
+/** read/write/edit 共用的路径参数解析（file_path 优先，path 兜底，最终 "..." 兜底）。 */
+function toolPathArg(args: Record<string, unknown>): string {
+  return (args.file_path || args.path || "...") as string;
+}
+
+/** bash → `$ <command 预览>`。 */
+function formatBashToolCall(args: Record<string, unknown>, theme: ThemeLike): string {
+  const command = (args.command as string) || "...";
+  const preview = command.length > BASH_PREVIEW_MAX_CHARS ? `${command.slice(0, BASH_PREVIEW_MAX_CHARS)}...` : command;
+  return theme.fg("muted", "$ ") + theme.fg("toolOutput", preview);
+}
+
+/** read 的 `:start-end` 行号后缀文本（offset/limit 均缺省时返回空串——外层据此跳过着色）。 */
+function readLineRangeText(args: Record<string, unknown>): string {
+  const offset = args.offset as number | undefined;
+  const limit = args.limit as number | undefined;
+  if (offset === undefined && limit === undefined) return "";
+  const startLine = offset ?? 1;
+  const endLine = limit !== undefined ? startLine + limit - 1 : "";
+  return `:${startLine}${endLine ? `-${endLine}` : ""}`;
+}
+
+/** read → `read <~路径:offset-limit>`。 */
+function formatReadToolCall(args: Record<string, unknown>, theme: ThemeLike): string {
+  let text = theme.fg("accent", shortenHomePath(toolPathArg(args)));
+  const range = readLineRangeText(args);
+  if (range) text += theme.fg("warning", range);
+  return theme.fg("muted", "read ") + text;
+}
+
+/** write → `write <~路径> (N lines)`。 */
+function formatWriteToolCall(args: Record<string, unknown>, theme: ThemeLike): string {
+  const content = (args.content || "") as string;
+  const lines = content.split("\n").length;
+  let text = theme.fg("muted", "write ") + theme.fg("accent", shortenHomePath(toolPathArg(args)));
+  if (lines > 1) text += theme.fg("dim", ` (${lines} lines)`);
+  return text;
+}
+
+/** edit → `edit <~路径>`。 */
+function formatEditToolCall(args: Record<string, unknown>, theme: ThemeLike): string {
+  return theme.fg("muted", "edit ") + theme.fg("accent", shortenHomePath(toolPathArg(args)));
+}
+
+/** ls → `ls <~路径>`。 */
+function formatLsToolCall(args: Record<string, unknown>, theme: ThemeLike): string {
+  const rawPath = (args.path || ".") as string;
+  return theme.fg("muted", "ls ") + theme.fg("accent", shortenHomePath(rawPath));
+}
+
+/** find → `find <pattern> in <~路径>`。 */
+function formatFindToolCall(args: Record<string, unknown>, theme: ThemeLike): string {
+  const pattern = (args.pattern || "*") as string;
+  const rawPath = (args.path || ".") as string;
+  return theme.fg("muted", "find ") + theme.fg("accent", pattern) + theme.fg("dim", ` in ${shortenHomePath(rawPath)}`);
+}
+
+/** grep → `grep /<pattern>/ in <~路径>`。 */
+function formatGrepToolCall(args: Record<string, unknown>, theme: ThemeLike): string {
+  const pattern = (args.pattern || "") as string;
+  const rawPath = (args.path || ".") as string;
+  return theme.fg("muted", "grep ") + theme.fg("accent", `/${pattern}/`) + theme.fg("dim", ` in ${shortenHomePath(rawPath)}`);
+}
+
+/** default 落空语义：`<toolName> <argsJSON 预览>`（与原 switch default 逐字节一致）。 */
+function formatUnknownToolCall(toolName: string, args: Record<string, unknown>, theme: ThemeLike): string {
+  const argsStr = JSON.stringify(args);
+  const preview = argsStr.length > ARGS_PREVIEW_MAX_CHARS ? `${argsStr.slice(0, ARGS_PREVIEW_MAX_CHARS)}...` : argsStr;
+  return theme.fg("accent", toolName) + theme.fg("dim", ` ${preview}`);
+}
+
+/** toolName → 格式化函数查找表（Map：杜绝 Object 原型链键误命中）。 */
+const TOOL_CALL_FORMATTERS: ReadonlyMap<string, ToolCallFormatter> = new Map([
+  ["bash", formatBashToolCall],
+  ["read", formatReadToolCall],
+  ["write", formatWriteToolCall],
+  ["edit", formatEditToolCall],
+  ["ls", formatLsToolCall],
+  ["find", formatFindToolCall],
+  ["grep", formatGrepToolCall],
+]);
+
 /**
  * [STEP3] 格式化单个 toolCall 为展示行（对齐 nicobailon formatToolCall）。
  *
- * 返回不含前缀（`→ ` 由调用方加）。根据 toolName 提取关键参数格式化：
+ * 返回不含前缀（`→ ` 由调用方加）。根据 toolName 查表提取关键参数格式化：
  *   bash → `$ <command 预览>`
  *   read → `read <~路径:offset-limit>`
  *   edit/write → `<op> <~路径>`
  *   grep/find/ls → 对应格式
- *   default → `<toolName> <argsJSON 预览>`
+ *   未命中（含 default）→ `<toolName> <argsJSON 预览>`
  */
 export function formatToolCall(
   toolName: string,
   args: Record<string, unknown>,
   theme: ThemeLike,
 ): string {
-  const shortenPath = (p: string): string => {
-    // 仅用于显示层路径缩写（~ 替换 home 前缀），不读取 pi 目录（TC9 合法命中）
-    const home = os.homedir();
-    return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
-  };
-
-  switch (toolName) {
-    case "bash": {
-      const command = (args.command as string) || "...";
-      const preview = command.length > BASH_PREVIEW_MAX_CHARS ? `${command.slice(0, BASH_PREVIEW_MAX_CHARS)}...` : command;
-      return theme.fg("muted", "$ ") + theme.fg("toolOutput", preview);
-    }
-    case "read": {
-      const rawPath = (args.file_path || args.path || "...") as string;
-      const filePath = shortenPath(rawPath);
-      const offset = args.offset as number | undefined;
-      const limit = args.limit as number | undefined;
-      let text = theme.fg("accent", filePath);
-      if (offset !== undefined || limit !== undefined) {
-        const startLine = offset ?? 1;
-        const endLine = limit !== undefined ? startLine + limit - 1 : "";
-        text += theme.fg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
-      }
-      return theme.fg("muted", "read ") + text;
-    }
-    case "write": {
-      const rawPath = (args.file_path || args.path || "...") as string;
-      const content = (args.content || "") as string;
-      const lines = content.split("\n").length;
-      let text = theme.fg("muted", "write ") + theme.fg("accent", shortenPath(rawPath));
-      if (lines > 1) text += theme.fg("dim", ` (${lines} lines)`);
-      return text;
-    }
-    case "edit": {
-      const rawPath = (args.file_path || args.path || "...") as string;
-      return theme.fg("muted", "edit ") + theme.fg("accent", shortenPath(rawPath));
-    }
-    case "ls": {
-      const rawPath = (args.path || ".") as string;
-      return theme.fg("muted", "ls ") + theme.fg("accent", shortenPath(rawPath));
-    }
-    case "find": {
-      const pattern = (args.pattern || "*") as string;
-      const rawPath = (args.path || ".") as string;
-      return theme.fg("muted", "find ") + theme.fg("accent", pattern) + theme.fg("dim", ` in ${shortenPath(rawPath)}`);
-    }
-    case "grep": {
-      const pattern = (args.pattern || "") as string;
-      const rawPath = (args.path || ".") as string;
-      return theme.fg("muted", "grep ") + theme.fg("accent", `/${pattern}/`) + theme.fg("dim", ` in ${shortenPath(rawPath)}`);
-    }
-    default: {
-      const argsStr = JSON.stringify(args);
-      const preview = argsStr.length > ARGS_PREVIEW_MAX_CHARS ? `${argsStr.slice(0, ARGS_PREVIEW_MAX_CHARS)}...` : argsStr;
-      return theme.fg("accent", toolName) + theme.fg("dim", ` ${preview}`);
-    }
-  }
+  const formatter = TOOL_CALL_FORMATTERS.get(toolName);
+  if (formatter) return formatter(args, theme);
+  return formatUnknownToolCall(toolName, args, theme);
 }
 
 /**
@@ -385,157 +404,247 @@ export function formatDisplayItem(item: DisplayItem, theme: ThemeLike): string {
 }
 
 // ============================================================
-// ANSI 安全截断
+// Workflow view 格式化（WorkflowsView / detail-content 专用差异段）
+//
+// 自 views/format.ts 并入（D7-① 双轨合并）：workflow 视图特有的 badge/phase/
+// trace 行格式化在此作差异段保留。并入时收敛的同构构件——ThemeLike、
+// formatElapsedSeconds（本文件版含小时分支，>1h 显示 "1h15m" 而非 "75m30s"）、
+// segFillColored、padToVisible（后者已随 C4 迁 ./tui-kit.ts，经 re-export 复用）。
 // ============================================================
 
-/**
- * SGR 序列 sticky regex（truncLine 专用）。
- *
- * lastIndex 置位后 exec/test 只在该位置匹配（等价 `flat.slice(pos).match(/^\x1b\[[0-9;]*m/)`，
- * 但零子串分配）。同步代码内「设 lastIndex → 立即用」，无跨调用残留。
- */
-const SGR_STICKY_RE = /\x1b\[[0-9;]*m/y;
+// ── Workflow view 布局常量 ────────────────────────────────────
 
-/** 判断 s 在 pos 处是否开始一个 SGR 序列（非 SGR ESC——OSC/非 SGR CSI/裸 ESC——返回 false）。 */
-function isSgrStart(s: string, pos: number): boolean {
-  SGR_STICKY_RE.lastIndex = pos;
-  return SGR_STICKY_RE.test(s);
-}
+// views 专属布局常量（SIDEBAR_WIDTH / PROMPT_FOLD_LINES / OUTPUT_TRUNCATE_BYTES /
+// BOX_BORDER_CHARS / BUDGET_TOKENS_DIVISOR / MAX_TOOL_CALLS_DISPLAY）已沉回
+// ./views/view-constants.ts（就近消费方，post-convergence C4）；
+// 终端兜底零件（终端行数兜底、翻页兜底步长）单定义在 ./tui-kit.ts。
+// ELLIPSIS 留此：formatActivityLine / formatPhaseLine（本文件）亦消费，非 views 专属。
+export const ELLIPSIS = "\u2026"; // U+2026
+
+/** formatElapsed 的毫秒→秒换算。 */
+const MS_PER_SEC = 1000;
 
 /**
- * 截断文本到 maxWidth 可见宽度(带省略号 `…`,ANSI 安全).
- *
- * 问题:pi-tui 的 truncateToWidth 在省略号前插 `\x1b[0m`(全局 reset),
- * 导致 contentBox 施加的背景色在省略号处断裂.
+ * 可显示的状态文本集合。
  *
- * 解决:遍历追踪 active SGR styles,遇 `\x1b[0m` 清空、遇其他 `\x1b[..m` push,
- * 截断时 `result + activeStyles.join("") + "…"`——重应用 active 样式,背景不断裂.
- * 用 Intl.Segmenter grapheme 切分,正确处理 emoji/CJK/组合字符.
+ * 包含 RunStatus（"running"|"done" 不直接显示，转 reason）+ DoneReason
+ * （completed/failed/aborted/budget_limited/time_limited）+ ExecutionTraceNode.status
+ * （含 "pending"——trace 节点的初始态）。
  *
- * 性能（IF12/#18）：旧实现逐字符 `flat.slice(end).match(...)` 是 O(n²)（每字符
- * 一次子串分配 + 正则扫描）；现改为 `indexOf("\x1b", ...)` 跳到下一 ESC，仅在 ESC
- * 位置做一次 sticky 判定——纯文本段零分配零正则。
- *
- * **非 SGR ESC 行为（等价关键，逐字节等价的定义点）**：OSC（\x1b]0;..\x07）、
- * 非 SGR CSI（\x1b[K）、裸 \x1b 后跟非 [ 字符——均不构成文本段边界，作为纯文本
- * 并入 textPortion 被 segmenter 消费（占 currentWidth、进 result），与旧实现
- * 「while 停点集合 = SGR 序列起点」完全一致。输出由 __fixtures__/truncline.snapshot.json
- * （改造前实现生成）逐字节锚定。
- *
- * 移植自 pi-subagents render.ts:44-89.
+ * 收窄自 string → 显式联合，编译器会在新增 status 时强制 switch 补齐分支。
  */
-export function truncLine(text: string, maxWidth: number): string {
-  if (maxWidth <= 0) return "";
-  // 剥离换行符（\n / \r）：text 可能含多行 prompt / turn.text，\n 不占可见宽度
-  // 但在终端会换行，导致单行渲染意外变成多行，破坏行对齐（list overlay 左右列错位、
-  // tool block 行数跳变）。单行渲染入口必须保证无 \n。用空格替代（保留词边界可读性）。
-  const flat = text.replace(/[\r\n]+/g, " ");
-  if (visibleWidth(flat) <= maxWidth) return flat;
-
-  const targetWidth = Math.max(0, maxWidth - 1);
-  let result = "";
-  let currentWidth = 0;
-  let activeStyles: string[] = [];
-  let i = 0;
-
-  while (i < flat.length) {
-    // 捕获 ANSI SGR 序列（sticky：只在 i 处匹配，等价旧 slice(i).match(/^.../m)）
-    SGR_STICKY_RE.lastIndex = i;
-    const ansiMatch = SGR_STICKY_RE.exec(flat);
-    if (ansiMatch) {
-      const code = ansiMatch[0];
-      result += code;
-
-      if (code === "\x1b[0m" || code === "\x1b[m") {
-        activeStyles = []; // reset → 清空栈
-      } else {
-        activeStyles.push(code);
-      }
-      i += code.length;
-      continue;
-    }
+export type StatusText =
+  | RunStatus
+  | DoneReason
+  | "pending";
 
-    // 找到下一段纯文本(非 ANSI)的边界：下一处 SGR 序列起点（或串尾）。
-    // indexOf 跳到 ESC 候选位，仅对 ESC 位置做一次 sticky 判定；非 SGR ESC
-    // （OSC/\x1b[K/裸 \x1b）不构成边界、并入文本段（end 推进到该 ESC 之后继续找），
-    // 与旧逐字符 while 的停点集合逐字节一致。
-    let end = flat.length;
-    for (
-      let escPos = flat.indexOf("\x1b", i);
-      escPos !== -1;
-      escPos = flat.indexOf("\x1b", escPos + 1)
-    ) {
-      if (isSgrStart(flat, escPos)) {
-        end = escPos;
-        break;
-      }
-    }
-
-    // 按 grapheme 迭代这段文本,累加到 targetWidth
-    const textPortion = flat.slice(i, end);
-    for (const seg of segmenter.segment(textPortion)) {
-      const grapheme = seg.segment;
-      const graphemeWidth = visibleWidth(grapheme);
-
-      if (currentWidth + graphemeWidth > targetWidth) {
-        // 截断:重应用 active 样式 + 省略号 + reset。
-        // reset 不可省——否则行尾颜色渗透到 padToVisible 的填充空格、乃至下一帧行，
-        // 视觉上表现为颜色重影（被截断的着色延伸到行尾之外）。
-        // 但纯文本输入（activeStyles 为空）不发 reset——\x1b[0m 是全局重置，
-        // 会清除 theme.bg 施加的外层背景色（背景框内省略号后失去背景的根因）。
-        return result + activeStyles.join("") + "…" + (activeStyles.length ? "\x1b[0m" : "");
-      }
+// ── Workflow status helpers ──────────────────────────────────
 
-      result += grapheme;
-      currentWidth += graphemeWidth;
-    }
-    i = end;
+/** status → 语义颜色 token（用于给任意文本染色，不含符号）。 */
+function statusColorToken(
+  status: StatusText,
+): "success" | "warning" | "error" | "muted" {
+  switch (status) {
+    case "completed": return "success";
+    case "running": return "warning";
+    case "failed": case "aborted": return "error";
+    default: return "muted";
   }
+}
 
-  // 理论上 visibleWidth 检查已提前返回,此行兜底
-  return result + activeStyles.join("") + "…" + (activeStyles.length ? "\x1b[0m" : "");
+export function statusDotStr(
+  status: StatusText,
+  theme: ThemeLike,
+): string {
+  return theme.fg(statusColorToken(status), "●");
+}
+
+/** Format a status badge with color for the header area. */
+export function formatStatusBadge(
+  status: StatusText,
+  theme: ThemeLike,
+): string {
+  switch (status) {
+    case "running": return theme.fg("warning", "\u25CF running");
+    case "completed": return theme.fg("success", "\u2713 completed");
+    case "failed": return theme.fg("error", "\u2717 failed");
+    case "aborted": return theme.fg("error", "\u2717 aborted");
+    case "budget_limited": return theme.fg("error", "\u26A0 budget");
+    case "time_limited": return theme.fg("error", "\u26A0 timeout");
+    default: return theme.fg("muted", status);
+  }
 }
 
+// ── Workflow 时间 / 统计格式化 ────────────────────────────────
+
 /**
- * 把长文本按指定可见宽度拆成多行（word-wrap），完整展示不截断。
+ * Format elapsed time string from startedAt（workflow trace 风格：now 显式参数化，
+ * 缺 startedAt 时 "-" 前缀兜底）。秒→字符串形态**单实现**收敛到 formatElapsedSeconds，
+ * 经委托构造保证同输入同输出——不再靠注释对齐两份小时分支（post-convergence C4）。
  *
- * 用于 detail 模式完整展示长内容（task / output text）。detail 有翻屏能力，
- * 不应像预览那样截断成一行省略号——信息完整性优先。
- *
- * 输入为纯文本（不含 ANSI 颜色）。调用方对返回的每行单独着色，
- * 这样避免对 ANSI 文本做复杂 wrap（SGR 状态跨行续重应用）。
+ *   < 1s    → "0s"
+ *   < 60s   → "Xs"
+ *   < 3600s → "XmYs" ("45m30s")
+ *   ≥ 3600s → "XhYm" ("1h15m")
+ */
+export function formatElapsed(startedAt?: string, now: number = Date.now()): string {
+  if (!startedAt) return "-";
+  const secs = Math.floor((now - new Date(startedAt).getTime()) / MS_PER_SEC);
+  // 钳 0：亚秒（floor=0）与时钟回拨（负值）同走 "0s"（原 `ms < MS_PER_SEC` 分支语义）
+  return formatElapsedSeconds(Math.max(0, secs));
+}
+
+/**
+ * Format a live eventLog entry（live 路径 Activity 区用）。
  *
- * grapheme 迭代（CJK/emoji 安全）：逐字素累加可见宽度，超 maxWidth 即断行。
- * CJK 可在任意字素间断（每个汉字占 2 列但可断），拉丁文不强制保留词边界
- * （detail 场景优先完整性，width 足够宽时自然在空格附近断）。
+ *   tool_start → "→ {label}"
+ *   tool_end   → "← {label}"（done）/ "✗ {label}"（failed）
+ *   turn_end   → "∘ {label}"（turn 摘要）
+ *   error      → "✗ {label}"
  *
- * 原始 \n 保留为段落分隔（split 后每段独立 wrap，空行保留为 ""）。
- * 与 truncLine 的扁平化不同：wrapText 的产物是多行，\n 是有意的段落边界。
+ * 对齐上方 subagents formatEventLine 的视觉风格，但语义域是 workflow trace
+ * （前缀符号不同、label 不 sanitize）——与 formatEventLine 是两个概念域的实现，
+ * 同文件共存故以 Trace 前缀区分命名。
  */
-export function wrapText(text: string, maxWidth: number): string[] {
-  if (maxWidth <= 0) return [text];
-  const result: string[] = [];
-  for (const para of text.split(/\r?\n/)) {
-    const trimmed = para.trim();
-    if (!trimmed) {
-      result.push("");
-      continue;
+export function formatTraceEventLine(entry: AgentEventLogEntry, theme: ThemeLike): string {
+  switch (entry.type) {
+    case "tool_start":
+      return `→ ${entry.label}`;
+    case "tool_end":
+      return entry.status === "failed"
+        ? theme.fg("error", `✗ ${entry.label}`)
+        : `✓ ${entry.label}`;
+    case "turn_end":
+      return theme.fg("dim", `∘ ${entry.label}`);
+    case "error":
+      return theme.fg("error", `✗ ${entry.label}`);
+    default:
+      return entry.label;
+  }
+}
+
+/** Format token + tool call statistics. */
+export function formatTokenStat(
+  usage?: { input: number; output: number },
+  toolCalls?: ToolCallEntry[],
+  elapsed?: string,
+): string {
+  const tokens = usage ? usage.input + usage.output : 0;
+  const tools = toolCalls?.length ?? 0;
+  const base = `${tokens} tok · ${tools} tool calls`;
+  return elapsed ? `${base} · ${elapsed}` : base;
+}
+
+/**
+ * renderResult 的文本兜底：从 result.content[0] 提取纯文本。
+ * 多处 tool 的 renderResult 曾各自内联此逻辑，提取后统一调用。
+ */
+export function renderTextFallback(
+  result: { content?: Array<{ type: string; text?: string }> },
+): string {
+  const first = result.content?.[0];
+  return first?.type === "text" ? (first.text ?? "") : "";
+}
+
+/** Format a single activity line: ToolName(argsPreview). */
+export function formatActivityLine(entry: ToolCallEntry, maxWidth: number): string {
+  // 语义阈值与开销：低于此宽度只显名称；括号占 2 字符 (name)。
+  const MIN_ACTIVITY_WIDTH = 10;
+  const PARENS_OVERHEAD = 2;
+  if (maxWidth < MIN_ACTIVITY_WIDTH) return entry.name;
+  const argsBudget = maxWidth - entry.name.length - PARENS_OVERHEAD;
+  if (argsBudget <= 0) return truncateToWidth(entry.name, maxWidth);
+  const truncated = entry.input.length > argsBudget
+    ? entry.input.slice(0, argsBudget - 1) + ELLIPSIS
+    : entry.input;
+  return `${entry.name}(${truncated})`;
+}
+
+// ── Workflow phase group（filters empty phases）──────────────
+
+export interface PhaseGroup {
+  name: string;
+  nodes: ExecutionTraceNode[];
+  doneCount: number;
+}
+
+/** Group trace nodes by phase. Nodes without phase go to "(no phase)". */
+function groupByPhase(nodes: ExecutionTraceNode[]): Map<string, ExecutionTraceNode[]> {
+  const map = new Map<string, ExecutionTraceNode[]>();
+  for (const node of nodes) {
+    const phase = node.phase || "(default)";
+    let arr = map.get(phase);
+    if (!arr) {
+      arr = [];
+      map.set(phase, arr);
     }
-    let line = "";
-    let lineWidth = 0;
-    for (const seg of segmenter.segment(trimmed)) {
-      const g = seg.segment;
-      const gw = visibleWidth(g);
-      if (lineWidth + gw > maxWidth && line.length > 0) {
-        result.push(line);
-        line = g;
-        lineWidth = gw;
-      } else {
-        line += g;
-        lineWidth += gw;
-      }
+    arr.push(node);
+  }
+  // Sort within each phase by stepIndex ascending (FR-3.2)
+  for (const arr of map.values()) {
+    arr.sort((a, b) => a.stepIndex - b.stepIndex);
+  }
+  return map;
+}
+
+/** The fallback phase name when node has no explicit phase. */
+const NO_PHASE = "(default)";
+
+/** Build phase groups. Nodes without a phase are placed in an unnamed group. */
+export function buildPhaseGroups(nodes: ExecutionTraceNode[]): PhaseGroup[] {
+  const map = groupByPhase(nodes);
+  const result: PhaseGroup[] = [];
+  for (const [name, phaseNodes] of map) {
+    if (phaseNodes.length > 0) {
+      result.push({
+        name: name === NO_PHASE ? "" : name,
+        nodes: phaseNodes,
+        doneCount: phaseNodes.filter((n) => n.status === "completed").length,
+      });
     }
-    if (line.length > 0) result.push(line);
   }
   return result;
 }
+
+// ── Workflow sidebar phase line formatter ────────────────────
+
+export function formatPhaseLine(
+  pg: PhaseGroup,
+  idx: number,
+  isSelected: boolean,
+  theme: ThemeLike,
+  maxWidth: number,
+): string {
+  const pointer = isSelected ? "❯ " : "  ";
+  const dot = statusDotStr(pg.doneCount === pg.nodes.length ? "completed" : "running", theme);
+  const name = pg.name || "(unnamed)";
+  const label = `${idx + 1} ${name} ${pg.doneCount}/${pg.nodes.length}`;
+  // pointer(2) + dot(1) + space(1)
+  const PHASE_PREFIX_WIDTH = 4;
+  const budget = maxWidth - PHASE_PREFIX_WIDTH;
+  const truncated = visibleWidth(label) > budget
+    ? truncateToWidth(label, budget - 1) + ELLIPSIS
+    : label;
+  return `${pointer}${dot} ${truncated}`;
+}
+
+// ── Workflow agent one-liner for overview right panel ────────
+
+const TOKEN_K = 1000;
+
+export function formatAgentOneLiner(node: ExecutionTraceNode, theme: ThemeLike): string {
+  const dot = statusDotStr(node.status, theme);
+  const elapsed = formatElapsed(
+    node.startedAt,
+    node.completedAt ? new Date(node.completedAt).getTime() : Date.now(),
+  );
+  const tok = node.result?.usage;
+  const tokStr = tok
+    ? `${Math.round((tok.input + tok.output) / TOKEN_K)}k tok`
+    : "";
+  const tcCount = node.result?.toolCalls?.length ?? 0;
+  const parts = [dot, displayAgentName(node.agent), node.model];
+  if (tokStr) parts.push(`${tokStr} · ${tcCount} tools`);
+  parts.push(elapsed);
+  return parts.join("    ");
+}