@zhushanwen/pi-subagent-workflow 9.0.1 → 9.1.0

package/src/interface/format/__tests__/display-state.test.ts

@@ -0,0 +1,146 @@
+// src/interface/__tests__/display-state.test.ts
+//
+// [§2.2 B 档] run 域展示态单点：三态投影 + 色调 / 徽标 / 签名片段三张映射的等价性。
+//
+// 回归价值：本批把原散在 WorkflowsView 三处的判定收敛到一处——本测试同时钉住
+// 「与既有 TUI 输出逐字一致」与「run 域色档与 format.ts 的 statusColorToken 同档」
+//（后者是本批修掉的三处可见错误之一的防线）。
+import { describe, expect, it } from "vitest";
+
+import {
+  doneReasonToRunOutcome,
+  noteRebuiltSettlement,
+  type DoneReason,
+  type WorkflowRun,
+} from "@zhushanwen/subagent-core";
+
+import {
+  formatRunBadge,
+  isFailedTerminal,
+  runDisplaySignaturePart,
+  runDisplayStateOf,
+  runToneOf,
+} from "../display-state.ts";
+import {
+  formatStatusBadge,
+  type ThemeLike,
+} from "../format.ts";
+
+const markingTheme: ThemeLike = {
+  fg: (color, text) => `${color}(${text})`,
+  bg: (color, text) => `${color}(${text})`,
+  bold: (text) => `bold(${text})`,
+  underline: (text) => `u(${text})`,
+};
+
+/** 每次构造唯一 runId——终局记录注册表按 runId 分区，跨用例不复用条目。 */
+let displayRunSeq = 0;
+
+/** 最小 run 形态（display-state 读 runSummary：runId/spec/meta/state 四组字段）。 */
+function makeRun(shape: {
+  status?: string;
+  reason?: string;
+  interruptedAt?: string;
+  budget?: { usedTokens: number; maxTokens?: number; usedCost: number };
+} = {}): WorkflowRun {
+  const runId = `wf-display-${displayRunSeq++}`;
+  const status = shape.status ?? "running";
+  // [D6(a) 第 1 步] 终局判定源 = 终局记录注册表：done 形态 fixture 必须携带注册表
+  // 条目（生产 = 壳重建点 noteRebuiltSettlement 注入 run-settled 帧事实）——
+  // doneReason 经 outcome 往返（budget_limited 需 errorCode 同载）。
+  if (status === "done") {
+    const doneReason = (shape.reason ?? "completed") as DoneReason;
+    noteRebuiltSettlement(runId, {
+      outcome: doneReasonToRunOutcome(doneReason),
+      ...(doneReason === "budget_limited" ? { errorCode: "budget_limited" as const } : {}),
+      settledAt: Date.parse("2026-09-30T02:00:00.000Z"),
+    });
+  }
+  return {
+    runId,
+    spec: { scriptName: "display-wf" },
+    meta: { startedAt: "2026-09-30T00:00:00.000Z", ...(shape.interruptedAt ? { interruptedAt: shape.interruptedAt } : {}) },
+    state: {
+      status,
+      ...(shape.reason !== undefined ? { reason: shape.reason } : {}),
+      budget: shape.budget ?? { usedTokens: 0, maxTokens: 200_000, usedCost: 0 },
+      trace: { toArray: () => [] },
+      errorLogs: [],
+    },
+  } as unknown as WorkflowRun;
+}
+
+describe("runDisplayStateOf（三态投影与可中断性）", () => {
+  it("running → status running + abortable", () => {
+    const ds = runDisplayStateOf(makeRun());
+    expect(ds.status).toBe("running");
+    expect(ds.abortable).toBe(true);
+    expect(ds.doneReason).toBeUndefined();
+  });
+
+  it("interrupted（meta.interruptedAt）→ 不可中断、无 doneReason", () => {
+    const ds = runDisplayStateOf(makeRun({ interruptedAt: "2026-09-30T01:00:00.000Z" }));
+    expect(ds.status).toBe("interrupted");
+    expect(ds.abortable).toBe(false);
+  });
+
+  it("done + reason → 不可中断 + doneReason 透传", () => {
+    const ds = runDisplayStateOf(makeRun({ status: "done", reason: "failed" }));
+    expect(ds.status).toBe("done");
+    expect(ds.abortable).toBe(false);
+    expect(ds.doneReason).toBe("failed");
+  });
+
+  it("会计面透传活体快照（含 maxTokens 缺席形态）", () => {
+    const ds = runDisplayStateOf(makeRun({ budget: { usedTokens: 1234, usedCost: 0.5 } }));
+    expect(ds.accounting).toEqual({ usedTokens: 1234, usedCost: 0.5 });
+  });
+});
+
+describe("映射表（色调 / 徽标 / 失败族）", () => {
+  it.each([
+    [{}, "warning", "warning(● running)"],
+    [{ interruptedAt: "t" }, "muted", "muted(○ interrupted)"],
+    [{ status: "done", reason: "completed" }, "success", "success(✓ completed)"],
+    [{ status: "done" }, "success", "success(✓ completed)"],
+    [{ status: "done", reason: "failed" }, "error", "error(✗ failed)"],
+    [{ status: "done", reason: "aborted" }, "error", "error(✗ aborted)"],
+    [{ status: "done", reason: "budget_limited" }, "error", "error(⚠ budget)"],
+    [{ status: "done", reason: "time_limited" }, "error", "error(⚠ timeout)"],
+  ] as const)("形态 %j → tone %s / badge %s", (shape, tone, badge) => {
+    const ds = runDisplayStateOf(makeRun(shape as never));
+    expect(runToneOf(ds)).toBe(tone);
+    expect(formatRunBadge(ds, markingTheme)).toBe(badge);
+  });
+
+  it("失败族判定只认 done + 非 completed", () => {
+    expect(isFailedTerminal(runDisplayStateOf(makeRun({ status: "done", reason: "failed" })))).toBe(true);
+    expect(isFailedTerminal(runDisplayStateOf(makeRun({ status: "done", reason: "completed" })))).toBe(false);
+    expect(isFailedTerminal(runDisplayStateOf(makeRun({ status: "done" })))).toBe(false);
+    expect(isFailedTerminal(runDisplayStateOf(makeRun()))).toBe(false);
+  });
+
+  it("run 域徽标与 format.ts 的既有徽标逐字一致（同输入同输出，防两表漂移）", () => {
+    const cases: Array<[never, string]> = [
+      [{} as never, "running"],
+      [{ interruptedAt: "t" } as never, "interrupted"],
+      [{ status: "done", reason: "completed" } as never, "completed"],
+      [{ status: "done", reason: "failed" } as never, "failed"],
+      [{ status: "done", reason: "aborted" } as never, "aborted"],
+      [{ status: "done", reason: "budget_limited" } as never, "budget_limited"],
+      [{ status: "done", reason: "time_limited" } as never, "time_limited"],
+    ];
+    for (const [shape, legacyStatus] of cases) {
+      const ds = runDisplayStateOf(makeRun(shape));
+      expect(formatRunBadge(ds, markingTheme)).toBe(formatStatusBadge(legacyStatus as never, markingTheme));
+    }
+  });
+
+  it("签名片段：生命周期面全字段进签名（状态/原因/可中断性任一变化即失效）", () => {
+    const running = runDisplaySignaturePart(runDisplayStateOf(makeRun()));
+    const failed = runDisplaySignaturePart(runDisplayStateOf(makeRun({ status: "done", reason: "failed" })));
+    const completed = runDisplaySignaturePart(runDisplayStateOf(makeRun({ status: "done", reason: "completed" })));
+    expect(new Set([running, failed, completed]).size).toBe(3);
+    expect(running).toContain("running");
+  });
+});

