@zhushanwen/pi-subagent-workflow 0.1.0 → 0.2.0

package/src/interface/views/__tests__/detail-content-session-file.test.ts

@@ -0,0 +1,70 @@
+// src/interface/views/__tests__/detail-content-session-file.test.ts
+//
+// TUI 渲染测试：buildDetailContent 在 agent 终态时渲染 session: 路径行。
+//
+// 防的 bug：node.sessionFile 有值但 TUI detail 不显示——用户在交互面板里
+// 看不到 agent 的 session jsonl 路径，无法定位文件做后续查看。
+
+import { describe, expect, it } from "vitest";
+
+import { buildDetailContent } from "../detail-content.ts";
+import type { ThemeLike } from "../format.ts";
+import type { ExecutionTraceNode } from "../../../orchestration/models/types.ts";
+import type { WorkflowRun } from "../../../orchestration/models/workflow-run.ts";
+
+/** plain theme: fg/bold 直接返回原文，无 ANSI 色码——测试断言纯文本。 */
+const plainTheme: ThemeLike = {
+  fg: (_tag: string, text: string) => text,
+  bold: (text: string) => text,
+};
+
+function makeNode(overrides: Partial<ExecutionTraceNode> = {}): ExecutionTraceNode {
+  return {
+    stepIndex: 0,
+    agent: "worker",
+    task: "do something",
+    model: "default",
+    status: "completed",
+    ...overrides,
+  };
+}
+
+/** 最小 WorkflowRun——buildDetailContent 只读 run.state.errorLogs。 */
+function makeRun(): WorkflowRun {
+  return {
+    state: { errorLogs: [] },
+  } as unknown as WorkflowRun;
+}
+
+describe("buildDetailContent session 路径行渲染", () => {
+  it("node.sessionFile 有值 → 详情末尾渲染 session: <路径>", () => {
+    const sessionPath = "/abs/.pi/agent/subagents/enc/sessions/2026-07-15T_session-abc.jsonl";
+    const node = makeNode({
+      status: "completed",
+      sessionFile: sessionPath,
+      result: { content: "done" },
+    });
+    const lines = buildDetailContent(node, { promptExpanded: false }, makeRun(), plainTheme, 120, Date.now());
+    const sessionLine = lines.find((l) => l.includes("session:"));
+    expect(sessionLine).toBeDefined();
+    expect(sessionLine).toContain(sessionPath);
+  });
+
+  it("node.sessionFile undefined（窗口期）→ 不渲染 session: 行", () => {
+    const node = makeNode({ status: "completed", sessionFile: undefined, result: { content: "done" } });
+    const lines = buildDetailContent(node, { promptExpanded: false }, makeRun(), plainTheme, 120, Date.now());
+    const sessionLine = lines.find((l) => l.includes("session:"));
+    expect(sessionLine).toBeUndefined();
+  });
+
+  it("长路径截断到 mainWidth（防溢出）", () => {
+    const longPath = "/very/long/path/" + "x".repeat(200) + "/session.jsonl";
+    const node = makeNode({ status: "completed", sessionFile: longPath, result: { content: "done" } });
+    const narrowWidth = 60;
+    const lines = buildDetailContent(node, { promptExpanded: false }, makeRun(), plainTheme, narrowWidth, Date.now());
+    const sessionLine = lines.find((l) => l.includes("session:"));
+    expect(sessionLine).toBeDefined();
+    // 截断后行宽不超过 mainWidth + 边框余量
+    expect(sessionLine!.length).toBeLessThanOrEqual(narrowWidth);
+  });
+});

package/src/interface/views/detail-content.ts

@@ -87,6 +87,7 @@ export function buildDetailContent(
   renderPromptSection(rightLines, node, state, theme);
   renderActivitySection(rightLines, node, mainWidth, theme);
   renderOutcomeSection(rightLines, node, mainWidth, theme);
+  renderSessionSection(rightLines, node, mainWidth, theme);
   return rightLines;
 }
 
