@zhushanwen/subagent-core 0.2.0

package/src/execution/__tests__/subprocess-agent-runner.test.ts

@@ -0,0 +1,612 @@
+// src/execution/__tests__/subprocess-agent-runner.test.ts
+//
+// Wave 4: SubprocessAgentRunner 委托重写测试
+//
+// 覆盖 test-matrix 用例：
+//   T3.1  (正常): SAR 委托 executeAndAwait 返回 content
+//   T3.2  (正常): parsedOutput 透传
+//   T3.4  (边界): cwd 透传（非 git worktree）
+//   T3.5  (边界): model 填底（opts.model 空 → ctxModel）
+//   T3.6  (异常): timeoutMs 超时 → signal abort → error
+//   T3.7  (正常): onEvent 桥接 AgentEvent 透传
+//   T3.17 (NFR): mergeTimeoutSignal listener 清理
+//   T3.18 (NFR): dispose 兜底覆盖（delegate 后子进程进 spawnedChildren）
+//   T3.19 (NFR): AgentCallOpts→ExecuteOptions 映射保真
+
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// u0-data-discovery 注入化：getEngineDataDir 回退段经 HostServices.dataRoot() 端口，
+// 未 configureCore 即消费会抛 core_host_not_configured（SAR.run 内部调用，dataRoot
+// 值不被本文件断言）——端口态显式配置，测试隔离经 resetCoreForTests
+import { configureCore, resetCoreForTests } from "../../core/host-services.ts";
+
+import type { AgentCallOpts, AgentResult } from "../../orchestration/models/types.ts";
+import { ModelConfigService, setModelConfigService } from "../model-config-service.ts";
+import type { ModelRegistryLike } from "../model-resolver.ts";
+import { replayJournal } from "../engine/common/event-journal.ts";
+import type { SubprocessAgentRunnerDeps } from "../subprocess-agent-runner.ts";
+import { SubprocessAgentRunner } from "../subprocess-agent-runner.ts";
+
+// ── 测试辅助 ──
+
+/** 构造 mock SubagentService.executeAndAwait 返回值 */
+function makeMockResult(overrides: Partial<AgentResult> = {}): AgentResult {
+  return {
+    content: "OK",
+    parsedOutput: undefined,
+    durationMs: 100,
+    error: undefined,
+    sessionId: undefined,
+    toolCalls: [],
+    ...overrides,
+  };
+}
+
+/** 创建 mock SubagentService（只实现 executeAndAwait） */
+function createMockService(impl?: typeof vi.fn) {
+  const executeAndAwait = impl ?? vi.fn().mockResolvedValue(makeMockResult());
+  return { executeAndAwait } as unknown as {
+    executeAndAwait: (
+      opts: Record<string, unknown>,
+      signal?: AbortSignal,
+      onEvent?: (e: Record<string, unknown>) => void,
+      stream?: unknown,
+    ) => Promise<AgentResult>;
+  };
+}
+
+function makeBaseOpts(): AgentCallOpts {
+  return {
+    prompt: "test task",
+    agent: "worker",
+    cwd: "/some/path",
+    schema: undefined,
+    model: undefined,
+    scene: undefined,
+    description: undefined,
+    timeoutMs: undefined,
+    skill: undefined,
+    skillPath: undefined,
+    appendSystemPrompt: undefined,
+    schemaEnv: undefined,
+  };
+}
+
+// ── T3.1: 正常路径 ──
+
+describe("SubprocessAgentRunner (wave-4 delegate)", () => {
+  beforeEach(() => {
+    configureCore({ dataRoot: () => "/fake-sar-data-root", log: () => {} });
+  });
+
+  afterEach(() => {
+    resetCoreForTests();
+  });
+
+  // ────────────────────────────────────────────────
+  // T3.1: 正常路径 — SAR 委托 executeAndAwait 返回 content
+  // ────────────────────────────────────────────────
+  describe("T3.1 主流程", () => {
+    it("委托 executeAndAwait 并返回 content", async () => {
+      const mockService = createMockService(
+        vi.fn().mockResolvedValue(makeMockResult({ content: "hello world" })),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const opts = makeBaseOpts();
+      const signal = new AbortController().signal;
+
+      const result = await sar.run(opts, signal);
+
+      expect(result.content).toBe("hello world");
+      expect(mockService.executeAndAwait).toHaveBeenCalledTimes(1);
+    });
+
+    it("不 reject — 失败信息入 result.error", async () => {
+      const mockService = createMockService(
+        vi.fn().mockResolvedValue(makeMockResult({ error: "some error" })),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const result = await sar.run(makeBaseOpts(), new AbortController().signal);
+      expect(result.error).toBe("some error");
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // T3.2: parsedOutput 透传
+  // ────────────────────────────────────────────────
+  describe("T3.2 parsedOutput 透传", () => {
+    it("parsedOutput 直通", async () => {
+      const parsedData = { x: 1, y: 2 };
+      const mockService = createMockService(
+        vi.fn().mockResolvedValue(makeMockResult({ content: "ok", parsedOutput: parsedData })),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const result = await sar.run(makeBaseOpts(), new AbortController().signal);
+      expect(result.parsedOutput).toEqual(parsedData);
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // T3.4: cwd 透传
+  // ────────────────────────────────────────────────
+  describe("T3.4 cwd 透传", () => {
+    it("cwd 传入 executeAndAwait 的 ExecuteOptions", async () => {
+      let capturedOpts: Record<string, unknown> | undefined;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((opts: Record<string, unknown>) => {
+          capturedOpts = opts;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const opts = { ...makeBaseOpts(), cwd: "/custom/cwd" };
+      await sar.run(opts, new AbortController().signal);
+
+      expect(capturedOpts).toBeDefined();
+      expect(capturedOpts!.cwd).toBe("/custom/cwd");
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // T3.5: model 填底
+  // ────────────────────────────────────────────────
+  describe("T3.5 model 填底 (D-008)", () => {
+    it("opts.model 优先", async () => {
+      let capturedOpts: Record<string, unknown> | undefined;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((opts: Record<string, unknown>) => {
+          capturedOpts = opts;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const ctxModel = { id: "ctx-model", provider: "test", input: [] };
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService, ctxModel };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const opts = { ...makeBaseOpts(), model: "explicit-model" };
+      await sar.run(opts, new AbortController().signal);
+
+      expect(capturedOpts!.model).toBe("explicit-model");
+    });
+
+    it("opts.model 空 → ctxModel", async () => {
+      let capturedOpts: Record<string, unknown> | undefined;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((opts: Record<string, unknown>) => {
+          capturedOpts = opts;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const ctxModel = { id: "ctx-model", provider: "test", input: [] };
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService, ctxModel };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const opts = { ...makeBaseOpts(), model: undefined };
+      await sar.run(opts, new AbortController().signal);
+
+      // 修复后：opts.model 不再从 ctxModel.id 填底，ctxModel 作为完整对象透传
+      expect(capturedOpts!.model).toBeUndefined();
+      expect(capturedOpts!.ctxModel).toBe(ctxModel);
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // [U1 D2] RunContext.modelRef 接入：ctxModel 继承路径孪生守卫
+  // ────────────────────────────────────────────────
+  describe("U1 ctxModel twin guard (RunContext.modelRef 接入)", () => {
+    const prevDataDir = process.env["XYZ_AGENT_DATA_DIR"];
+    let tmpRoot = "";
+
+    /** 装配含指定快照的 ModelConfigService 单例（initModel 注入 registry）。 */
+    function installModelService(registry: ModelRegistryLike): void {
+      tmpRoot = mkdtempSync(join(tmpdir(), "sar-model-ref-"));
+      process.env["XYZ_AGENT_DATA_DIR"] = join(tmpRoot, "engine-data");
+      const svc = new ModelConfigService({ agentDir: join(tmpRoot, "agent"), cwd: tmpRoot });
+      svc.initModel({ modelRegistry: registry, sessionId: "sar-guard" });
+      setModelConfigService(svc);
+    }
+
+    afterEach(() => {
+      // 单例 slot 无 reset API，重装一个空注册服务隔离后续用例（同文件后续
+      // describe 不消费 ctxModel 守卫，getGlobalConfig 对空目录返回默认值）
+      if (tmpRoot) {
+        const svc = new ModelConfigService({ agentDir: join(tmpRoot, "agent"), cwd: tmpRoot });
+        svc.initModel({ modelRegistry: { getAvailable: () => [], find: () => undefined, hasConfiguredAuth: () => false }, sessionId: "cleanup" });
+        setModelConfigService(svc);
+        rmSync(tmpRoot, { recursive: true, force: true });
+        tmpRoot = "";
+      }
+      if (prevDataDir === undefined) delete process.env["XYZ_AGENT_DATA_DIR"];
+      else process.env["XYZ_AGENT_DATA_DIR"] = prevDataDir;
+    });
+
+    it("P-A2 拒单路径：ctxModel 命中但 registry 含孪生 → run 返回 error（ambiguous），executeAndAwait 未被调", async () => {
+      const models = [
+        { id: "GLM-5.3-Flash", name: "flash", provider: "zai-coding-cn", reasoning: false },
+        { id: "glm-5.3-flash", name: "flash lower", provider: "zai-coding-cn", reasoning: false },
+      ];
+      installModelService({
+        getAvailable: () => models,
+        find: (p, id) => models.find((m) => m.provider === p && m.id === id),
+        hasConfiguredAuth: () => true,
+      });
+      const mockService = createMockService();
+      const sar = new SubprocessAgentRunner({
+        subagentService: mockService as unknown as SubprocessAgentRunnerDeps["subagentService"],
+        ctxModel: { id: "GLM-5.3-Flash", name: "flash", provider: "zai-coding-cn", reasoning: false },
+      });
+
+      const result = await sar.run(makeBaseOpts(), new AbortController().signal);
+
+      expect(result.error).toMatch(/ambiguous case variants/);
+      expect(result.content).toBe("");
+      // 守卫在 engine.run 之前：不产生任何 record/spawn（委托零发生）
+      expect(mockService.executeAndAwait).not.toHaveBeenCalled();
+    });
+
+    it("P-A2 放行路径：无孪生 registry 下同 ctxModel 正常委托（守卫零误伤）", async () => {
+      const models = [
+        { id: "GLM-5.3-Flash", name: "flash", provider: "zai-coding-cn", reasoning: false },
+      ];
+      installModelService({
+        getAvailable: () => models,
+        find: (p, id) => models.find((m) => m.provider === p && m.id === id),
+        hasConfiguredAuth: () => true,
+      });
+      const mockService = createMockService(
+        vi.fn().mockResolvedValue(makeMockResult({ content: "ok" })),
+      );
+      const sar = new SubprocessAgentRunner({
+        subagentService: mockService as unknown as SubprocessAgentRunnerDeps["subagentService"],
+        ctxModel: { id: "GLM-5.3-Flash", name: "flash", provider: "zai-coding-cn", reasoning: false },
+      });
+
+      const result = await sar.run(makeBaseOpts(), new AbortController().signal);
+
+      expect(result.error).toBeUndefined();
+      expect(result.content).toBe("ok");
+      expect(mockService.executeAndAwait).toHaveBeenCalledTimes(1);
+    });
+
+    it("ctxModel 未指定时守卫跳过（无单例也不阻断）", async () => {
+      const mockService = createMockService(
+        vi.fn().mockResolvedValue(makeMockResult({ content: "ok" })),
+      );
+      const sar = new SubprocessAgentRunner({
+        subagentService: mockService as unknown as SubprocessAgentRunnerDeps["subagentService"],
+      });
+      const result = await sar.run(makeBaseOpts(), new AbortController().signal);
+      expect(result.content).toBe("ok");
+      expect(mockService.executeAndAwait).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // H1: SAR ctxModel 刷新（model_select 后不再 stale）
+  // ────────────────────────────────────────────────
+  describe("H1 ctxModel refresh via updateCtxModel", () => {
+    it("updateCtxModel 后 run() 传入新的 ctxModel 而非旧值", async () => {
+      let capturedOpts: Record<string, unknown> | undefined;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((opts: Record<string, unknown>) => {
+          capturedOpts = opts;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const oldModel = { id: "old-model", provider: "test", input: [] };
+      const newModel = { id: "new-model", provider: "test", input: [] };
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService, ctxModel: oldModel };
+      const sar = new SubprocessAgentRunner(deps);
+
+      // 模拟 model_select：刷新 ctxModel
+      sar.updateCtxModel(newModel);
+
+      const opts = { ...makeBaseOpts(), model: undefined };
+      await sar.run(opts, new AbortController().signal);
+
+      expect(capturedOpts!.ctxModel).toBe(newModel);
+      expect(capturedOpts!.ctxModel).not.toBe(oldModel);
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // T3.6: timeoutMs 超时 → signal abort → error
+  // ────────────────────────────────────────────────
+  describe("T3.6 timeoutMs 超时", () => {
+    it("timeoutMs > 0 → merged signal 传给 executeAndAwait", async () => {
+      let capturedSignal: AbortSignal | undefined;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((_opts: Record<string, unknown>, signal?: AbortSignal) => {
+          capturedSignal = signal;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const opts = { ...makeBaseOpts(), timeoutMs: 5000 };
+      await sar.run(opts, new AbortController().signal);
+
+      // 有 timeoutMs 时 merged signal 不等于原始 signal
+      expect(capturedSignal).toBeDefined();
+    });
+
+    it("timeoutMs 到期 → merged signal.aborted=true", async () => {
+      vi.useFakeTimers();
+      let capturedSignal: AbortSignal | undefined;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((_opts: Record<string, unknown>, signal?: AbortSignal) => {
+          capturedSignal = signal;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const opts = { ...makeBaseOpts(), timeoutMs: 50 };
+      sar.run(opts, new AbortController().signal);
+
+      // 推进 51ms 后 merged signal 应 abort
+      vi.advanceTimersByTime(51);
+
+      expect(capturedSignal?.aborted).toBe(true);
+      vi.useRealTimers();
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // T3.7: onEvent 桥接
+  // ────────────────────────────────────────────────
+  describe("T3.7 onEvent 桥接", () => {
+    it("executeAndAwait 的 onEvent 透传到 workflow onEvent", async () => {
+      const mockService = createMockService(
+        vi.fn().mockImplementation(
+          (_opts: Record<string, unknown>, _signal?: AbortSignal, onEvent?: (e: Record<string, unknown>) => void) => {
+            // 模拟 executeAndAwait 触发 onEvent
+            onEvent?.({ type: "tool_start", toolName: "read", args: { path: "/a.txt" } });
+            return Promise.resolve(makeMockResult());
+          },
+        ),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const workflowOnEvent = vi.fn();
+      await sar.run(makeBaseOpts(), new AbortController().signal, workflowOnEvent);
+
+      // workflow 的 onEvent 应被调用
+      expect(workflowOnEvent).toHaveBeenCalledTimes(1);
+      expect(workflowOnEvent).toHaveBeenCalledWith({
+        type: "tool_start",
+        toolName: "read",
+        args: { path: "/a.txt" },
+      });
+    });
+
+    it("无 workflow onEvent → 引擎仍收到包装 onEvent（P2 journal 通道恒开）", async () => {
+      let engineOnEvent: ((e: Record<string, unknown>) => void) | undefined;
+      const mockService = createMockService(
+        vi.fn().mockImplementation(
+          (_opts: Record<string, unknown>, _signal?: AbortSignal, onEvent?: (e: Record<string, unknown>) => void) => {
+            engineOnEvent = onEvent;
+            return Promise.resolve(makeMockResult());
+          },
+        ),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      await sar.run(makeBaseOpts(), new AbortController().signal);
+
+      // P2 接线（设计 D6 第②级）：SAR 包装 onEvent 写 journal 后转发——原 onEvent
+      // 未传时也恒传包装版（全引擎免费获得 journal；P1「undefined 透传」细节已被
+      // 有意变更，本用例锁定新语义：引擎侧 onEvent 通道恒开）
+      expect(typeof engineOnEvent).toBe("function");
+      // 包装版不向外抛（journal append 是同步入队）
+      expect(() => engineOnEvent?.({ type: "turn_end" })).not.toThrow();
+    });
+
+    it("P2 journal 接线：run 期间事件落盘 journal-<taskId>.jsonl（中立格式，可重放）", async () => {
+      vi.useFakeTimers({ toFake: [] }); // 真实 timers：journal 写盘走真实 fs
+      const dataDir = mkdtempSync(join(tmpdir(), "sar-journal-test-"));
+      const prevEnv = process.env.XYZ_AGENT_DATA_DIR;
+      process.env.XYZ_AGENT_DATA_DIR = dataDir;
+      try {
+        const mockService = createMockService(
+          vi.fn().mockImplementation(
+            (_opts: Record<string, unknown>, _signal?: AbortSignal, onEvent?: (e: Record<string, unknown>) => void) => {
+              onEvent?.({ type: "tool_start", toolName: "bash", args: { cmd: "ls" } });
+              onEvent?.({ type: "turn_end" });
+              return Promise.resolve(makeMockResult());
+            },
+          ),
+        );
+        const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+        const sar = new SubprocessAgentRunner(deps);
+
+        const workflowOnEvent = vi.fn();
+        await sar.run(makeBaseOpts(), new AbortController().signal, workflowOnEvent);
+
+        // journal 落在 <dataDir>/engines/pi/shared/journal-<taskId>.jsonl
+        const journalFile = join(dataDir, "engines", "pi", "shared");
+        const files = readdirSync(journalFile).filter((f) => f.startsWith("journal-") && f.endsWith(".jsonl"));
+        expect(files.length).toBe(1);
+        const replayed = replayJournal(join(journalFile, files[0] ?? ""));
+        expect(replayed).toEqual([
+          { type: "tool_start", toolName: "bash", args: { cmd: "ls" } },
+          { type: "turn_end" },
+        ]);
+        // workflow onEvent 照常透传（journal 包装不吞事件）
+        expect(workflowOnEvent).toHaveBeenCalledTimes(2);
+      } finally {
+        if (prevEnv === undefined) delete process.env.XYZ_AGENT_DATA_DIR;
+        else process.env.XYZ_AGENT_DATA_DIR = prevEnv;
+        rmSync(dataDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // T3.17: mergeTimeoutSignal listener 清理
+  // ────────────────────────────────────────────────
+  describe("T3.17 mergeTimeoutSignal listener 清理", () => {
+    it("外部 signal abort → timer 清理", async () => {
+      vi.useFakeTimers();
+      const mockService = createMockService(
+        vi.fn().mockResolvedValue(makeMockResult()),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const ctrl = new AbortController();
+      const opts = { ...makeBaseOpts(), timeoutMs: 5000 };
+
+      // 启动 run（不 await，让它在后台）
+      const runPromise = sar.run(opts, ctrl.signal);
+
+      // 外部 abort
+      ctrl.abort();
+
+      await runPromise;
+
+      // 推进时间——timer 应已清理，不会造成副作用
+      vi.advanceTimersByTime(6000);
+      // 无异常 = listener 已正确清理
+      vi.useRealTimers();
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // T3.19: AgentCallOpts → ExecuteOptions 映射保真
+  // ────────────────────────────────────────────────
+  describe("T3.19 映射保真", () => {
+    it("prompt → task, agent → agent, schemaEnv 透传", async () => {
+      let capturedOpts: Record<string, unknown> | undefined;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((opts: Record<string, unknown>) => {
+          capturedOpts = opts;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const opts: AgentCallOpts = {
+        ...makeBaseOpts(),
+        prompt: "do the thing",
+        agent: "code-reviewer",
+        schemaEnv: '{"type":"object"}',
+        skillPath: "/skills/code-review.md",
+      };
+      await sar.run(opts, new AbortController().signal);
+
+      expect(capturedOpts).toBeDefined();
+      expect(capturedOpts!.task).toBe("do the thing");
+      expect(capturedOpts!.agent).toBe("code-reviewer");
+      expect(capturedOpts!.skillPath).toBe("/skills/code-review.md");
+      // schemaEnv 应通过 ExecuteOptions 透传
+      expect((capturedOpts as Record<string, unknown>).schemaEnv).toBe('{"type":"object"}');
+    });
+
+    it("schema 透传为原始对象", async () => {
+      let capturedOpts: Record<string, unknown> | undefined;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((opts: Record<string, unknown>) => {
+          capturedOpts = opts;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const opts = {
+        ...makeBaseOpts(),
+        schema: { type: "object", properties: { name: { type: "string" } } },
+      };
+      await sar.run(opts, new AbortController().signal);
+
+      expect(capturedOpts!.schema).toEqual({
+        type: "object",
+        properties: { name: { type: "string" } },
+      });
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // T3.18: executeAndAwait throw → catch → error
+  // ────────────────────────────────────────────────
+  describe("T3.18 异常处理", () => {
+    it("executeAndAwait throw → 不 reject，返回 error", async () => {
+      const mockService = createMockService(
+        vi.fn().mockRejectedValue(new Error("nesting depth exceeded")),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const result = await sar.run(makeBaseOpts(), new AbortController().signal);
+      expect(result.error).toContain("nesting depth exceeded");
+      expect(result.content).toBe("");
+    });
+
+    it("非 Error throw → error 字段含 message", async () => {
+      const mockService = createMockService(
+        vi.fn().mockRejectedValue("raw string error"),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const result = await sar.run(makeBaseOpts(), new AbortController().signal);
+      expect(result.error).toBe("raw string error");
+    });
+  });
+
+  // ────────────────────────────────────────────────
+  // U1: stream 透传给 executeAndAwait
+  // ────────────────────────────────────────────────
+  describe("U1 stream 透传", () => {
+    it("SAR.run 传 stream → executeAndAwait 第 4 参收到同一 stream 对象", async () => {
+      let capturedStream: unknown;
+      const mockService = createMockService(
+        vi.fn().mockImplementation((_opts, _sig, _onEvt, stream) => {
+          capturedStream = stream;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      const fakeStream = { onDelta: vi.fn(), dispose: vi.fn() };
+      await sar.run(makeBaseOpts(), new AbortController().signal, undefined, fakeStream as never);
+
+      expect(capturedStream).toBe(fakeStream);
+    });
+
+    it("SAR.run 不传 stream → executeAndAwait 第 4 参为 undefined", async () => {
+      let capturedStream: unknown = "sentinel";
+      const mockService = createMockService(
+        vi.fn().mockImplementation((_opts, _sig, _onEvt, stream) => {
+          capturedStream = stream;
+          return Promise.resolve(makeMockResult());
+        }),
+      );
+      const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+      const sar = new SubprocessAgentRunner(deps);
+
+      await sar.run(makeBaseOpts(), new AbortController().signal);
+
+      expect(capturedStream).toBeUndefined();
+    });
+  });
+});

package/src/execution/__tests__/temp-prompt.test.ts

@@ -0,0 +1,53 @@
+// src/__tests__/temp-prompt.test.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { cleanupTempPrompt, writePromptToTempFile } from "../temp-prompt.ts";
+
+describe("writePromptToTempFile", () => {
+  it("创建临时目录 + 写入 prompt 文件", async () => {
+    const result = await writePromptToTempFile("test-agent", "You are a helper.");
+    expect(result.dir).toBeTruthy();
+    expect(result.filePath).toBeTruthy();
+    expect(fs.existsSync(result.dir)).toBe(true);
+    expect(fs.existsSync(result.filePath)).toBe(true);
+
+    const content = fs.readFileSync(result.filePath, "utf-8");
+    expect(content).toBe("You are a helper.");
+
+    // 清理
+    await cleanupTempPrompt(result);
+    expect(fs.existsSync(result.dir)).toBe(false);
+  });
+
+  it("agentName 非法字符替换为下划线", async () => {
+    const result = await writePromptToTempFile("my agent/v2:spec", "prompt");
+    expect(path.basename(result.filePath)).toBe("prompt-my_agent_v2_spec.md");
+    await cleanupTempPrompt(result);
+  });
+
+  it("文件权限 0o600（仅 owner 读写）", async () => {
+    const result = await writePromptToTempFile("secure", "secret prompt");
+    const stat = fs.statSync(result.filePath);
+    // 只取低 9 位（rwxrwxrwx），忽略文件类型位
+    const mode = stat.mode & 0o777;
+    expect(mode).toBe(0o600);
+    await cleanupTempPrompt(result);
+  });
+
+  it("多字节内容（中文）正确写入", async () => {
+    const result = await writePromptToTempFile("cn", "你是一个助手。");
+    const content = fs.readFileSync(result.filePath, "utf-8");
+    expect(content).toBe("你是一个助手。");
+    await cleanupTempPrompt(result);
+  });
+});
+
+describe("cleanupTempPrompt", () => {
+  it("不存在的目录不抛错（best-effort）", async () => {
+    const fake = { dir: "/nonexistent/path/xyz", filePath: "/nonexistent/path/xyz/p.md" };
+    await expect(cleanupTempPrompt(fake)).resolves.not.toThrow();
+  });
+});