@zhushanwen/pi-subagent-workflow 9.0.1 → 9.1.0

package/src/interface/{tool-subagents.ts → tool/tool-subagents.ts}

@@ -2,19 +2,20 @@
  * Subagent Workflow Extension — subagents tool（批量派发入口，一跳扁平 schema）。
  *
  * ⚠️ 命名同名不同命名空间，互指防混淆：本文件是 **tool**（模型调用的批量派发面，
- * 名为 `subagents`），`interface/subagents.ts` 是 **slash 命令**壳（`/subagents`：
+ * 名为 `subagents`），`interface/command/subagents.ts` 是 **slash 命令**壳（`/subagents`：
  * TUI list overlay + GUI 定向消息通道）。两者无共享状态、无调用关系——改本文件
  * 不影响命令壳，反之亦然。
  *
  * 行为契约（设计 §3.1 终态 / §3.3 D1-D3、D8、D9）：
- * - 唯一批量入口：N 个已知独立任务一次派发；handler 确定性转译
- *   runWorkflow("fan-out")（执行管道唯一——collect 时代的批协调状态已退役，
- *   不存在第二套批机制）。
- * - 批量派发的等价性契约：tasks[] 经 handler 确定性转译为内置 fan-out 模板脚本，
- *   走 runWorkflow 完整管道执行——模板仅由 tasks[] 确定性生成、不含任何批协调
- *   状态，执行管道唯一（不存在第二套批机制）；走管道使批量派发继承 workflow 的
- *   持久化、journal、GUI 投影与断点恢复（resume）全套能力，这是刻意保留间接层
- *   的原因。
+ * - 唯一批量入口：N 个已知独立任务一次派发；handler 按固定名解析内置 `fan-out`
+ *   模板（FAN_OUT_SCRIPT_NAME，不经 registry 之外的第二套批机制），组装
+ *   `args = {tasks, agents?, aggregate?}` 后交 runWorkflow 执行——**不生成脚本
+ *   文本**，执行形态 = 内置模板 + 一跳扁平 args 透传。
+ * - 执行形态保留间接层的原因：模板经 worker 执行模型（脚本 eval + postMessage
+ *   调用协议）运载，该形态同时承载 resume 重放（脚本确定性重跑 + 已 settled 调用
+ *   走 record 回放）、注入安全（workerData.scriptPath 定位 _shared，不回退当前目录）
+ *   与脚本可探索性（@pi-meta 进可用 workflow 清单）——走 workflow 管道使批量派发
+ *   继承持久化、journal、GUI 投影与断点恢复全套能力。
  * - 无 action 分发：status/abort 不复制，直接指路 workflow tool（runId 同体系）。
  * - 无 args 嵌套：tasks/agents/aggregate/... 全在顶层（弱模型信任 schema 结构信号，
  *   两跳转译是事故高发区——对照 workflow tool 的 name+args 形态）。
@@ -61,7 +62,7 @@ import type { RunStartDetails, WorkflowToolResult } from "./tool-result.ts";
 /**
  * 本工具的固定执行体（内置模板）脚本名。
  *
- * 常量而非参数：subagents tool 的契约就是「转译到 fan-out 模板」——参数化会让
+ * 常量而非参数：subagents tool 的契约就是「把 tasks 透传给 fan-out 模板」——参数化会让
  * 工具的语义随脚本漂移（对照 D3「执行管道唯一」）。脚本按名经 registry 解析
  * （内置名优先链与 workflow tool actionRun 同一条，见 plan U2「复刻既有加载路径」）。
  */
@@ -209,7 +210,7 @@ export async function runSubagentsBatch(
     );
   }
 
-  // D3 确定性转译：tasks/agents/aggregate 原样进 args（模板参数面，$ARGS）；未提供的
+  // D3 确定性 args 组装：tasks/agents/aggregate 原样进 args（模板参数面，$ARGS）；未提供的
   // 缺省键不写入（模板侧 aggregate 缺省 false；空值不制造「都传/都缺」歧义形态）。
   const args: Record<string, unknown> = { tasks };
   if (params.agents !== undefined) args.agents = params.agents;

