@zhushanwen/subagent-core 0.8.0 → 0.9.0

package/src/orchestration/__tests__/worker-message-pump-workflow-dispatch.test.ts

@@ -0,0 +1,274 @@
+// src/orchestration/__tests__/worker-message-pump-workflow-dispatch.test.ts
+//
+// [H2 W3] pump 切换 executeWorkflowAgent 端到端单测（设计
+// subagent-workflow-record-unification.md §3.5 终态数据流 / §5 W3）。
+//
+// 真实链路形态：handleWorkerMessage(agent-call) → dispatchAgentCall →
+// deps.workflowAgentDispatch（SubagentService.executeWorkflowAgent 注入形态）→
+// fake pi EnginePort（协议 seam 替身，与 W2 workflow-agent-dispatch.test 同源）。
+//
+// 锁四组面：
+//   1. record 进 store：dispatch 在途时 record 带 origin:"workflow" +
+//      parentRunId=run.runId（真实 record 经 store 治理面可见——进度源切换的
+//      数据前提）；record 级 pending:register 照旧发射。
+//   2. worker 协议回包不变：引擎应答 → executeAgentCall finalize →
+//      postMessage({type:"agent-result", callId, result})（cached:false）；
+//      trace node 终态摘要保真（node.result 来自 executeWorkflowAgent 的
+//      AgentResult 出口，D2「node 保留 result」）。
+//   3. 成功即终态化（D7 联动回归）：settle 后 record closed/gc + record 级
+//      pending:unregister（archive 出内存，run 视图经磁盘面回查终态）。
+//   4. 注入面回退：未注入 workflowAgentDispatch（旧测试 deps）→ deps.runner.run
+//      被调（SAR 旧编排路径，W4 归位；两路互不串扰）。
+//
+// 替身形态与测试红线对齐 W2 workflow-agent-dispatch.test.ts：XYZ_AGENT_DATA_DIR
+// 指 tmpdir（不触真实数据目录）；logger mock 防噪声。
+
+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";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+import { Budget } from "../models/budget.ts";
+import { RunRuntime } from "../models/run-runtime.ts";
+import { Trace } from "../models/trace.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
+import type { AgentCallOpts } from "../models/types.ts";
+import type { WorkerHandle } from "../worker-handle.ts";
+import { handleWorkerMessage } from "../worker-message-pump.ts";
+import { ModelConfigService } from "../../execution/model-config-service.ts";
+import type { ModelInfo, ModelRegistryLike } from "../../execution/model-resolver.ts";
+import type { RecordStore } from "../../execution/record-store.ts";
+import { SubagentService } from "../../execution/subagent-service.ts";
+import type { PiLike } from "../../execution/subagent-service.ts";
+import { clearEngines } from "../../execution/engine/registry.ts";
+import { registerFakePiEngine, type FakePiEnginePort } from "../../execution/__tests__/helpers/fake-engine-port.ts";
+
+// ── harness ──────────────────────────────────────────────────
+
+function makeEmptyRegistry(): ModelRegistryLike {
+  return { getAvailable: () => [], find: () => undefined, hasConfiguredAuth: () => true };
+}
+
+const ctxModel: ModelInfo = { id: "m", name: "M", provider: "p", reasoning: false };
+
+interface PumpHarness {
+  service: SubagentService;
+  store: RecordStore;
+  pi: { appendEntry: ReturnType<typeof vi.fn>; events: { emit: ReturnType<typeof vi.fn> }; sendMessage: ReturnType<typeof vi.fn> };
+  fake: FakePiEnginePort;
+  run: WorkflowRun;
+  postMessage: ReturnType<typeof vi.fn>;
+  deps: LifecycleDeps;
+  tmpRoot: string;
+}
+
+function makePumpHarness(runId: string): PumpHarness {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "wf-pump-it-"));
+  process.env.XYZ_AGENT_DATA_DIR = path.join(tmpRoot, "engine-data");
+  const agentDir = path.join(tmpRoot, "agent");
+  const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
+  modelService.initModel({ modelRegistry: makeEmptyRegistry(), sessionId: "wf-pump-it", ctxModel });
+  const service = new SubagentService({ cwd: agentDir, modelService });
+  const pi = {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  };
+  service.initSession({ pi: pi as unknown as PiLike, sessionId: "wf-pump-it" });
+  clearEngines();
+  const fake = registerFakePiEngine();
+
+  const run = new WorkflowRun(
+    runId,
+    { scriptName: "test-wf", scriptSource: "agent('调研 A')", args: {}, scriptPath: "/tmp/test.js" },
+    { status: "running", budget: new Budget({ maxTokens: 100_000 }), calls: new Map(), trace: new Trace(), errorLogs: [] },
+    { startedAt: new Date().toISOString() },
+  );
+  const postMessage = vi.fn();
+  const initialWorker = { postMessage, terminate: vi.fn(async () => {}) } as unknown as WorkerHandle;
+  run.assignRuntime(new RunRuntime(initialWorker, new AbortController()));
+
+  // 组合根注入形态（extension index.ts makeDeps 的等价内联）：dispatch 闭包捕获
+  // service 单例，parentRunId 由 pump 侧补 run.runId。
+  const deps = {
+    store: { save: vi.fn(async () => {}) },
+    workerHost: { start: vi.fn() },
+    runner: { run: vi.fn(async () => ({ content: "legacy-runner", durationMs: 1, error: undefined, toolCalls: [] })) },
+    runs: new Map([[runId, run]]),
+    eventBus: { emit: vi.fn() },
+    log: vi.fn(),
+    workflowAgentDispatch: (opts: AgentCallOpts, parentRunId: string, signal?: AbortSignal) =>
+      service.executeWorkflowAgent(opts, parentRunId, signal),
+  } as unknown as LifecycleDeps;
+  return { service, store: Reflect.get(service, "store") as RecordStore, pi, fake, run, postMessage, deps, tmpRoot };
+}
+
+function makeHandlers(): WorkerHandlers {
+  return {
+    onMessage: vi.fn(async () => {}),
+    onError: vi.fn(async () => {}),
+    onExit: vi.fn(async () => {}),
+  } as unknown as WorkerHandlers;
+}
+
+/** 微任务冲刷（dispatch → 路由 → record 注册 → acquire → engine.run 链）。 */
+async function flush(times = 8): Promise<void> {
+  for (let i = 0; i < times; i++) {
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  }
+}
+
+function findAgentResultPost(postMessage: ReturnType<typeof vi.fn>, callId: number) {
+  return postMessage.mock.calls
+    .map((c) => c[0] as { type?: string; callId?: number; result?: { content?: string; error?: string }; cached?: boolean })
+    .find((m) => m.type === "agent-result" && m.callId === callId);
+}
+
+let prevDataDirEnv: string | undefined;
+
+beforeEach(() => {
+  prevDataDirEnv = process.env["XYZ_AGENT_DATA_DIR"];
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  if (prevDataDirEnv === undefined) delete process.env["XYZ_AGENT_DATA_DIR"];
+  else process.env["XYZ_AGENT_DATA_DIR"] = prevDataDirEnv;
+});
+
+// ── 1+2+3：注入 dispatch 的端到端主路径 ───────────────────────
+
+describe("pump → executeWorkflowAgent 端到端", () => {
+  it("record 进 store（origin=workflow + parentRunId）→ settle → 回包/终态摘要/D7 终态化全链", async () => {
+    const h = makePumpHarness("wf-pump-e2e-1");
+    await handleWorkerMessage(
+      h.run,
+      { type: "agent-call", callId: 1, opts: { prompt: "调研 A", description: "research-a" } },
+      h.deps,
+      makeHandlers(),
+    );
+    await flush();
+
+    // 1. dispatch 在途：真实 record 在 store（origin/parentRunId——views store 订阅的数据
+    //    前提）。经 views 同款查询面（queries.collectRecordsByParentRunId）断言命中，
+    //    再经 getMutable 拿真 record 验 originFields（listRunning 是 RecordSnapshot
+    //    轻投影，无 origin 字段——勿用）。
+    const found = h.service.queries.collectRecordsByParentRunId("wf-pump-e2e-1", 100);
+    expect(found).toHaveLength(1);
+    expect(found[0]!.origin).toBe("workflow");
+    expect(found[0]!.parentRunId).toBe("wf-pump-e2e-1");
+    expect(found[0]!.status).toBe("running");
+    const record = h.store.getMutable(found[0]!.id)!;
+    expect(record.origin).toBe("workflow");
+    expect(record.parentRunId).toBe("wf-pump-e2e-1");
+    // 引擎收到 run（taskId = record.id——守护/journal 键，W2 已锁定）
+    expect(h.fake.runs).toHaveLength(1);
+    // record 级 pending:register 照旧（D5：record 域发射面不动）
+    const registered = h.pi.events.emit.mock.calls.find((c) => c[0] === "pending:register");
+    expect(registered?.[1]).toMatchObject({ id: record.id, type: "subagent" });
+
+    // 2. 引擎应答 → worker 协议回包 + trace node 终态摘要
+    //    （settle 后链路含 journal.close 的真 fs await，用 waitFor 收敛）
+    h.fake.runs[0]!.settle({ content: "ok", sessionId: "sess-1", sessionFile: "/tmp/sess-1.jsonl", durationMs: 5 });
+    await vi.waitFor(() => {
+      expect(findAgentResultPost(h.postMessage, 1)).toBeDefined();
+    });
+
+    const posted = findAgentResultPost(h.postMessage, 1);
+    expect(posted).toBeDefined();
+    expect(posted!.cached).toBe(false);
+    expect(posted!.result!.content).toBe("ok");
+    expect(posted!.result!.error).toBeUndefined();
+    // node 终态摘要（D2：live 删除后 node 保留 result——数据源 = executeWorkflowAgent
+    // 的 AgentResult 出口，经 executeAgentCall finalizeCall 写入）
+    const node = h.run.state.trace.find(1);
+    expect(node?.status).toBe("completed");
+    expect(node?.result?.content).toBe("ok");
+    expect(node?.result?.sessionFile).toBe("/tmp/sess-1.jsonl");
+    expect(node?.completedAt).toBeDefined();
+    expect(h.run.state.calls.get(1)?.status).toBe("done");
+
+    // 3. D7 联动：成功即终态化（closed/gc + archive 出内存）+ record 级 unregister。
+    //    （archive 后从磁盘重建面回查终态的「run 视图不丢行」行为由 W1 record-store
+    //    的 mergedRecords 测试锁定——本 harness 的 pi mock 不落盘，不在此重复。）
+    expect(h.store.listRunning()).toHaveLength(0);
+    const unregistered = h.pi.events.emit.mock.calls.find((c) => c[0] === "pending:unregister");
+    expect(unregistered?.[1]).toMatchObject({ id: record.id });
+
+    // 4. run 级 pending 配对不回归（D5：lifecycle↔pump 的 run 级注册/注销对零改动
+    //    ——lifecycle.ts 零 diff 由 git 自查；此处锁 pump 侧 run 终态注销行为）：
+    //    脚本 return → finalizeRun emit pending:unregister with id=runId。
+    await handleWorkerMessage(h.run, { type: "return", result: "done" }, h.deps, makeHandlers());
+    const runUnregister = h.deps.eventBus!.emit as ReturnType<typeof vi.fn>;
+    const runUnregCall = runUnregister.mock.calls.find((c) => c[0] === "pending:unregister");
+    expect(runUnregCall?.[1]).toMatchObject({ id: "wf-pump-e2e-1" });
+    expect(h.run.state.status).toBe("done");
+  });
+
+  it("失败结果：引擎 error outcome → 回包 error + trace failed 终态摘要", async () => {
+    const h = makePumpHarness("wf-pump-e2e-2");
+    await handleWorkerMessage(
+      h.run,
+      { type: "agent-call", callId: 2, opts: { prompt: "调研 B", description: "research-b" } },
+      h.deps,
+      makeHandlers(),
+    );
+    await flush();
+    expect(h.fake.runs).toHaveLength(1);
+
+    // 失败结果带巨额 usage 打爆 run 预算（Budget maxTokens=100k）——executeAgentCall
+    // 的「预算超限不重试」分支直接 finalize（否则 error 结果走 1s/2s 退避重试，
+    // 测试需 fake timers 推进；重试语义已由 execute-agent-call.test.ts 锁定，此处
+    // 聚焦 pump 切换后的回包/终态摘要）。
+    h.fake.runs[0]!.settle({ content: "", error: "engine blew up", durationMs: 3, usage: { input: 1_000_000, output: 1, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 1 } });
+    await vi.waitFor(() => {
+      expect(findAgentResultPost(h.postMessage, 2)).toBeDefined();
+    });
+
+    const posted = findAgentResultPost(h.postMessage, 2);
+    expect(posted).toBeDefined();
+    expect(posted!.result!.error).toBe("engine blew up");
+    const node = h.run.state.trace.find(2);
+    expect(node?.status).toBe("failed");
+    expect(node?.result?.error).toBe("engine blew up");
+    expect(h.run.state.calls.get(2)?.status).toBe("done");
+  });
+});
+
+// ── 4：注入面回退（旧 deps 不注入 dispatch） ──────────────────
+
+describe("workflowAgentDispatch 未注入回退", () => {
+  it("旧 deps（仅 runner）→ deps.runner.run 被调（[H2 W4] SAR.run 已掏空为纯转调 executeWorkflowAgent，两分支执行体归一；生产恒注入 dispatch 本分支不可达，仅为旧测试 deps 形态兼容）", async () => {
+    const run = new WorkflowRun(
+      "wf-pump-fallback-1",
+      { scriptName: "test-wf", scriptSource: "agent('hi')", args: {}, scriptPath: "/tmp/test.js" },
+      { status: "running", budget: new Budget(), calls: new Map(), trace: new Trace(), errorLogs: [] },
+      { startedAt: new Date().toISOString() },
+    );
+    const runnerRun = vi.fn(async () => ({ content: "legacy", durationMs: 1, error: undefined, toolCalls: [] }));
+    const postMessage = vi.fn();
+    const deps = {
+      store: { save: vi.fn(async () => {}) },
+      workerHost: { start: vi.fn() },
+      runner: { run: runnerRun },
+      runs: new Map(),
+      eventBus: { emit: vi.fn() },
+      log: vi.fn(),
+    } as unknown as LifecycleDeps;
+    run.assignRuntime(new RunRuntime({ postMessage, terminate: vi.fn(async () => {}) } as unknown as WorkerHandle, new AbortController()));
+
+    await handleWorkerMessage(run, { type: "agent-call", callId: 7, opts: { prompt: "p" } }, deps, makeHandlers());
+    await flush();
+
+    expect(runnerRun).toHaveBeenCalledTimes(1);
+    const posted = findAgentResultPost(postMessage, 7);
+    expect(posted?.result?.content).toBe("legacy");
+  });
+});

