@zhushanwen/pi-subagent-workflow 0.1.0

package/src/execution/__tests__/session-reconstructor.test.ts

@@ -0,0 +1,359 @@
+// src/__tests__/session-reconstructor.test.ts
+//
+// session-reconstructor 专属测试。
+// 覆盖：从 session.jsonl 重建 turns[]/usage/result/error/eventLog；
+//      identity custom entry 解析；toolCall↔toolResult 配对；
+//      防御性降级（文件缺失/损坏/缺 identity/无 assistant message）。
+//
+// 用 tmpdir + 真实 .jsonl 文件（隔离文件系统）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { IDENTITY_CUSTOM_TYPE, reconstructFromFile } from "../session-reconstructor.ts";
+
+/** 写一行到文件（JSON.stringify + 换行）。 */
+function writeLine(file: number | fs.PathOrFileDescriptor, obj: unknown): void {
+  fs.writeSync(file, `${JSON.stringify(obj)}\n`);
+}
+
+/** session header 行。 */
+function headerLine(cwd = "/tmp"): unknown {
+  return { type: "session", version: 3, id: "sess-uuid", timestamp: "2026-01-01T00:00:00.000Z", cwd };
+}
+
+/** identity custom entry。 */
+function identityEntry(identity: object): unknown {
+  return {
+    type: "custom", id: "id-1", parentId: null, timestamp: "2026-01-01T00:00:00.000Z",
+    customType: IDENTITY_CUSTOM_TYPE, data: identity,
+  };
+}
+
+/** assistant message entry（content blocks + usage + stopReason）。 */
+function assistantEntry(
+  blocks: object[],
+  opts: { usage?: object; stopReason?: string; errorMessage?: string; ts?: number; parentId?: string } = {},
+): unknown {
+  return {
+    type: "message", id: `msg-${Math.random().toString(36).slice(2, 8)}`,
+    parentId: opts.parentId ?? "id-1",
+    timestamp: new Date(opts.ts ?? 1000).toISOString(),
+    message: {
+      role: "assistant",
+      content: blocks,
+      usage: opts.usage ?? { input: 10, output: 20, cacheRead: 0, cacheWrite: 0, totalTokens: 30, cost: { total: 0 } },
+      stopReason: opts.stopReason ?? "stop",
+      errorMessage: opts.errorMessage,
+      timestamp: opts.ts ?? 1000,
+    },
+  };
+}
+
+/** toolResult message entry。 */
+function toolResultEntry(toolCallId: string, toolName: string, opts: { isError?: boolean; parentId?: string; text?: string } = {}): unknown {
+  return {
+    type: "message", id: `tr-${Math.random().toString(36).slice(2, 8)}`,
+    parentId: opts.parentId ?? "id-1",
+    timestamp: new Date(2000).toISOString(),
+    message: {
+      role: "toolResult", toolCallId, toolName,
+      content: [{ type: "text", text: opts.text ?? "result" }],
+      isError: opts.isError ?? false,
+      timestamp: 2000,
+    },
+  };
+}
+
+describe("reconstructFromFile", () => {
+  let tmpDir: string;
+  let filePath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sr-test-"));
+    filePath = path.join(tmpDir, "test.jsonl");
+  });
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writeJsonl(lines: unknown[]): void {
+    const fd = fs.openSync(filePath, "w");
+    for (const line of lines) writeLine(fd, line);
+    fs.closeSync(fd);
+  }
+
+  // ============================================================
+  // 基本重建
+  // ============================================================
+  describe("基本重建", () => {
+    it("单 assistant message → 1 turn，text/usage 正确", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "bg-1", agent: "worker", mode: "background", task: "do it", startedAt: 500 }),
+        assistantEntry([{ type: "text", text: "hello world" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec).toBeDefined();
+      expect(rec!.id).toBe("bg-1");
+      expect(rec!.agent).toBe("worker");
+      expect(rec!.mode).toBe("background");
+      expect(rec!.task).toBe("do it");
+      expect(rec!.status).toBe("done");
+      expect(rec!.turns).toHaveLength(1);
+      expect(rec!.turns[0].text).toBe("hello world");
+      expect(rec!.turnCount).toBe(1);
+      expect(rec!.totalTokens).toBe(30); // 10+20+0+0
+      expect(rec!.result).toBe("hello world");
+    });
+
+    it("thinking block 累积进 turn.thinking", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        assistantEntry([
+          { type: "thinking", thinking: "let me think" },
+          { type: "text", text: "answer" },
+        ]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.turns[0].thinking).toBe("let me think");
+      expect(rec!.turns[0].text).toBe("answer");
+    });
+
+    it("多 assistant message → 多 turn，result 用空行拼接", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "first" }], { ts: 1000 }),
+        assistantEntry([{ type: "text", text: "second" }], { ts: 2000, parentId: undefined }),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.turns).toHaveLength(2);
+      expect(rec!.turnCount).toBe(2);
+      expect(rec!.result).toBe("first\n\nsecond");
+    });
+
+    it("读出 identity 里的 rootSessionId", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "bg-1", agent: "w", mode: "background", task: "t", startedAt: 100, rootSessionId: "sess-A" }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.rootSessionId).toBe("sess-A");
+    });
+
+    it("旧文件 identity 写 parentSessionId → fallback 读到 rootSessionId（向后兼容）", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "bg-1", agent: "w", mode: "background", task: "t", startedAt: 100, parentSessionId: "sess-legacy" }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.rootSessionId).toBe("sess-legacy");
+    });
+
+    it("identity 无 rootSessionId（旧文件）→ rootSessionId 为 undefined", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "bg-1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.rootSessionId).toBeUndefined();
+    });
+
+    it("读出 identity 里的 parentRecordId/depth（递归层级）", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "run-2", agent: "w", mode: "sync", task: "t", startedAt: 100, rootSessionId: "sess-A", parentRecordId: "run-1", depth: 2 }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.parentRecordId).toBe("run-1");
+      expect(rec!.depth).toBe(2);
+    });
+
+    it("旧文件无 parentRecordId/depth → 兑底 undefined/0（顶层）", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "bg-1", agent: "w", mode: "background", task: "t", startedAt: 100, rootSessionId: "sess-A" }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.parentRecordId).toBeUndefined();
+      expect(rec!.depth).toBe(0);
+    });
+
+    it("endedAt 为最后一条 entry 的时间戳（非 now）", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "bg-1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "first" }], { ts: 1000 }),
+        assistantEntry([{ type: "text", text: "second" }], { ts: 5000, parentId: undefined }),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.endedAt).toBe(5000);
+    });
+  });
+
+  // ============================================================
+  // toolCall ↔ toolResult 配对
+  // ============================================================
+  describe("toolCall 配对", () => {
+    it("toolCall + toolResult → InternalToolCall done", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        assistantEntry([
+          { type: "toolCall", id: "call-1", name: "read", arguments: { path: "/x.ts" } },
+        ]),
+        toolResultEntry("call-1", "read"),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.turns[0].toolCalls).toHaveLength(1);
+      const tc = rec!.turns[0].toolCalls[0];
+      expect(tc.toolName).toBe("read");
+      expect(tc._status).toBe("done");
+      expect(tc.isError).toBe(false);
+    });
+
+    it("toolResult isError → InternalToolCall failed", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        assistantEntry([
+          { type: "toolCall", id: "call-1", name: "bash", arguments: { command: "false" } },
+        ]),
+        toolResultEntry("call-1", "bash", { isError: true }),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.turns[0].toolCalls[0]._status).toBe("failed");
+      expect(rec!.turns[0].toolCalls[0].isError).toBe(true);
+    });
+
+    it("孤儿 toolResult（无匹配 toolCall）→ 丢弃，不崩", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+        toolResultEntry("nonexistent", "read"),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec).toBeDefined();
+      expect(rec!.turns[0].toolCalls).toHaveLength(0);
+    });
+  });
+
+  // ============================================================
+  // error / stopReason
+  // ============================================================
+  describe("error 处理", () => {
+    it("stopReason=error → lastError + error 字段", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "partial" }], {
+          stopReason: "error", errorMessage: "API timeout",
+        }),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.lastError).toBe("API timeout");
+      expect(rec!.error).toBe("API timeout");
+      expect(rec!.status).toBe("failed"); // error stopReason → failed
+    });
+
+    it("stopReason=aborted 无 errorMessage → lastError = 'aborted'", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "" }], { stopReason: "aborted" }),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.lastError).toBe("aborted");
+      expect(rec!.status).toBe("failed");
+    });
+
+    it("前序 error 但最后 stop → lastError 清除（镜像 turn_end 语义），status=done", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "oops" }], {
+          stopReason: "error", errorMessage: "transient", ts: 1000,
+        }),
+        assistantEntry([{ type: "text", text: "recovered" }], { stopReason: "stop", ts: 2000 }),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.lastError).toBeUndefined(); // 后续 stop 清除了 error
+      expect(rec!.status).toBe("done");
+      expect(rec!.result).toBe("oops\n\nrecovered");
+    });
+  });
+
+  // ============================================================
+  // eventLog 派生
+  // ============================================================
+  describe("eventLog 派生", () => {
+    it("tool_start + tool_end + turn_end 条目", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+        assistantEntry([
+          { type: "toolCall", id: "c1", name: "read", arguments: { path: "/x.ts" } },
+        ]),
+        toolResultEntry("c1", "read"),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      const types = rec!.eventLog.map((e) => e.type);
+      expect(types).toContain("tool_start");
+      expect(types).toContain("tool_end");
+      expect(types).toContain("turn_end");
+    });
+  });
+
+  // ============================================================
+  // 防御性降级
+  // ============================================================
+  describe("防御性降级", () => {
+    it("文件缺失 → undefined", () => {
+      expect(reconstructFromFile(path.join(tmpDir, "nonexistent.jsonl"))).toBeUndefined();
+    });
+
+    it("空文件 → undefined", () => {
+      fs.writeFileSync(filePath, "", "utf-8");
+      expect(reconstructFromFile(filePath)).toBeUndefined();
+    });
+
+    it("缺 identity custom entry → undefined", () => {
+      writeJsonl([
+        headerLine(),
+        assistantEntry([{ type: "text", text: "no identity" }]),
+      ]);
+      expect(reconstructFromFile(filePath)).toBeUndefined();
+    });
+
+    it("有 identity 但无 assistant message → undefined", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }),
+      ]);
+      expect(reconstructFromFile(filePath)).toBeUndefined();
+    });
+
+    it("损坏 JSON 行跳过，合法行仍解析", () => {
+      const fd = fs.openSync(filePath, "w");
+      fs.writeSync(fd, `${JSON.stringify(headerLine())}\n`);
+      fs.writeSync(fd, "THIS IS NOT JSON\n");
+      fs.writeSync(fd, `${JSON.stringify(identityEntry({ id: "r1", agent: "w", mode: "sync", task: "t", startedAt: 100 }))}\n`);
+      fs.writeSync(fd, `${JSON.stringify(assistantEntry([{ type: "text", text: "survived" }]))}\n`);
+      fs.closeSync(fd);
+      const rec = reconstructFromFile(filePath);
+      expect(rec).toBeDefined();
+      expect(rec!.result).toBe("survived");
+    });
+  });
+});