package/src/interface/{tool-workflow-script.ts → tool/tool-workflow-script.ts}

@@ -39,7 +39,7 @@ import {
   saveWorkflow,
 } from "@zhushanwen/subagent-core";
 import type { WorkflowScriptRegistry } from "@zhushanwen/subagent-core";
-import { toGuiCtx } from "./gui-mappers.ts";
+import { toGuiCtx } from "../gui/gui-mappers.ts";
 import type { WorkflowToolResult } from "./tool-result.ts";
 import { assertNotAborted, renderTextResult, throwPrefixed, withGuiAttach } from "./tool-shared.ts";
 

package/src/interface/{tool-workflow.ts → tool/tool-workflow.ts}

@@ -17,7 +17,7 @@
  * 层归属：Interface。依赖 Pi SDK + Engine lifecycle/launcher + helpers。
  */
 
-import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
 import os from "node:os";
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -50,7 +50,7 @@ import {
 } from "@zhushanwen/subagent-core";
 import { assertEntryTimeBudget, assertEntryTokenBudget, assertSlugWithinLimit } from "@zhushanwen/subagent-core";
 import { runSummary } from "@zhushanwen/subagent-core";
-import { ID_PREVIEW_LENGTH } from "./id-preview.ts";
+import { ID_PREVIEW_LENGTH } from "../format/id-preview.ts";
 import type { RunStartDetails, WorkflowToolResult } from "./tool-result.ts";
 import {
   acquireReentryGuard,
@@ -58,7 +58,7 @@ import {
   type ReentryGuardRef,
   releaseReentryGuard,
 } from "./reentry-guard.ts";
-import { formatRunStatusElapsed } from "./format.ts";
+import { formatRunStatusElapsed } from "../format/format.ts";
 import {
   assertNotAborted,
   buildRunSpecFromScript,
@@ -107,7 +107,7 @@ const WorkflowParams = Type.Object({
         "the differing fields listed. Omit to reuse the original args.",
     }),
   ),
-  tokens: Type.Optional(Type.Number({ description: "Max token budget — ONLY set when user explicitly requests a limit; omit = unlimited (default)" })),
+  tokens: Type.Optional(Type.Number({ description: "Max token budget — ONLY set when user explicitly requests a limit; omit = unlimited (default). For resume: the token budget applied to the resumed execution (tokens already spent by the run are counted against it)" })),
   time: Type.Optional(Type.Number({ description: `Max time budget in ms — ONLY set when user explicitly requests a limit; omit = unlimited (default; hard ceiling ${MAX_TIMER_DELAY_MS} ms — larger values fail fast at entry). For resume: the budget applied to the resumed execution (active time already spent by the run is counted against it; suspended time is not)` })),
   error: Type.Optional(
     Type.String({ description: "Error/reason message (optional, used with abort)" }),
@@ -236,7 +236,7 @@ export function registerWorkflowTool(
       "- run: {\"action\":\"run\",\"name\":\"<script>\",\"args\":{...},\"tokens\":N,\"time\":N,\"model\":\"<provider/modelId>\",\"thinkingLevel\":\"<level>\"}. " +
       "- status: {\"action\":\"status\"}. " +
       "- abort: {\"action\":\"abort\",\"runId\":\"<id>\"} (optional: {\"error\":\"<reason>\"}). " +
-      "- resume: {\"action\":\"resume\",\"runId\":\"<id>\",\"args\":{...},\"time\":N} — args/time optional.",
+      "- resume: {\"action\":\"resume\",\"runId\":\"<id>\",\"args\":{...},\"tokens\":N,\"time\":N} — args/tokens/time optional.",
       "Budget: Do NOT set tokens/time unless the user explicitly requests a limit. Built-in workflows run unlimited by default.",
       "Model/thinkingLevel: omit by default (inherit main agent's model). Only set model/thinkingLevel when the user explicitly requests a specific model or thinking depth for this run.",
       "Anti-patterns: Flattening args sub-fields (task/items/...) to the top level — they belong inside args. Calling {\"action\":\"run\"} without name.",
@@ -527,140 +527,11 @@ async function actionAbort(
   }
 }
 
-// ── resume action（D14 args 校验 + resumeRun 接线）──────────
-
-/**
- * D14 比对排除键：rfl 仪表向 spec.args 原地注入的稳定 `_runId`（lifecycle
- * runWorkflow 注入面）——run 派发的机器字段，不属用户意图，比对前双侧剔除。
- */
-const RESUME_ARGS_EXCLUDED_KEY = "_runId";
-
-/** record 流内 run-created 帧的 args 读取结果（D14 比对的数据源形态）。 */
-type HistoricalArgs =
-  | { kind: "args"; args: Record<string, unknown> }
-  | { kind: "absent" }
-  | { kind: "truncated" };
-
-/**
- * record 行 → run-created 帧窄化（type 字面量判别 + args 全文 / argsSummary 透传；
- * 非该帧 / 非 object 返回 undefined——结构判别走运行时守卫，不做断言）。
- */
-function asRunCreatedFrame(parsed: unknown): { args?: unknown; argsSummary: unknown } | undefined {
-  if (typeof parsed !== "object" || parsed === null) return undefined;
-  if (!("type" in parsed) || parsed.type !== "run-created") return undefined;
-  return {
-    args: "args" in parsed ? parsed.args : undefined,
-    argsSummary: "argsSummary" in parsed ? parsed.argsSummary : undefined,
-  };
-}
-
-/**
- * 读 run-created 帧的历史 args（D14 比对数据源；record 流是唯一事实源）。
- *
- * - args 全文优先（设计 §3.1 载荷表 run-created 行「args」——现行写入面
- *   dispatchRunCreated 随帧落全文，任意体积的 args 都可逐字段深度比对）；
- * - 流不存在 / 无 run-created 帧 → absent：不在 D14 层拒绝——资格判据（无 record
- *   流 / 首帧缺失）归 resumeRun 权威文案，此处不重复实现（分层：D14 只管 args 一致性）；
- * - 旧格式帧回落 argsSummary（无 args 字段）：截断（>256 字符，写侧
- *   summarizeRunArgs 截断标记）→ truncated——截断摘要无法逐字段比对，保守拒绝
- *   （静默放行 = 静默忽略传入 args，D14 不采用形态）；
- * - 解析失败 → throw：args/argsSummary 是 JSON.stringify 产物，未截断必可解析——
- *   不可解析 = 流被篡改或写入器 bug（对齐 D12 拒绝精神）。
- */
-function readHistoricalArgs(recordPath: string, runId: string): HistoricalArgs {
-  let content: string;
-  try {
-    content = readFileSync(recordPath, "utf8");
-  } catch {
-    return { kind: "absent" };
-  }
-  for (const line of content.split("\n")) {
-    if (line.trim().length === 0) continue;
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(line);
-    } catch {
-      continue;
-    }
-    const frame = asRunCreatedFrame(parsed);
-    if (frame === undefined) continue;
-    // args 全文优先：大 args run 的 D14 逐字段比对由此成立（truncated 拒绝只对
-    // 旧格式帧的截断摘要形态出现）
-    if (isPlainObject(frame.args)) return { kind: "args", args: frame.args };
-    const summary = frame.argsSummary;
-    if (typeof summary !== "string" || summary.length === 0) return { kind: "absent" };
-    if (summary.endsWith("…")) return { kind: "truncated" };
-    let args: unknown;
-    try {
-      args = JSON.parse(summary);
-    } catch {
-      // 未截断摘要必可解析（JSON.stringify 产物）——不可解析 = 字段被篡改/流损坏，
-      // 与上方 malformed 分支同构拒绝（裸 SyntaxError 无恢复指引，不透出）。
-      throw new Error(
-        `Resume rejected: original args of run ${runId} are malformed in its record stream — ` +
-          "the record stream is the sole source of truth. Recovery: inspect the record file for external edits; " +
-          "if unrepairable, start a new run.",
-      );
-    }
-    if (!isPlainObject(args)) {
-      throw new Error(
-        `Resume rejected: original args of run ${runId} are malformed in its record stream — ` +
-          "the record stream is the sole source of truth. Recovery: inspect the record file for external edits; " +
-          "if unrepairable, start a new run.",
-      );
-    }
-    return { kind: "args", args };
-  }
-  return { kind: "absent" };
-}
-
-/** plain object 判定（数组/null 排除——数组按值比、不递归键差）。 */
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-/**
- * 逐字段深度比对（D14）——返回差异字段描述列表（空 = 一致）。
- *
- * 差异三形态：仅 resume 侧有（unexpected）/ 仅原 run 侧有（missing）/ 值不等
- * （mismatch）。嵌套 plain object 递归比对（路径 `a.b` 形态）；数组与原始值按
- * JSON 值比。值展示用 JSON.stringify（函数/undefined 等不可序列化形态按原样）。
- */
-export function diffResumeArgs(
-  incoming: Record<string, unknown>,
-  historical: Record<string, unknown>,
-): string[] {
-  return diffPlainObject(incoming, historical).map((d) => `args.${d}`);
-}
-
-/** diffResumeArgs 的递归体（裸键路径，`a.b` 形态——前缀由公开包装统一添加）。 */
-function diffPlainObject(
-  incoming: Record<string, unknown>,
-  historical: Record<string, unknown>,
-): string[] {
-  const diffs: string[] = [];
-  const keys = new Set([...Object.keys(incoming), ...Object.keys(historical)]);
-  keys.delete(RESUME_ARGS_EXCLUDED_KEY);
-  for (const key of [...keys].sort()) {
-    const hasIn = Object.hasOwn(incoming, key);
-    const hasHist = Object.hasOwn(historical, key);
-    if (!hasIn || !hasHist) {
-      const holder = hasIn ? "resume args only (not in original run)" : "original run only (missing from resume args)";
-      diffs.push(`${key}: ${holder}`);
-      continue;
-    }
-    const a = incoming[key];
-    const b = historical[key];
-    if (isPlainObject(a) && isPlainObject(b)) {
-      diffs.push(...diffPlainObject(a, b).map((d) => `${key}.${d}`));
-      continue;
-    }
-    const sa = JSON.stringify(a);
-    const sb = JSON.stringify(b);
-    if (sa !== sb) diffs.push(`${key}: resume ${sa ?? String(a)} vs original ${sb ?? String(b)}`);
-  }
-  return diffs;
-}
+// ── resume action（args 判定归 core D14 单源 + resumeRun 接线）──
+//
+// [§2.5 下沉] args 一致性判定（D14）已移入 core `orchestration/resume-args-guard.ts`，
+// 由 `assertResumeEligibility` 用**已读到的** run-created 事件执行——本文件只做参数
+// 装配（args + journalDir）与成功文案，不再读 record 文件、不再持有比对逻辑与拒绝文案。
 
 /**
  * resume action：interrupted 态 run 断点续跑。
@@ -671,6 +542,8 @@ function diffPlainObject(
  *   不一致明确拒绝并列出差异字段（换 args 重放 = 换意图，属新 run）；不传默认沿用历史；
  * - time 可选——resume 执行段的时间预算（活跃段算式在 core：已耗活跃时间计入、
  *   搁置不计）；入口护栏（负值/超安全域）与 run action 同源（assertEntryTimeBudget）。
+ * - tokens 可选——resume 执行段的 token 预算（已耗加权 tokens 计入，帧推导下界
+ *   口径）；入口护栏（负值）与 run action 同源（assertEntryTokenBudget）。
  *
  * 资格拒绝（非 interrupted / record 损坏 / 锁被占 / D13 嵌套 / 预算耗尽）由 core
  * resumeRun 权威裁决——ResumeRejectionError 文案含恢复指引，原样透出（throw，
@@ -687,35 +560,17 @@ export async function actionResume(
     );
   }
   assertEntryTimeBudget(params.time);
-
-  // D14 args 校验（fail-fast——先于任何副作用；不一致即拒绝，不触碰 run 状态）
-  if (params.args !== undefined) {
-    const historical = readHistoricalArgs(deps.store.stateFilePath(runId), runId);
-    if (historical.kind === "truncated") {
-      // 仅旧格式帧（args 全文载荷落地前落盘、截断摘要形态）到达此分支——现行
-      // 写入面随帧落 args 全文，任意体积可逐字段比对
-      throw new Error(
-        `Resume rejected: original args of run ${runId} exceed the record's args summary limit ` +
-          "(legacy record stream without the full-args payload) — they cannot be verified field-by-field. " +
-          "Recovery: start a new run for these arguments, or resume WITHOUT args knowing $ARGS will be empty " +
-          "(a truncated summary cannot be reconstructed).",
-      );
-    }
-    if (historical.kind === "args") {
-      const diffs = diffResumeArgs(params.args, historical.args);
-      if (diffs.length > 0) {
-        throw new Error(
-          `Resume rejected: args for run ${runId} differ from the original run — resume replays the same intent; ` +
-            `changed arguments belong to a new run. Differing fields:\n  - ${diffs.join("\n  - ")}\n` +
-            "Recovery: pass the original args exactly, omit args to reuse them, or start a new run.",
-        );
-      }
-    }
-    // absent：D14 层不拒绝——无 record 流 / 无 run-created 帧的资格判据归 resumeRun 权威文案
-  }
+  assertEntryTokenBudget(params.tokens);
 
   const options: ResumeRunOptions = {
     ...(params.time !== undefined ? { budgetTimeMs: params.time } : {}),
+    // token 预算显式覆盖（与 time 同款通道；三档回落与落盘归 core 单点）
+    ...(params.tokens !== undefined ? { budgetTokens: params.tokens } : {}),
+    // [§2.5] args 原样下传由 core 判定（D14 单源）；journalDir 传壳的 store 同源目录，
+    // 否则 core 会按模块锚解析 record 路径——多 session 场景会静默读成「无记录」
+    //（D14 静默放行 = 安全语义反转；core 锚点与壳 store 锚点必须同源）。
+    ...(params.args !== undefined ? { args: params.args } : {}),
+    journalDir: dirname(deps.store.stateFilePath(runId)),
     host: os.hostname(),
   };
   await resumeRun(runId, deps, options);

package/src/interface/tui/__tests__/list-view.test.ts

@@ -0,0 +1,188 @@
+/**
+ * createSubagentsView factory 驱动测试（与 list-component.test.ts 的组件/键位直测互补：
+ * 本文件只覆盖 factory 编排面——G-017 防叠加、directId 分流、onChange 防抖订阅、
+ * animTimer 动画循环、wrappedDone 收尾顺序）。
+ *
+ * 驱动方式：fake ctx.ui.custom 同步调 factory 捕获 Component；service 为最小 stub
+ * （collectRecords / onChange / cancel）；fake timers 驱动 250ms 动画帧与 120ms 防抖。
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SubagentRecord, SubagentService } from "@zhushanwen/subagent-core";
+
+import type { ThemeLike } from "../../format/format.ts";
+import { createSubagentsView } from "../list-view.ts";
+
+const ESC = "\x1b";
+
+const plainTheme: ThemeLike = {
+  bg: (_color: string, text: string) => text,
+  fg: (_tag: string, text: string) => text,
+  bold: (text: string) => text,
+  underline: (text: string) => text,
+};
+
+function makeRecord(over: Partial<SubagentRecord> = {}): SubagentRecord {
+  return {
+    id: "run-1",
+    agent: "worker",
+    task: "do the thing",
+    status: "closed",
+    mode: "sync",
+    startedAt: 1000,
+    endedAt: 2000,
+    depth: 0,
+    turns: 1,
+    totalTokens: 10,
+    model: "test/model",
+    eventLog: [],
+    displayItems: [],
+    result: "ok",
+    ...over,
+  } as SubagentRecord;
+}
+
+interface ListComponentView { // oe-exempt:20260930:test:test double shape for component capture (test infra)
+  render(width: number): string[];
+  handleInput(data: string): void;
+  invalidate(): void;
+  hasRunning(): boolean;
+}
+
+interface Driver { // oe-exempt:20260930:test:test fixture harness shape (test infra)
+  component: ListComponentView;
+  done: Promise<void>;
+  notifies: Array<{ msg: string; type?: string }>;
+  service: {
+    collectRecords: ReturnType<typeof vi.fn>;
+    onChange: ReturnType<typeof vi.fn>;
+    cancel: ReturnType<typeof vi.fn>;
+  };
+  unsubscribe: ReturnType<typeof vi.fn>;
+  tui: { terminal: { columns: number; rows: number }; requestRender: ReturnType<typeof vi.fn> };
+}
+
+function openDriver(opts: { records?: SubagentRecord[]; directId?: string } = {}): Driver {
+  const records = opts.records ?? [makeRecord()];
+  const unsubscribe = vi.fn();
+  const collectRecords = vi.fn(() => records);
+  const onChange = vi.fn(() => unsubscribe);
+  const cancel = vi.fn(() => true);
+  const getFullRecord = vi.fn(() => undefined as SubagentRecord | undefined);
+  const service = {
+    queries: { collectRecords, onChange, getFullRecord, findRecord: vi.fn(() => undefined), lookupRecordAnyState: vi.fn(() => undefined) },
+    cancel,
+  } as unknown as SubagentService;
+  const tui = { terminal: { columns: 100, rows: 30 }, requestRender: vi.fn() };
+  const notifies: Array<{ msg: string; type?: string }> = [];
+  let component!: ListComponentView;
+  let resolveDone!: () => void;
+  const done = new Promise<void>((resolve) => {
+    resolveDone = resolve;
+  });
+  const ctx = {
+    mode: "tui",
+    ui: {
+      notify: (msg: string, type?: string) => notifies.push({ msg, type }),
+      custom: (
+        factory: (t: unknown, th: unknown, kb: unknown, d: (v: void) => void) => ListComponentView,
+      ): Promise<void> => {
+        component = factory(tui, plainTheme, {}, () => resolveDone());
+        return done;
+      },
+    },
+  } as unknown as ExtensionContext;
+  void createSubagentsView(service, plainTheme, ctx, opts.directId);
+  return { component, done, notifies, service: { collectRecords, onChange, cancel }, unsubscribe, tui };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("createSubagentsView factory", () => {
+  it("打开即返回可用组件：render 出行、无 directId 时零 notify", () => {
+    const d = openDriver();
+    expect(d.component.render(100).length).toBeGreaterThan(0);
+    expect(d.notifies).toEqual([]);
+    expect(d.service.onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("directId 未命中 → warning notify，仍打开列表", () => {
+    const d = openDriver({ directId: "ghost" });
+    expect(d.notifies).toEqual([{ msg: 'No record found for id "ghost", showing all', type: "warning" }]);
+    expect(d.component.render(100).length).toBeGreaterThan(0);
+  });
+
+  it("directId 命中 → 直接进详情模式（esc 先退详情而非关闭 overlay）", async () => {
+    const d = openDriver({ directId: "run-1" });
+    d.component.handleInput(ESC); // detailMode=true → 退出详情，overlay 保持
+    const resolved = await Promise.race([d.done.then(() => true), Promise.resolve(false)]);
+    expect(resolved).toBe(false);
+    expect(d.unsubscribe).not.toHaveBeenCalled();
+    // 再按 esc（list 模式无 filter）→ 关闭
+    d.component.handleInput(ESC);
+    await d.done;
+    expect(d.unsubscribe).toHaveBeenCalledTimes(1);
+  });
+
+  it("G-017 防叠加：第二个 overlay 打开时关闭前一个（前一 done 落定 + 解订）", async () => {
+    const d1 = openDriver();
+    const d2 = openDriver();
+    await d1.done; // 前一个被 activeView.close() 关闭
+    expect(d1.unsubscribe).toHaveBeenCalledTimes(1);
+    // d2 仍存活：esc 关闭
+    d2.component.handleInput(ESC);
+    await d2.done;
+    expect(d2.unsubscribe).toHaveBeenCalledTimes(1);
+  });
+
+  it("onChange 防抖：120ms 窗口内多次触发只重绘一次；disposed 后触发早退", async () => {
+    const d = openDriver();
+    const fire = d.service.onChange.mock.calls[0][0] as () => void;
+    fire();
+    fire();
+    fire();
+    vi.advanceTimersByTime(120);
+    expect(d.tui.requestRender).toHaveBeenCalledTimes(1);
+    // 关闭后触发 → disposed 早退，不再重绘
+    d.component.handleInput(ESC);
+    await d.done;
+    const calls = d.tui.requestRender.mock.calls.length;
+    fire();
+    vi.advanceTimersByTime(120);
+    expect(d.tui.requestRender.mock.calls.length).toBe(calls);
+  });
+
+  it("animTimer：有 running record 时 250ms 帧刷新；全终态后停止浪费刷新", () => {
+    const d = openDriver({ records: [makeRecord({ status: "running" })] });
+    expect(d.component.hasRunning()).toBe(true);
+    vi.advanceTimersByTime(250);
+    expect(d.tui.requestRender).toHaveBeenCalledTimes(1);
+    // 记录集变全终态（collectRecords 每次重查）→ hasRunning false → 不再 invalidate
+    (d.service.collectRecords as ReturnType<typeof vi.fn>).mockReturnValue([makeRecord({ status: "closed" })]);
+    vi.advanceTimersByTime(250);
+    expect(d.tui.requestRender).toHaveBeenCalledTimes(1);
+  });
+
+  it("wrappedDone 幂等：esc 关闭后重复关闭不再解订/不再 done", async () => {
+    const d = openDriver();
+    d.component.handleInput(ESC);
+    await d.done;
+    // 组件 closeFn 幂等（state.disposed 早退），二次 esc 无副作用
+    d.component.handleInput(ESC);
+    expect(d.unsubscribe).toHaveBeenCalledTimes(1);
+  });
+
+  it("cancel 接线：详情模式对 running record 按 x → service.cancel + info notify", () => {
+    const d = openDriver({ records: [makeRecord({ id: "run-x", status: "running" })], directId: "run-x" });
+    d.component.handleInput("x");
+    expect(d.service.cancel).toHaveBeenCalledWith("run-x");
+    expect(d.notifies).toEqual([{ msg: "Requested stop for run-x", type: "info" }]);
+  });
+});

package/src/interface/{list-component.ts → tui/list-component.ts}

@@ -1,4 +1,4 @@
-// src/interface/list-component.ts
+// src/interface/tui/list-component.ts
 //
 // /subagents list 全屏带框左右分屏组件实现。
 // 从 list-view.ts 抽出（文件行数控制）：list-view.ts 保留 factory / key 处理，
@@ -27,7 +27,7 @@ import {
   spinnerGlyph,
   statusGlyph,
   type ThemeLike,
-} from "./format.ts";
+} from "../format/format.ts";
 import {
   b,
   dash,

package/src/interface/{list-shared.ts → tui/list-shared.ts}

@@ -1,4 +1,4 @@
-// src/interface/list-shared.ts
+// src/interface/tui/list-shared.ts
 //
 // list-view 与 list-component 共享的类型/常量/纯函数，避免两者循环依赖。
 // 原循环：list-view import 组件类 SubagentsListComponent；组件 import key 处理 + 状态类型。

package/src/interface/{list-view.ts → tui/list-view.ts}

@@ -1,4 +1,4 @@
-// src/interface/list-view.ts
+// src/interface/tui/list-view.ts
 //
 // /subagents list 全屏带框左右分屏 overlay。
 //   左列：record 列表（状态图标 + agent + mode + 绝对时长）
@@ -37,7 +37,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import type { SubagentService } from "@zhushanwen/subagent-core";
 import type { SubagentRecord } from "@zhushanwen/subagent-core";
-import { type ThemeLike } from "./format.ts";
+import { type ThemeLike } from "../format/format.ts";
 import { SubagentsListComponent } from "./list-component.ts";
 import {
   type DetailKeyContext,

package/src/interface/{tui-kit.ts → tui/tui-kit.ts}

@@ -1,4 +1,4 @@
-// src/interface/tui-kit.ts
+// src/interface/tui/tui-kit.ts
 //
 // TUI 终端零件 kit（post-convergence C4）：全屏视图族的共享零件单点——
 // 终端探测常量 / termRows() / 边框着色家族（b/dash/dashes/titleBorder/plainBorder/walled，

package/src/interface/{views → tui/views}/WorkflowsView.ts

@@ -36,6 +36,11 @@ import {
 import type { ExecutionTraceNode } from "@zhushanwen/subagent-core";
 import type { SubagentRecord } from "@zhushanwen/subagent-core";
 import type { WorkflowRun } from "@zhushanwen/subagent-core";
+import {
+  formatRunBadge,
+  runDisplaySignaturePart,
+  runDisplayStateOf,
+} from "../../format/display-state.ts";
 import {
   buildPhaseGroups,
   ELLIPSIS,
@@ -44,13 +49,12 @@ import {
   formatElapsed,
   formatElapsedSeconds,
   formatPhaseLine,
-  formatStatusBadge,
   statusDotStr,
   type ThemeLike,
-} from "../format.ts";
+} from "../../format/format.ts";
 // [W2/V1 D1 分流表第 9 行] CLI 视图显示换源：投影二值 status（混合判源收拢在
 // displayStatusOf 单点——判源 = core runSummary 投影）。
-import { displayStatusOf } from "../tool-workflow.ts";
+import { displayStatusOf } from "../../tool/tool-workflow.ts";
 import {
   b,
   dashes,
@@ -233,7 +237,7 @@ export function computeRenderSignature(
     const l = liveProgress.get(n.stepIndex);
     return `${n.stepIndex}:${n.status}:${n.sessionFile ?? "-"}:${l?.totalTokens ?? -1}:${l?.toolCallCount ?? -1}:${l?.elapsedSeconds ?? -1}:${l?.turns ?? -1}:${l?.eventLog.length ?? -1}:${l?.currentActivity ? `${l.currentActivity.type}:${l.currentActivity.label}` : "-"}:${l?.lastError ?? "-"}`;
   });
-  return [displayStatusOf(run), Math.floor(now / SECOND_MS), `${completed}/${traceArr.length}`, budgetPart, errorLogsPart, ...nodeParts].join("|");
+  return [runDisplaySignaturePart(runDisplayStateOf(run)), Math.floor(now / SECOND_MS), `${completed}/${traceArr.length}`, budgetPart, errorLogsPart, ...nodeParts].join("|");
 }
 
 // ── View state ────────────────────────────────────────────────
@@ -706,7 +710,7 @@ function renderHeader(
   const completed = traceArr.filter((n) => n.status === "completed").length;
   const total = traceArr.length;
   const elapsed = formatElapsed(run.meta.startedAt);
-  const headerRight = `${formatStatusBadge(displayStatusOf(run), theme)} · ${completed}/${total} agents · ${elapsed}`;
+  const headerRight = `${formatRunBadge(runDisplayStateOf(run), theme)} · ${completed}/${total} agents · ${elapsed}`;
   const budget = run.state.budget;
   const budgetStr = `${Math.round(budget.usedTokens / BUDGET_TOKENS_DIVISOR)}k/${budget.maxTokens ? `${Math.round(budget.maxTokens / BUDGET_TOKENS_DIVISOR)}k` : "∞"} tok · $${budget.usedCost.toFixed(BUDGET_COST_DECIMALS)}`;
 
@@ -749,7 +753,7 @@ function renderFooter(
       ? "↑↓ agent · ⏎ detail"
       : "↑↓ agent · ⏎ prompt · PgUp/PgDn scroll";
   const actionParts: string[] = [];
-  if (displayStatusOf(run) === "running") {
+  if (runDisplayStateOf(run).abortable) {
     actionParts.push("a abort");
   }
   actionParts.push("s save");