@zhushanwen/subagent-core 0.2.0

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@zhushanwen/subagent-core",
+  "version": "0.2.0",
+  "description": "Cross-host shared subagent execution layer and workflow orchestration core (dual-form npm package: TS source for workspace, dist ESM+CJS for npm)",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "default": "./dist/index.js"
+    },
+    "./engines/zcode/reader": {
+      "import": {
+        "types": "./dist/execution/engine/engines/zcode/reader.d.ts",
+        "default": "./dist/execution/engine/engines/zcode/reader.js"
+      },
+      "require": {
+        "types": "./dist/execution/engine/engines/zcode/reader.d.cts",
+        "default": "./dist/execution/engine/engines/zcode/reader.cjs"
+      },
+      "default": "./dist/execution/engine/engines/zcode/reader.js"
+    },
+    "./engines/zcode/constants": {
+      "import": {
+        "types": "./dist/execution/engine/engines/zcode/constants.d.ts",
+        "default": "./dist/execution/engine/engines/zcode/constants.js"
+      },
+      "require": {
+        "types": "./dist/execution/engine/engines/zcode/constants.d.cts",
+        "default": "./dist/execution/engine/engines/zcode/constants.cjs"
+      },
+      "default": "./dist/execution/engine/engines/zcode/constants.js"
+    },
+    "./engine/paths": {
+      "import": {
+        "types": "./dist/execution/engine/paths.d.ts",
+        "default": "./dist/execution/engine/paths.js"
+      },
+      "require": {
+        "types": "./dist/execution/engine/paths.d.cts",
+        "default": "./dist/execution/engine/paths.cjs"
+      },
+      "default": "./dist/execution/engine/paths.js"
+    },
+    "./relay-env": {
+      "import": {
+        "types": "./dist/execution/relay-env.d.ts",
+        "default": "./dist/execution/relay-env.js"
+      },
+      "require": {
+        "types": "./dist/execution/relay-env.d.cts",
+        "default": "./dist/execution/relay-env.cjs"
+      },
+      "default": "./dist/execution/relay-env.js"
+    },
+    "./workflows/*": {
+      "require": "./workflows/*",
+      "import": "./workflows/*",
+      "default": "./workflows/*"
+    }
+  },
+  "$comment": "D5 公共 API 面定稿（docs/design/subagent-core-package-extraction.md §3.3 D5）：公共面 = 主入口 barrel + 4 条语义子入口（./engines/zcode/reader、./engines/zcode/constants、./engine/paths、./relay-env）+ ./workflows/* 资产子入口。exports 面 = semver 契约，收窄不放宽。双形态（D4）：workspace TS 消费走 import 条件 -> src（与 extension-protocol 先例同型）；npm 消费走 publishConfig 发布面（npm publish 时整体替换 exports）：import -> dist ESM、require -> dist CJS。require 条件指向 dist CJS 是本仓首例，D4 依据：zsw 宿主为纯 CJS（node>=20），而 core 依赖的 @xyz-agent/extension-protocol npm dist 仅 ESM（.mjs），node 20 下 require() 加载 ESM 不可靠——因此对 extension-protocol 设 noExternal 防御性 bundle 边界（当前 entry 闭包无其运行时引用、dist 实测零常量命中；未来 entry 一旦引入运行时引用即 bundle），绝不让外部 ESM 依赖出现在 require 链上；require 分支的 types 用 .d.cts 对应。开发态 require 条件即指向 dist：dist 是 require 语义的真实载体，未 build 时 require 失败属预期（build 前置）。语义子入口精确条目优先于 `./*` 通配（Node 规范：exact match beats pattern），`./*` -> src 通配仅为仓内壳侧深路径消费保留（壳侧 `<pkg>/<域>/<路径>.ts` 形态 import，量级百处、以 grep 实测为准，不在此固化易过期数字），发布面刻意不带该通配——npm 消费面收窄到上列受控入口。workflows/ 资产 .cjs/.js 不编译（D1：src=dist 同字节直发），require/import 条件同径。tsup 多入口保形输出见 tsup.config.ts（dist/<entry> 与 src 同构，d.ts/d.cts 全覆盖）。",
+  "files": [
+    "src/",
+    "workflows/",
+    "dist/"
+  ],
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.9.0",
+    "@xyz-agent/extension-protocol": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/agent-opts-resolver-schema-prompt.test.ts

