@zhushanwen/pi-subagent-workflow 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",

package/src/execution/__tests__/execute-nesting.test.ts

@@ -105,6 +105,22 @@ vi.mock("../finalized-marker.ts", () => ({
   readFinalized: vi.fn(() => false),
 }));
 
+// manifest-store mock：writeManifest 用真实 fs.promises 写盘，但本文件 fs 同步方法已 mock
+// （目录从不真实创建）→ open/rename/unlink 全 ENOENT → bestEffort 异步 console.debug。
+// 这些延迟 console 通过 worker RPC（onUserConsoleLog）回流，与 vitest teardown 形成 race：
+// "Closing rpc while onUserConsoleLog was pending" → unhandled rejection / exit 1（flaky）。
+// 本组用例测编排逻辑（pool / depth / throttle），不测 manifest 持久化（有 manifest-store.test.ts
+// 独立覆盖）。故 mock 成 no-op，消除 teardown race 的根因——异步 console 输出。
+vi.mock("../manifest-store.ts", () => {
+  class FakeManifestStore {
+    writeManifest = vi.fn(async () => {});
+    readManifest = vi.fn(async () => null);
+    listAllSync = vi.fn(() => []);
+    recoverTmpFiles = vi.fn(async () => []);
+  }
+  return { ManifestStore: FakeManifestStore };
+});
+
 // temp-prompt：mock 掉真实 fs.promises I/O，消除 fake-timers 下的 flaky 竞态
 // （详见 run-spawn-integration.test.ts 同名 mock 的注释）。
 vi.mock("../temp-prompt.ts", () => ({

package/src/interface/__tests__/workflow-tool-prompt.test.ts

@@ -40,8 +40,8 @@ describe("U1: workflow tool prompt mentions built-in workflows", () => {
   });
 
   it("tool-workflow.ts promptGuidelines 含 run action 的正例", () => {
-    // 给出 workflow run <name> 的调用示例，LLM 才知道参数格式。
-    expect(TOOL_WORKFLOW_SRC).toMatch(/workflow run .+--args/i);
+    // 给出 run 调用的 JSON 示例，LLM 才知道参数格式（action/name/args 嵌套）。
+    expect(TOOL_WORKFLOW_SRC).toContain('{"action":"run","name":"');
   });
 
   it("promptGuidelines 含 JSON 调用正例（run/status/lifecycle）", () => {
@@ -69,4 +69,15 @@ describe("U1: workflow tool prompt mentions built-in workflows", () => {
     // 反向交叉引用：list 的指引里要提到用 workflow tool 的 run action 启动脚本。
     expect(TOOL_WORKFLOW_SCRIPT_SRC).toMatch(/workflow.*tool.*run|run.*workflow.*tool/i);
   });
+
+  it("tool-workflow.ts promptGuidelines 强化 anti-generate（直接 run，不要 generate）", () => {
+    // session 证据：弱模型看到 workflow list 后倾向 workflow-script generate 而非直接 run。
+    // 提示词必须显式禁止对内置编排使用 generate。
+    expect(TOOL_WORKFLOW_SRC).toContain("NEVER use workflow-script action:generate");
+  });
+
+  it("tool-workflow-script.ts promptGuidelines 强化 anti-generate（CRITICAL ANTI-PATTERN）", () => {
+    expect(TOOL_WORKFLOW_SCRIPT_SRC).toContain("CRITICAL ANTI-PATTERN");
+    expect(TOOL_WORKFLOW_SCRIPT_SRC).toContain("NEVER generate");
+  });
 });

package/src/interface/tool-workflow-script.ts

@@ -178,9 +178,10 @@ export function registerWorkflowScriptTool(
       "Use this to discover built-in workflows (chain/parallel/scatter-gather/map-reduce) " +
       "and user-generated scripts before starting a run. After listing, start a script via " +
       "the workflow tool with action:run and the script name.",
-      "ANTI-PATTERN: Do NOT generate a new script for chain/parallel/scatter-gather/map-reduce " +
-      "orchestration — these are built-in. Call action:list first. Generate only when no built-in " +
-      "matches the use case.",
+      "CRITICAL ANTI-PATTERN: NEVER generate scripts for chain/parallel/scatter-gather/map-reduce. " +
+      "These are BUILT-IN — use the workflow tool with action:run directly. " +
+      "generate is for NOVEL orchestration patterns ONLY. When in doubt, action:list first, " +
+      "then action:run — not action:generate.",
     ],
     parameters: WorkflowScriptParams,
 

package/src/interface/tool-workflow.ts

@@ -235,12 +235,12 @@ export function registerWorkflowTool(
     promptSnippet: "Run, pause, resume, abort, or check workflow status",
     promptGuidelines: [
       "PRIORITY: When user says 'workflow', 'run workflow', try run action FIRST.",
-      "BUILT-IN workflows (ready to use, no script generation needed): " +
-      "chain (analyze→transform→synthesize sequential; args: task), " +
+      "BUILT-IN workflows — run DIRECTLY with action:run, do NOT use workflow-script generate for these: " +
+      "chain (sequential 3-step: analyze→transform→synthesize; args: task), " +
       "parallel (multi-perspective analysis; args: target, optional perspectives), " +
-      "scatter-gather (split→parallel process→merge; args: task), " +
+      "scatter-gather (split→parallel→merge; args: task), " +
       "map-reduce (parallel map→reduce; args: items/itemsJson + operation). " +
-      "Example: workflow run chain --args task=\"<description>\".",
+      "Example: {\"action\":\"run\",\"name\":\"parallel\",\"args\":{\"target\":\"src/auth.ts\"}}.",
       "DISCOVERY: If unsure what workflows exist, call the workflow-script tool with " +
       "action:list first — it returns all available scripts (built-in + user-generated) " +
       "with source tags and descriptions. Then use this tool's run action to start one.",
@@ -251,6 +251,9 @@ export function registerWorkflowTool(
       "- status: {\"action\":\"status\"}. " +
       "- pause/resume/abort: {\"action\":\"pause\",\"runId\":\"<id>\"} (abort optional: ,\"error\":\"<reason>\"}).",
       "Anti-patterns: Flattening args sub-fields (task/items/...) to the top level — they belong inside args. Calling {\"action\":\"run\"} without name.",
+      "CRITICAL: For chain/parallel/scatter-gather/map-reduce orchestration, ALWAYS use action:run with the built-in name. " +
+      "NEVER use workflow-script action:generate to create these patterns — they already exist. " +
+      "workflow-script generate is ONLY for novel patterns not covered by built-ins.",
     ],
     parameters: WorkflowParams,
 

package/src/orchestration/__tests__/error-recovery-postmessage-defense.test.ts

@@ -0,0 +1,390 @@
+// src/orchestration/__tests__/error-recovery-postmessage-defense.test.ts
+//
+// W2: 主线程层 postMessage 防御测试。
+//
+// 背景：主线程有 3 处 run.runtime?.worker.postMessage(...) 调用（经 helper 函数），
+// 全部没有 try/catch。若 result 对象含不可克隆成员（function/Symbol/循环引用），
+// postMessage 同步抛 DataCloneError：
+// - postAgentResult：result 是 agent 返回值，不可克隆概率最高。DataCloneError 冒泡到
+//   dispatchAgentCall 的 .then 回调，中断后续 postBudgetUpdate/store.save/budget 检查，
+//   run 卡在 running。
+// - postBudgetUpdate：payload 是 number，风险低但无兜底。
+// - dispatchWorkflowCall 的 postResult：result 是子 workflow 任意返回值。
+//
+// 修复后三处均包 try/catch + fallback。本测试通过 mock worker.postMessage 抛
+// DataCloneError，验证：
+// 1. 调用方不抛错（流程不中断）
+// 2. fallback result（纯字符串，必可克隆）被发送
+// 3. console.error 记录诊断
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { handleWorkerMessage, postBudgetUpdate } from "../error-recovery.ts";
+import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
+import type { WorkflowRun } from "../models/workflow-run.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ERROR_RECOVERY_SRC = readFileSync(
+  join(__dirname, "../error-recovery.ts"),
+  "utf-8",
+);
+
+// ── helpers ──────────────────────────────────────────────────
+
+/** flush microtask 队列，让 void .then().catch() 链路跑完。 */
+async function flushMicrotasks(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/** 构造一个 postMessage mock：前 n 次抛 DataCloneError，之后正常（模拟 fallback 成功）。 */
+function makeFailingPostMessage(failTimes: number): ReturnType<typeof vi.fn> {
+  let calls = 0;
+  return vi.fn(() => {
+    calls += 1;
+    if (calls <= failTimes) {
+      const err = new Error("Could not clone object: function found");
+      err.name = "DataCloneError";
+      throw err;
+    }
+    // fallback 成功路径：no-op
+  });
+}
+
+/** 构造一个永远抛 DataCloneError 的 postMessage mock（fallback 也失败）。 */
+function makeAlwaysFailingPostMessage(): ReturnType<typeof vi.fn> {
+  return vi.fn(() => {
+    const err = new Error("Could not clone object");
+    err.name = "DataCloneError";
+    throw err;
+  });
+}
+
+/** 构造 status="running" 的 mock WorkflowRun，postMessage 由调用方注入。 */
+function makeRunningRun(postMessage: ReturnType<typeof vi.fn>): WorkflowRun {
+  return {
+    state: { status: "running" },
+    runtime: { worker: { postMessage } },
+  } as unknown as WorkflowRun;
+}
+
+/** LifecycleDeps 只需 onWorkflowCall（dispatchWorkflowCall 唯一消费的 dep）。 */
+function makeDeps(onWorkflowCall?: LifecycleDeps["onWorkflowCall"]): LifecycleDeps {
+  return { onWorkflowCall } as unknown as LifecycleDeps;
+}
+
+/** WorkerHandlers 占位（workflow-call 路径不触发 handler 回调）。 */
+function makeHandlers(): WorkerHandlers {
+  return {
+    onMessage: vi.fn(async () => {}),
+    onError: vi.fn(async () => {}),
+    onExit: vi.fn(async () => {}),
+  } as unknown as WorkerHandlers;
+}
+
+interface PostedMsg {
+  type: string;
+  callId?: number;
+  result?: { content: string; error?: string };
+  budget?: { usedTokens: number; usedCost: number };
+  cached?: boolean;
+}
+
+/** 从 postMessage mock 取第 idx 次调用的第 0 参。 */
+function postedAt(postMessage: ReturnType<typeof vi.fn>, idx: number): PostedMsg {
+  return postMessage.mock.calls[idx]![0] as PostedMsg;
+}
+
+/** 静默 console.error（防御路径会打印诊断，避免污染测试输出）。 */
+function silenceConsoleError(): () => void {
+  const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+  return () => spy.mockRestore();
+}
+
+// ── W2a: postBudgetUpdate try/catch ──
+
+describe("W2a: postBudgetUpdate 防御 DataCloneError", () => {
+  it("postMessage 抛错时不向上传播（流程不中断）", () => {
+    const restore = silenceConsoleError();
+    try {
+      const postMessage = makeAlwaysFailingPostMessage();
+      const run = {
+        state: {
+          status: "running",
+          budget: { usedTokens: 42, usedCost: 0.5 },
+        },
+        runtime: { worker: { postMessage } },
+      } as unknown as WorkflowRun;
+
+      // 不应抛错——防御性兜底
+      expect(() => postBudgetUpdate(run)).not.toThrow();
+    } finally {
+      restore();
+    }
+  });
+
+  it("postMessage 失败时记录 console.error 诊断", () => {
+    const restore = silenceConsoleError();
+    try {
+      const postMessage = makeAlwaysFailingPostMessage();
+      const run = {
+        state: {
+          status: "running",
+          budget: { usedTokens: 42, usedCost: 0.5 },
+        },
+        runtime: { worker: { postMessage } },
+      } as unknown as WorkflowRun;
+
+      postBudgetUpdate(run);
+
+      expect(console.error).toHaveBeenCalledTimes(1);
+      const diag = (console.error as ReturnType<typeof vi.fn>).mock.calls[0]![0] as string;
+      expect(diag).toContain("postBudgetUpdate failed");
+      expect(diag).toContain("Could not clone object");
+    } finally {
+      restore();
+    }
+  });
+
+  it("正常 payload（纯 number）成功发送", () => {
+    const postMessage = vi.fn();
+    const run = {
+      state: {
+        status: "running",
+        budget: { usedTokens: 42, usedCost: 0.5 },
+      },
+      runtime: { worker: { postMessage } },
+    } as unknown as WorkflowRun;
+
+    postBudgetUpdate(run);
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    expect(postedAt(postMessage, 0)).toEqual({
+      type: "budget-update",
+      budget: { usedTokens: 42, usedCost: 0.5 },
+    });
+  });
+});
+
+// ── W2b: dispatchWorkflowCall postResult 闭包防御 ──
+
+describe("W2b: dispatchWorkflowCall postResult 防御 DataCloneError", () => {
+  it("result 不可克隆 → 回发纯字符串 fallback result", async () => {
+    const restore = silenceConsoleError();
+    try {
+      // 第 1 次 postMessage 抛 DataCloneError（原始 result 不可克隆），
+      // 第 2 次（fallback）成功。
+      const postMessage = makeFailingPostMessage(1);
+      const onWorkflowCall = vi.fn(async () => ({ nonCloneable: () => {} }));
+      const run = makeRunningRun(postMessage);
+      const deps = makeDeps(onWorkflowCall);
+
+      await handleWorkerMessage(
+        run,
+        { type: "workflow-call", callId: 9, name: "sub", args: {} },
+        deps,
+        makeHandlers(),
+      );
+      await flushMicrotasks();
+
+      // 调用两次：1 原始（失败）+ 1 fallback（成功）
+      expect(postMessage).toHaveBeenCalledTimes(2);
+      const fallback = postedAt(postMessage, 1);
+      expect(fallback.type).toBe("workflow-result");
+      expect(fallback.callId).toBe(9);
+      expect(fallback.result?.content).toBe("");
+      expect(fallback.result?.error).toContain("Workflow result serialization failed");
+    } finally {
+      restore();
+    }
+  });
+
+  it("postResult 不抛错到调用方（不中断 onWorkflowCall 链路）", async () => {
+    const restore = silenceConsoleError();
+    try {
+      const postMessage = makeAlwaysFailingPostMessage();
+      const onWorkflowCall = vi.fn(async () => ({ bad: () => {} }));
+      const run = makeRunningRun(postMessage);
+      const deps = makeDeps(onWorkflowCall);
+
+      // handleWorkerMessage 自身不应抛——postResult 内部已 catch
+      await expect(
+        handleWorkerMessage(
+          run,
+          { type: "workflow-call", callId: 10, name: "sub", args: {} },
+          deps,
+          makeHandlers(),
+        ),
+      ).resolves.toBeUndefined();
+      await flushMicrotasks();
+    } finally {
+      restore();
+    }
+  });
+
+  it("fallback 也失败 → console.error 记录 worker pending 将挂起", async () => {
+    const restore = silenceConsoleError();
+    try {
+      const postMessage = makeAlwaysFailingPostMessage();
+      const onWorkflowCall = vi.fn(async () => ({ bad: () => {} }));
+      const run = makeRunningRun(postMessage);
+      const deps = makeDeps(onWorkflowCall);
+
+      await handleWorkerMessage(
+        run,
+        { type: "workflow-call", callId: 11, name: "sub", args: {} },
+        deps,
+        makeHandlers(),
+      );
+      await flushMicrotasks();
+
+      // 至少 2 次尝试（原始 + fallback），fallback 失败也记日志
+      expect(postMessage.mock.calls.length).toBeGreaterThanOrEqual(2);
+      const errorCalls = (console.error as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[0] as string);
+      expect(errorCalls.some((s) => s.includes("fallback also failed"))).toBe(true);
+    } finally {
+      restore();
+    }
+  });
+});
+
+// ── W2c: postAgentResult 防御（经 handleWorkerMessage 触发） ──
+//
+// postAgentResult 是私有函数，通过 workflow-call 路径无法触发。但它可经 agent-call
+// 路径的「cached replay」分支触发：dispatchAgentCall 发现 run.state.calls.get(callId)
+// 已是 done 时，直接 postAgentResult(run, callId, cached.result, true)（无需 spawn
+// 子进程）。利用这一点构造行为测试——往 cached.result 里塞不可克隆值（function），
+// mock postMessage 在首次发送 agent-result 时抛 DataCloneError，验证 fallback 路径。
+//
+// 另外补充：验证 error-recovery.ts 源码中三处 postMessage 调用点都有 try/catch 包裹，
+// 防止未来重构误删防御（类似 worker-script-builder.test.ts 的源码字符串断言模式）。
+
+/** 构造 status="running" 且 calls 已含一个 done 结果（含不可克隆成员）的 mock run。
+ *  触发 dispatchAgentCall 的 cached replay 分支（line ~234），直接走 postAgentResult。 */
+function makeRunningRunWithCachedDone(
+  postMessage: ReturnType<typeof vi.fn>,
+  callId: number,
+  result: unknown,
+): WorkflowRun {
+  const calls = new Map();
+  calls.set(callId, { status: "done", result });
+  return {
+    state: {
+      status: "running",
+      calls,
+      trace: { append: vi.fn(), update: vi.fn() },
+      budget: { isExceeded: vi.fn(() => false) },
+    },
+    runtime: { worker: { postMessage } },
+  } as unknown as WorkflowRun;
+}
+
+describe("W2c: postAgentResult 行为测试（cached replay 路径）", () => {
+  it("result 不可克隆 → 回发纯字符串 fallback result（cached: false）", async () => {
+    const restore = silenceConsoleError();
+    try {
+      // 第 1 次 postMessage 抛 DataCloneError（原始 cached.result 含 function 不可克隆），
+      // 第 2 次（fallback）成功。
+      const postMessage = makeFailingPostMessage(1);
+      // cached.result 含 function 成员 → 模拟 agent 返回不可克隆值（{ bad: () => {} }）
+      const run = makeRunningRunWithCachedDone(postMessage, 7, { bad: () => {} });
+      const deps = makeDeps();
+
+      await handleWorkerMessage(
+        run,
+        { type: "agent-call", callId: 7, opts: { prompt: "noop" } },
+        deps,
+        makeHandlers(),
+      );
+      await flushMicrotasks();
+
+      // 调用两次：1 原始 agent-result（失败）+ 1 fallback（成功）
+      expect(postMessage).toHaveBeenCalledTimes(2);
+
+      // 第 1 次：原始 agent-result，result 透传原值，cached 为 replay 的 true
+      const original = postedAt(postMessage, 0);
+      expect(original.type).toBe("agent-result");
+      expect(original.callId).toBe(7);
+      expect(original.cached).toBe(true);
+
+      // 第 2 次：fallback agent-result，result 形状为 {content:"", error:"Result serialization failed: ..."}，
+      // 且 cached 固定为 false（fallback result 非缓存命中，透传原值含义失真）
+      const fallback = postedAt(postMessage, 1);
+      expect(fallback.type).toBe("agent-result");
+      expect(fallback.callId).toBe(7);
+      expect(fallback.result?.content).toBe("");
+      expect(fallback.result?.error).toContain("Result serialization failed");
+      expect(fallback.result?.error).toContain("Could not clone object");
+      expect(fallback.cached).toBe(false);
+    } finally {
+      restore();
+    }
+  });
+
+  it("fallback 也失败 → 不向上抛错，记录 worker pending 将挂起", async () => {
+    const restore = silenceConsoleError();
+    try {
+      // postMessage 永远抛 DataCloneError（原始 + fallback 均失败）
+      const postMessage = makeAlwaysFailingPostMessage();
+      const run = makeRunningRunWithCachedDone(postMessage, 8, { bad: () => {} });
+      const deps = makeDeps();
+
+      // handleWorkerMessage 自身不应抛——postAgentResult 内部已 catch
+      await expect(
+        handleWorkerMessage(
+          run,
+          { type: "agent-call", callId: 8, opts: { prompt: "noop" } },
+          deps,
+          makeHandlers(),
+        ),
+      ).resolves.toBeUndefined();
+      await flushMicrotasks();
+
+      // 至少 2 次尝试（原始 + fallback），fallback 失败也记日志
+      expect(postMessage.mock.calls.length).toBeGreaterThanOrEqual(2);
+      const errorCalls = (console.error as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[0] as string);
+      expect(errorCalls.some((s) => s.includes("postAgentResult failed"))).toBe(true);
+      expect(errorCalls.some((s) => s.includes("fallback also failed"))).toBe(true);
+    } finally {
+      restore();
+    }
+  });
+});
+
+describe("W2c: postAgentResult 防御（源码结构断言）", () => {
+  /** 校验：给定函数体内的 postMessage 调用被 try/catch 包裹。
+   *  简化策略——在函数体片段中确认存在 try { ... postMessage ... } catch。 */
+  function hasTryCatchAroundPostMessage(funcBody: string): boolean {
+    return /try\s*\{[\s\S]*?postMessage[\s\S]*?\}\s*catch/.test(funcBody);
+  }
+
+  it("postAgentResult 包含 try/catch + fallback result", () => {
+    const match = ERROR_RECOVERY_SRC.match(/function postAgentResult\([\s\S]*?\n\}/);
+    expect(match, "postAgentResult 函数定义应存在").toBeTruthy();
+    expect(hasTryCatchAroundPostMessage(match![0])).toBe(true);
+    // fallback 通过共享工厂 makeSerializeFailedResult 构造纯字符串 result（必可克隆）
+    expect(match![0]).toContain('result: makeSerializeFailedResult("Result serialization failed"');
+    expect(match![0]).toContain("Result serialization failed");
+    // 原 result 不可克隆时 cached 透传原值含义失真 → fallback 固定 cached: false
+    expect(match![0]).toContain("cached: false");
+  });
+
+  it("postBudgetUpdate 包含 try/catch", () => {
+    const match = ERROR_RECOVERY_SRC.match(/export function postBudgetUpdate\([\s\S]*?\n\}/);
+    expect(match, "postBudgetUpdate 函数定义应存在").toBeTruthy();
+    expect(hasTryCatchAroundPostMessage(match![0])).toBe(true);
+  });
+
+  it("dispatchWorkflowCall postResult 闭包包含 try/catch + fallback", () => {
+    // postResult 是 const 闭包，匹配到下一个 }; 结尾
+    const match = ERROR_RECOVERY_SRC.match(/const postResult = \(result[\s\S]*?\n  \};/);
+    expect(match, "postResult 闭包定义应存在").toBeTruthy();
+    expect(hasTryCatchAroundPostMessage(match![0])).toBe(true);
+    expect(match![0]).toContain("Workflow result serialization failed");
+    // 防御变量名遮蔽：错误变量用 err 而非 msg（外层参数名 msg）
+    expect(match![0]).toMatch(/catch \(err\)/);
+  });
+});

package/src/orchestration/__tests__/worker-script-builder.test.ts

@@ -55,3 +55,77 @@ describe("buildWorkerScript — agent() skill field in task/agent branch", () =>
     expect(taskAgentBranch![0]).toContain("skill: firstArg.skill");
   });
 });
+
+// ── W1: postMessage 防御 + parallel() 降级类型安全 ──
+
+describe("buildWorkerScript — W1 postMessage defense & parallel degrade", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  describe("_safePost wrapper", () => {
+    it("injects _safePost function", () => {
+      expect(script).toContain("function _safePost(msg, context)");
+    });
+
+    it("_safePost wraps postMessage in try/catch", () => {
+      expect(script).toMatch(/_safePost[\s\S]*?try \{ parentPort\.postMessage\(msg\)/);
+    });
+
+    it("_safePost logs failure with context to workerLogs", () => {
+      expect(script).toContain('_pushWorkerLog("error"');
+      expect(script).toContain('"[postMessage failed:" + context + "]"');
+    });
+  });
+
+  describe("agent() uses _safePost", () => {
+    it("agent-call postMessage guarded by _safePost", () => {
+      expect(script).toContain("_safePost({ type: \"agent-call\"");
+      expect(script).toContain('"agent-call"');
+    });
+
+    it("agent() throws on postMessage failure", () => {
+      expect(script).toContain("postMessage failed for agent-call");
+    });
+  });
+
+  describe("workflow() uses _safePost", () => {
+    it("workflow-call postMessage guarded by _safePost", () => {
+      expect(script).toContain("_safePost({ type: \"workflow-call\"");
+    });
+  });
+
+  describe("return/error use _safePost", () => {
+    it("return postMessage uses _safePost", () => {
+      expect(script).toContain('_safePost({ type: "return"');
+    });
+
+    it("error postMessage uses _safePost", () => {
+      expect(script).toContain('_safePost({ type: "error"');
+    });
+  });
+
+  describe("parallel() degrade returns object", () => {
+    it("rejected results become {status:failed,error} objects", () => {
+      expect(script).toContain('status: "failed"');
+      expect(script).toMatch(/parallel[\s\S]*?status: "failed"/);
+    });
+
+    it("non-object fulfilled values wrapped as failed", () => {
+      expect(script).toContain("agent returned non-object result");
+    });
+
+    it("object fulfilled values pass through unchanged", () => {
+      expect(script).toContain("!Array.isArray(v)");
+    });
+  });
+
+  describe("pipeline() error observability", () => {
+    it("single-arg mode logs stage errors before re-throwing", () => {
+      expect(script).toContain("[pipeline stage ");
+      expect(script).toContain("_pushWorkerLog(\"error\"");
+    });
+
+    it("cartesian mode logs stage errors instead of silent swallow", () => {
+      expect(script).toContain("[pipeline cartesian stage failed");
+    });
+  });
+});

package/src/orchestration/error-recovery.ts

@@ -427,6 +427,19 @@ function dispatchAgentCall(
     });
 }
 
