@zhushanwen/pi-subagent-workflow 8.11.0 → 8.12.0

package/src/interface/views/__tests__/WorkflowsView-signature.test.ts

@@ -6,14 +6,22 @@
  * 字段。本测试证明「已入字段变化 → 签名变」+「静态 run 不变」（完备性无法靠
  * 测试证明，字段核对表见 WorkflowsView.ts computeRenderSignature doc）。
  *
- * 确定性说明：签名非完全纯——live 节点 elapsedSeconds 由 projectLiveProgress 内
- * computeElapsedSeconds 现算（record.endedAt ?? Date.now()）。fake timers 控制
+ * [H2 W3] live 数据源切换：签名第 2 参从 node.live 直读改为 store record 投影
+ * （Map<stepIndex, LiveProgressView>，经 collectNodeLiveProgress 配对注入）——
+ * 字段口径不变（totalTokens/toolCallCount/elapsedSeconds/turns/eventLog.length/
+ * currentActivity/lastError），本文件用 makeLiveView 直接构造投影驱动「已入字段
+ * 变 → 签名变」；投影与旧 projectLiveProgress 的逐字段等价性见
+ * record-progress.test.ts（双路径对齐断言）。
+ *
+ * 确定性说明：签名非完全纯——live 投影的 elapsedSeconds 由 projectRecordProgress
+ * 内 computeElapsedSeconds 现算（record.endedAt ?? Date.now()）。fake timers 控制
  * Date.now() 与 now 参数同源推进，保证确定性。
  */
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 
 import { computeRenderSignature } from "../WorkflowsView.ts";
-import type { ExecutionRecord } from "@zhushanwen/subagent-core";
+import type { LiveProgressView } from "../detail-content.ts";
+import type { AgentEventLogEntry } from "@zhushanwen/subagent-core";
 import type { ExecutionTraceNode, WorkerLogEntry } from "@zhushanwen/subagent-core";
 import type { WorkflowRun } from "@zhushanwen/subagent-core";
 
@@ -21,30 +29,21 @@ import type { WorkflowRun } from "@zhushanwen/subagent-core";
 
 const T0 = 1_700_000_000_000; // 固定 epoch ms
 
-function makeLive(overrides: Partial<ExecutionRecord> = {}): ExecutionRecord {
+function makeLiveView(overrides: Partial<LiveProgressView> = {}): LiveProgressView {
   return {
-    id: "run-0",
-    agent: "worker",
-    model: "default",
-    thinkingLevel: undefined,
-    mode: "sync",
-    task: "t",
-    slug: "s",
-    startedAt: T0,
-    rootSessionId: undefined,
-    parentRecordId: undefined,
-    depth: 0,
-    status: "running",
-    turns: [],
-    turnCount: 0,
     totalTokens: 0,
+    toolCallCount: 0,
+    elapsedSeconds: 5,
+    turns: 0,
+    eventLog: [],
+    currentActivity: undefined,
     lastError: undefined,
-    endedAt: T0 + 5000,
-    result: undefined,
-    error: undefined,
-    agentResult: undefined,
     ...overrides,
-  } as unknown as ExecutionRecord;
+  };
+}
+
+function makeEventLog(entries: Partial<AgentEventLogEntry>[] = []): AgentEventLogEntry[] {
+  return entries.map((e, i) => ({ type: "tool_start", label: `t-${i}`, ts: T0, ...e })) as AgentEventLogEntry[];
 }
 
 function makeNode(overrides: Partial<ExecutionTraceNode> = {}): ExecutionTraceNode {
@@ -76,6 +75,15 @@ function makeRun(shape: RunShape = {}): WorkflowRun {
   } as unknown as WorkflowRun;
 }
 
