@zhushanwen/pi-subagent-workflow 7.4.0 → 8.0.0

package/src/orchestration/models/__tests__/trace.test.ts

@@ -0,0 +1,408 @@
+// 测试框架：vitest
+// 运行命令：npx vitest run src/orchestration/models/__tests__/trace.test.ts
+//
+// Trace 首个直接单测（W1TC1-W1TC12，.cw/swf-perf-impl/rt-w1-design.json）：
+// - W1TC1-3/9：byIndex 倒排索引一致性与 no-op 防御语义
+// - W1TC4-8：result.content 裁剪（append/update 入口、8000 边界、patch 缺省、fromArray 原样保留）
+// - W1TC10-11：集成——executeAgentCall 真链路 / jsonl save-load round-trip
+// - W1TC12：重复 stepIndex 违规语义锚定（last-wins + remove 后 desync 孤儿）
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { TRACE_RESULT_MAX_CHARS, Trace } from "../trace.js";
+import { AgentCall } from "../agent-call.js";
+import { Budget } from "../budget.js";
+import { WorkflowRun } from "../workflow-run.js";
+import type { ExecutionTraceNode, AgentResult, RunSpec } from "../types.js";
+import type { AgentRunner } from "../ports.js";
+import { executeAgentCall } from "../../execute-agent-call.js";
+import { JsonlRunStore } from "../../jsonl-run-store.js";
+
+// ── 测试辅助 ─────────────────────────────────────────────────
+
+/** 构造最小 ExecutionTraceNode（status 默认 pending，无 result）。 */
+function makeTraceNode(stepIndex: number): ExecutionTraceNode {
+  return {
+    stepIndex,
+    agent: "test-agent",
+    task: "test task",
+    model: "default",
+    status: "pending",
+  };
+}
+
+/** 构造指定长度 content 的 AgentResult（sessionId 等可选字段透传）。 */
+function makeResult(content: string, extras: Partial<AgentResult> = {}): AgentResult {
+  return { content, ...extras };
+}
+
+// ── byIndex 索引一致性 ────────────────────────────────────────
+
+describe("Trace byIndex 索引一致性", () => {
+  it("W1TC1: append/update/remove 后 find 命中且引用共享", () => {
+    const trace = new Trace();
+    const node0 = makeTraceNode(0);
+    const node1 = makeTraceNode(1);
+    const node2 = makeTraceNode(2);
+    trace.append(node0);
+    trace.append(node1);
+    trace.append(node2);
+
+    trace.update(1, { status: "completed" });
+
+    // byIndex 与 nodes 引用共享非拷贝
+    expect(trace.find(0)).toBe(node0);
+    expect(trace.find(1)).toBe(node1);
+    expect(trace.find(2)).toBe(node2);
+    // Map 值是节点引用，update 字段 mutate 可见
+    expect(trace.find(1)!.status).toBe("completed");
+
+    trace.removeByStepIndex(1);
+    expect(trace.find(1)).toBeUndefined();
+    expect(trace.length).toBe(2);
+    // 其余节点不受影响
+    expect(trace.find(0)).toBe(node0);
+    expect(trace.find(2)).toBe(node2);
+  });
+});
+
+// ── remove 后 re-append 同 stepIndex 覆盖 ─────────────────────
+
+describe("Trace remove 后 re-append 同 stepIndex", () => {
+  it("W1TC2: rebuild discard 清理后重跑重发同 callId——旧节点不再可达", () => {
+    const trace = new Trace();
+    const nodeA = makeTraceNode(0);
+    trace.append(nodeA);
+    trace.removeByStepIndex(0);
+
+    const nodeB = makeTraceNode(0);
+    trace.append(nodeB);
+
+    expect(trace.find(0)).toBe(nodeB);
+    expect(trace.toArray()).toHaveLength(1);
+    expect(trace.toArray()[0]).toBe(nodeB);
+  });
+});
+
+// ── 重复 stepIndex 违规语义锚定（W1TC12）──────────────────────
+
+describe("Trace 重复 stepIndex 违规语义锚定（W1TC12）", () => {
+  it("W1TC12: 重复 append find last-wins；重复 append 后 remove 呈 desync 孤儿", () => {
+    // ① 重复 append 同 stepIndex 且未 remove：find 返回第二个节点（Map
+    //    last-wins；旧线性扫 first-match 会返回第一个）
+    const t1 = new Trace();
+    const first = makeTraceNode(0);
+    const second = makeTraceNode(0);
+    t1.append(first);
+    t1.append(second);
+    expect(t1.find(0)).toBe(second);
+    expect(t1.length).toBe(2);
+
+    // ② 重复 append 后 removeByStepIndex：findIndex 命中首个旧节点 splice、
+    //    byIndex.delete 删掉整个键——第二个节点残留为孤儿（find 不可达但
+    //    nodes.length=1）。desync 行为锚定：防未来改回线性扫时静默漂移
+    //    （线性扫实现下 find(0) 会命中残留节点 second，本断言即失败）
+    const t2 = new Trace();
+    const a = makeTraceNode(0);
+    const b = makeTraceNode(0);
+    t2.append(a);
+    t2.append(b);
+    t2.removeByStepIndex(0);
+    expect(t2.find(0)).toBeUndefined();
+    expect(t2.length).toBe(1);
+    expect(t2.toArray()[0]).toBe(b);
+  });
+});
+
+// ── fromArray 重建 ───────────────────────────────────────────
+
+describe("Trace.fromArray 重建", () => {
+  it("W1TC3: 索引全命中 + 防御性拷贝语义保持", () => {
+    const node0 = makeTraceNode(0);
+    const node1 = makeTraceNode(1);
+    const node2 = makeTraceNode(2);
+    const src = [node0, node1, node2];
+
+    const trace = Trace.fromArray(src);
+
+    expect(trace.length).toBe(3);
+    // fromArray push {...node} 副本——find(i) 与 toArray()[i] 同引用（byIndex 命中副本）
+    for (let i = 0; i < 3; i++) {
+      expect(trace.find(i)).toBe(trace.toArray()[i]);
+    }
+
+    // 传入数组后续 mutate 不影响 trace（浅拷贝语义保持）
+    src.push(makeTraceNode(3));
+    expect(trace.length).toBe(3);
+    src[0]!.status = "failed";
+    expect(trace.find(0)!.status).toBe("pending");
+  });
+});
+
+// ── append 入口裁剪 ──────────────────────────────────────────
+
+describe("Trace append 入口超长 result 裁剪", () => {
+  it("W1TC4: 标记含原始长度，节点引用不变，其余字段浅拷贝保留", () => {
+    const content = "x".repeat(10000);
+    const node = {
+      ...makeTraceNode(0),
+      result: makeResult(content, { sessionId: "s1", parsedOutput: { a: 1 } }),
+    };
+
+    const trace = new Trace();
+    trace.append(node);
+
+    const stored = trace.toArray()[0]!;
+    // 节点对象引用不变（mutate result 字段，不 push 副本——D-10 traceNode 引用共享）
+    expect(stored).toBe(node);
+
+    const marker = `\n…[trace result truncated, original 10000 chars]…\n`;
+    expect(stored.result!.content).toBe(content.slice(0, 4000) + marker + content.slice(-4000));
+    // 头尾与标记子串
+    expect(stored.result!.content.startsWith(content.slice(0, 4000))).toBe(true);
+    expect(stored.result!.content.endsWith(content.slice(-4000))).toBe(true);
+    expect(stored.result!.content).toContain("[trace result truncated, original 10000 chars]");
+    // result 其余字段浅拷贝保留
+    expect(stored.result!.sessionId).toBe("s1");
+    expect(stored.result!.parsedOutput).toEqual({ a: 1 });
+  });
+});
+
+// ── update 入口裁剪 ──────────────────────────────────────────
+
+describe("Trace update patch.result 超长裁剪", () => {
+  it("W1TC5: 节点持裁剪副本，patch 原对象不被污染（call.result 保真）", () => {
+    const trace = new Trace();
+    trace.append(makeTraceNode(0));
+
+    const full = makeResult("y".repeat(9000), { sessionId: "s1" });
+    trace.update(0, { result: full });
+
+    const stored = trace.find(0)!.result!;
+    const marker = `\n…[trace result truncated, original 9000 chars]…\n`;
+    expect(stored.content.length).toBe(4000 + marker.length + 4000);
+    expect(stored.content).toContain("original 9000 chars");
+    // 节点持裁剪副本新对象，与 patch.result 脱钩
+    expect(stored).not.toBe(full);
+    // 浅拷贝保留其他字段
+    expect(stored.sessionId).toBe("s1");
+    // AgentCall.result 保真——原对象不被污染（replay 数据源）
+    expect(full.content).toHaveLength(9000);
+  });
+});
+
+// ── 边界：恰好 8000 不裁 / 8001 裁 ────────────────────────────
+
+describe("Trace 裁剪边界（严格大于 TRACE_RESULT_MAX_CHARS）", () => {
+  it("W1TC6: 恰好 8000 引用透传零拷贝；8001 触发裁剪", () => {
+    const trace = new Trace();
+    trace.append(makeTraceNode(0));
+    trace.append(makeTraceNode(1));
+
+    // 恰好 8000：不裁
+    const exact = makeResult("a".repeat(TRACE_RESULT_MAX_CHARS));
+    trace.update(0, { result: exact });
+    expect(trace.find(0)!.result).toBe(exact);
+    expect(trace.find(0)!.result!.content).toHaveLength(8000);
+    expect(trace.find(0)!.result!.content).not.toContain("truncated");
+
+    // 8001：裁剪（head/tail 固定 4000 比例，重叠段属预期）
+    const over = makeResult("b".repeat(TRACE_RESULT_MAX_CHARS + 1));
+    trace.update(1, { result: over });
+    expect(trace.find(1)!.result!.content).toContain("original 8001 chars");
+    expect(trace.find(1)!.result!.content).not.toBe(over.content);
+  });
+});
+
+// ── patch.result 未提供不触发裁剪 ────────────────────────────
+
+describe("Trace update patch.result 缺省", () => {
+  it("W1TC7: 只改 status/completedAt 等字段——已持 result 不被触碰", () => {
+    const origResult = makeResult("keep");
+    const node = { ...makeTraceNode(0), result: origResult };
+    const trace = new Trace();
+    trace.append(node);
+
+    trace.update(0, { status: "completed", completedAt: "2026-08-15T00:00:00Z" });
+    expect(trace.find(0)!.result!.content).toBe("keep");
+    expect(trace.find(0)!.result).toBe(origResult);
+
+    // 其他字段路径同样不影响 result
+    trace.update(0, { sessionId: "s9" });
+    expect(trace.find(0)!.result).toBe(origResult);
+  });
+});
+
+// ── fromArray 原样保留（read 路径不二次裁剪）──────────────────
+
+describe("Trace.fromArray 原样保留", () => {
+  it("W1TC8: 超长 content 不被二次裁剪；已含标记的形态逐字节不变", () => {
+    // 旧版本未裁剪的快照重水合：20000 字符全长保留
+    const long = {
+      ...makeTraceNode(0),
+      result: makeResult("z".repeat(20000)),
+    };
+    const trace = Trace.fromArray([long]);
+    expect(trace.find(0)!.result!.content).toHaveLength(20000);
+    expect(trace.find(0)!.result!.content).not.toContain("truncated");
+
+    // 新快照 round-trip：已裁剪含标记的 content 经 fromArray 后逐字节不变（无标记嵌套）
+    const marker = `\n…[trace result truncated, original 10000 chars]…\n`;
+    const trimmed = "x".repeat(4000) + marker + "x".repeat(4000);
+    const trace2 = Trace.fromArray([{ ...makeTraceNode(0), result: makeResult(trimmed) }]);
+    expect(trace2.find(0)!.result!.content).toBe(trimmed);
+  });
+});
+
+// ── no-op 防御语义回归 ───────────────────────────────────────
+
+describe("Trace no-op 防御语义", () => {
+  it("W1TC9: update/remove 不存在的 stepIndex 不抛错、状态不变", () => {
+    const trace = new Trace();
+    trace.append(makeTraceNode(0));
+
+    expect(() => trace.update(999, { status: "completed" })).not.toThrow();
+    expect(() => trace.removeByStepIndex(999)).not.toThrow();
+    expect(trace.length).toBe(1);
+    expect(trace.find(999)).toBeUndefined();
+  });
+});
+
+// ── 集成：executeAgentCall 真链路（W1TC10）────────────────────
+
+describe("W1TC10: executeAgentCall 真链路——call.result 全量、trace 节点持裁剪副本", () => {
+  it("W1TC10: runner.run 返回 12000 字符 → 两形态并存（AgentCall.result 不裁）", async () => {
+    const content = "w".repeat(12000);
+    const runner: AgentRunner = {
+      run: vi.fn().mockResolvedValue(makeResult(content, { sessionId: "s1" })),
+    };
+
+    const trace = new Trace();
+    const traceNode = makeTraceNode(0);
+    trace.append(traceNode);
+    const call = new AgentCall(0, { prompt: "test task", agent: "worker" }, traceNode);
+
+    await executeAgentCall(call, runner, new Budget(), new AbortController().signal, trace);
+
+    // AgentCall.result 全量（worker cached replay 数据源保真）
+    expect(call.result!.content).toHaveLength(12000);
+    // trace 节点持裁剪副本
+    const stored = trace.find(0)!.result!;
+    const marker = `\n…[trace result truncated, original 12000 chars]…\n`;
+    expect(stored.content).toBe(content.slice(0, 4000) + marker + content.slice(-4000));
+    expect(stored.content.length).toBe(4000 + marker.length + 4000);
+    expect(stored.sessionId).toBe("s1");
+    expect(trace.find(0)!.status).toBe("completed");
+  });
+});
+
+// ── 集成：jsonl save/load round-trip（W1TC11）─────────────────
+
+describe("W1TC11: jsonl save/load round-trip——落盘裁剪形态 + 重水合不二次裁", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-trace-trim-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function makeSpec(): RunSpec {
+    return {
+      scriptSource: "module.exports = async () => {};",
+      args: {},
+      scriptName: "test-script",
+      scriptPath: "/tmp/test.js",
+      description: "test",
+    };
+  }
+
+  /** 构造含 10000 字符 result 已完成 call 的 WorkflowRun（模式对齐 jsonl-run-store-session-file.test.ts）。 */
+  function makeRunWithDoneCall(): WorkflowRun {
+    const trace = new Trace();
+    const node = makeTraceNode(0);
+    trace.append(node);
+    const call = new AgentCall(0, { prompt: "task", agent: "worker" }, node);
+    call.markRunning();
+    // markDone 存全量 result（AgentCall.result 不裁）
+    call.markDone(makeResult("q".repeat(10000), { sessionId: "session-abc" }));
+    call.setSessionId("session-abc");
+    // trace.update 经入口裁剪——节点持裁剪副本
+    trace.update(0, {
+      status: "completed",
+      result: call.result,
+      completedAt: new Date().toISOString(),
+      sessionId: "session-abc",
+    });
+
+    return new WorkflowRun(
+      "run-trim-001",
+      makeSpec(),
+      {
+        status: "done",
+        reason: "completed",
+        budget: new Budget(),
+        calls: new Map([[0, call]]),
+        trace,
+        errorLogs: [],
+      },
+      { startedAt: new Date().toISOString(), completedAt: new Date().toISOString() },
+    );
+  }
+
+  it("W1TC11: save 落盘 trace 裁剪 + calls[].result 全量；loadAll 回读逐字节一致", async () => {
+    const entries: Array<{ type: string; customType?: string; data?: unknown }> = [];
+    const mockPi = {
+      appendEntry: vi.fn((type: string, data: unknown) => {
+        entries.push({ type: "custom", customType: type, data });
+      }),
+    };
+    const mockCtx = {
+      sessionManager: { getEntries: () => entries },
+    };
+    const store = new JsonlRunStore({
+      sessionDir: tmpDir,
+      pi: mockPi as never,
+      ctx: mockCtx as never,
+    });
+
+    const run = makeRunWithDoneCall();
+    await store.save(run);
+
+    // 读磁盘快照验证落盘形态
+    const raw = fs.readFileSync(
+      path.join(tmpDir, "workflow-state", "run-trim-001.jsonl"),
+      "utf8",
+    );
+    const snapshot = JSON.parse(raw.trim()) as {
+      state: {
+        trace: Array<{ result?: { content: string } }>;
+        calls: Array<{ result?: { content: string }; traceNode: { result?: { content: string } } }>;
+      };
+    };
+
+    // trace 投影瘦身生效：trace[0] 含标记
+    expect(snapshot.state.trace[0]!.result!.content).toContain(
+      "[trace result truncated, original 10000 chars]",
+    );
+    // calls[].traceNode 是同一裁剪后节点引用（剥 live 后的 rest），亦含标记
+    expect(snapshot.state.calls[0]!.traceNode.result!.content).toContain(
+      "[trace result truncated, original 10000 chars]",
+    );
+    // 顶层 calls[].result 字段不裁——全量 10000
+    expect(snapshot.state.calls[0]!.result!.content).toHaveLength(10000);
+
+    // loadAll 回读：fromArray 不再裁，与落盘形态逐字节一致（无标记嵌套）
+    const loaded = await store.loadAll();
+    expect(loaded).toHaveLength(1);
+    const restoredContent = loaded[0]!.state.trace.toArray()[0]!.result!.content;
+    expect(restoredContent).toBe(snapshot.state.trace[0]!.result!.content);
+    expect(restoredContent.match(/truncated/g)).toHaveLength(1);
+  });
+});