@@ -0,0 +1,142 @@
+// agent-opts-resolver schema prompt wording lock (suggestion #4).
+//
+// M2 修正后 resolveAgentOpts 把 schema structured-output 指令内容直传进
+// appendSystemPrompt（不再写临时文件、不再 push 路径）。本测试锁死 SO 指令措辞 +
+// 验证 agent 正文不经此通道（防双重注入回归）。
+//
+// 覆盖 design.json TC1（措辞）/ TC2（无 schema）/ TC3（不处理 agent ref）。
+
+import { describe, expect, it } from "vitest";
+
+import type { AgentCallOpts } from "../orchestration/models/types.ts";
+import { resolveAgentOpts } from "../orchestration/agent-opts-resolver.ts";
+
+describe("resolveAgentOpts schema prompt wording + M2 content passthrough", () => {
+  it("schema 提供时 appendSystemPrompt 含 SO 指令内容（TC1 措辞锁）", () => {
+    const opts: AgentCallOpts = {
+      prompt: "do the thing",
+      schema: { type: "object" },
+      agent: "/abs/path/worker.md",
+    };
+    const result = resolveAgentOpts(opts);
+
+    expect(result.error).toBeUndefined();
+    expect(result.opts.appendSystemPrompt).toBeDefined();
+    expect(result.opts.appendSystemPrompt!.length).toBe(1);
+
+    const content = result.opts.appendSystemPrompt![0];
+    // 措辞锁（单参数口径）：工具参数即结果数据本身，schema 已无独立 data 参数
+    expect(content).toContain("Your call arguments ARE the result data itself");
+    expect(content).toContain("Your result must conform to this schema:");
+    expect(content).toContain("The system validates them against the schema above automatically");
+    // 反向回流锁：旧双参数口径文案（"do NOT pass a schema parameter" / "ONLY the data
+    // parameter"）一旦回流立即失败
+    expect(content).not.toMatch(
+      /do NOT pass a .schema. parameter|ONLY the .data. parameter/i,
+    );
+    // 内容直传（M2 fix）：非路径
+    expect(content).not.toMatch(/\/tmp\/|\/var\/folders\//);
+    expect(content).not.toMatch(/\.md$/);
+  });
+
+  it("无 schema 无 skill 时 appendSystemPrompt undefined（TC2）", () => {
+    const opts: AgentCallOpts = {
+      prompt: "x",
+      agent: "/abs/path/worker.md",
+      description: "test",
+      slug: "test",
+    };
+    const result = resolveAgentOpts(opts);
+
+    expect(result.error).toBeUndefined();
+    expect(result.opts.appendSystemPrompt).toBeUndefined();
+    // agent ref 原样保留（交 resolveIdentity 处理）
+    expect(result.opts.agent).toBe("/abs/path/worker.md");
+  });
+
+  it("resolveAgentOpts 不处理 agent ref——不存在路径不报错（TC3）", () => {
+    const opts: AgentCallOpts = {
+      prompt: "x",
+      agent: "/nonexistent/agent.md",
+    };
+    const result = resolveAgentOpts(opts);
+
+    // resolveAgentOpts 不校验 agent 路径（已移交 resolveIdentity）
+    expect(result.error).toBeUndefined();
+    expect(result.opts.agent).toBe("/nonexistent/agent.md");
+    // model/thinkingLevel 不被 resolveAgentOpts 修改（agent 层级提升已消除）
+    expect(result.opts.model).toBeUndefined();
+    expect(result.opts.thinkingLevel).toBeUndefined();
+  });
+
+  it("sets schemaEnv from the provided schema (PI_WORKFLOW_SCHEMA contract)", () => {
+    const schema: Record<string, unknown> = {
+      type: "object",
+      properties: { n: { type: "number" } },
+    };
+    const opts: AgentCallOpts = { prompt: "x", schema };
+    const result = resolveAgentOpts(opts);
+
+    expect(result.opts.schemaEnv).toBe(JSON.stringify(schema));
+  });
+
+  it("无 schema 时 schemaEnv undefined", () => {
+    const opts: AgentCallOpts = { prompt: "x" };
+    const result = resolveAgentOpts(opts);
+
+    expect(result.opts.schemaEnv).toBeUndefined();
+  });
+
+  // [U3] 根类型条件化：ASP 文案与 structured-output 工具 description 同源互斥——
+  // object 根口径「arguments ARE the data」；非 object 根参数层实为 {value} 包装，
+  // 文案必须告知 {value: <data>} 契约，两形态文案互斥不可共存。
+  describe("根类型条件化文案（U3：与工具 description 同源互斥）", () => {
+    it("object 根 → arguments 即 data 口径，无 {value} 包装语汇", () => {
+      const opts: AgentCallOpts = {
+        prompt: "x",
+        schema: { type: "object", properties: { n: { type: "number" } } },
+      };
+      const content = resolveAgentOpts(opts).opts.appendSystemPrompt![0];
+
+      expect(content).toContain("Your call arguments ARE the result data itself");
+      expect(content).not.toContain("{value:");
+      expect(content).not.toContain("value.");
+      // Rules 首条同样是 object 根口径
+      expect(content).toContain(
+        "- Call the structured-output tool with your result data as its arguments.",
+      );
+      expect(content).not.toContain("{value: <your result data>}");
+    });
+
+    it("非 object 根（array）→ {value} 包装契约语汇，无 arguments 即 data 口径", () => {
+      const opts: AgentCallOpts = {
+        prompt: "x",
+        schema: { type: "array", items: { type: "string" } },
+      };
+      const content = resolveAgentOpts(opts).opts.appendSystemPrompt![0];
+
+      // 包装契约与 value. 错误路径前缀（与工具 description 同语汇）
+      expect(content).toContain("{value: <data>}");
+      expect(content).toContain("value.");
+      expect(content).toContain("that prefix addresses the wrapper, not your data");
+      // 互斥：object 根专属文案不得出现
+      expect(content).not.toContain("Your call arguments ARE the result data itself");
+      expect(content).not.toContain(
+        "- Call the structured-output tool with your result data as its arguments.",
+      );
+      // Rules 首条切换为包装口径
+      expect(content).toContain("- Call the structured-output tool with `{value: <your result data>}`.");
+    });
+
+    it("组合根（anyOf，可能接受非 object 值）→ 按非 object 包装口径", () => {
+      const opts: AgentCallOpts = {
+        prompt: "x",
+        schema: { anyOf: [{ type: "string" }, { type: "number" }] },
+      };
+      const content = resolveAgentOpts(opts).opts.appendSystemPrompt![0];
+
+      expect(content).toContain("{value: <data>}");
+      expect(content).not.toContain("Your call arguments ARE the result data itself");
+    });
+  });
+});

package/src/__tests__/append-system-prompt-assembly.test.ts

@@ -0,0 +1,242 @@
+/**
+ * writeAppendSystemPromptFile 组装矩阵（W2 移交 CRAP 43.1；私有函数，经公共
+ * runSpawn 驱动，与 spawn-worktree-guidance.test.ts 同 mock 模式——mock
+ * temp-prompt 捕获 appendParts.join 后的完整 content）。
+ *
+ * 覆盖分支（session-runner.ts g. 段）：
+ *   - agentConfig.systemPrompt / appendSystemPrompt 片段 / maxTurns wrap-up hint 的注入与顺序
+ *   - ask_user RPC 提示的 mode 门控（rpc=gui 响应 / json=headless 不注入）
+ *   - maxTurns 缺省/0 → 不注入 wrap-up hint
+ *   - fork depth（env block Depth 行）与 ask_user+wrap-up 的组合互不干扰
+ *
+ * worktree 分支（WORKTREE_GUIDANCE_PROMPT）已由 spawn-worktree-guidance.test.ts
+ * 覆盖，此处不重复。
+ */
+import type { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const captured = vi.hoisted(() => ({ content: "", calls: 0 }));
+
+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();
+    stdin = 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("../execution/alive-store.ts", () => ({
+  writeAliveMarker: vi.fn(),
+}));
+
+vi.mock("../execution/temp-prompt.ts", () => ({
+  writePromptToTempFile: vi.fn(async (agent: string, content: string) => {
+    captured.calls++;
+    captured.content = content;
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { spawn } from "node:child_process";
+
+import { createRecord } from "../execution/execution-record.ts";
+import { runSpawn, type RunOptions, type SessionRunnerContext } from "../execution/session-runner.ts";
+
+const mockSpawn = vi.mocked(spawn);
+
+interface FakeChild {
+  pid: number;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  killed: boolean;
+  killSignal: string | undefined;
+  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 FakeChild;
+}
+
+/** 等待第 targetCount 次 spawn 发生（同测试多次 runSpawn 时按基线递增等待）。 */
+async function waitForSpawn(targetCount = 1, timeoutMs = 1000): Promise<void> {
+  const start = Date.now();
+  while (mockSpawn.mock.results.length < targetCount) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`spawn #${targetCount} not called within ${timeoutMs}ms`);
+    }
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+let seq = 0;
+
+function makeRecord() {
+  seq += 1;
+  return createRecord(`append-asm-${seq}`, {
+    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(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
+  return {
+    cwd: "/fake/cwd",
+    agentDir: "/fake/agent",
+    skillDirs: [],
+    mainCwd: "/fake/cwd",
+    sessionRootId: "root-session-test",
+    rootCwd: "/fake/cwd",
+    ...overrides,
+  };
+}
+
+/** 跑一次 runSpawn 并捕获 appendSystemPrompt content（完成后释放子进程）。 */
+async function captureAppendContent(opts: RunOptions, ctx: SessionRunnerContext): Promise<string> {
+  const baseline = mockSpawn.mock.results.length;
+  const resultPromise = runSpawn(makeRecord(), "test task", opts, ctx);
+  await waitForSpawn(baseline + 1);
+  const content = captured.content;
+  const child = getLastSpawnedChild();
+  child.emit("close", 0);
+  await resultPromise;
+  return content;
+}
+
+describe("writeAppendSystemPromptFile 组装（经 runSpawn 驱动）", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    captured.content = "";
+    captured.calls = 0;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("全片段组装：env block → agent body → 调用方片段 → wrap-up hint，顺序稳定", async () => {
+    const content = await captureAppendContent(
+      makeRunOpts({
+        agentConfig: { systemPrompt: "AGENT-BODY-MARKER" },
+        appendSystemPrompt: ["FRAG-ONE", "FRAG-TWO"],
+        maxTurns: 5,
+      }),
+      makeCtx(),
+    );
+    expect(content).toContain("AGENT-BODY-MARKER");
+    expect(content).toContain("FRAG-ONE");
+    expect(content).toContain("FRAG-TWO");
+    // maxTurns>0 → 注入 wrap-up 收尾提示（rpc steer 未接通的启动期补偿）
+    expect(content).toContain("You have a turn limit");
+    // 顺序：env block 最前，agent body 在调用方片段前，hint 在其后
+    const envIdx = content.indexOf("--- environment");
+    const bodyIdx = content.indexOf("AGENT-BODY-MARKER");
+    const fragIdx = content.indexOf("FRAG-ONE");
+    const hintIdx = content.indexOf("You have a turn limit");
+    expect(envIdx).toBeLessThan(bodyIdx);
+    expect(bodyIdx).toBeLessThan(fragIdx);
+    expect(fragIdx).toBeLessThan(hintIdx);
+  });
+
+  it("maxTurns 缺省/0 → 不注入 wrap-up hint（不限时不预告收尾）", async () => {
+    const undefinedCase = await captureAppendContent(makeRunOpts(), makeCtx());
+    expect(undefinedCase).not.toContain("You have a turn limit");
+    const zeroCase = await captureAppendContent(makeRunOpts({ maxTurns: 0 }), makeCtx());
+    expect(zeroCase).not.toContain("You have a turn limit");
+  });
+
+  it("ask_user RPC 提示 mode 门控：rpc（gui 响应）注入，json（headless）不注入", async () => {
+    const opts = makeRunOpts({ agentConfig: { tools: ["ask_user"] } });
+    const rpcContent = await captureAppendContent(opts, makeCtx({ mode: "rpc" }));
+    expect(rpcContent).toContain("ask_user Tool Availability");
+    const jsonContent = await captureAppendContent(opts, makeCtx({ mode: "json" }));
+    // headless 无 UI 通道，注入会误导 LLM（W4 守卫）
+    expect(jsonContent).not.toContain("ask_user Tool Availability");
+  });
+
+  it("mode 响应但 tools 不含 ask_user → 不注入", async () => {
+    const content = await captureAppendContent(
+      makeRunOpts({ agentConfig: { tools: ["read", "bash"] } }),
+      makeCtx({ mode: "rpc" }),
+    );
+    expect(content).not.toContain("ask_user Tool Availability");
+  });
+
+  it("fork 场景：parentForkDepth 传入 → env block 带 Depth 行（buildEnvBlock 取 max 语义）", async () => {
+    const content = await captureAppendContent(
+      makeRunOpts({ fork: true, parentForkDepth: 2 }),
+      makeCtx(),
+    );
+    expect(content).toContain("Depth:");
+    // 无 fork 无嵌套时不出现 Depth 行
+    const plain = await captureAppendContent(makeRunOpts(), makeCtx());
+    expect(plain).not.toContain("Depth:");
+  });
+
+  it("env block 恒为第一段：最小配置也落盘（writePromptToTempFile 必被调用）", async () => {
+    await captureAppendContent(makeRunOpts(), makeCtx());
+    expect(captured.calls).toBe(1);
+    expect(captured.content).toContain("Working directory: /fake/cwd");
+  });
+});

package/src/__tests__/builtin-workflows-structure.test.ts

@@ -0,0 +1,180 @@
+// U2 + E1: 内置 workflow 脚本 null guard 覆盖 + 文件结构一致性
+//
+// U2: agent() 失败时 resolve 成空字符串/undefined（设计行为），脚本直接访问
+// 返回值属性会 TypeError。验证 4 个内置脚本的 agent() 返回值属性访问均含
+// null guard（?. 或 ??），不遗留裸 .property 访问。
+//
+// E1: workflows/ 目录含 4 个 .js 文件，每个 meta.name 与文件名 stem 一致。
+
+import { readdirSync,readFileSync } from "node:fs";
+import { dirname,join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { parseResourceMeta } from "../shared/meta-parser.ts";
+
+import { describe, expect, it } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const WORKFLOWS_DIR = join(__dirname, "../../workflows");
+
+const SCRIPTS = ["chain.js", "parallel.js", "scatter-gather.js", "map-reduce.js", "review-fix-loop.js"] as const;
+
+function readScript(name: string): string {
+  return readFileSync(join(WORKFLOWS_DIR, name), "utf-8");
+}
+
+/** 提取 meta.name 值（经 IF1 parseResourceMeta，m2 收敛）。 */
+function extractMetaName(src: string): string | null {
+  const meta = parseResourceMeta(src, "workflow");
+  return meta && meta.kind === "workflow" ? meta.name : null;
+}
+
+describe("E1: 内置 workflow 文件结构一致性", () => {
+  it("workflows/ 目录含 5 个 .js 文件", () => {
+    const files = readdirSync(WORKFLOWS_DIR).filter((f) => f.endsWith(".js"));
+    expect(files.sort()).toEqual([...SCRIPTS].sort());
+  });
+
+  it.each(SCRIPTS)("meta.name 与文件名 stem 一致：%s", (filename) => {
+    const src = readScript(filename);
+    const metaName = extractMetaName(src);
+    const stem = filename.replace(/\.js$/, "");
+    expect(metaName).toBe(stem);
+  });
+});
+
+describe("U2: 内置脚本 agent() 返回值属性访问含 null guard", () => {
+  // 策略：检查脚本中 ?. 和 ?? 的出现次数 >= agent() 调用次数（每个 agent() 返回值
+  // 至少有一处属性访问需 guard）。更精确地：脚本不应有裸的 `变量.属性` 访问
+  // agent() 返回值——但区分 agent() 返回值和局部对象属性访问需要 AST 分析，
+  // 这里用启发式：验证含 agent() 结果属性访问的脚本都含 ?. 模式（null guard 已存在）。
+  //
+  // 注意：parallel.js 的 aggregate 段为纯代码 concat（无 LLM 聚合 agent()），
+  // 其 parallel() 多结果由 W4 的 r.status === "failed" / typeof / Array.isArray 守卫，
+  // 不再用 ?.，故不纳入此 ?. 启发式检查。
+  // map-reduce 的 reduce、scatter-gather 的 gather 恢复为 LLM agent() 调用，
+  // 故 map-reduce.js 重新纳入此检查。
+
+  // 仍含 agent() 返回值属性访问、需 ?. guard 的脚本：chain（analysis/plan/final）、
+  // scatter-gather（split 的 subtasks、gather 的 mergedResult/completeness）、
+  // map-reduce（reduce 的 reduced/stats）、review-fix-loop（aggRaw?.length 等）。
+  const GUARD_SCRIPTS = ["chain.js", "scatter-gather.js", "map-reduce.js", "review-fix-loop.js"] as const;
+
+  it.each(GUARD_SCRIPTS)("%s 含 optional chaining（?.）null guard 模式", (filename) => {
+    const src = readScript(filename);
+    // chain.js 至少有 6 处 ?. guard；scatter-gather.js 至少有 split/gather 多处；
+    // map-reduce.js 至少有 reduce 的 reduced/stats 多处
+    expect(src).toContain("?.");
+  });
+
+  it("chain.js 的 analysis/plan/final 属性访问均含 null guard", () => {
+    const src = readScript("chain.js");
+    // analysis 的 insights/keyPoints
+    expect(src).toContain("analysis?.insights");
+    expect(src).toContain("analysis?.keyPoints");
+    // plan 的 plan/actions
+    expect(src).toContain("plan?.plan");
+    expect(src).toContain("plan?.actions");
+    // final 的 summary/recommendation
+    expect(src).toContain("final?.summary");
+    expect(src).toContain("final?.recommendation");
+  });
+
+  it("scatter-gather.js 的 split/gathered 属性访问含 null guard", () => {
+    const src = readScript("scatter-gather.js");
+    // split 的 subtasks
+    expect(src).toContain("split?.subtasks");
+    // gather（gatheredResult）的 mergedResult / completeness
+    expect(src).toContain("gatheredResult?.mergedResult");
+    expect(src).toContain("gatheredResult?.completeness");
+  });
+
+  it("map-reduce.js 的 reduced 属性访问含 null guard", () => {
+    const src = readScript("map-reduce.js");
+    // reduce（reducedResult）的 reduced / stats
+    expect(src).toContain("reducedResult?.reduced");
+    expect(src).toContain("reducedResult?.stats");
+  });
+
+  it.each(SCRIPTS)("%s 不含裸 analysis.insights/plan.plan 等无 guard 访问", (filename) => {
+    const src = readScript(filename);
+    // 检查不存在 "变量.属性" 形式的裸访问（不含 ?. 的）
+    // 排除 schema 对象定义里的 properties.xxx 和 JSON.stringify 等合法用法
+    // 只检查 agent() 返回值变量名后的裸属性访问
+    const agentVars = ["analysis", "plan", "final", "split", "gatheredResult", "reducedResult"];
+    for (const v of agentVars) {
+      // 匹配 `变量.属性`（非 `变量?.属性`），但排除变量声明和赋值左侧
+      const bareAccess = new RegExp(`[^?\\w.]${v}\\.[a-zA-Z]`);
+      // 排除 schema properties 定义中的合法用法（如 properties: { insights: ... }）
+      // 这里只关注 prompt 拼接和 outcome 构造中的裸访问
+      const lines = src.split("\n");
+      for (const line of lines) {
+        // 跳过 schema 定义行（含 type: / properties: / description:）
+        if (/^\s*(type|properties|description|required|items):/.test(line)) continue;
+        // 跳过 const 声明行（如 `const plan = await agent(...)`）
+        if (/^\s*const\s+\w+\s*=/.test(line) && line.includes("agent(")) continue;
+        if (bareAccess.test(line)) {
+          // 检查这个裸访问是否真的在属性读取位置（而非变量定义）
+          const match = line.match(bareAccess);
+          if (match && !line.includes(`?.`)) {
+            // 确认是 agent() 返回值的属性访问（同一行有拼接/赋值上下文）
+            // 如果行里同时有 ?. 版本，说明是 guard 后的，不算裸访问
+            expect(line).toMatch(new RegExp(`${v}\\?\\.`));
+          }
+        }
+      }
+    }
+  });
+});
+
+// W4: parallel() 降级返回值 {status:'failed'} 兼容 + 结果字段守卫 + spread 消除
+describe("W4: parallel() failed-status 兼容 + 结果字段守卫 + spread 消除", () => {
+  // W1 后 worker parallel() 可能返回 {status:'failed', error:'...'}，脚本 for 循环
+  // 必须识别此对象并标记失败（不能误判为成功）。验证三个含 parallel() 的脚本。
+  const PARALLEL_SCRIPTS = ["parallel.js", "scatter-gather.js", "map-reduce.js"] as const;
+
+  it.each(PARALLEL_SCRIPTS)("%s 含 r.status === \"failed\" 失败识别（W1 兼容）", (filename) => {
+    const src = readScript(filename);
+    // 三个脚本都应有 `r.status === "failed"` 检查（识别 W1 的降级对象）
+    expect(src).toContain('r.status === "failed"');
+  });
+
+  it("parallel.js perPerspective 不再用 spread 透传 agent 字段（spread 消除）", () => {
+    const src = readScript("parallel.js");
+    // W4 后显式取 score/findings，不再 ...r
+    expect(src).not.toContain("...r");
+    // 显式字段守卫存在
+    expect(src).toContain("typeof r.score === \"number\"");
+    expect(src).toContain("Array.isArray(r.findings)");
+  });
+
+  it("scatter-gather.js r.result 字段守卫存在", () => {
+    const src = readScript("scatter-gather.js");
+    expect(src).toContain("typeof r.result === \"string\"");
+    expect(src).toContain("\"(无结果)\"");
+  });
+
+  it("map-reduce.js r.mapped 字段守卫存在", () => {
+    const src = readScript("map-reduce.js");
+    expect(src).toContain("typeof r.mapped === \"string\"");
+    expect(src).toContain("\"(无结果)\"");
+  });
+
+  it("parallel.js perspectives 元素类型校验存在", () => {
+    const src = readScript("parallel.js");
+    expect(src).toContain("perspectives.some");
+    expect(src).toContain("typeof p !== \"string\"");
+  });
+
+  it("scatter-gather.js subtasks 元素结构校验存在", () => {
+    const src = readScript("scatter-gather.js");
+    expect(src).toContain("subtasks.some");
+    expect(src).toContain("typeof s.name !== \"string\"");
+  });
+
+  it("chain.js task 类型校验拒绝非字符串与空白", () => {
+    const src = readScript("chain.js");
+    expect(src).toContain("typeof task !== \"string\"");
+    expect(src).toContain("task.trim() === \"\"");
+  });
+});