+/**
+ * postMessage 序列化失败时回发的 fallback result（必可克隆），让 worker pending resolve。
+ *
+ * postResult（workflow-call）与 postAgentResult（agent-call）各自前缀不同，故 prefix 参数化，
+ * 共享返回类型与构造逻辑，避免字面量重复导致形状漂移。
+ */
+function makeSerializeFailedResult(
+  prefix: string,
+  errMsg: string,
+): { content: string; error: string } {
+  return { content: "", error: `${prefix}: ${errMsg}` };
+}
+
 /**
  * 派发 workflow 嵌套调用：调 deps.onWorkflowCall 获取子 workflow 结果，
  * 异步 postMessage(workflow-result) 回 worker。
@@ -449,11 +462,31 @@ function dispatchWorkflowCall(
 
   const postResult = (result: unknown): void => {
     if (run.state.status !== "running") return;
-    run.runtime?.worker.postMessage({
-      type: "workflow-result",
-      callId: msg.callId,
-      result,
-    });
+    // W2 主线程防御：result 是子 workflow 任意返回值，可能含不可克隆成员（function/
+    // Symbol/循环引用）→ postMessage 同步抛 DataCloneError。内部 try/catch + 回发
+    // 纯字符串 fallback result，让 worker 内 workflow() pending Promise resolve。
+    // 注意：错误变量用 err（外层 dispatchWorkflowCall 参数名为 msg，避免遮蔽）。
+    try {
+      run.runtime?.worker.postMessage({
+        type: "workflow-result",
+        callId: msg.callId,
+        result,
+      });
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      console.error(`[workflow] postResult (workflow-call callId=${msg.callId}) failed: ${errMsg}. Sending error fallback.`);
+      // 回发纯字符串 fallback result（必可克隆），让 worker pending resolve
+      try {
+        run.runtime?.worker.postMessage({
+          type: "workflow-result",
+          callId: msg.callId,
+          result: makeSerializeFailedResult("Workflow result serialization failed", errMsg),
+        });
+      } catch {
+        // fallback 也失败——worker 此 callId 的 pending 只能靠 timeout 兜底
+        console.error(`[workflow] postResult fallback also failed (callId=${msg.callId}): worker pending will hang until timeout`);
+      }
+    }
   };
 
   if (!deps.onWorkflowCall) {
@@ -477,6 +510,12 @@ function dispatchWorkflowCall(
 
 /**
  * 回发 agent-result 给 worker（worker 内 pending Promise 据此 resolve）。
+ *
+ * W2 主线程防御：result 是 agent 返回值，含不可克隆成员（function/Symbol/循环引用）时
+ * postMessage 同步抛 DataCloneError。若冒泡到 dispatchAgentCall 的 .then 回调，会中断
+ * 后续 postBudgetUpdate/store.save/budget 检查，run 卡在 running。故内部 try/catch：
+ * 失败时记录诊断 + 回发纯字符串 fallback result（必可克隆），让 worker pending resolve。
+ * 函数签名不变（所有调用点无需改动），仅用 console.error 记日志（deps 不在手边）。
  */
 function postAgentResult(
   run: WorkflowRun,
@@ -484,7 +523,25 @@ function postAgentResult(
   result: AgentResult,
   cached: boolean,
 ): void {
-  run.runtime?.worker.postMessage({ type: "agent-result", callId, result, cached });
+  try {
+    run.runtime?.worker.postMessage({ type: "agent-result", callId, result, cached });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[workflow] postAgentResult failed (callId=${callId}): ${msg}. Result likely contains non-cloneable value.`);
+    // 回发纯字符串 fallback result（必可克隆），让 worker pending resolve（避免永久挂起）
+    try {
+      run.runtime?.worker.postMessage({
+        type: "agent-result",
+        callId,
+        result: makeSerializeFailedResult("Result serialization failed", msg),
+        // 原 result 不可克隆时 cached 透传原值含义失真（fallback result 非缓存命中）→ 固定 false
+        cached: false,
+      });
+    } catch {
+      // fallback 也失败——worker 此 callId 的 pending 只能靠 timeout/exit 兜底
+      console.error(`[workflow] postAgentResult fallback also failed (callId=${callId}): worker pending will hang until timeout`);
+    }
+  }
 }
 
 /**
@@ -496,13 +553,20 @@ function postAgentResult(
  * （dispatch 后同步 worker $BUDGET）——单一实现，避免消息形状漂移。
  */
 export function postBudgetUpdate(run: WorkflowRun): void {
-  run.runtime?.worker.postMessage({
-    type: "budget-update",
-    budget: {
-      usedTokens: run.state.budget.usedTokens,
-      usedCost: run.state.budget.usedCost,
-    },
-  });
+  try {
+    run.runtime?.worker.postMessage({
+      type: "budget-update",
+      budget: {
+        usedTokens: run.state.budget.usedTokens,
+        usedCost: run.state.budget.usedCost,
+      },
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // budget 是纯 number 不太可能失败，但防御性兜底——budget 同步非关键（worker 仍可
+    // 基于 $BUDGET.spent() 自行累计），失败仅记日志，不中断调用方流程。
+    console.error(`[workflow] postBudgetUpdate failed: ${msg}. Budget sync to worker skipped (non-critical).`);
+  }
 }
 
 /**

package/src/orchestration/worker-script-builder.ts

@@ -69,6 +69,17 @@ export function buildWorkerScript(userScript: string): string {
     '  console.error = function (...args) { _pushWorkerLog("error", args); };',
     '  console.info = function (...args) { _pushWorkerLog("info", args); };',
     '',
+    '  // ── safePostMessage wrapper: 统一 postMessage 防御（DataCloneError 等）──',
+    '  function _safePost(msg, context) {',
+    '    try { parentPort.postMessage(msg); return true; }',
+    '    catch (e) {',
+    '      const errMsg = e && e.message ? e.message : String(e);',
+    '      const stack = e && e.stack ? e.stack : "";',
+    '      _pushWorkerLog("error", ["[postMessage failed:" + context + "]", errMsg, stack]);',
+    '      return false;',
+    '    }',
+    '  }',
+    '',
     '  // ── Internal state ──',
     '  let _callIdCounter = 0;',
     '  let _agentCallCount = 0;',
@@ -201,7 +212,9 @@ export function buildWorkerScript(userScript: string): string {
     '    const _effectivePhase = opts.phase || _currentPhase;\n' +
       '    delete opts.phase;\n' +
       '\n' +
-      '    parentPort.postMessage({ type: "agent-call", callId, opts, phase: _effectivePhase });',
+      '    if (!_safePost({ type: "agent-call", callId, opts, phase: _effectivePhase }, "agent-call")) {',
+    '      return Promise.reject(new Error("postMessage failed for agent-call (callId=" + callId + "): see workerLogs"));',
+    '    }',
     '    return new Promise((resolve, reject) => {',
     '      _pendingCalls.set(callId, { resolve, reject });',
     '    });',
@@ -219,7 +232,21 @@ export function buildWorkerScript(userScript: string): string {
     '      if (typeof c === "object" && c !== null && (c.task || c.agent)) { return agent(c); }',
     '      return agent(c);',
     '    }));',
-    '    return settled.map((r) => r.status === "fulfilled" ? r.value : (r.reason instanceof Error ? r.reason.message : String(r.reason)));',
+    '    return settled.map((r) => {',
+    '      if (r.status === "fulfilled") {',
+    '        const v = r.value;',
+    '        if (v !== null && typeof v === "object" && !Array.isArray(v)) {',
+    '          // 主线程 fallback（postAgentResult/postResult serialization failed）回发的对象含 error 字段',
+    '          // → 归一化为 failed 形状，与脚本侧 r.status === "failed" 检查统一',
+    '          if (typeof v.error === "string" && v.error.length > 0) return { status: "failed", error: v.error };',
+    '          return v;',
+    '        }',
+    '        return { status: "failed", error: "agent returned non-object result (type=" + typeof v + ")" };',
+    '      }',
+    '      const reason = r.reason;',
+    '      const errMsg = reason instanceof Error ? reason.message : String(reason);',
+    '      return { status: "failed", error: errMsg };',
+    '    });',
     '  }',
     '',
  // ── pipeline global ──
@@ -227,19 +254,31 @@ export function buildWorkerScript(userScript: string): string {
     '    // Single-arg mode: pipeline([stage1, stage2, ...])',
     '    if (Array.isArray(firstArg) && restStages.length === 0) {',
     '      let result;',
-    '      for (const stage of firstArg) { result = await stage(result); }',
+    '      for (let i = 0; i < firstArg.length; i++) {',
+    '        try { result = await firstArg[i](result); }',
+    '        catch (e) {',
+    '          const msg = e && e.message ? e.message : String(e);',
+    '          _pushWorkerLog("error", ["[pipeline stage " + i + " failed]", msg]);',
+    '          throw e;',
+    '        }',
+    '      }',
     '      return result;',
     '    }',
     '    // Cartesian product mode: pipeline([items], stage1, stage2, ...)',
     '    if (Array.isArray(firstArg) && restStages.length > 0 && typeof restStages[0] === "function") {',
     '      const results = [];',
-    '      for (const item of firstArg) {',
+    '      for (let idx = 0; idx < firstArg.length; idx++) {',
+    '        const item = firstArg[idx];',
     '        let val = item;',
     '        let failed = false;',
     '        for (const stage of restStages) {',
     '          if (failed) break;',
     '          try { val = await stage(val); }',
-    '          catch (e) { val = null; failed = true; }',
+    '          catch (e) {',
+    '          const msg = e && e.message ? e.message : String(e);',
+    '          _pushWorkerLog("error", ["[pipeline cartesian stage failed for item " + (idx + 1) + "]", msg]);',
+    '          val = null; failed = true;',
+    '          }',
     '        }',
     '        results.push(val);',
     '      }',
@@ -256,7 +295,9 @@ export function buildWorkerScript(userScript: string): string {
     '    const workflowArgs = (typeof args === "object" && args !== null) ? args : {};',
     '    const callId = _callIdCounter;',
     '    _callIdCounter++;',
-    '    parentPort.postMessage({ type: "workflow-call", callId, name, args: workflowArgs });',
+    '    if (!_safePost({ type: "workflow-call", callId, name, args: workflowArgs }, "workflow-call")) {',
+    '      return Promise.reject(new Error("postMessage failed for workflow-call (name=" + name + "): see workerLogs"));',
+    '    }',
     '    return new Promise((resolve, reject) => {',
     '      _pendingCalls.set(callId, { resolve, reject });',
     '    });',
@@ -272,11 +313,11 @@ export function buildWorkerScript(userScript: string): string {
     '})().then((result) => {',
     '  const { parentPort, workerData } = require("node:worker_threads");',
     '  const runId = (workerData.args && typeof workerData.args === "object" && workerData.args._runId) || "";',
-    '  parentPort.postMessage({ type: "return", runId, result, workerLogs: _workerLogs });',
+    '  _safePost({ type: "return", runId, result, workerLogs: _workerLogs }, "return");',
     '}).catch((err) => {',
     '  const { parentPort, workerData } = require("node:worker_threads");',
     '  const runId = (workerData.args && typeof workerData.args === "object" && workerData.args._runId) || "";',
-    '  parentPort.postMessage({ type: "error", runId, error: err.message || String(err), workerLogs: _workerLogs });',
+    '  _safePost({ type: "error", runId, error: err.message || String(err), workerLogs: _workerLogs }, "error");',
     '});',
   ].join("\n");
 }

package/workflows/README.md

@@ -28,7 +28,9 @@ workflow run parallel --args target="src/auth/login.ts"
 workflow run parallel --args target="..." --args 'perspectives=["security","readability"]'
 ```
 
-`perspectives` 默认 `["security","performance","maintainability"]`。每个视角一个并行 agent，各自返回评分+发现的问题；最后再一个 agent 汇总成总体评分+top 问题+共识。
+`perspectives` 默认 `["security","performance","maintainability"]`。每个视角一个并行 agent，各自返回评分+发现的问题，最后纯代码拼接各视角的 findings。
+
+> **Note (breaking)**: `outcome.aggregate` is now a concatenated string of each perspective's findings (format: `[perspective] finding1; finding2`, joined by newlines). Previously it was an LLM-produced object `{overallScore, topIssues, consensus}`. If you have generated workflows or downstream tools parsing the old object shape, update them to read `outcome.per_perspective` for structured per-perspective scores/findings, or treat `outcome.aggregate` as plain text.
 
 ### scatter-gather — 分发-收集
 
@@ -36,7 +38,7 @@ workflow run parallel --args target="..." --args 'perspectives=["security","read
 workflow run scatter-gather --args task="重构认证模块，涉及 session/jwt/oauth 三块"
 ```
 
-三段：第一个 agent 把大任务拆成 2-4 个可并行子任务 → `parallel()` 并行处理每个子任务 → 最后一个 agent 合并所有结果。
+三段：第一个 agent 把大任务拆成 2-4 个可并行子任务 → `parallel()` 并行处理每个子任务 → gather 阶段用 `agent()` 把各子任务结果合并成最终结论（LLM 合并，非纯代码拼接）。
 
 ### map-reduce — 映射-归约
 
@@ -45,7 +47,7 @@ workflow run map-reduce --args 'items=["file1.ts","file2.ts","file3.ts"]' --args
 workflow run map-reduce --args itemsJson=/path/to/items.json --args operation="..."
 ```
 
-`items` 直接传 JSON 数组，或 `itemsJson` 传 JSON 文件路径（二选一）。`parallel()` 对每个 item 并行执行 `operation` → 一个 agent 把所有结果归约成单一结论。
+`items` 直接传 JSON 数组，或 `itemsJson` 传 JSON 文件路径（二选一）。`parallel()` 对每个 item 并行执行 `operation` → reduce 阶段用 `agent()` 把各 item 的 map 结果归约成单一结论（LLM 归约，非纯代码拼接）。
 
 ## 编排 API
 

package/workflows/chain.js

@@ -19,8 +19,8 @@ const meta = {
 
 // ── 入参（$ARGS）──────────────────────────────────────────────────
 const task = $ARGS.task;
-if (!task) {
-  throw new Error("chain 缺少必需参数 task。用法：workflow run chain --args task=\"<任务描述>\"");
+if (typeof task !== "string" || task.trim() === "") {
+  throw new Error("chain 缺少必需参数 task（非空字符串）。用法：workflow run chain --args task=\"<描述>\"");
 }
 
 log("chain 开始，task=" + task);

package/workflows/map-reduce.js

@@ -82,12 +82,12 @@ try {
   let mapFailed = 0;
   for (let i = 0; i < mappedRaw.length; i++) {
     const r = mappedRaw[i];
-    if (!r || r.error) {
+    if (!r || r.status === "failed" || r.error) {
       mapped.push({
         itemIndex: i,
         item: items[i],
         status: "failed",
-        error: r ? r.error : "agent 无返回",
+        error: r ? (r.error || "agent 返回 failed 状态") : "agent 无返回",
       });
       mapFailed++;
     } else {
@@ -95,7 +95,7 @@ try {
         itemIndex: i,
         item: items[i],
         status: "ok",
-        mapped: r.mapped,
+        mapped: (typeof r.mapped === "string" ? r.mapped : "(无结果)"),
       });
     }
   }
@@ -104,10 +104,11 @@ try {
   }
   log("map 完成：ok=" + (items.length - mapFailed) + " failed=" + mapFailed);
 
-  // ── 段 2：reduce（agent 聚合所有 map 结果）──────────────────────
+  // ── 段 2：reduce（agent 归约所有 map 结果）──────────────────────
   phase("reduce");
   currentPhase = "reduce";
-  const reduced = await agent({
+
+  const reducedResult = await agent({
     prompt:
       "以下是对 " + items.length + " 个 item 执行「" + operation + "」的结果，请归约成单一结论：\n\n" +
       JSON.stringify(mapped, null, 2),
@@ -127,7 +128,10 @@ try {
     phases_run: ["map", "reduce"],
     items_total: items.length,
     items_mapped: items.length - mapFailed,
-    reduced: { reduced: (reduced?.reduced ?? "(归约无结果)"), stats: (reduced?.stats ?? "(归约无结果)") },
+    reduced: {
+      reduced: (reducedResult?.reduced ?? "(归约无结果)"),
+      stats: (reducedResult?.stats ?? "(归约无结果)"),
+    },
     message: "map-reduce 完成：map " + items.length + " 项（失败 " + mapFailed + "）→ reduce",
   };
 } catch (err) {

package/workflows/parallel.js

@@ -28,6 +28,9 @@ if (!target) {
 const perspectives = Array.isArray($ARGS.perspectives) && $ARGS.perspectives.length > 0
   ? $ARGS.perspectives
   : ["security", "performance", "maintainability"];
+if (perspectives.some((p) => typeof p !== "string")) {
+  throw new Error("parallel 参数 perspectives 必须是字符串数组，实际含非字符串元素");
+}
 
 log("parallel 开始，target=" + target + " perspectives=" + JSON.stringify(perspectives));
 
@@ -68,15 +71,20 @@ try {
   let failedCount = 0;
   for (let i = 0; i < perPerspectiveRaw.length; i++) {
     const r = perPerspectiveRaw[i];
-    if (!r || r.error) {
+    if (!r || r.status === "failed" || r.error) {
       perPerspective.push({
         perspective: perspectives[i],
         status: "failed",
-        error: r ? r.error : "agent 无返回",
+        error: r ? (r.error || "agent 返回 failed 状态") : "agent 无返回",
       });
       failedCount++;
     } else {
-      perPerspective.push({ perspective: perspectives[i], status: "ok", ...r });
+      perPerspective.push({
+        perspective: perspectives[i],
+        status: "ok",
+        score: typeof r.score === "number" ? r.score : undefined,
+        findings: Array.isArray(r.findings) ? r.findings : [],
+      });
     }
   }
   if (failedCount === perspectives.length) {
@@ -87,36 +95,18 @@ try {
   // ── 段 2：aggregate（汇总多视角结果）────────────────────────────
   phase("aggregate");
   currentPhase = "aggregate";
-  const aggregate = await agent({
-    prompt:
-      "以下是多视角分析结果，请综合出总体评分、top 问题和共识：\n\n" +
-      JSON.stringify(perPerspective, null, 2),
-    schema: {
-      type: "object",
-      properties: {
-        overallScore: { type: "number", description: "综合评分 0-10" },
-        topIssues: {
-          type: "array",
-          items: { type: "string" },
-          description: "最关键的问题（按严重度排序）",
-        },
-        consensus: { type: "string", description: "多视角共识总结" },
-      },
-      required: ["overallScore", "topIssues", "consensus"],
-    },
-    description: "parallel-aggregate",
-  });
+
+  // 纯代码合并：拼接各视角发现的问题（不调用 LLM）
+  const aggregateResult = perPerspective
+    .map((p) => "[" + (p.perspective || "?") + "] " + (p.findings ? p.findings.join("; ") : "(no findings)"))
+    .join("\n");
 
   outcome = {
     status: failedCount > 0 ? "partial" : "ok",
     phases_run: ["parallel-analyze", "aggregate"],
     perspectives_analyzed: perspectives.length,
     per_perspective: perPerspective,
-    aggregate: {
-      overallScore: (aggregate?.overallScore ?? "(聚合无结果)"),
-      topIssues: (aggregate?.topIssues ?? []),
-      consensus: (aggregate?.consensus ?? "(聚合无结果)"),
-    },
+    aggregate: aggregateResult,
     message: "parallel 完成：" + perspectives.length + " 视角（失败 " + failedCount + "）→ 聚合",
   };
 } catch (err) {

package/workflows/scatter-gather.js

@@ -62,6 +62,9 @@ try {
   if (subtasks.length === 0) {
     throw new Error("scatter 返回的 subtasks 为空");
   }
+  if (subtasks.some((s) => !s || typeof s.name !== "string")) {
+    throw new Error("scatter 返回的 subtasks 每项需含 name 字符串字段");
+  }
   log("scatter 出 " + subtasks.length + " 个子任务");
 
   // ── 段 2：process（parallel 并行处理每个子任务）──────────────────
@@ -89,15 +92,19 @@ try {
   let failedCount = 0;
   for (let i = 0; i < processedRaw.length; i++) {
     const r = processedRaw[i];
-    if (!r || r.error) {
+    if (!r || r.status === "failed" || r.error) {
       processed.push({
         subtask: subtasks[i].name,
         status: "failed",
-        error: r ? r.error : "agent 无返回",
+        error: r ? (r.error || "agent 返回 failed 状态") : "agent 无返回",
       });
       failedCount++;
     } else {
-      processed.push({ subtask: subtasks[i].name, status: "ok", result: r.result });
+      processed.push({
+        subtask: subtasks[i].name,
+        status: "ok",
+        result: (typeof r.result === "string" ? r.result : "(无结果)"),
+      });
     }
   }
   if (failedCount === subtasks.length) {
@@ -105,10 +112,11 @@ try {
   }
   log("process 完成：ok=" + (subtasks.length - failedCount) + " failed=" + failedCount);
 
-  // ── 段 3：gather（合并所有子任务结果）───────────────────────────
+  // ── 段 3：gather（agent 合并所有子任务结果）─────────────────────
   phase("gather");
   currentPhase = "gather";
-  const gathered = await agent({
+
+  const gatheredResult = await agent({
     prompt:
       "以下是各子任务的处理结果，请合并成一个完整、一致的最终结果：\n\n" +
       JSON.stringify(processed, null, 2),
@@ -129,8 +137,8 @@ try {
     subtasks_total: subtasks.length,
     subtasks_processed: subtasks.length - failedCount,
     gathered: {
-      mergedResult: (gathered?.mergedResult ?? "(合并无结果)"),
-      completeness: (gathered?.completeness ?? "(合并无结果)"),
+      mergedResult: (gatheredResult?.mergedResult ?? "(合并无结果)"),
+      completeness: (gatheredResult?.completeness ?? "(合并无结果)"),
     },
     message: "scatter-gather 完成：split " + subtasks.length + " → process（失败 " + failedCount + "）→ merge",
   };