@@ -296,3 +297,22 @@ function renderOutcomeSection(
     }
   }
 }
+
+/**
+ * 渲染 session jsonl 路径行（agent 级）。
+ *
+ * 对齐 subagents list-component 的 `session:` 行渲染（dim 色 + 截断）。
+ * sessionFile 是绝对路径，可能很长——截断到 mainWidth 防溢出。
+ * 窗口期（session 尚未创建）sessionFile 为 undefined，整段不渲染。
+ */
+function renderSessionSection(
+  rightLines: string[],
+  node: ExecutionTraceNode,
+  mainWidth: number,
+  theme: ThemeLike,
+): void {
+  if (!node.sessionFile) return;
+  rightLines.push("");
+  const line = `session: ${node.sessionFile}`.slice(0, mainWidth - BOX_BORDER_CHARS);
+  rightLines.push(theme.fg("dim", `  ${line}`));
+}

package/src/orchestration/__tests__/agent-call-catch-fallback.test.ts

@@ -0,0 +1,208 @@
+// src/orchestration/__tests__/agent-call-catch-fallback.test.ts
+//
+// U7: dispatchAgentCall catch 分支回发 agent-result 给 worker（吞错兜底）
+//
+// 场景：executeAgentCall（或 gate.withSlot）抛非 Abort 异常时，原 catch 块仅
+// console.error，worker 内对应 callId 的 pending Promise 永不 resolve → agent()
+// 永久 await → worker 脚本挂死。修复后 catch 块构造 failed AgentResult 并
+// postAgentResult 回 worker，使 pending Promise 能 resolve（结果为 error）。
+//
+// 通过 handleWorkerMessage 触发 dispatchAgentCall（内部函数不 export）。
+// Mock 构造模式参考 agent-call-stream.test.ts。
+
+import { describe, expect, it, vi } from "vitest";
+
+import { handleWorkerMessage } from "../error-recovery.ts";
+import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
+import { Trace } from "../models/trace.ts";
+import type { WorkflowRun } from "../models/workflow-run.ts";
+import type { AgentResult } from "../models/types.ts";
+
+// ── helpers ──────────────────────────────────────────────────
+
+/** 构造 status="running" 的 mock WorkflowRun，含 trace/budget/calls/runtime。
+ *  worker.postMessage 为 vi.fn spy，便于断言回发内容。gate.withSlot 直接 await fn()
+ *  让异常透传到外层 .catch（模拟 executeAgentCall 抛错的真实链路）。 */
+function makeRunningRun(runId: string): WorkflowRun {
+  const trace = new Trace();
+  const controller = new AbortController();
+  return {
+    runId,
+    spec: { scriptName: "test-wf", scriptSource: "agent('hi')", args: {}, runId, slug: undefined },
+    state: {
+      status: "running" as const,
+      reason: undefined,
+      trace,
+      budget: {
+        usedTokens: 0,
+        usedCost: 0,
+        totalCallCount: 0,
+        consume: vi.fn(),
+        isExceeded: vi.fn(() => false),
+        incrementCallCount: vi.fn(),
+      },
+      calls: new Map(),
+      scriptResult: undefined,
+    },
+    meta: { startedAt: new Date().toISOString(), workerErrorCount: 0, scriptErrorCount: 0 },
+    runtime: {
+      controller,
+      worker: { postMessage: vi.fn() },
+      gate: {
+        // 直接 await fn()：executeAgentCall 内 runner.run reject 会沿 withSlot → 外层 .catch
+        withSlot: vi.fn(async (fn: () => Promise<void>, _signal: AbortSignal) => {
+          await fn();
+        }),
+      },
+    },
+    transition: vi.fn(),
+    replaceRuntime: vi.fn(),
+  } as unknown as WorkflowRun;
+}
+
+/** LifecycleDeps mock，runner.run 可配置为 reject 指定 error。 */
+function makeDeps(opts: { runnerError?: Error } = {}): LifecycleDeps {
+  const runnerRun = vi.fn(async () => {
+    if (opts.runnerError) throw opts.runnerError;
+    return { content: "OK", durationMs: 10, error: undefined, toolCalls: [] } as AgentResult;
+  });
+  return {
+    store: { save: vi.fn(async () => {}) },
+    workerHost: { start: vi.fn() },
+    runner: { run: runnerRun },
+    runs: new Map(),
+    eventBus: { emit: vi.fn() },
+    onRunDone: vi.fn(),
+    log: vi.fn(),
+    // streamSink 不设 = undefined（本测试不关心 stream）
+  } as unknown as LifecycleDeps;
+}
+
+function makeHandlers(): WorkerHandlers {
+  return {
+    onMessage: vi.fn(async () => {}),
+    onError: vi.fn(async () => {}),
+    onExit: vi.fn(async () => {}),
+  } as unknown as WorkerHandlers;
+}
+
+/** agent-call 消息 */
+function makeAgentCallMsg(callId: number): unknown {
+  return {
+    type: "agent-call",
+    callId,
+    phase: "test-phase",
+    opts: { prompt: "test task", agent: "worker", description: "test-slug" },
+  };
+}
+
+/** 从 postMessage spy 的所有调用中找 type:"agent-result" 且 callId 匹配的参数。 */
+function findAgentResultPost(
+  postMessage: ReturnType<typeof vi.fn>,
+  callId: number,
+): { type: string; callId: number; result: AgentResult; cached: boolean } | undefined {
+  for (const call of postMessage.mock.calls) {
+    const msg = call[0] as { type?: string; callId?: number; result?: AgentResult; cached?: boolean };
+    if (msg?.type === "agent-result" && msg.callId === callId) return msg as never;
+  }
+  return undefined;
+}
+
+/** 静默 console.error（catch 块会打印失败日志，避免污染测试输出）。 */
+function silenceConsoleError(): () => void {
+  const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+  return () => spy.mockRestore();
+}
+
+// ── U7a: 非 Abort 异常 → postAgentResult 回发 failed result ──
+
+describe("U7a: catch 分支兜底回发 agent-result（非 Abort 异常）", () => {
+  it("runner.run reject 'runner exploded' → worker 收到 {success:false, error:'runner exploded'}", async () => {
+    const restore = silenceConsoleError();
+    try {
+      const deps = makeDeps({ runnerError: new Error("runner exploded") });
+      const run = makeRunningRun("wf-catch-001");
+      const handlers = makeHandlers();
+      const postMessage = run.runtime!.worker.postMessage as ReturnType<typeof vi.fn>;
+
+      await handleWorkerMessage(run, makeAgentCallMsg(2), deps, handlers);
+
+      // dispatchAgentCall 内 void withSlot(...)（fire-and-forget），需等微任务完成
+      await vi.waitFor(() => {
+        expect(findAgentResultPost(postMessage, 2)).toBeDefined();
+      });
+
+      const posted = findAgentResultPost(postMessage, 2)!;
+      expect(posted.type).toBe("agent-result");
+      expect(posted.callId).toBe(2);
+      expect(posted.cached).toBe(false);
+      // AgentResult.error 字段承载错误信息（与 resolveAgentOpts 失败路径一致）
+      expect(posted.result.error).toBe("runner exploded");
+      expect(posted.result.content).toBe("");
+
+      // state 一致性三件套（review should_fix）：
+      // trace node 标 failed（不遗留 running 幽灵节点）
+      const traceNode = run.state.trace.find(2);
+      expect(traceNode?.status).toBe("failed");
+      expect(traceNode?.result?.error).toBe("runner exploded");
+      // node.live 清除（防内存泄漏）
+      expect(traceNode?.live).toBeUndefined();
+      // 持久化（catch 是最需留证的场景）
+      expect(deps.store.save).toHaveBeenCalled();
+    } finally {
+      restore();
+    }
+  });
+
+  it("非 Error 值 reject（字符串）→ error 字段为该字符串", async () => {
+    const restore = silenceConsoleError();
+    try {
+      const deps = makeDeps({ runnerError: "string failure" as unknown as Error });
+      const run = makeRunningRun("wf-catch-002");
+      const handlers = makeHandlers();
+      const postMessage = run.runtime!.worker.postMessage as ReturnType<typeof vi.fn>;
+
+      await handleWorkerMessage(run, makeAgentCallMsg(7), deps, handlers);
+
+      await vi.waitFor(() => {
+        expect(findAgentResultPost(postMessage, 7)).toBeDefined();
+      });
+
+      const posted = findAgentResultPost(postMessage, 7)!;
+      expect(posted.result.error).toBe("string failure");
+    } finally {
+      restore();
+    }
+  });
+});
+
+// ── U7b: AbortError → 不回发（预期路径，吞掉） ──
+
+describe("U7b: AbortError 不回发 agent-result", () => {
+  it("runner.run reject AbortError → postAgentResult 不被调用", async () => {
+    const restore = silenceConsoleError();
+    try {
+      const abortErr = new Error("aborted");
+      abortErr.name = "AbortError";
+      const deps = makeDeps({ runnerError: abortErr });
+      const run = makeRunningRun("wf-catch-003");
+      const handlers = makeHandlers();
+      const postMessage = run.runtime!.worker.postMessage as ReturnType<typeof vi.fn>;
+
+      await handleWorkerMessage(run, makeAgentCallMsg(3), deps, handlers);
+
+      // 等待 fire-and-forget 链路稳定：无 agent-result 回发。
+      // 先 flush 微任务队列（多次确保 withSlot promise 已 settle），
+      // 再断言断言期内无 agent-result。vi.waitFor 用反向断言会一满足就 return，
+      // 故采用：跑若干 microtask tick 后静态断言。
+      for (let i = 0; i < 5; i++) {
+        // eslint-disable-next-line no-await-in-loop
+        await Promise.resolve();
+      }
+      const posted = findAgentResultPost(postMessage, 3);
+      expect(posted).toBeUndefined();
+    } finally {
+      restore();
+    }
+  });
+});