package/src/execution/__tests__/session-runner-schema-env.test.ts

@@ -0,0 +1,314 @@
+// src/__tests__/session-runner-schema-env.test.ts
+//
+// Wave 2 (issue #3): schemaEnv bridge 测试。
+//
+// 覆盖 test-matrix 用例:
+//   - T3.9  (boundary): schemaEnv 透传——传入时 childEnv 含 PI_WORKFLOW_SCHEMA
+//   - T3.11 (state):    schemaEnv 不传 → childEnv 无 PI_WORKFLOW_SCHEMA（BC-6 tool 层不变）
+//   - T3.16 (NFR-compatibility): schemaEnv 不传时 BC-6 childEnv 等价——不传时与合并前
+//     行为一致，不注入 PI_WORKFLOW_SCHEMA → structured-output tool 不注册
+//
+// 测试策略：
+//   - applySchemaEnvToChildEnv 纯函数单测（不依赖 runSpawn/spawn mock）
+//   - runSpawn 集成测试：通过 mock spawn 拦截 childEnv，验证 schemaEnv 实际注入
+//
+// D-A6: schemaEnv 经 RunOptions 透传到 runSpawn childEnv。
+// BC-6: tool 层 execute 不传 schemaEnv → childEnv 不设 PI_WORKFLOW_SCHEMA → 行为不变。
+
+import type { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── mock modules (与 run-spawn-integration.test.ts 同模式) ──
+
+vi.mock("node:child_process", async () => {
+  const { EventEmitter } = await import("node:events");
+  const { PassThrough } = await import("node:stream");
+
+  class FakeChild extends EventEmitter {
+    pid = 12345;
+    stdout = new PassThrough();
+    stderr = new PassThrough();
+    killed = false;
+    killSignal: string | undefined;
+    kill(sig?: string): boolean {
+      this.killed = true;
+      this.killSignal = sig;
+      return true;
+    }
+  }
+
+  return {
+    spawn: vi.fn(() => new FakeChild()),
+    execFileSync: vi.fn(() => ""),
+  };
+});
+
+vi.mock("node:fs", async () => {
+  const actual = await import("node:fs");
+  return {
+    default: {
+      ...actual,
+      mkdirSync: vi.fn(),
+      existsSync: vi.fn(() => false),
+      appendFileSync: vi.fn(),
+      writeFileSync: vi.fn(),
+      readdirSync: vi.fn(() => []),
+    },
+    mkdirSync: vi.fn(),
+    existsSync: vi.fn(() => false),
+    appendFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+    promises: actual.promises,
+  };
+});
+
+vi.mock("../alive-store.ts", () => ({
+  writeAliveMarker: vi.fn(),
+}));
+
+vi.mock("../temp-prompt.ts", () => ({
+  writePromptToTempFile: vi.fn(async (agent: string) => {
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { execFileSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
+
+import { createRecord } from "../execution-record.ts";
+import {
+  applySchemaEnvToChildEnv,
+  type RunOptions,
+  runSpawn,
+  type SessionRunnerContext,
+} from "../session-runner.ts";
+
+const mockSpawn = vi.mocked(spawn);
+const mockExec = vi.mocked(execFileSync);
+const mockExistsSync = vi.mocked(fs.existsSync);
+
+interface FakeChild {
+  pid: number;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  killed: boolean;
+  killSignal: string | undefined;
+  kill(sig?: string): boolean;
+  emit(event: string, ...args: unknown[]): boolean;
+}
+
+function getLastSpawnedChild(): FakeChild {
+  const result = mockSpawn.mock.results.at(-1);
+  if (!result) throw new Error("spawn was not called yet");
+  return result.value as unknown as FakeChild;
+}
+
+function getLastSpawnEnv(): Record<string, string | undefined> {
+  return mockSpawn.mock.calls.at(-1)?.[2]?.env as Record<string, string | undefined> ?? {};
+}
+
+/**
+ * 等待 runSpawn 内部调到 spawn。
+ * runSpawn 是 async，spawn 在 writePromptToTempFile await 之后才调。
+ */
+async function waitForSpawn(timeoutMs = 1000): Promise<void> {
+  const start = Date.now();
+  while (mockSpawn.mock.results.length === 0) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`spawn was not called within ${timeoutMs}ms`);
+    }
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+// ── 公共 fixture ──
+
+function makeRecord() {
+  return createRecord("test-1", {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "sync",
+    task: "test task",
+    startedAt: Date.now(),
+    rootSessionId: "s1",
+    parentRecordId: undefined,
+    depth: 0,
+  });
+}
+
+function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
+  return {
+    resolved: { model: { provider: "test", id: "model" }, thinkingLevel: undefined },
+    agentConfig: undefined,
+    appendSystemPrompt: undefined,
+    skillPath: undefined,
+    schema: undefined,
+    maxTurns: undefined,
+    graceTurns: undefined,
+    signal: undefined,
+    onEvent: undefined,
+    ...overrides,
+  };
+}
+
+function makeCtx(): SessionRunnerContext {
+  return {
+    cwd: "/fake/cwd",
+    agentDir: "/fake/agent",
+    skillDirs: [],
+    mainCwd: "/fake/cwd",
+  };
+}
+
+// ── applySchemaEnvToChildEnv 纯函数单测 ──
+
+describe("applySchemaEnvToChildEnv (T3.9/T3.11/T3.16)", () => {
+  // T3.11: schemaEnv 不传 → childEnv 无 PI_WORKFLOW_SCHEMA
+  it("T3.11: schemaEnv 不传时 childEnv 不含 PI_WORKFLOW_SCHEMA（BC-6）", () => {
+    const childEnv: Record<string, string | undefined> = { PATH: "/usr/bin" };
+    applySchemaEnvToChildEnv(childEnv, undefined);
+    expect(childEnv).not.toHaveProperty("PI_WORKFLOW_SCHEMA");
+    expect(childEnv.PATH).toBe("/usr/bin"); // 其他 key 不受影响
+  });
+
+  // T3.16: schemaEnv 不传时 BC-6 childEnv 等价——合并前后行为一致
+  it("T3.16: schemaEnv 不传时 childEnv 等价于合并前（BC-6，不注入 PI_WORKFLOW_SCHEMA）", () => {
+    const childEnv: Record<string, string | undefined> = {};
+    applySchemaEnvToChildEnv(childEnv, undefined);
+    // 不传 schemaEnv 时，childEnv 应与调用前完全一致（不含 PI_WORKFLOW_SCHEMA）
+    expect(Object.keys(childEnv)).toHaveLength(0);
+    expect(childEnv.PI_WORKFLOW_SCHEMA).toBeUndefined();
+  });
+
+  // T3.16 补充: schemaEnv 为空串也不注入（空串不是有效 schema）
+  it("T3.16 补充: schemaEnv 为空串时不注入（false-ish 语义）", () => {
+    const childEnv: Record<string, string | undefined> = {};
+    applySchemaEnvToChildEnv(childEnv, "");
+    expect(childEnv).not.toHaveProperty("PI_WORKFLOW_SCHEMA");
+  });
+
+  // T3.9: schemaEnv 传入 → childEnv 含 PI_WORKFLOW_SCHEMA
+  it("T3.9: schemaEnv 传入时 childEnv 含 PI_WORKFLOW_SCHEMA", () => {
+    const childEnv: Record<string, string | undefined> = {};
+    const schemaJson = '{"type":"object","properties":{"x":{"type":"number"}}}';
+    applySchemaEnvToChildEnv(childEnv, schemaJson);
+    expect(childEnv.PI_WORKFLOW_SCHEMA).toBe(schemaJson);
+  });
+
+  // T3.9 补充: schemaEnv 值为复杂 JSON 字符串时正确透传
+  it("T3.9 补充: schemaEnv 值为复杂 JSON 字符串时完整透传", () => {
+    const childEnv: Record<string, string | undefined> = {};
+    const schemaJson = JSON.stringify({
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        age: { type: "number", minimum: 0 },
+      },
+      required: ["name"],
+    });
+    applySchemaEnvToChildEnv(childEnv, schemaJson);
+    expect(childEnv.PI_WORKFLOW_SCHEMA).toBe(schemaJson);
+    // 验证可以 parse 回原始结构
+    expect(() => JSON.parse(childEnv.PI_WORKFLOW_SCHEMA!)).not.toThrow();
+  });
+
+  // T3.9 补充: schemaEnv 与已有 key 不冲突
+  it("T3.9 补充: schemaEnv 注入不覆盖 childEnv 已有 key", () => {
+    const childEnv: Record<string, string | undefined> = {
+      PATH: "/usr/bin",
+      HOME: "/home/user",
+    };
+    applySchemaEnvToChildEnv(childEnv, '{"x":1}');
+    expect(childEnv.PATH).toBe("/usr/bin");
+    expect(childEnv.HOME).toBe("/home/user");
+    expect(childEnv.PI_WORKFLOW_SCHEMA).toBe('{"x":1}');
+  });
+});
+
+// ── runSpawn 集成测试：schemaEnv 经 RunOptions → childEnv ──
+
+describe("runSpawn schemaEnv childEnv 注入 (T3.9/T3.11)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockExistsSync.mockReturnValue(false);
+    mockExec.mockReturnValue("");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // T3.11: schemaEnv 不传 → childEnv 的 PI_WORKFLOW_SCHEMA 保持 process.env 原值
+  // BC-6: applySchemaEnvToChildEnv 不注入新值，但 process.env 可能已有此 key（子进程继承父环境）。
+  // 验证点: 不传 schemaEnv 时我们的代码不修改 PI_WORKFLOW_SCHEMA。
+  it("T3.11 (integration): RunOptions 无 schemaEnv → childEnv 继承 process.env 原值（BC-6）", async () => {
+    const record = makeRecord();
+    const opts = makeRunOpts({ schemaEnv: undefined });
+    const ctx = makeCtx();
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+    const childEnv = getLastSpawnEnv();
+    // BC-6: schemaEnv 未传入 → PI_WORKFLOW_SCHEMA 应为 process.env 原值（我们的代码不注入）
+    expect(childEnv.PI_WORKFLOW_SCHEMA).toBe(process.env.PI_WORKFLOW_SCHEMA);
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  // T3.9: schemaEnv 传入 → childEnv 含 PI_WORKFLOW_SCHEMA
+  it("T3.9 (integration): RunOptions 有 schemaEnv → childEnv 含 PI_WORKFLOW_SCHEMA", async () => {
+    const record = makeRecord();
+    const schemaJson = '{"type":"object","properties":{"result":{"type":"string"}}}';
+    const opts = makeRunOpts({ schemaEnv: schemaJson });
+    const ctx = makeCtx();
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+    const childEnv = getLastSpawnEnv();
+    expect(childEnv.PI_WORKFLOW_SCHEMA).toBe(schemaJson);
+
+    // 关闭子进程
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  // T3.9 + fork: schemaEnv 与 fork env 共存时不冲突
+  it("T3.9 + fork: schemaEnv 与 fork depth env 共存不冲突", async () => {
+    const record = createRecord("test-fork-1", {
+      agent: "general-purpose",
+      model: "test/model",
+      mode: "sync",
+      task: "test task",
+      startedAt: Date.now(),
+      rootSessionId: "s1",
+      parentRecordId: undefined,
+      depth: 1,
+    });
+    const schemaJson = '{"type":"object"}';
+    const opts = makeRunOpts({
+      schemaEnv: schemaJson,
+      fork: true,
+      parentForkDepth: 0,
+    });
+    const ctx = makeCtx();
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+    const childEnv = getLastSpawnEnv();
+    // fork depth env 应存在
+    expect(childEnv.PI_SUBAGENT_FORK_DEPTH).toBe("1");
+    // schemaEnv 也应存在
+    expect(childEnv.PI_WORKFLOW_SCHEMA).toBe(schemaJson);
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+});