package/src/interface/format/display-state.ts

@@ -0,0 +1,112 @@
+// src/interface/format/display-state.ts
+//
+// [§2.2 B 档 · run 域] 展示态单一中间表示——run 域所有展示映射的唯一输入。
+//
+// 为什么需要（登记 §2.2）：run 生命周期的展示此前散在三处各写各的判定与映射
+//（`WorkflowsView.renderHeader` 的徽标、`renderFooter` 的 abort 可用性、
+// `computeRenderSignature` 的签名首段），每处自己决定「什么状态显示成什么」；改一处
+// 漏一处即出现口径漂移（本批修掉的三处可见错误正是这种漂移的产物）。
+//
+// 边界（刻意不做的）：**不并子代理域与通知域**。run 生命周期（三态投影）与子代理执行
+// 状态（running/idle）、通知正文（outcome + closedReason 兜底）没有共同的输入词汇，
+// 强行共用一张表会把两套语义塞进一个枚举——`gui-mappers.ts` 与 `bg-notify-render.ts`
+// 各自留在自己的域里（§2.2 裁决）。
+//
+// 单一判定源纪律：本模块**不判定状态**——`status` 直接取 core `runSummary(run).status`
+//（pi 侧唯一投影，`tool-workflow.displayStatusOf` 同源），只把「生命周期 / 终局原因 /
+// 可中断性 / 会计」整理成展示形态。判定 1 个、展示 1 个。
+import { runSummary, type DoneReason, type WorkflowRun } from "@zhushanwen/subagent-core";
+
+import type { ThemeLike } from "./format.ts";
+
+/** run 展示三态（与 core `runSummary` 投影、shared `WorkflowRunStatus` 同词）。 */
+export type RunDisplayStatus = "running" | "interrupted" | "done";
+
+/** run 展示态（唯一中间表示）。 */
+export interface RunDisplayState { // oe-exempt:20260930:framework:run 域展示契约——TUI 各渲染位共用同一形状，非单实现投机抽象
+  /** 生命周期三态（唯一判定源 = core runSummary）。 */
+  status: RunDisplayStatus;
+  /** 终局原因（仅 status === "done" 且 core 侧有值时；展示文案与失败族判定用）。 */
+  doneReason?: DoneReason;
+  /** 可中断（abort）——仅 running；interrupted 态已停、done 已终局。 */
+  abortable: boolean;
+  /** 会计面（活体快照值；重启重建后的近似值同样走这里，见 §2.1b）。 */
+  accounting: {
+    usedTokens: number;
+    maxTokens?: number;
+    usedCost: number;
+  };
+}
+
+/**
+ * run → 展示态（纯函数，不读 store、不发事件）。
+ *
+ * 注意 `runSummary` 的终局判定优先读进程内终局注册表（活体终局），重启后由 record
+ * 流 fold 出的聚合兜底——因此本函数对活体与重水合两种形态同样正确。
+ */
+export function runDisplayStateOf(run: WorkflowRun): RunDisplayState {
+  const summary = runSummary(run);
+  const budget = run.state.budget;
+  return {
+    status: summary.status,
+    ...(summary.reason !== undefined ? { doneReason: summary.reason } : {}),
+    abortable: summary.status === "running",
+    accounting: {
+      usedTokens: budget.usedTokens,
+      ...(budget.maxTokens !== undefined ? { maxTokens: budget.maxTokens } : {}),
+      usedCost: budget.usedCost,
+    },
+  };
+}
+
+/** 失败族终局（done 且原因非 completed）——色档与徽标共用同一判定，防两处各判。 */
+export function isFailedTerminal(ds: RunDisplayState): boolean {
+  return ds.status === "done" && ds.doneReason !== undefined && ds.doneReason !== "completed";
+}
+
+/**
+ * 展示态 → 语义色调（run 域色档单表）。
+ *
+ * 与 `format.ts` 的 `statusColorToken`（trace 节点 / 通知域用）保持同档：running =
+ * warning、interrupted = muted、失败族 = error、成功终局 = success；两处**输入词汇不同**
+ *（本表吃 RunDisplayState，那张吃 StatusText），故各自成表但档位口径一致。
+ */
+export function runToneOf(ds: RunDisplayState): "success" | "warning" | "error" | "muted" {
+  switch (ds.status) {
+    case "running": return "warning";
+    case "interrupted": return "muted";
+    case "done": return isFailedTerminal(ds) ? "error" : "success";
+  }
+}
+
+/**
+ * 展示态 → 头部徽标（run 域唯一徽标构造点）。
+ *
+ * 文案与符号沿用既有 TUI 输出（逐字不变）：● running / ○ interrupted / ✓ completed /
+ * ✗ failed / ✗ aborted / ⚠ budget / ⚠ timeout。done 缺 reason 时按 completed 显示
+ *（旧格式 run 的常见形态）。
+ */
+export function formatRunBadge(ds: RunDisplayState, theme: ThemeLike): string {
+  if (ds.status === "running") return theme.fg("warning", "\u25CF running");
+  if (ds.status === "interrupted") return theme.fg("muted", "\u25CB interrupted");
+  switch (ds.doneReason) {
+    case "budget_limited": return theme.fg("error", "\u26A0 budget");
+    case "time_limited": return theme.fg("error", "\u26A0 timeout");
+    case "aborted": return theme.fg("error", "\u2717 aborted");
+    case "failed": return theme.fg("error", "\u2717 failed");
+    default: return theme.fg("success", "\u2713 completed");
+  }
+}
+
+/**
+ * 展示态 → 渲染签名片段（`computeRenderSignature` 用）。
+ *
+ * 签名的作用是「字段变了必须失效重绘」——把展示态的**生命周期面全字段**序列化进来，
+ * 新增字段自动进签名，不再依赖「手工同步签名表」的纪律（原实现只放 status，新增展示
+ * 字段靠人记得补签名，DS8 维护约定即为此存在）。会计面（accounting）**刻意不重复进
+ * 本片段**：签名里已有的 `budgetPart` 是同一组值的既有同精度形态（token 取整桶 +
+ * cost 定点小数），重复只会引入第二套精度口径。
+ */
+export function runDisplaySignaturePart(ds: RunDisplayState): string {
+  return [ds.status, ds.doneReason ?? "-", ds.abortable ? "A" : "-"].join(":");
+}