package/src/orchestration/__tests__/agent-call-stream.test.ts

@@ -0,0 +1,157 @@
+// src/orchestration/__tests__/agent-call-stream.test.ts
+//
+// U4: dispatchAgentCall 创建 SubagentStream 并在 agent call 结束后 dispose
+// U5: dispatchAgentCall widgetKey 格式 = subagent-stream-<runId>-<stepIndex>
+// U6: streamSink 为 undefined 时 dispatchAgentCall 不创建 stream 不报错
+//
+// 通过 handleWorkerMessage 触发 dispatchAgentCall（内部函数不 export）。
+
+import { describe, expect, it, vi } from "vitest";
+
+import { handleWorkerMessage } from "../error-recovery.ts";
+import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
+import { Trace } from "../models/trace.ts";
+import type { WorkflowRun } from "../models/workflow-run.ts";
+import type { AgentResult } from "../models/types.ts";
+
+// ── helpers ──────────────────────────────────────────────────
+
+function makeMockResult(): AgentResult {
+  return { content: "OK", durationMs: 10, error: undefined, toolCalls: [] };
+}
+
+/** 构造 status="running" 的 mock WorkflowRun，含 trace/budget/calls/runtime */
+function makeRunningRun(runId: string): WorkflowRun {
+  const trace = new Trace();
+  const controller = new AbortController();
+  return {
+    runId,
+    spec: { scriptName: "test-wf", scriptSource: "agent('hi')", args: {}, runId, slug: undefined },
+    state: {
+      status: "running" as const,
+      reason: undefined,
+      trace,
+      budget: {
+        usedTokens: 0,
+        usedCost: 0,
+        totalCallCount: 0,
+        consume: vi.fn(),
+        isExceeded: vi.fn(() => false),
+        incrementCallCount: vi.fn(),
+      },
+      calls: new Map(),
+      scriptResult: undefined,
+    },
+    meta: { startedAt: new Date().toISOString(), workerErrorCount: 0, scriptErrorCount: 0 },
+    runtime: {
+      controller,
+      worker: { postMessage: vi.fn() },
+      gate: {
+        withSlot: vi.fn(async (fn: () => Promise<void>, _signal: AbortSignal) => {
+          await fn();
+        }),
+      },
+    },
+    transition: vi.fn(),
+    replaceRuntime: vi.fn(),
+  } as unknown as WorkflowRun;
+}
+
+/** LifecycleDeps mock，runner.run 可控制返回值，streamSink 可配置 */
+function makeDeps(opts: {
+  streamSink?: { setWidget: ReturnType<typeof vi.fn> };
+  runnerResult?: AgentResult;
+} = {}): LifecycleDeps {
+  return {
+    store: { save: vi.fn(async () => {}) },
+    workerHost: { start: vi.fn() },
+    runner: { run: vi.fn(async () => opts.runnerResult ?? makeMockResult()) },
+    runs: new Map(),
+    eventBus: { emit: vi.fn() },
+    onRunDone: vi.fn(),
+    log: vi.fn(),
+    streamSink: opts.streamSink,
+  } as unknown as LifecycleDeps;
+}
+
+function makeHandlers(): WorkerHandlers {
+  return {
+    onMessage: vi.fn(async () => {}),
+    onError: vi.fn(async () => {}),
+    onExit: vi.fn(async () => {}),
+  } as unknown as WorkerHandlers;
+}
+
+/** agent-call 消息 */
+function makeAgentCallMsg(callId: number): unknown {
+  return {
+    type: "agent-call",
+    callId,
+    phase: "test-phase",
+    opts: { prompt: "test task", agent: "worker", description: "test-slug" },
+  };
+}
+
+// ── U4: dispatchAgentCall 创建 SubagentStream 并 dispose ──
+
+describe("U4: dispatchAgentCall stream dispose", () => {
+  it("agent call 结束后 stream.dispose 被调用（setWidget 末次 lines=undefined）", async () => {
+    const setWidget = vi.fn();
+    const deps = makeDeps({ streamSink: { setWidget } });
+    const run = makeRunningRun("wf-test-123");
+    const handlers = makeHandlers();
+
+    await handleWorkerMessage(run, makeAgentCallMsg(0), deps, handlers);
+    // dispatchAgentCall 内部 void withSlot(...)（fire-and-forget），需等 microtask 完成
+    await vi.waitFor(() => {
+      expect(setWidget.mock.calls.length).toBeGreaterThanOrEqual(1);
+    });
+
+    const calls = setWidget.mock.calls;
+    const lastCall = calls[calls.length - 1];
+    expect(lastCall[1]).toBeUndefined();
+  });
+});
+
+// ── U5: widgetKey 格式 ──
+
+describe("U5: widgetKey 格式", () => {
+  it("widgetKey = subagent-stream-<runId>-<stepIndex>", async () => {
+    const setWidget = vi.fn();
+    const deps = makeDeps({ streamSink: { setWidget } });
+    const run = makeRunningRun("wf-test-123");
+    const handlers = makeHandlers();
+
+    await handleWorkerMessage(run, makeAgentCallMsg(2), deps, handlers);
+    await vi.waitFor(() => {
+      expect(setWidget.mock.calls.length).toBeGreaterThanOrEqual(1);
+    });
+
+    const widgetKey = setWidget.mock.calls[0][0] as string;
+    expect(widgetKey).toBe("subagent-stream-wf-test-123-2");
+  });
+});
+
+// ── U6: streamSink 为 undefined 时不报错 ──
+
+describe("U6: streamSink undefined 降级", () => {
+  it("streamSink=undefined → runner.run 仍被调用，无异常", async () => {
+    const runnerRun = vi.fn(async () => makeMockResult());
+    const deps = {
+      store: { save: vi.fn(async () => {}) },
+      workerHost: { start: vi.fn() },
+      runner: { run: runnerRun },
+      runs: new Map(),
+      eventBus: { emit: vi.fn() },
+      onRunDone: vi.fn(),
+      log: vi.fn(),
+      // streamSink 不设 = undefined
+    } as unknown as LifecycleDeps;
+    const run = makeRunningRun("wf-test-456");
+    const handlers = makeHandlers();
+
+    await handleWorkerMessage(run, makeAgentCallMsg(0), deps, handlers);
+
+    expect(runnerRun).toHaveBeenCalledTimes(1);
+  });
+});