package/src/orchestration/models/budget.ts

@@ -100,7 +100,7 @@ export class Budget {
  * maxTokens===0 或 undefined 视为不限制（守卫）；
  * maxCost===0 或 undefined 视为不限制。
  * 时间预算（maxTimeMs）不由本方法判断——它是 wall-clock 约束，需参照 startedAt，
- * 由 lifecycle 层的 scheduleTimeBudget（runWorkflow/resumeRun 内 setTimeout）
+ * 由 lifecycle 层的 scheduleTimeBudget（runWorkflow 内 setTimeout）
  * 独立调度，到期 abortRun(doneReason="time_limited")。
  */
   isExceeded(): boolean {

package/src/orchestration/models/run-runtime.ts

@@ -7,12 +7,10 @@
  * 职责：封装一次 running-segment 的所有技术资源（worker 线程 + 并发信号量 +
  * abort controller），统一 release 入口（AC-2：单 release 替代多 boolean flag）。
  *
- * pause/resume 生命周期（G3-001）：
- * - pause 时 WorkflowRun.releaseRuntime 使整个 RunRuntime 丢弃（runtime=undefined）
- * - resume 时 WorkflowRun.assignRuntime(new RunRuntime(...)) 全部重建
- * - 原因：AbortController 一次性语义决定 controller 无法跨 pause/resume 复用，
- * gate 队列也在 worker 重跑脚本 + callCache replay 时清空无影响——所以整个
- * RunRuntime 重建最简单、语义最清晰。
+ * 一次性生命周期（G3-001）：runtime 释放后不再复用——AbortController 一次性
+ * 语义决定 controller 无法跨释放复用，gate 队列也在 worker 重跑脚本 +
+ * callCache replay 时清空无影响，所以整个 RunRuntime 重建。唯一注入路径：
+ * assignRuntime（runWorkflow 创建）与 replaceRuntime（error-recovery 崩溃重试）。
  *
  * 参考：domain-models.md §10、clarification.md G3-001。
  */
@@ -23,11 +21,11 @@ import { WorkerHandle } from "../worker-handle.ts";
 /**
  * release mode 枚举——调用方表达意图。
  *
- * 注：pause 与 terminal 在 RunRuntime 内部行为等价（都全释放 worker + controller）。
- * 保留枚举为可读性——调用方语义清晰（lifecycle pauseRun 传 "pause"，
- * terminateRun 传 "terminal"），且为未来细分留余地。
+ * 一次性生命周期后唯一语义：terminal（终局释放，worker + controller 全释放，
+ * runtime 即被调用方丢弃）。原 "pause" 值已随 pause/resume 生命周期删除（F8）
+ * ——release 后不存在「保留待恢复」的中间形态。
  */
-export type ReleaseMode = "pause" | "terminal";
+export type ReleaseMode = "terminal";
 
 // ── RunRuntime ───────────────────────────────────────────────
 
@@ -39,8 +37,8 @@ export class RunRuntime {
  /** per-running-segment AbortController（一次性，无法复用——G3-001）。 */
   readonly controller: AbortController;
  /** Run 级墙钟时间预算计时器（spec.budgetTimeMs > 0 时由 lifecycle 调度，
-   * 到期 abortRun time_limited）。release 时清理，避免 pause/abort 后孤儿计时器
-   * 仍触发（resume 会重新调度一个全新的计时器，旧的不应残留）。 */
+   * 到期 abortRun time_limited）。release 时清理，避免 abort/replaceRuntime
+   * 后孤儿计时器仍触发（rebuildRuntime 会重排一个全新的计时器，旧的不应残留）。 */
   readonly timeBudgetTimer?: ReturnType<typeof setTimeout>;
  /** 防止 release 重复执行（幂等）。 */
   private released = false;
@@ -62,24 +60,24 @@ export class RunRuntime {
  *
  * 幂等——重复调用安全（第二次起 no-op，released flag 守卫）。
  * 调用后此 RunRuntime 应被调用方丢弃（WorkflowRun.runtime = undefined），
- * resume/retry 时由 assignRuntime/replaceRuntime 注入新实例（G3-001）。
+ * 崩溃重试时由 replaceRuntime 注入新实例（G3-001）。
  *
  * worker.terminate 本身幂等，controller.abort 本身幂等
  * （重复 abort 无副作用），但 released flag 让本方法语义更明确：
  * 「释放过一次的 runtime 不再释放第二次」。
  *
- * @param mode pause | terminal —— 当前等价，保留为调用方表达意图
+ * @param mode terminal —— 终局释放（唯一值，保留参数为调用方语义显式化）
  */
   release(_mode: ReleaseMode): void {
     if (this.released) return;
     this.released = true;
- // 清理 run 级时间预算计时器——pause/abort/replaceRuntime 后它不应再触发
- // （resume 会调度全新计时器；孤儿触发会把已 paused/aborted 的 run 误转 done）。
+ // 清理 run 级时间预算计时器——abort/terminate/replaceRuntime 后它不应再触发
+ // （rebuildRuntime 会重排全新计时器；孤儿触发会把已终态的 run 误转 done）。
     if (this.timeBudgetTimer) clearTimeout(this.timeBudgetTimer);
  // worker.terminate 异步但幂等——不 await（release 是同步签名，调用方
  // 不应被底层线程关闭阻塞；worker 收到 terminate 后自行清理）。
     void this.worker.terminate();
- // controller.abort 触发 listener（kill agent subprocess、pause workflow）。
+ // controller.abort 触发 listener（kill agent subprocess、中止在飞调用）。
  // 一次性语义——已 aborted 的 controller 重复 abort 无副作用。
     this.controller.abort();
   }

package/src/orchestration/models/run-spec.ts

@@ -18,7 +18,7 @@ import type { Budget } from "./budget.ts";
 /**
  * RunSpec——一次 workflow run 的不可变输入规格。
  *
- * 作为 RunStore 持久化的一部分（WorkflowRun.spec），跨 session pause/resume 时
+ * 作为 RunStore 持久化的一部分（WorkflowRun.spec），崩溃恢复重水合后
  * 需要 scriptSource/args 重建 worker（G3-001）。
  */
 export interface RunSpec {
@@ -30,7 +30,7 @@ export interface RunSpec {
  * undefined = 不校验（安全退化——漏拷 parameters 退化是「不校验」非「校验错」）。
  * 由调用方（actionRun/runAndWait/executeNestedWorkflow）从 script.meta.parameters 拷贝。
  * lifecycle.runWorkflow 首行经 validateRunArgs 校验 spec.args（coerceTypes 原地规范化
- * args 对象内容，字段引用不变；worker 启动与 pause/resume 重建共用同一对象）。
+ * args 对象内容，字段引用不变；worker 启动与崩溃重建共用同一对象）。
  */
   readonly parameters?: Record<string, unknown>;
   /** 调用方传入的参数（worker 内通过 $ARGS 访问）。 */

package/src/orchestration/models/run-state.ts

@@ -22,16 +22,16 @@ import type { DoneReason, RunStatus, WorkerLogEntry } from "./types.ts";
  * RunState——一次 run 的可持久化执行状态。
  *
  * 持久化由 RunStore.save(WorkflowRun) 触发（WorkflowRun 持 RunState）。
- * 跨 session pause/resume 时，RunState 从 JSONL 重水合（callCache 保留，worker 重建）。
+ * 跨进程重启时 RunState 从 JSONL 重水合（callCache 保留，worker 由崩溃恢复重建）。
  */
 export interface RunState {
- /** 当前状态（running/paused/done）。 */
+ /** 当前状态（running/done）。 */
   status: RunStatus;
  /** 终态原因（done 时必有）。 */
   reason?: DoneReason;
  /** Token/cost 预算（含 usedTokens/usedCost 累积）。 */
   budget: Budget;
- /** 按 callId 索引的 agent 调用集合（含 result，跨 pause/resume 存活）。 */
+ /** 按 callId 索引的 agent 调用集合（含 result，跨 runtime 重建存活——callCache replay）。 */
   calls: Map<number, AgentCall>;
  /** 执行追踪事件流（唯一来源 D-10）。 */
   trace: Trace;