package/src/interface/{format.ts → format/format.ts}

@@ -1,4 +1,4 @@
-// src/interface/format.ts
+// src/interface/format/format.ts
 //
 // 纯格式化函数.零 Pi 依赖、零 runtime 依赖,可单测.
 //
@@ -7,7 +7,7 @@
 //   禁用 `│` 做 stats 分隔、`├─`/`└─` 做 eventLog 前缀.
 //
 // 截断/填充/换行（truncLine / padToVisible / segFillColored / wrapText）单定义
-// ./tui-kit.ts（零依赖叶），消费方直接从 tui-kit import。
+// ../tui/tui-kit.ts（零依赖叶），消费方直接从 tui-kit import。
 
 import os from "node:os";
 
@@ -21,7 +21,6 @@ import type {
   DoneReason,
   ExecutionTraceNode,
   RunEventFoldCheckpoint,
-  RunStatus,
   ToolCallEntry,
 } from "@zhushanwen/subagent-core";
 import { displayAgentName } from "@zhushanwen/subagent-core";
@@ -414,15 +413,15 @@ export function formatDisplayItem(item: DisplayItem, theme: ThemeLike): string {
 // 自 views/format.ts 并入（D7-① 双轨合并）：workflow 视图特有的 badge/phase/
 // trace 行格式化在此作差异段保留。并入时收敛的同构构件——ThemeLike、
 // formatElapsedSeconds（本文件版含小时分支，>1h 显示 "1h15m" 而非 "75m30s"）、
-// segFillColored、padToVisible（后者已随 C4 迁 ./tui-kit.ts，消费方直接 import）。
+// segFillColored、padToVisible（后者已随 C4 迁 ../tui/tui-kit.ts，消费方直接 import）。
 // ============================================================
 
 // ── Workflow view 布局常量 ────────────────────────────────────
 
 // 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。
+// ../tui/views/view-constants.ts（就近消费方，post-convergence C4）；
+// 终端兜底零件（终端行数兜底、翻页兜底步长）单定义在 ../tui/tui-kit.ts。
 // ELLIPSIS 留此：formatActivityLine / formatPhaseLine（本文件）亦消费，非 views 专属。
 export const ELLIPSIS = "\u2026"; // U+2026
 
@@ -432,16 +431,18 @@ const MS_PER_SEC = 1000;
 /**
  * 可显示的状态文本集合。
  *
- * 包含 RunStatus（"running"|"done" 不直接显示，转 reason）+ 中断投影态
- * "interrupted"（[D2] 重水合中断 run 经 meta.interruptedAt 投影——displayStatusOf
- * 三态输出的第三值）+ DoneReason（completed/failed/aborted/budget_limited/
- * time_limited）+ ExecutionTraceNode.status（含 "pending"——trace 节点的初始态）。
+ * 生命周期三态（"running"|"done" 不直接显示，done 转 reason；"interrupted" 为
+ * [D2] 重水合中断投影——displayStatusOf 三态输出的第三值，与 core runSummary
+ * 投影 / shared WorkflowRunStatus 同词）+ DoneReason（completed/failed/aborted/
+ * budget_limited/time_limited）+ ExecutionTraceNode.status（含 "pending"——trace
+ * 节点的初始态）。
  *
  * 收窄自 string → 显式联合，编译器会在新增 status 时强制 switch 补齐分支。
  */
 export type StatusText =
-  | RunStatus
+  | "running"
   | "interrupted"
+  | "done"
   | DoneReason
   | "pending";
 
@@ -452,9 +453,11 @@ function statusColorToken(
   status: StatusText,
 ): "success" | "warning" | "error" | "muted" {
   switch (status) {
-    case "completed": return "success";
+    // [§2.2 色档对齐] 预算耗尽 / 超时是失败族终局——与 formatStatusBadge 同档 error
+    //（此前本函数把它们归 muted，同一状态在徽标与圆点两处一个当错误一个当灰）。
+    case "failed": case "aborted": case "budget_limited": case "time_limited": return "error";
+    case "completed": case "done": return "success";
     case "running": return "warning";
-    case "failed": case "aborted": return "error";
     default: return "muted";
   }
 }
@@ -472,9 +475,12 @@ export function formatStatusBadge(
   theme: ThemeLike,
 ): string {
   switch (status) {
+    // [§2.2 终局徽标修复] displayStatusOf（唯一生产入参）的终局值是 "done"，此前无该
+    // 分支 → 落 default 显示 muted 裸字 "done"；补成分支后与 completed 同形（success
+    // ✓ completed），TUI 头部不再出现无色的裸状态字。
+    case "done": case "completed": return theme.fg("success", "\u2713 completed");
     case "running": return theme.fg("warning", "\u25CF running");
     case "interrupted": return theme.fg("muted", "\u25CB interrupted");
-    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");

package/src/interface/{id-preview.ts → format/id-preview.ts}

@@ -1,4 +1,4 @@
-// src/interface/id-preview.ts
+// src/interface/format/id-preview.ts
 //
 // run/subagent 标识符的截断展示口径（单点常量）。
 //

package/src/interface/{bg-notify-render.ts → gui/bg-notify-render.ts}

@@ -1,4 +1,4 @@
-// src/interface/bg-notify-render.ts
+// src/interface/gui/bg-notify-render.ts
 //
 // background 完成通知的对话流渲染器。
 // pi.registerMessageRenderer("subagent-bg-notify", ...) 注册。
@@ -31,8 +31,8 @@ import {
   shortId,
   statusGlyph,
   type ThemeLike,
-} from "./format.ts";
-import { padToVisible, truncLine } from "./tui-kit.ts";
+} from "../format/format.ts";
+import { padToVisible, truncLine } from "../tui/tui-kit.ts";
 
 /** agent 名最大显示宽度。 */
 const AGENT_MAX_WIDTH = 40;
@@ -213,50 +213,75 @@ function sanitizeAnsiForBg(text: string): string {
  *     - cancelled: `■ default — background subagent cancelled - bg-f6f731-10`
  *   第 2 行（正文）：结果首行 / Error 首行 / cancelled 无第二行
  */
-function renderRecordLines(record: BgNotifyRecord, t: ThemeLike): string[] {
-  const glyph = statusGlyph(record.status);
+/**
+ * 标题行组装（renderRecordLines 拆出）：glyph 与 verb 只读 outcome 分流 + model 段
+ * （空则省略，向后兼容旧 record）。
+ *
+ * [§2.2 通知字形修复] 字形与 verb 同源、只读 outcome：终态 record 的 status 恒为
+ * "closed"（statusGlyph 对 closed 返回 ✓ success），此前失败通知会画绿勾 + "failed"
+ * 文案自相矛盾。running 记录（无 outcome）仍走 statusGlyph。
+ */
+function recordHeadLine(record: BgNotifyRecord, outcome: RecordOutcome, t: ThemeLike): string {
+  const glyph =
+    outcome === "failed"
+      ? { icon: "✗", color: "error" as const }
+      : outcome === "cancelled"
+        ? { icon: "■", color: "muted" as const }
+        : statusGlyph(record.status);
   const icon = glyph.icon ?? "•";
   const agent = truncLine(displayAgentName(record.agent), AGENT_MAX_WIDTH);
   // model 段：agent 后、状态描述前，accent 色。空则省略（向后兼容旧 record）。
   const modelPart = record.model
     ? ` ${t.fg("dim", "·")} ${t.fg("accent", truncLine(record.model, MODEL_MAX_WIDTH))}`
     : "";
+  const verb = outcome === "cancelled" ? "cancelled" : outcome === "failed" ? "failed" : "finished";
+  const idShort = shortId(record.id);
+  return `${t.fg(glyph.color, icon)} ${t.bold(agent)}${modelPart}${t.fg("dim", ` — background subagent ${verb} - ${idShort}`)}`;
+}
+
+/**
+ * closed 态正文行组装（renderRecordLines 拆出）：cancelled 无正文（空数组）；
+ * failed 显示 Error 首行；其余结果首行 / patch 提示（[MF#1]）。空数组由调用方
+ * 与 head 拼接（单行 = 仅标题）。
+ */
+function closedBodyLines(record: BgNotifyRecord, outcome: RecordOutcome, t: ThemeLike): string[] {
+  if (outcome === "cancelled") return [];
+  if (outcome === "failed") {
+    return [t.fg("dim", truncLine(`Error: ${firstLineSanitized(record.error ?? "")}`, BODY_MAX_WIDTH))];
+  }
+  if (!record.result && !record.patchFile) return [];
+  const lines: string[] = [];
+  if (record.result) {
+    lines.push(t.fg("dim", truncLine(firstLineSanitized(record.result), BODY_MAX_WIDTH)));
+  }
+  // [MF#1] 显示 patch 路径提示（与 LLM content 同源），让用户也能看到改动需 `git apply`。
+  if (record.patchFile) {
+    lines.push(t.fg("dim", truncLine(`patch: ${record.patchFile} (run: git apply)`, BODY_MAX_WIDTH)));
+  }
+  return lines;
+}
+
+/**
+ * 渲染单条 record 为多行文本（纯视觉文本，不含边框/背景——由 BorderedBgBox 包裹）。
+ *
+ * 格式（两行）：
+ *   第 1 行（标题）：✓/✗/■ glyph + agent + model + 状态描述 + shortId
+ *     - done:      `✓ default — background subagent finished - bg-f6f731-10`
+ *     - failed:    `✗ default — background subagent failed - bg-f6f731-10`
+ *     - cancelled: `■ default — background subagent cancelled - bg-f6f731-10`
+ *   第 2 行（正文）：结果首行 / Error 首行 / cancelled 无第二行
+ * （组装拆见 recordHeadLine / closedBodyLines。）
+ */
+function renderRecordLines(record: BgNotifyRecord, t: ThemeLike): string[] {
   // U3 C-outcome：verb 与正文分流只读 outcome——单一权威派生（升级前旧消息重放等
   // details 缺 outcome 的存量形态经 deriveOutcome(closedReason, error) 兜底，非同构
   // 重写）。判定先于 patchFile：failed 分支不展示 patch/result（失败轮也会写
   // patchFile，历史 bug 存档见 deriveOutcome 注释）。
   const outcome = record.outcome ?? deriveOutcome(record.closedReason, record.error);
-  let verb: string;
-  if (outcome === "cancelled") {
-    verb = "cancelled";
-  } else if (outcome === "failed") {
-    verb = "failed";
-  } else {
-    verb = "finished";
-  }
-  const idShort = shortId(record.id);
-  const head = `${t.fg(glyph.color, icon)} ${t.bold(agent)}${modelPart}${t.fg("dim", ` — background subagent ${verb} - ${idShort}`)}`;
-
+  const head = recordHeadLine(record, outcome, t);
   switch (record.status) {
-    case "closed": {
-      // U3 C-outcome：cancelled 无正文；failed 显示错误；否则结果/patch（同上，分流只读 outcome）。
-      if (outcome === "cancelled") {
-        return [head];
-      }
-      if (outcome === "failed") {
-        return [head, t.fg("dim", truncLine(`Error: ${firstLineSanitized(record.error ?? "")}`, BODY_MAX_WIDTH))];
-      }
-      if (!record.result && !record.patchFile) return [head];
-      const lines: string[] = [];
-      if (record.result) {
-        lines.push(t.fg("dim", truncLine(firstLineSanitized(record.result), BODY_MAX_WIDTH)));
-      }
-      // [MF#1] 显示 patch 路径提示（与 LLM content 同源），让用户也能看到改动需 `git apply`。
-      if (record.patchFile) {
-        lines.push(t.fg("dim", truncLine(`patch: ${record.patchFile} (run: git apply)`, BODY_MAX_WIDTH)));
-      }
-      return [head, ...lines];
-    }
+    case "closed":
+      return [head, ...closedBodyLines(record, outcome, t)];
     case "running":
     default:
       // v4 B-1: 对话模式轮次完成（旧 idle 折入 running）——仅标题行。

package/src/interface/gui/gui-mappers.ts

@@ -0,0 +1,74 @@
+/**
+ * GUI 协议映射辅助函数 —— run/subagent 状态字符串 → 协议 TreeItem 状态 + 图标。
+ *
+ * 协议包 @zhushanwen/extension-protocol 的 list-tree 组件用 TreeItem.status（三态）
+ * + TreeItem.icon 表达运行态。本模块把**子代理执行状态**（ExecutionStatus）映射到
+ * 这两个枚举，供 subagent-actions.ts 复用。
+ *
+ * 参考：@zhushanwen/extension-protocol GuiComponentProps['list-tree']。
+ */
+
+import type { ExecutionStatus } from "@zhushanwen/subagent-core";
+import type { GuiContext, TreeItem, TreeItemIcon } from "@zhushanwen/extension-protocol";
+
+/**
+ * 从 Pi ExtensionContext 构造协议 GuiContext 的最小子集。
+ *
+ * Pi SDK 的 ExtensionContext 在结构上满足协议 GuiContext（有 mode/hasUI/ui），
+ * 但 ui.custom 的泛型签名与协议 GuiContext.ui.custom 不兼容（前者复杂泛型，后者
+ * 简化签名），直接 `as GuiContext` 会触发 TS 结构兼容错误（ui.custom 参数逆变）。
+ * 此 helper 显式提取 mode/hasUI，构造最小 GuiContext，规避 ui.custom 签名冲突。
+ *
+ * 与 ask-user extension 的 runRpcInteraction 同构（见 ask-user/src/index.ts）。
+ */
+export function toGuiCtx(ctx: { mode: GuiContext["mode"]; hasUI: boolean } | undefined): GuiContext | undefined {
+  if (!ctx) return undefined;
+  return { mode: ctx.mode, hasUI: ctx.hasUI };
+}
+
+/** TreeItem.status 枚举（协议三态）。 */
+type TreeStatus = NonNullable<TreeItem["status"]>;
+
+/**
+ * [§2.2 入参收窄] 本模块服务的状态域 = **子代理执行状态**（`ExecutionStatus`
+ * "running" | "idle"，唯一生产调用方 subagent-actions.ts 传的就是 SubagentListItem
+ * .status）。
+ *
+ * 历史形态是裸 string + 关键词子串匹配（failed/abort/cancel/crash/error/budget/
+ * time_limited），宣称服务 workflow run 状态——但 workflow 路径早已无调用方，那些
+ * 失败关键词分支在生产**全部不可达**，用例也只是在测死词表。收窄到显式联合后，
+ * 新增状态值会在编译期强制补齐分支（与 format.ts 的 statusGlyph 同款做法）。
+ */
+type SubagentDisplayStatus = ExecutionStatus;
+
+/** 子代理状态 → 协议三态 / 图标（穷尽 switch，无 default 静默兜底）。 */
+function displayIndexOf(status: SubagentDisplayStatus): { tree: TreeStatus; icon: TreeItemIcon } {
+  switch (status) {
+    // running = 有任务在飞；idle = 无进行中工作（可续聊）——「为什么停」不进树形状态
+    //（协议无该维度），空闲落 done/check。
+    case "running": return { tree: "running", icon: "circle" };
+    case "idle": return { tree: "done", icon: "check" };
+    // 运行时兜底：类型层已排除域外值，但 extension 入参来自宿主/存量数据，可能带
+    // 旧词表（如 done/failed）——落 done/check（与收窄前的 default 行为一致），
+    // 不抛错（树形渲染不该因一个状态字崩掉整棵列表）。
+    default: return { tree: "done", icon: "check" };
+  }
+}
+
+/**
+ * 子代理执行状态 → list-tree 三态 status。
+ *
+ *   running → running；idle → done（空闲 = 无进行中工作，check 图标）
+ */
+export function mapRunStatus(status: SubagentDisplayStatus): TreeStatus {
+  return displayIndexOf(status).tree;
+}
+
+/**
+ * 子代理执行状态 → TreeItem.icon。
+ *
+ *   running → circle；idle → check
+ */
+export function mapRunIcon(status: SubagentDisplayStatus): TreeItemIcon {
+  return displayIndexOf(status).icon;
+}

package/src/interface/{subagent-actions.ts → gui/subagent-actions.ts}

@@ -1,4 +1,4 @@
-// src/interface/subagent-actions.ts
+// src/interface/gui/subagent-actions.ts
 //
 // subagent tool 六 action 的 TUI/GUI 渲染壳（sink 设计 D6② 消费收缩）。
 //
@@ -25,8 +25,8 @@ import type {
   SubagentToolResult,
 } from "@zhushanwen/subagent-core";
 import { mapRunIcon, mapRunStatus } from "./gui-mappers.ts";
-import { ID_PREVIEW_LENGTH } from "./id-preview.ts";
-import { withGuiAttach } from "./tool-shared.ts";
+import { ID_PREVIEW_LENGTH } from "../format/id-preview.ts";
+import { withGuiAttach } from "../tool/tool-shared.ts";
 
 // ============================================================
 // 渲染层常量 / 类型（pi TUI 渲染族，按设计留壳）