package/src/orchestration/__tests__/error-recovery-handlers.test.ts

@@ -39,6 +39,8 @@ function makeRunningRun(opts: {
     state: {
       status: "running",
       budget: { usedTokens: 50, usedCost: 0.1 },
+      // L9: errorLogs 现在用 push 追加——必须是真实数组，不能省略
+      errorLogs: [],
     },
     meta: {
       startedAt: new Date().toISOString(),

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

@@ -0,0 +1,171 @@
+// src/orchestration/__tests__/execute-agent-call.test.ts
+//
+// U2: executeAgentCall 透传 stream 给 runner.run
+// U3: executeAgentCall retry 递归也透传 stream（不丢、不重建）
+
+import { describe, expect, it, vi } from "vitest";
+
+import { executeAgentCall } from "../execute-agent-call.ts";
+import { AgentCall } from "../models/agent-call.ts";
+import { Budget } from "../models/budget.ts";
+import type { AgentRunner } from "../models/ports.ts";
+import { Trace } from "../models/trace.ts";
+import type { ExecutionTraceNode } from "../models/types.ts";
+import type { AgentCallOpts, AgentResult } from "../models/types.ts";
+
+// ── 测试辅助 ──
+
+function makeMockResult(overrides: Partial<AgentResult> = {}): AgentResult {
+  return {
+    content: "OK",
+    durationMs: 100,
+    error: undefined,
+    toolCalls: [],
+    ...overrides,
+  };
+}
+
+function makeBaseOpts(): AgentCallOpts {
+  return {
+    prompt: "test task",
+    agent: "worker",
+    cwd: "/some/path",
+  } as AgentCallOpts;
+}
+
+/** 构造一个 traceNode（ExecutionTraceNode 最小子集） */
+function makeTraceNode(stepIndex = 0): ExecutionTraceNode {
+  return {
+    stepIndex,
+    agent: "test-agent",
+    task: "test task",
+    model: "default",
+    status: "pending",
+  };
+}
+
+/** 构造 AgentCall + 关联的 Trace（call.id 与 trace 节点 stepIndex 对齐） */
+function makeAgentCallAndTrace(): { call: AgentCall; trace: Trace } {
+  const trace = new Trace();
+  const traceNode = makeTraceNode(0);
+  trace.append(traceNode);
+  const call = new AgentCall(0, makeBaseOpts(), traceNode);
+  return { call, trace };
+}
+
+/** 创建 mock AgentRunner（只实现 run） */
+function createMockRunner(impl?: ReturnType<typeof vi.fn>): AgentRunner & { run: ReturnType<typeof vi.fn> } {
+  const run = impl ?? vi.fn().mockResolvedValue(makeMockResult());
+  return { run } as unknown as AgentRunner & { run: ReturnType<typeof vi.fn> };
+}
+
+// ── U2: executeAgentCall 透传 stream 给 runner.run ──
+
+describe("U2: executeAgentCall 透传 stream", () => {
+  it("executeAgentCall 传 stream → runner.run 第 4 参收到同一 stream", async () => {
+    let capturedStream: unknown;
+    const runner = createMockRunner(
+      vi.fn().mockImplementation((_opts, _sig, _onEvt, stream) => {
+        capturedStream = stream;
+        return Promise.resolve(makeMockResult());
+      }),
+    );
+
+    const fakeStream = { onDelta: vi.fn(), dispose: vi.fn() };
+    const { call, trace } = makeAgentCallAndTrace();
+    const budget = new Budget();
+
+    await executeAgentCall(call, runner, budget, new AbortController().signal, trace, undefined, fakeStream as never);
+
+    expect(capturedStream).toBe(fakeStream);
+  });
+
+  it("executeAgentCall 不传 stream → runner.run 第 4 参为 undefined", async () => {
+    let capturedStream: unknown = "sentinel";
+    const runner = createMockRunner(
+      vi.fn().mockImplementation((_opts, _sig, _onEvt, stream) => {
+        capturedStream = stream;
+        return Promise.resolve(makeMockResult());
+      }),
+    );
+
+    const { call, trace } = makeAgentCallAndTrace();
+    const budget = new Budget();
+
+    await executeAgentCall(call, runner, budget, new AbortController().signal, trace);
+
+    expect(capturedStream).toBeUndefined();
+  });
+});
+
+// ── U1: finalizeCall 透传 sessionFile 到 trace 节点（方案 A）──
+
+describe("U1: finalizeCall sessionFile → trace 节点", () => {
+  it("runner.run 返回带 sessionFile 的 result → trace 节点携带 sessionFile", async () => {
+    const sessionFilePath = "/abs/.pi/agent/subagents/enc/sessions/2026-07-15T_session-abc.jsonl";
+    const runner = createMockRunner(
+      vi.fn().mockResolvedValue(
+        makeMockResult({ sessionId: "session-abc", sessionFile: sessionFilePath }),
+      ),
+    );
+    const { call, trace } = makeAgentCallAndTrace();
+    const budget = new Budget();
+
+    await executeAgentCall(call, runner, budget, new AbortController().signal, trace);
+
+    const node = trace.find(0);
+    expect(node).toBeDefined();
+    expect(node!.sessionFile).toBe(sessionFilePath);
+    expect(node!.sessionId).toBe("session-abc");
+  });
+
+  it("runner.run 返回无 sessionFile 的 result → trace 节点 sessionFile undefined", async () => {
+    const runner = createMockRunner(
+      vi.fn().mockResolvedValue(makeMockResult({ sessionId: "session-xyz" })),
+    );
+    const { call, trace } = makeAgentCallAndTrace();
+    const budget = new Budget();
+
+    await executeAgentCall(call, runner, budget, new AbortController().signal, trace);
+
+    const node = trace.find(0);
+    expect(node).toBeDefined();
+    expect(node!.sessionFile).toBeUndefined();
+  });
+});
+
+// ── U3: retry 递归也透传 stream ──
+
+describe("U3: executeAgentCall retry 透传 stream", () => {
+  it("首次 runner.run 返回 error → retry 时第 4 参仍是同一 stream", async () => {
+    vi.useFakeTimers();
+
+    const capturedStreams: unknown[] = [];
+    const runner = createMockRunner(
+      vi.fn().mockImplementation((_opts, _sig, _onEvt, stream) => {
+        capturedStreams.push(stream);
+        // 首次 error，第二次成功
+        if (capturedStreams.length === 1) {
+          return Promise.resolve(makeMockResult({ error: "transient error" }));
+        }
+        return Promise.resolve(makeMockResult());
+      }),
+    );
+
+    const fakeStream = { onDelta: vi.fn(), dispose: vi.fn() };
+    const { call, trace } = makeAgentCallAndTrace();
+    const budget = new Budget();
+
+    const promise = executeAgentCall(call, runner, budget, new AbortController().signal, trace, undefined, fakeStream as never);
+    // 推进 retry 退避定时器（BACKOFF_BASE_MS = 1000，首退避 1s）
+    await vi.advanceTimersByTimeAsync(2000);
+    await promise;
+
+    expect(runner.run).toHaveBeenCalledTimes(2);
+    // 两次调用的第 4 参都是同一 stream 对象
+    expect(capturedStreams[0]).toBe(fakeStream);
+    expect(capturedStreams[1]).toBe(fakeStream);
+
+    vi.useRealTimers();
+  });
+});