+/** 单节点 run + 该节点的 live 投影（最常见断言形态的便捷封装）。 */
+function runWithLive(nodeOverrides: Partial<ExecutionTraceNode>, live: LiveProgressView) {
+  const node = makeNode(nodeOverrides);
+  return {
+    run: makeRun({ nodes: [node] }),
+    live: new Map<number, LiveProgressView>([[node.stepIndex, live]]),
+  };
+}
+
 beforeEach(() => {
   vi.useFakeTimers();
   vi.setSystemTime(T0);
@@ -86,19 +94,19 @@ afterEach(() => {
 });
 
 describe("computeRenderSignature — 基础确定性", () => {
-  it("同输入同签名（含 live 节点，endedAt 固定使 elapsed 确定）", () => {
-    const run = makeRun({ nodes: [makeNode({ live: makeLive() })] });
-    expect(computeRenderSignature(run, T0)).toBe(computeRenderSignature(run, T0));
+  it("同输入同签名（含 live 投影，elapsedSeconds 固定值确定）", () => {
+    const { run, live } = runWithLive({}, makeLiveView());
+    expect(computeRenderSignature(run, live, T0)).toBe(computeRenderSignature(run, live, T0));
   });
 
   it("静态 run（无 live、同秒桶）200ms 内签名不变", () => {
     const run = makeRun({ nodes: [makeNode({ status: "completed" })] });
-    expect(computeRenderSignature(run, T0)).toBe(computeRenderSignature(run, T0 + 200));
+    expect(computeRenderSignature(run, new Map(), T0)).toBe(computeRenderSignature(run, new Map(), T0 + 200));
   });
 
   it("秒桶跨秒（now 相差 1s 桶）→ 签名变", () => {
     const run = makeRun();
-    expect(computeRenderSignature(run, T0)).not.toBe(computeRenderSignature(run, T0 + 1000));
+    expect(computeRenderSignature(run, new Map(), T0)).not.toBe(computeRenderSignature(run, new Map(), T0 + 1000));
   });
 });
 
@@ -106,131 +114,108 @@ describe("computeRenderSignature — run 级字段", () => {
   it("run.state.status 变化 → 签名变", () => {
     const a = makeRun({ status: "running" });
     const b = makeRun({ status: "done" });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    expect(computeRenderSignature(a, new Map(), T0)).not.toBe(computeRenderSignature(b, new Map(), T0));
   });
 
   it("completed/total 变化（节点 status 推导）→ 签名变", () => {
     const a = makeRun({ nodes: [makeNode({ status: "running" })] });
     const b = makeRun({ nodes: [makeNode({ status: "completed" })] });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    expect(computeRenderSignature(a, new Map(), T0)).not.toBe(computeRenderSignature(b, new Map(), T0));
   });
 
   it("budget tokens 量化值变化 → 签名变", () => {
     const a = makeRun({ budget: { usedTokens: 1500, maxTokens: 200_000, usedCost: 0.01 } });
     const b = makeRun({ budget: { usedTokens: 2500, maxTokens: 200_000, usedCost: 0.01 } });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    expect(computeRenderSignature(a, new Map(), T0)).not.toBe(computeRenderSignature(b, new Map(), T0));
   });
 
   it("budget cost 第 4 位小数变化（toFixed(4) 可见精度）→ 签名变", () => {
     // 0.0100 vs 0.0101：量化展示相同到第 3 位，第 4 位是渲染可见精度
     const a = makeRun({ budget: { usedTokens: 0, maxTokens: 200_000, usedCost: 0.0100 } });
     const b = makeRun({ budget: { usedTokens: 0, maxTokens: 200_000, usedCost: 0.0101 } });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    expect(computeRenderSignature(a, new Map(), T0)).not.toBe(computeRenderSignature(b, new Map(), T0));
   });
 
   it("run.state.errorLogs 追加 → 签名变（末条内容入指纹）", () => {
     const a = makeRun({ errorLogs: [{ level: "error", message: "E-0" }] });
     const b = makeRun({ errorLogs: [{ level: "error", message: "E-0" }, { level: "warn", message: "W-1" }] });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    expect(computeRenderSignature(a, new Map(), T0)).not.toBe(computeRenderSignature(b, new Map(), T0));
   });
 
   it("errorLogs 封顶后 length 不变内容移（push+slice(-MAX_ERROR_LOGS)）→ 签名仍变（指纹非 length）", () => {
     // 模拟 error-recovery 的变异路径：push 后 slice(-500) 截断。两次 state 均 500 条
     // （length 相同），仅末条/窗口内容不同——指纹含末条内容才不漏失效。
     const MAX_ERROR_LOGS = 500;
-    const mk = (n: number): WorkerLogEntry[] => ({ level: "error", message: `E-${n}` });
+    const mk = (n: number): WorkerLogEntry => ({ level: "error", message: `E-${n}` });
     const before: WorkerLogEntry[] = Array.from({ length: MAX_ERROR_LOGS }, (_, i) => mk(i));
     const after = [...before, mk(MAX_ERROR_LOGS)].slice(-MAX_ERROR_LOGS); // E-1..E-500
     expect(after).toHaveLength(MAX_ERROR_LOGS); // 前置校验：封顶后 length 不变
     const a = makeRun({ errorLogs: before });
     const b = makeRun({ errorLogs: after });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    expect(computeRenderSignature(a, new Map(), T0)).not.toBe(computeRenderSignature(b, new Map(), T0));
   });
 });
 
-describe("computeRenderSignature — 节点级字段（live 投影）", () => {
+describe("computeRenderSignature — 节点级字段（store record 投影）", () => {
   it("节点 status 变化 → 签名变", () => {
     const a = makeRun({ nodes: [makeNode({ status: "running" })] });
     const b = makeRun({ nodes: [makeNode({ status: "failed" })] });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    expect(computeRenderSignature(a, new Map(), T0)).not.toBe(computeRenderSignature(b, new Map(), T0));
   });
 
   it("live.totalTokens 变化 → 签名变", () => {
-    const a = makeRun({ nodes: [makeNode({ live: makeLive({ totalTokens: 1000 }) })] });
-    const b = makeRun({ nodes: [makeNode({ live: makeLive({ totalTokens: 2000 }) })] });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    const a = runWithLive({}, makeLiveView({ totalTokens: 1000 }));
+    const b = runWithLive({}, makeLiveView({ totalTokens: 2000 }));
+    expect(computeRenderSignature(a.run, a.live, T0)).not.toBe(computeRenderSignature(b.run, b.live, T0));
   });
 
-  it("getAllToolCalls(node.live).length 变化 → 签名变（toolCalls 追加）", () => {
-    const live1 = makeLive({
-      turns: [{ text: "", closed: false, toolCalls: [{ toolName: "read", args: {}, result: "", isError: false, _status: "completed", startedTs: T0 }] }],
-    });
-    const live2 = makeLive({
-      turns: [{ text: "", closed: false, toolCalls: [
-        { toolName: "read", args: {}, result: "", isError: false, _status: "completed", startedTs: T0 },
-        { toolName: "bash", args: {}, result: "", isError: false, _status: "completed", startedTs: T0 },
-      ] }],
-    });
-    const a = makeRun({ nodes: [makeNode({ live: live1 })] });
-    const b = makeRun({ nodes: [makeNode({ live: live2 })] });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  it("live.toolCallCount 变化（store 投影：eventLog tool_start 计数）→ 签名变", () => {
+    const a = runWithLive({}, makeLiveView({ toolCallCount: 1 }));
+    const b = runWithLive({}, makeLiveView({ toolCallCount: 2 }));
+    expect(computeRenderSignature(a.run, a.live, T0)).not.toBe(computeRenderSignature(b.run, b.live, T0));
   });
 
-  it("live.elapsedSeconds 变化 → 签名变（running 节点跨秒）", () => {
-    // endedAt undefined → computeElapsedSeconds 用真实 Date.now()；fake timers 推进 1s
-    const live = makeLive({ endedAt: undefined });
-    const run = makeRun({ nodes: [makeNode({ live })] });
-    const before = computeRenderSignature(run, T0);
-    vi.setSystemTime(T0 + 1000);
-    const after = computeRenderSignature(run, T0 + 1000);
+  it("live.elapsedSeconds 变化 → 签名变（跨秒推进）", () => {
+    const run = makeRun({ nodes: [makeNode()] });
+    const before = computeRenderSignature(run, new Map([[0, makeLiveView({ elapsedSeconds: 5 })]]), T0);
+    const after = computeRenderSignature(run, new Map([[0, makeLiveView({ elapsedSeconds: 6 })]]), T0);
     expect(after).not.toBe(before);
   });
 
   it("live.turns 计数变化 → 签名变", () => {
-    const a = makeRun({ nodes: [makeNode({ live: makeLive({ turnCount: 1 }) })] });
-    const b = makeRun({ nodes: [makeNode({ live: makeLive({ turnCount: 2 }) })] });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    const a = runWithLive({}, makeLiveView({ turns: 1 }));
+    const b = runWithLive({}, makeLiveView({ turns: 2 }));
+    expect(computeRenderSignature(a.run, a.live, T0)).not.toBe(computeRenderSignature(b.run, b.live, T0));
   });
 
-  it("live.eventLog 追加（turn 闭合产生 turn_end 条目）→ 签名变", () => {
-    const live1 = makeLive({
-      turns: [{ text: "partial", closed: false, toolCalls: [] }],
-    });
-    const live2 = makeLive({
-      turns: [{ text: "partial", closed: true, closedTs: T0, toolCalls: [] }],
-    });
-    const a = makeRun({ nodes: [makeNode({ live: live1 })] });
-    const b = makeRun({ nodes: [makeNode({ live: live2 })] });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  it("live.eventLog 追加（length 变化）→ 签名变", () => {
+    const a = runWithLive({}, makeLiveView({ eventLog: makeEventLog([{ type: "tool_start", label: "read" }]) }));
+    const b = runWithLive({}, makeLiveView({ eventLog: makeEventLog([{ type: "tool_start", label: "read" }, { type: "tool_end", label: "read" }]) }));
+    expect(computeRenderSignature(a.run, a.live, T0)).not.toBe(computeRenderSignature(b.run, b.live, T0));
   });
 
   it("live.currentActivity 出现 / 变化（type+label）→ 签名变", () => {
-    const noActivity = makeLive({ turns: [{ text: "", closed: false, toolCalls: [] }] });
-    const toolRunning = makeLive({
-      turns: [{ text: "", closed: false, toolCalls: [{ toolName: "write", args: {}, result: "", isError: false, _status: "running", startedTs: T0 }] }],
-    });
-    const toolRunningOtherLabel = makeLive({
-      turns: [{ text: "", closed: false, toolCalls: [{ toolName: "bash", args: {}, result: "", isError: false, _status: "running", startedTs: T0 }] }],
-    });
-    const base = makeRun({ nodes: [makeNode({ live: noActivity })] });
-    const withTool = makeRun({ nodes: [makeNode({ live: toolRunning })] });
-    const otherLabel = makeRun({ nodes: [makeNode({ live: toolRunningOtherLabel })] });
+    const noActivity = runWithLive({}, makeLiveView({ currentActivity: undefined }));
+    const withTool = runWithLive({}, makeLiveView({ currentActivity: { type: "tool", label: "write" } }));
+    const otherLabel = runWithLive({}, makeLiveView({ currentActivity: { type: "tool", label: "bash" } }));
 
-    const s0 = computeRenderSignature(base, T0);
-    expect(computeRenderSignature(withTool, T0)).not.toBe(s0); // 出现
-    expect(computeRenderSignature(otherLabel, T0)).not.toBe(computeRenderSignature(withTool, T0)); // label 变
+    const s0 = computeRenderSignature(noActivity.run, noActivity.live, T0);
+    const s1 = computeRenderSignature(withTool.run, withTool.live, T0);
+    const s2 = computeRenderSignature(otherLabel.run, otherLabel.live, T0);
+    expect(s1).not.toBe(s0); // 出现
+    expect(s2).not.toBe(s1); // label 变
   });
 
   it("live.lastError 出现（内容入签名）→ 签名变", () => {
-    const a = makeRun({ nodes: [makeNode({ live: makeLive({ lastError: undefined }) })] });
-    const b = makeRun({ nodes: [makeNode({ live: makeLive({ lastError: "EPIPE: broken pipe" }) })] });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    const a = runWithLive({}, makeLiveView({ lastError: undefined }));
+    const b = runWithLive({}, makeLiveView({ lastError: "EPIPE: broken pipe" }));
+    expect(computeRenderSignature(a.run, a.live, T0)).not.toBe(computeRenderSignature(b.run, b.live, T0));
   });
 
   it("node.sessionFile 出现 → 签名变", () => {
     const a = makeRun({ nodes: [makeNode({})] });
     const b = makeRun({ nodes: [makeNode({ sessionFile: "/tmp/sessions/run-0.jsonl" })] });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    expect(computeRenderSignature(a, new Map(), T0)).not.toBe(computeRenderSignature(b, new Map(), T0));
   });
 });
 
@@ -239,10 +224,11 @@ describe("computeRenderSignature — 多节点与无 live 终态", () => {
     const run = makeRun({
       nodes: [
         makeNode({ stepIndex: 0, status: "completed" }),
-        makeNode({ stepIndex: 1, status: "running", live: makeLive({ totalTokens: 500 }) }),
+        makeNode({ stepIndex: 1, status: "running" }),
       ],
     });
-    const sig = computeRenderSignature(run, T0);
+    const live = new Map([[1, makeLiveView({ totalTokens: 500 })]]);
+    const sig = computeRenderSignature(run, live, T0);
     expect(sig).toContain("0:completed:-:-1:-1:-1:-1:-1:-:-");
     expect(sig).toContain("1:running:-:500:0:5:0:0:-:-");
   });
@@ -251,14 +237,15 @@ describe("computeRenderSignature — 多节点与无 live 终态", () => {
     // 同一节点集、字段值均不变，仅 trace 数组顺序对调——nodeParts 按 trace 序拼接，
     // 首字段 stepIndex 随之换位，签名必变（不漏失效）。
     const first = makeNode({ stepIndex: 0, status: "completed" });
-    const second = makeNode({ stepIndex: 1, status: "running", live: makeLive() });
+    const second = makeNode({ stepIndex: 1, status: "running" });
+    const live = new Map([[1, makeLiveView()]]);
     const a = makeRun({ nodes: [first, second] });
     const b = makeRun({ nodes: [second, first] });
-    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+    expect(computeRenderSignature(a, live, T0)).not.toBe(computeRenderSignature(b, live, T0));
   });
 
   it("无节点 run 签名仅含 run 级五段（status/秒桶/completed-total/budget/errorLogs）", () => {
-    const sig = computeRenderSignature(makeRun({ nodes: [] }), T0);
+    const sig = computeRenderSignature(makeRun({ nodes: [] }), new Map(), T0);
     expect(sig.split("|")).toHaveLength(5);
   });
 });

package/src/interface/views/__tests__/record-progress.test.ts

@@ -0,0 +1,234 @@
+/**
+ * [H2 W3] store record live 进度投影单测（设计 D2 进度源切换）。
+ *
+ * 三组面：
+ *   1. 双路径对齐（S1 等价表依据）：同一 ExecutionRecord（同构造事件序列累积出的
+ *      turns 形态）→ 旧投影 projectLiveProgress(record) + getAllToolCalls(record).length
+ *      vs 新投影 projectRecordProgress(SubagentRecord 投影面)。逐字段断言相等
+ *      ——「数据源换 store、字段口径不变」的可证伪锁定。
+ *   2. 派生恒等：toolCallCount（eventLog tool_start 计数）=== getAllToolCalls 长度
+ *      （getEventLog 对每个 toolCall 恰产一条 tool_start）；lastError（eventLog 末条
+ *      error label）=== record.lastError（getEventLog 仅 lastError 非空时追加末条）。
+ *   3. collectNodeLiveProgress 配对：task 标签匹配 + startedAt 最近邻 + 贪心唯一；
+ *      终态 node 不配；无匹配 record（重试间隙）返回空。
+ *
+ * ExecutionRecord 经 duck-typed 构造（对齐 WorkflowsView-signature.test.ts 先例）；
+ * 新路径输入 SubagentRecord 的 eventLog/currentActivity/turns/totalTokens 取自
+ * recordToSubagent 的同源投影（getEventLog/getCurrentActivity/turnCount/totalTokens
+ * ——其投影恒等由 core 侧 record-store 测试锁定，此处消费投影面）。
+ */
+import { describe, it, expect } from "vitest";
+
+import { computeElapsedSeconds, getAllToolCalls, projectLiveProgress } from "@zhushanwen/subagent-core";
+import type { ExecutionRecord, SubagentRecord, WorkflowRun } from "@zhushanwen/subagent-core";
+import { collectNodeLiveProgress } from "../WorkflowsView.ts";
+import { projectRecordProgress } from "../detail-content.ts";
+
+// ── Fixtures ──────────────────────────────────────────────────
+
+const T0 = 1_700_000_000_000;
+
+/** duck-typed ExecutionRecord（turns 形态对齐 updateFromEvent 累积产物）。 */
+function makeRecord(overrides: Partial<ExecutionRecord> = {}): ExecutionRecord {
+  return {
+    id: "sa-x",
+    agent: "worker",
+    model: "default",
+    thinkingLevel: undefined,
+    mode: "background",
+    task: "调研 A",
+    slug: "research-a",
+    startedAt: T0,
+    rootSessionId: undefined,
+    parentRecordId: undefined,
+    depth: 0,
+    status: "running",
+    turns: [],
+    turnCount: 0,
+    totalTokens: 0,
+    lastError: undefined,
+    endedAt: undefined,
+    result: undefined,
+    error: undefined,
+    agentResult: undefined,
+    ...overrides,
+  } as unknown as ExecutionRecord;
+}
+
+/** recordToSubagent 同源投影：SubagentRecord 的实时字段面（eventLog/currentActivity
+ *  在真实链经 getEventLog/getCurrentActivity 派生，此处消费旧投影输出（同一函数产物）。 */
+function toSubagentFace(record: ExecutionRecord, oldView: ReturnType<typeof projectLiveProgress>): SubagentRecord {
+  return {
+    id: record.id,
+    agent: record.agent,
+    task: record.task,
+    slug: record.slug,
+    status: record.status,
+    mode: record.mode,
+    startedAt: record.startedAt,
+    rootSessionId: undefined,
+    parentRecordId: undefined,
+    depth: 0,
+    endedAt: record.endedAt,
+    turns: oldView.turns,
+    totalTokens: oldView.totalTokens,
+    model: record.model,
+    thinkingLevel: undefined,
+    eventLog: oldView.eventLog,
+    displayItems: [],
+    currentActivity: oldView.currentActivity,
+    result: undefined,
+    error: undefined,
+  } as SubagentRecord;
+}
+
+/** 双 turn + running tool + lastError 的复合形态（覆盖七字段全维度）。 */
+function compositeRecord(over: Partial<ExecutionRecord> = {}): ExecutionRecord {
+  return makeRecord({
+    turnCount: 2,
+    totalTokens: 12345,
+    lastError: "EPIPE: broken pipe",
+    turns: [
+      {
+        text: "turn one done",
+        thinking: "",
+        closed: true,
+        closedTs: T0 + 1000,
+        toolCalls: [
+          { toolName: "read", args: { path: "/a/b.ts" }, result: "ok", isError: false, _status: "completed", startedTs: T0 + 100 },
+          { toolName: "bash", args: { command: "ls" }, result: "out", isError: false, _status: "completed", startedTs: T0 + 300 },
+        ],
+        usageDelta: undefined,
+      },
+      {
+        text: "",
+        thinking: "planning next",
+        closed: false,
+        toolCalls: [
+          { toolName: "write", args: { path: "/c.ts" }, result: "", isError: false, _status: "running", startedTs: T0 + 2000 },
+        ],
+        usageDelta: undefined,
+      },
+    ],
+    ...over,
+  });
+}
+
+// ── 1. 双路径对齐 ─────────────────────────────────────────────
+
+describe("projectRecordProgress × projectLiveProgress 双路径对齐", () => {
+  it("复合形态（双 turn + running tool + lastError）七字段逐项相等", () => {
+    const record = compositeRecord();
+    const oldView = projectLiveProgress(record);
+    const newView = projectRecordProgress(toSubagentFace(record, oldView));
+
+    expect(newView.totalTokens).toBe(oldView.totalTokens);
+    expect(newView.toolCallCount).toBe(getAllToolCalls(record).length); // 工具计数恒等（旧路径口径）
+    expect(newView.elapsedSeconds).toBe(oldView.elapsedSeconds);
+    expect(newView.turns).toBe(oldView.turns);
+    expect(newView.eventLog).toEqual(oldView.eventLog);
+    expect(newView.currentActivity).toEqual(oldView.currentActivity);
+    expect(newView.lastError).toBe(oldView.lastError);
+  });
+
+  it("空形态（零 turn 零 token）两边同退化为零值", () => {
+    const record = makeRecord();
+    const oldView = projectLiveProgress(record);
+    const newView = projectRecordProgress(toSubagentFace(record, oldView));
+    expect(newView.totalTokens).toBe(0);
+    expect(newView.toolCallCount).toBe(0);
+    expect(newView.turns).toBe(0);
+    expect(newView.eventLog).toEqual([]);
+    expect(newView.currentActivity).toBeUndefined();
+    expect(newView.lastError).toBeUndefined();
+  });
+
+  it("elapsedSeconds 同源：endedAt 固定时两边都由 computeElapsedSeconds 现算", () => {
+    const record = compositeRecord({ endedAt: T0 + 9000 });
+    const oldView = projectLiveProgress(record);
+    const newView = projectRecordProgress(toSubagentFace(record, oldView));
+    const direct = computeElapsedSeconds({ startedAt: T0, endedAt: T0 + 9000 });
+    expect(newView.elapsedSeconds).toBe(direct);
+    expect(oldView.elapsedSeconds).toBe(direct);
+  });
+});
+
+// ── 2. 派生恒等（构造性论证的行为锁定） ────────────────────────
+
+describe("projectRecordProgress 派生恒等", () => {
+  it("toolCallCount = eventLog tool_start 计数 = getAllToolCalls 长度", () => {
+    const record = compositeRecord();
+    const oldView = projectLiveProgress(record);
+    const starts = oldView.eventLog.filter((e) => e.type === "tool_start").length;
+    expect(starts).toBe(3); // read + bash + write
+    expect(projectRecordProgress(toSubagentFace(record, oldView)).toolCallCount).toBe(getAllToolCalls(record).length);
+  });
+
+  it("lastError 从 eventLog 末条 error 派生；无 error 条目 → undefined", () => {
+    const withErr = compositeRecord();
+    const oldErr = projectLiveProgress(withErr);
+    expect(oldErr.eventLog.at(-1)?.type).toBe("error"); // 前置：getEventLog 把 lastError 追加为末条
+    expect(projectRecordProgress(toSubagentFace(withErr, oldErr)).lastError).toBe("EPIPE: broken pipe");
+
+    const noErr = compositeRecord({ lastError: undefined });
+    const oldNo = projectLiveProgress(noErr);
+    expect(oldNo.eventLog.some((e) => e.type === "error")).toBe(false);
+    expect(projectRecordProgress(toSubagentFace(noErr, oldNo)).lastError).toBeUndefined();
+  });
+});
+
+// ── 3. collectNodeLiveProgress 配对（record ↔ trace node） ─────
+
+function makeRunShape(nodes: { stepIndex: number; task: string; status: string; startedAt: string }[]): WorkflowRun {
+  return {
+    state: { trace: { toArray: () => nodes } },
+  } as unknown as WorkflowRun;
+}
+
+function makeSub(over: Partial<SubagentRecord> = {}): SubagentRecord {
+  return {
+    id: "sa-match",
+    task: "调研 A",
+    status: "running",
+    startedAt: T0,
+    turns: 0,
+    totalTokens: 0,
+    eventLog: [],
+    ...over,
+  } as SubagentRecord;
+}
+
+describe("collectNodeLiveProgress 配对", () => {
+  it("task 全等匹配：running node ↔ running record，投影挂到 stepIndex", () => {
+    const run = makeRunShape([{ stepIndex: 0, task: "调研 A", status: "running", startedAt: new Date(T0).toISOString() }]);
+    const live = collectNodeLiveProgress(run, [makeSub({ totalTokens: 42 })]);
+    expect(live.get(0)?.totalTokens).toBe(42);
+  });
+
+  it("多候选（parallel 同 prompt）取 startedAt 最近邻，贪心一一不重复消费", () => {
+    const run = makeRunShape([
+      { stepIndex: 0, task: "调研 A", status: "running", startedAt: new Date(T0).toISOString() },
+      { stepIndex: 1, task: "调研 A", status: "running", startedAt: new Date(T0 + 5000).toISOString() },
+    ]);
+    const near0 = makeSub({ id: "sa-near0", startedAt: T0 + 10, totalTokens: 100 });
+    const near1 = makeSub({ id: "sa-near1", startedAt: T0 + 5010, totalTokens: 200 });
+    const live = collectNodeLiveProgress(run, [near1, near0]);
+    expect(live.get(0)?.totalTokens).toBe(100); // node0(startedAt=T0) 最近 = near0
+    expect(live.get(1)?.totalTokens).toBe(200); // node1(T0+5s) 最近 = near1
+  });
+
+  it("终态 node 不配对；task 不匹配（不同 prompt）不配对", () => {
+    const run = makeRunShape([
+      { stepIndex: 0, task: "调研 A", status: "completed", startedAt: new Date(T0).toISOString() },
+      { stepIndex: 1, task: "写总结", status: "running", startedAt: new Date(T0).toISOString() },
+    ]);
+    const live = collectNodeLiveProgress(run, [makeSub({ task: "调研 A", totalTokens: 99 })]);
+    expect(live.size).toBe(0); // node0 终态跳过；node1 task 不匹配
+  });
+
+  it("重试间隙（无 running record）→ 空 map（views 走终态 fallback 渲染）", () => {
+    const run = makeRunShape([{ stepIndex: 0, task: "调研 A", status: "running", startedAt: new Date(T0).toISOString() }]);
+    const live = collectNodeLiveProgress(run, [makeSub({ status: "closed" })]);
+    expect(live.size).toBe(0);
+  });
+});