package/src/orchestration/execute-agent-call.ts

@@ -127,7 +127,7 @@ function delay(ms: number): Promise<void> {
  * @param budget Budget 值对象（consume + isExceeded 检查）
  * @param signal AbortSignal（runner.run 传播；abort 后不重试）
  * @param trace Trace 值对象（finalizeCall 时 update）
- * @param onEvent 实时事件回调（live record 更新用）
+ * @param onEvent 透传 service 派发路径（journal 转发 + 守护刷新源）
  * @param stream streaming sink（透传 runner.run）
  * @param isOrphaned 孤儿判定谓词（OB2，可选，默认恒 false）：true 时 finalizeCall
  *   跳过 trace.update（判定语义与正确性论证见 finalizeCall 文档注释）。递归重试

package/src/orchestration/file-run-store.ts

@@ -240,7 +240,7 @@ export class FileRunStore implements RunStore {
     // mkdir recursive 每次 save 前执行：幂等零成本（目录已存在时仅一次 stat），
     // 且免「构造时预建」——构造时建会在宿主尚未 configureCore 的窗口抛错。
     await mkdir(this.stateDir(), { recursive: true });
-    // toRunSnapshot 补 v 字段（D4 裁决②写入侧）+ strip live 落盘
+    // toRunSnapshot 补 v 字段（D4 裁决②写入侧）；live strip 已随 [H2 W3] live 字段删除退役
     const line = JSON.stringify(toRunSnapshot(run));
     await appendFile(this.stateFilePath(run.runId), line + "\n", "utf8");
     if (isTerminal) {

package/src/orchestration/models/ports.ts

@@ -10,7 +10,7 @@
  *
  * 层归属：Engine。零 infra 依赖（AC-1）。
  */
-import type { StreamSink, SubagentStream } from "../../execution/stream-sink.ts";
+import type { SubagentStream } from "../../execution/stream-sink.ts";
 import type { AgentEvent } from "../../shared/agent-event.ts";
 import type { WorkerHandle } from "../worker-handle.ts";
 import type { RunSpec } from "./run-spec.ts";
@@ -22,11 +22,11 @@ import type { WorkflowRun } from "./workflow-run.ts";
 /**
  * Agent 子进程执行 port。Infra 实现：SubprocessAgentRunner。
  *
- * run 执行单次 agent 调用（委托 SubagentService.executeAndAwait），返回结构化结果。
- * signal 用于 abort 传播。
+ * run 执行单次 agent 调用（委托 SubagentService.executeWorkflowAgent，[H2 W4] 纯转调），
+ * 返回结构化结果。signal 用于 abort 传播。
  *
- * onEvent（可选）：强类型 AgentEvent 回调，供调用方实时更新 live record 供 TUI 展示进度。
- * 不传则不回调（向后兼容；现有调用点不传不受影响）。
+ * onEvent（可选）：强类型 AgentEvent 回调，透传 service 派发路径（journal 转发/守护
+ * 刷新源），生产 pump 侧恒 undefined。
  *
  * D-005: onEvent 签名从 raw Record<string,unknown> 升级为 AgentEvent——委托后不再有
  * raw JSONL 中间层（executeAndAwait 直接出 AgentEvent，session-runner handleSdkEvent 出口）。
@@ -153,12 +153,19 @@ export interface LifecycleDeps {
     parentRun: WorkflowRun,
   ) => Promise<unknown>;
  /**
- * UI streaming sink（ctx.ui.setWidget），workflow agent call 创建 SubagentStream 用。
- *
- * 由 Interface 层 makeDeps 注入（从 SubagentService.getStreamSink() 取）。
- * dispatchAgentCall 用它创建 SubagentStream（widgetKey=subagent-stream-<runId>-<stepIndex>），
- * 使 workflow agent call 的 text_delta 走与 background subagent 相同的 streaming 链路。
- * 可选——无 UI 模式（TUI/RPC 无 setWidget）时为 undefined，dispatchAgentCall 不创建 stream。
- */
-  streamSink?: StreamSink;
+  * [H2 W3] workflow 域 agent() 统一派发入口（SubagentService.executeWorkflowAgent 的
+  * deps 注入形态，设计 §3.5 终态数据流）。窄函数类型——不引 execution 层具体类，
+  * 保持本 ports 文件零 infra/execution 依赖。由组合根（extension index.ts makeDeps）
+  * 注入：闭包捕获 getSubagentService() 单例，parentRunId 由 pump 侧补 run.runId。
+  *
+  * 可选——未注入时（旧测试 deps）dispatchAgentCall 回退 deps.runner（[H2 W4] 后
+  * SAR 已掏空为纯转调 executeWorkflowAgent，两分支执行体归一非双轨，差异仅 parentRunId
+  * 来源：注入 = 真实 run.runId，回退 = SAR_UNATTACHED_PARENT_RUN_ID 占位；生产装配
+  * 两字段同时注入，dispatch 恒优先）。
+  */
+  workflowAgentDispatch?: (
+    opts: AgentCallOpts,
+    parentRunId: string,
+    signal?: AbortSignal,
+  ) => Promise<AgentResult>;
 }

package/src/orchestration/models/types.ts

@@ -20,7 +20,7 @@ import type {
   ToolCallEntry,
 } from "@zhushanwen/subagent-engine-sdk";
 
-import type { ExecutionRecord, WorktreeHandle } from "../../execution/types.ts";
+import type { WorktreeHandle } from "../../execution/types.ts";
 
 // ── 状态机 ────────────────────────────────────────────────────
 
@@ -76,7 +76,8 @@ export function canRunTransition(from: RunStatus, to: RunStatus): boolean {
  * 历史值 20 偏紧——描述性 slug 如 "audit-structured-output"（23）/ "fix-subagent-wf-tools"（21）
  * 会撞上限，放宽到 35 兼顾「短到能塞进 TUI 标题行」与「容纳合理描述性 kebab-case 名」。
  * 放本文件的原因：约束对象是 AgentCallOpts.description（slug 的源字段，见下方 slug 派生说明），
- * 与字段同文件；worker-message-pump（live record slug 截断）与壳侧 tool schema maxLength 共享引用。
+ * 与字段同文件；subagent-actions-core（slug 校验）、subagent-service（record slug 截断）
+ * 与壳侧 tool schema maxLength 共享引用。
  */
 export const SLUG_MAX_LENGTH = 35;
 
@@ -351,20 +352,17 @@ export interface ExecutionTraceNode {
  */
   sessionId?: string;
  /**
- * Session JSONL 绝对路径。finalizeCall 从 result.sessionFile 透传。
- * 持久化到快照（serializeRun），跨 session 重水合后保留。
- */
+  * Session JSONL 绝对路径。finalizeCall 从 result.sessionFile 透传。
+  * 持久化到快照（serializeRun），跨 session 重水合后保留。
+  */
   sessionFile?: string;
- /**
- * Live 执行进度对象（running 时存在，done 时由 dispatchAgentCall 清除）。
- *
- * 挂在 node 上（D-10 单源延伸：AgentCall.traceNode 与 Trace.nodes 共享同一引用）。
- * TUI 通过 trace.toArray() 读 node.live，派生 getEventLog/getCurrentActivity 实时展示。
- * 不持久化（序列化时 strip；重跑时由 dispatchAgentCall 重建）。
- */
-  live?: ExecutionRecord;
 }
 
+// [H2 W3] `live?: ExecutionRecord` 字段已删除（设计 subagent-workflow-record-
+// unification.md D2：trace node 的 live 字段删除，只保留 result 终态摘要）。运行期
+// 实时进度改由 views 经 store 查询 collectRecordsByParentRunId(parentRunId) 订阅
+// 真实 record（origin:"workflow"），不再经 pump 旁路 progress record 挂载。
+
 /**
  * Trace.update 用的 patch（字段全可选）。
  *

package/src/orchestration/run-snapshot.ts

@@ -4,8 +4,8 @@
 //
 // 为什么需要它：WorkflowRun 的 JSONL 快照投影此前两宿主各写一份（core
 // file-run-store.ts 的 toSnapshot/fromSnapshot 与 pi 壳 jsonl-run-store.ts 的
-// serializeRun/deserializeRun）——字段集一致但语义细节分叉（live-strip、版本
-// guard、budgetRef 剔除），修一处漏一处。本模块收敛为单源 codec：字段演进
+// serializeRun/deserializeRun）——字段集一致但语义细节分叉（版本 guard、
+// budgetRef 剔除），修一处漏一处。本模块收敛为单源 codec：字段演进
 // 单点（G2），两宿主（FileRunStore / pi JsonlRunStore）各自只保留 IO 策略
 // （rewrite/append/去抖），投影与版本衔接语义全部经此模块。
 //
@@ -103,10 +103,9 @@ export interface RunSnapshot {
  * WorkflowRun → 单行快照。
  *
  * - 补 v 字段（D4 裁决②：写入恒带当前版本）。
- * - strip live（防御内聚）：calls[].traceNode 与 trace 数组节点的 `live` 运行期
- *   对象剥除——ExecutionRecord 含可变 turns[]/controller，不可序列化且跨进程
- *   必死（重跑时由 dispatchAgentCall 重建）；strip 产出新对象，不 mutate 内存
- *   中的 run（save 后 run 可继续跑）。
+ * - trace 节点全量序列化（[H2 W3] live strip 分支随 ExecutionTraceNode.live 字段
+ *   删除而退役——节点不再携带运行期对象，无需防御性剥离；旧快照经 fromRunSnapshot
+ *   重水合时多余键自然丢弃，存量行零迁移）。
  * - spec.budgetRef 剔除：父 Budget 共享引用是进程内优化（嵌套 workflow 预算
  *   共享），非持久化数据；Budget 实例若混入 spec 落盘将退化为普通对象投影
  *   （重水合后类型不符的脏字段）——重水合后 budget 从 state.budget 独立重建，
@@ -131,22 +130,19 @@ export function toRunSnapshot(run: WorkflowRun): RunSnapshot {
         usedCost: run.state.budget.usedCost,
         totalCallCount: run.state.budget.totalCallCount,
       },
-      calls: Array.from(run.state.calls.values(), (c) => {
-        // strip live（同 trace 序列化，不持久化运行期对象）
-        const { live: _live, ...traceNodeRest } = c.traceNode;
-        return {
-          id: c.id,
-          opts: c.opts,
-          status: c.status,
-          attempts: c.attempts,
-          result: c.result,
-          sessionId: c.sessionId,
-          sessionFile: c.sessionFile,
-          traceNode: traceNodeRest,
-        };
-      }),
-      // trace 节点浅拷贝时 strip live 字段
-      trace: run.state.trace.toArray().map(({ live: _live, ...rest }) => rest),
+      calls: Array.from(run.state.calls.values(), (c) => ({
+        id: c.id,
+        opts: c.opts,
+        status: c.status,
+        attempts: c.attempts,
+        result: c.result,
+        sessionId: c.sessionId,
+        sessionFile: c.sessionFile,
+        traceNode: c.traceNode,
+      })),
+      // trace 节点全量拷贝序列化（toArray 返回内部数组只读引用，拷贝为可变数组
+      // 落盘——节点不再携带运行期对象，无需防御性剥离）
+      trace: [...run.state.trace.toArray()],
       errorLogs: run.state.errorLogs,
       error: run.state.error,
       scriptResult: run.state.scriptResult,

package/src/orchestration/worker-message-pump.ts

@@ -9,7 +9,7 @@
  *    pending:unregister → onRunDone」终态序列的唯一定义点（D5-② 单点化，收敛原
  *    8 处逐字复制；OR-8 收口步骤与 OR-4/B-4 双围栏内化于本函数）
  *
- * 4 个导出函数（domain-models.md §失败处理矩阵）：
+ * 4 个 handle* 路由函数（domain-models.md §失败处理矩阵）+ 终态化/重建/防御 helper 若干：
  * - handleWorkerMessage(run, raw, deps, handlers) — 路由 agent_call/return/error/log
  * - handleWorkerError(run, err, deps, handlers) — worker uncaught error
  * - handleWorkerExit(run, code, handle, deps, handlers) — worker exit
@@ -39,14 +39,10 @@
 
 import { getLogger } from "../core/logger.ts";
 
-import { SLUG_MAX_LENGTH } from "./models/types.ts";
-import { createRecord, updateFromEvent } from "../execution/execution-record.ts";
-import { SubagentStream } from "../execution/stream-sink.ts";
-import type { AgentEvent } from "../shared/agent-event.ts";
 import { resolveAgentOpts } from "./agent-opts-resolver.ts";
 import { executeAgentCall } from "./execute-agent-call.ts";
 import { AgentCall } from "./models/agent-call.ts";
-import type { LifecycleDeps, WorkerHandlers } from "./models/ports.ts";
+import type { AgentRunner, LifecycleDeps, WorkerHandlers } from "./models/ports.ts";
 import { RunRuntime } from "./models/run-runtime.ts";
 import type { WorkerLogEntry } from "./models/types.ts";
 import type { AgentCallOpts, AgentResult, DoneReason, ExecutionTraceNode } from "./models/types.ts";
@@ -400,7 +396,7 @@ function discardInFlightCalls(run: WorkflowRun): number[] {
  *   result 以 IN_FLIGHT_CALL_CANCELLED_MSG 承载取消原因；
  * - trace 节点置 failed + 固定取消文案 + completedAt（「failed + Cancelled 文案」
  *   即取消的既有表达形态，不新增状态枚举）；
- * - node.live 清除（终态 run 无 TUI 轮询，防 ExecutionRecord 滞留）。
+ * - node 无运行期附属对象（[H2 W3] trace.live 退役后节点只剩终态摘要字段）。
  *
  * 调用点约定：每个 transition("done") 成功后、store.save 之前——先收口再落盘，
  * 内存态与持久化快照在同一时点收敛（「run-snapshot 落盘前」的实现形态）。
@@ -419,7 +415,6 @@ export function closeOutInFlightCalls(run: WorkflowRun): number[] {
     if (call.status === "running") {
       call.markDone({ content: "", error: IN_FLIGHT_CALL_CANCELLED_MSG });
     }
-    call.traceNode.live = undefined;
     run.state.trace.update(callId, {
       status: "failed",
       result: { content: "", error: IN_FLIGHT_CALL_CANCELLED_MSG },
@@ -697,24 +692,13 @@ function dispatchAgentCall(
     return;
   }
 
-  // 构建 trace 节点 + live record（TUI 实时进度）
+  // 构建 trace 节点（[H2 W3] trace.live 退役——实时进度改由 views 经 store 订阅
+  // collectRecordsByParentRunId(parentRunId) 查询真实 record，设计 D2；节点保留
+  // 终态摘要 result，终态由 executeAgentCall → finalizeCall 写入）。
   const agentName = msg.opts.description ?? msg.opts.agent ?? "unknown";
-  // slug 复用 agentName（超长截断），live record 的 slug 仅用于 TUI 展示。
-  const liveSlug = agentName.length > SLUG_MAX_LENGTH ? agentName.slice(0, SLUG_MAX_LENGTH) : agentName;
   const now = new Date().toISOString();
-  // 未显式指定 model 的展示口径（live record 与 trace node 共用，两处一致）。
+  // 未显式指定 model 的展示口径。
   const model = msg.opts.model ?? "default";
-  // live record：收口 agent 执行过程中的 text/thinking/toolCalls/usage，
-  // 供 TUI 在 agent 运行期间显示进度（getEventLog/getCurrentActivity）。
-  // 完成时由下方 .then 清除（终态由 node.result 承载）。
-  const liveRecord = createRecord(String(msg.callId), {
-    agent: agentName,
-    model,
-    mode: "background",
-    task: msg.opts.prompt,
-    slug: liveSlug,
-    startedAt: Date.now(),
-  });
   const node: ExecutionTraceNode = {
     stepIndex: msg.callId,
     agent: agentName,
@@ -723,7 +707,6 @@ function dispatchAgentCall(
     status: "running" as const,
     phase: msg.phase,
     startedAt: now,
-    live: liveRecord,
   };
   run.state.trace.append(node);
 
@@ -750,8 +733,6 @@ function dispatchAgentCall(
     const errorResult: AgentResult = { content: "", error: resolved.error };
     call.markDone(errorResult);
     run.state.calls.set(msg.callId, call);
-    // 无子进程执行，清除空 live record（终态由 result 承载）
-    node.live = undefined;
     run.state.trace.update(msg.callId, {
       status: "failed",
       result: errorResult,
@@ -777,19 +758,20 @@ function dispatchAgentCall(
   // 后者已守 terminal（isTerminal）早期 return）。fallback new AbortController 已移除。
   const runtime = run.runtime!;
   const signal = runtime.controller.signal;
-  // D-005: onEvent 签名升级——executeAndAwait 直接出 AgentEvent（强类型，
-  // session-runner handleSdkEvent 出口），不再有 raw JSONL 中间层。
-  // 删 jsonlToAgentEvent 翻译——直接 updateFromEvent。
-  // TUI 靠 tick 轮询 trace.toArray() 读 node.live，无需显式通知。
-  const onEvent = (event: AgentEvent): void => {
-    updateFromEvent(liveRecord, event);
-  };
-  // 创建 streaming sink：widgetKey = subagent-stream-<runId>-<stepIndex>。
-  // 复用 background subagent 的 SubagentStream → setWidget → RPC 链路（agent-call-streaming-extension.md）。
-  // streamSink 缺失（无 UI 模式）时 stream=undefined，executeAgentCall 正常执行不 streaming。
-  const stream = deps.streamSink
-    ? new SubagentStream(`${run.runId}-${msg.callId}`, deps.streamSink)
-    : undefined;
+  // [H2 W3] 执行 port 切换（设计 §3.5 终态数据流：pump 薄化为「消息转调 + run 级
+  // 收尾」）：workflowAgentDispatch = SubagentService.executeWorkflowAgent 的注入
+  // 形态——真实 record（origin:"workflow" + parentRunId=run.runId）进 store、事件
+  // 流经 service 内 journal 接线进 record、streaming/守护/池归 service 派发路径。
+  // 未注入时（旧测试 deps）回退 deps.runner——[H2 W4] SAR.run 已掏空为纯转调
+  // executeWorkflowAgent，两分支执行体归一（同一 service 编排），仅 parentRunId
+  // 来源不同（注入路径闭包携带真实 run.runId；回退路径为 SAR 直调占位）。生产
+  // 装配恒注入 dispatch（extension index.ts makeDeps），回退分支生产不可达。
+  // 旁路 progress record 族（createRecord + updateFromEvent + SubagentStream +
+  // trace.live 挂载）随本切换整体退役——TUI/GUI 实时进度改从 store 订阅（D2）。
+  const dispatch = deps.workflowAgentDispatch;
+  const runner: AgentRunner = dispatch
+    ? { run: (rOpts, rSignal) => dispatch(rOpts, run.runId, rSignal) }
+    : deps.runner;
   // 原 gate.withSlot(fn, signal) 语义内联：pre-aborted 时 reject AbortError（
   // 下方 .catch 依赖此约定不记错），否则直接执行——并发调度归 ConcurrencyPool。
   const dispatchCall = async (): Promise<void> => {
@@ -798,22 +780,17 @@ function dispatchAgentCall(
       abortErr.name = "AbortError";
       throw abortErr;
     }
-    try {
-      // OB2（S7 残留）：isOrphaned 谓词注入——旧代际 finalize 在 trace.update 前被
-      // 拦截（判定语义与下方 .then/.catch 守卫同一 isOrphanedCall，详见
-      // execute-agent-call.ts finalizeCall 文档注释）。
-      await executeAgentCall(call, deps.runner, run.state.budget, signal, run.state.trace, onEvent, stream, () => isOrphanedCall(run, msg.callId, call));
-    } finally {
-      stream?.dispose();
-    }
+    // OB2（S7 残留）：isOrphaned 谓词注入——旧代际 finalize 在 trace.update 前被
+    // 拦截（判定语义与下方 .then/.catch 守卫同一 isOrphanedCall，详见
+    // execute-agent-call.ts finalizeCall 文档注释）。onEvent/stream 两实参显式
+    // undefined 占位（[H2 W3] live record 更新与 SubagentStream 已随旁路退役；
+    // 位置参数不得前移——isOrphaned 是第 8 形参）。
+    await executeAgentCall(call, runner, run.state.budget, signal, run.state.trace, undefined, undefined, () => isOrphanedCall(run, msg.callId, call));
   };
   void dispatchCall()
     .then(() => {
-      // 清除 live record：终态已由 executeAgentCall → finalizeCall 写入 node.result，
-      // live 不再需要（且含可变状态，不保留）。无论 stale 与否都清，避免内存泄漏。
-      // M4: 必须在 stale guard 之前清，否则跨 rebuild 的迟到 completion 会累积 live record。
-      node.live = undefined;
-      // run 终止（终态）后到达的 stale completion 不写 state
+      // run 终止（终态）后到达的 stale completion 不写 state（终态由
+      // executeAgentCall → finalizeCall 写入 node.result，node 无运行期附属对象）。
       if (run.state.status !== "running") return;
       // 孤儿 call 守卫（S7-second 竞态）：rebuild 的 discardInFlightCalls 已移除本
       // call、或重跑 dispatch 已用新实例替换同 callId 条目时，本 completion 属于旧
@@ -852,13 +829,12 @@ function dispatchAgentCall(
       // 兜底回发：executeAgentCall 抛非 Abort 异常时（如 runner undefined 的 TypeError、
       // dispatchCall 内部 bug）原 catch 仅 console.error，worker 内对 callId 的 pending
       // Promise 永不 resolve → agent() 永久 await → worker 脚本挂死。构造 failed AgentResult
-      //（与 resolveAgentOpts 失败路径 L262-275 一致的模式）postAgentResult 回 worker，
+      //（与 resolveAgentOpts 失败路径一致的模式）postAgentResult 回 worker，
       // 让 pending Promise resolve（结果为 error），脚本可继续或失败退出。
       // 孤儿 call 守卫（与 .then 对称，S7-second 竞态）：rebuild 后本 call 已被 discard
       // 移除/替换——markDone 虽在孤儿实例上无害，但 trace.update 会污染重跑新建的同
       // stepIndex 节点、postAgentResult 会劫持新 worker 的同 callId pending。孤儿时只
-      // 留日志，全部跳过。node.live 无条件先清（旧节点已脱离 trace，防御性统一）。
-      node.live = undefined;
+      // 留日志，全部跳过。
       if (isOrphanedCall(run, msg.callId, call)) {
         deps.log?.("debug", "workflow:worker-message-pump", "orphan agent call failure dropped", { runId: run.runId, callId: msg.callId });
         return;
@@ -871,8 +847,8 @@ function dispatchAgentCall(
         if (call.status === "pending") call.markRunning();
         call.markDone(errorResult);
       }
-      // state 一致性三件套（与 resolveAgentOpts 失败 L268-276 / .then L319-325 对等）：
-      // trace 标 failed + 清 live record（防泄漏）+ 持久化（catch 恰是最需留证的场景）。
+      // state 一致性三件套（与 resolveAgentOpts 失败 / .then 路径对等）：
+      // trace 标 failed + 持久化（catch 恰是最需留证的场景）。
       // stale 终态（run 已 done）时 run.runtime 为 undefined，postAgentResult 用
       // optional chaining 跳过 worker 回发；trace/state 写入仍执行（无害，终态快照已存）。
       run.state.trace.update(msg.callId, {