@zhushanwen/pi-subagent-workflow 0.4.1 → 0.4.3

package/src/orchestration/__tests__/workflows-e2e.test.ts

@@ -0,0 +1,386 @@
+/**
+ * 内置 workflow E2E（真实 worker thread + mock LLM runner）
+ *
+ * 验证 4 个内置 workflow（parallel/chain/map-reduce/scatter-gather）通过真实的编排
+ * 链路执行成功。调用真实的 runAndWait(name, args, deps)（src/orchestration/launcher.ts），
+ * 它内部会：
+ *   1. deps.registry.get(name) 加载真实 .js 脚本
+ *   2. 脚本校验（lintScript）
+ *   3. runWorkflow(spec, deps) 起真实的 node:worker_threads Worker 执行脚本
+ *   4. 脚本内调 agent()/parallel() → worker postMessage(agent-call) →
+ *      主线程 deps.runner.run() → 我们 mock 它返回固定结构化数据
+ *   5. 脚本聚合结果 → return outcome → runAndWait 返回 WorkflowRunResult
+ *
+ * 唯一 mock 的是 deps.runner（AgentRunner 接口）——真实 runner 会 spawn pi 子进程调 LLM，
+ * mock runner 根据 opts.schema 生成符合脚本 schema 的假数据。
+ *
+ * 真实 Infra 实现：
+ *   - WorkerHostImpl（真实 node:worker_threads Worker）
+ *   - JsonlRunStore（真实持久化，用临时目录）
+ *
+ * registry 绕过说明（见末尾 notes）：
+ *   WorkflowScriptRegistryImpl(config) 的扫描源是固定约定目录（.pi/workflows 等），
+ *   无法指向 extensions/subagent-workflow/workflows/。为不改源码，这里直接读 .js 文件
+ *   内容 + 手动构造 WorkflowScript 对象，包装为一个满足 WorkflowScriptRegistry 接口
+ *   的自定义 registry（loadWorkflowsFromDir）。
+ */
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { JsonlRunStore } from "../jsonl-run-store.ts";
+import { type LauncherDeps,runAndWait } from "../launcher.ts";
+import type { LifecycleDeps } from "../models/ports.ts";
+import type { AgentRunner } from "../models/ports.ts";
+import type { AgentResult, AgentUsage } from "../models/types.ts";
+import {
+  type WorkflowMeta,
+  WorkflowScript,
+  type WorkflowSource,
+} from "../models/workflow-script.ts";
+import type { WorkflowScriptRegistry } from "../models/workflow-script-registry.ts";
+import { WorkerHostImpl } from "../worker-host.ts";
+
+// ── 路径：定位真实 workflows 目录 ─────────────────────────────────────────
+// 本测试文件在 src/orchestration/__tests__/，workflows 目录在 extensions/subagent-workflow/workflows/
+// 即 __dirname → ..  (orchestration) → ..  (src) → ..  (subagent-workflow) → workflows
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const WORKFLOWS_DIR = join(__dirname, "..", "..", "..", "workflows");
+
+// ── 临时 session 目录（RunStore 持久化根），每用例重建 ──────────────────
+let sessionDir: string;
+let createdStores: JsonlRunStore[] = [];
+
+// ── 通用 mock usage（AgentResult.usage 可选，给一个固定值便于排查） ──────
+const MOCK_USAGE: AgentUsage = {
+  input: 10,
+  output: 5,
+  cacheRead: 0,
+  cacheWrite: 0,
+  cost: 0,
+  contextTokens: 15,
+  turns: 1,
+};
+
+// ── 根据 JSON schema 递归生成符合 schema 的占位值 ─────────────────────────
+
+type JsonSchema = {
+  type?: string;
+  description?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+};
+
+/**
+ * 从 JSON schema 生成占位值。
+ *
+ * - string → "mock"（脚本只校验存在性/字符串类型，不校验内容）
+ * - number → 7（0-10 评分等都能用）
+ * - boolean → true
+ * - array → [generate(items)]（至少 1 项；subtasks 这类对象数组给 2 项让脚本有东西可处理）
+ * - object → { properties 递归生成 }
+ *
+ * schema 缺失时回退 null（agent() 在 parsedOutput 为 null 时回退 content，但本测试
+ * 每个 agent() 都带 schema，故不会命中）。
+ */
+function generateFromSchema(schema: JsonSchema | undefined): unknown {
+  if (!schema) return null;
+  switch (schema.type) {
+    case "string":
+      return "mock";
+    case "number":
+    case "integer":
+      return 7;
+    case "boolean":
+      return true;
+    case "array": {
+      const item = generateFromSchema(schema.items);
+      // 对象数组给 2 项（scatter-gather 的 subtasks 需 ≥1 项才能进 process 段；
+      // 给 2 项让并行处理有意义），基本类型数组给 1 项。
+      return schema.items?.type === "object" ? [item, item] : [item];
+    }
+    case "object":
+    default: {
+      const out: Record<string, unknown> = {};
+      if (schema.properties) {
+        for (const [key, sub] of Object.entries(schema.properties)) {
+          out[key] = generateFromSchema(sub);
+        }
+      }
+      return out;
+    }
+  }
+}
+
+/**
+ * 构造 mock AgentRunner：根据每次调用的 opts.schema 生成符合 schema 的 AgentResult。
+ *
+ * runner.run 签名（ports.ts:35）：
+ *   run(opts, signal, onEvent?, stream?) => Promise<AgentResult>
+ * signal/onEvent/stream 接受但忽略（mock 不消费）。parsedOutput 为符合 schema 的对象，
+ * worker 内 agent()/parallel() 取 parsedOutput ?? content 作为脚本可见值。
+ */
+function makeMockRunner(): AgentRunner & { run: ReturnType<typeof vi.fn> } {
+  const run = vi.fn(async (opts: { schema?: unknown }): Promise<AgentResult> => {
+    const parsed = generateFromSchema(opts.schema as JsonSchema | undefined);
+    return {
+      content: "mock",
+      parsedOutput: parsed,
+      usage: MOCK_USAGE,
+      durationMs: 1,
+      error: undefined,
+    };
+  });
+  // AgentRunner 接口仅含 run 方法（ports.ts:35），{ run } 已满足结构。
+  // 额外标注 run 为 vi.fn 返回类型，便于断言调用次数。
+  return { run } as AgentRunner & { run: ReturnType<typeof vi.fn> };
+}
+
+// ── 自定义 registry：从指定目录加载 .js 脚本为 WorkflowScript ─────────────
+
+/**
+ * 从源码用 regex 提取 `const meta = { ... }`（与 config-loader.extractMetaViaRegex
+ * 同语义，避免执行用户代码）。失败时回落到 name=文件名 stem 的空 meta。
+ */
+function extractMeta(source: string, fallbackName: string): WorkflowMeta {
+  const metaPattern = /(?:export\s+)?const\s+meta\s*=\s*(\{[^]*?\});?\s*$/m;
+  const match = metaPattern.exec(source);
+  if (match) {
+    try {
+      const fn = new Function(`return (${match[1]});`);
+      const obj = fn();
+      if (obj && typeof obj === "object" && typeof obj.name === "string") {
+        return {
+          name: obj.name,
+          description: typeof obj.description === "string" ? obj.description : "",
+          phases: Array.isArray(obj.phases) ? obj.phases : [],
+        };
+      }
+    } catch (e) {
+      // meta 提取失败（非法 JS / regex 不匹配）→ 回落 fallback name，非测试关注点
+      void e;
+    }
+  }
+  return { name: fallbackName, description: "", phases: [] };
+}
+
+/**
+ * 从目录扫描 .js 文件，构造 WorkflowScript 实体 map（按 meta.name 索引）。
+ *
+ * 不依赖 WorkflowScriptRegistryImpl（其扫描源是固定约定目录，无法指向任意路径）。
+ * 直接读文件 + 构造 WorkflowScript（其 validate/toExecutable 是纯函数，可直接用）。
+ */
+function loadWorkflowsFromDir(dir: string): Map<string, WorkflowScript> {
+  const scripts = new Map<string, WorkflowScript>();
+  const files = readdirSync(dir);
+  for (const file of files) {
+    if (!file.endsWith(".js")) continue;
+    const fullPath = join(dir, file);
+    const sourceCode = readFileSync(fullPath, "utf-8");
+    const stem = file.replace(/\.js$/, "");
+    const meta = extractMeta(sourceCode, stem);
+    const source: WorkflowSource = "saved";
+    scripts.set(
+      meta.name,
+      new WorkflowScript({
+        name: meta.name,
+        source,
+        path: fullPath,
+        sourceCode,
+        meta,
+        available: true,
+      }),
+    );
+  }
+  return scripts;
+}
+
+/**
+ * 包装 scripts map 为 WorkflowScriptRegistry 接口实现。
+ *
+ * get(name) 返回对应 WorkflowScript（undefined 当不存在）；
+ * loadAll() 返回全部；invalidate() no-op（内存 map 无缓存概念）。
+ */
+function makeRegistry(scripts: Map<string, WorkflowScript>): WorkflowScriptRegistry {
+  return {
+    get: async (name: string) => scripts.get(name),
+    loadAll: async () => Array.from(scripts.values()),
+    invalidate: () => {},
+  };
+}
+
+// ── 构造完整 LauncherDeps（真实 WorkerHost + 真实 RunStore + mock runner） ─
+
+function makeDeps(): LauncherDeps {
+  const scripts = loadWorkflowsFromDir(WORKFLOWS_DIR);
+  const registry = makeRegistry(scripts);
+  const store = new JsonlRunStore({ sessionDir });
+  createdStores.push(store);
+  const runner = makeMockRunner();
+  const base: LifecycleDeps = {
+    store,
+    workerHost: new WorkerHostImpl(),
+    runner,
+    runs: new Map(),
+  };
+  return { ...base, registry };
+}
+
+// ── setup/teardown ──────────────────────────────────────────────────────
+
+beforeEach(() => {
+  sessionDir = mkdtempSync(join(tmpdir(), "wf-e2e-"));
+  createdStores = [];
+});
+
+afterEach(() => {
+  for (const dir of [sessionDir]) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch (e) {
+      // 临时目录清理失败（CI 偶发 EBUSY）不影响测试结论
+      void e;
+    }
+  }
+  sessionDir = "";
+  createdStores = [];
+  vi.restoreAllMocks();
+});
+
+// ── 断言 helper：对每个 workflow 的 WorkflowRunResult 做统一终态断言 ──────
+
+interface ScriptOutcome {
+  status: string;
+  message?: string;
+  error?: string;
+}
+
+/**
+ * 断言 runAndWait 返回成功完成的终态。
+ *
+ * - result.status === "done"（runAndWait 恒 done）
+ * - result.reason === "completed"（脚本正常 return，非 failed/aborted/time_limited）
+ * - result.scriptResult.status 是 "ok" 或 "partial"（脚本层 outcome，非 "error"）
+ * - result.error 为 undefined
+ */
+function assertCompleted(
+  result: { status: string; reason: string; scriptResult?: unknown; error?: string },
+  workflowName: string,
+): void {
+  expect(result.status, `${workflowName}: status 应为 done`).toBe("done");
+  expect(result.reason, `${workflowName}: reason 应为 completed`).toBe("completed");
+  expect(result.error, `${workflowName}: error 应为 undefined`).toBeUndefined();
+  const outcome = result.scriptResult as ScriptOutcome | undefined;
+  expect(outcome, `${workflowName}: scriptResult 应存在`).toBeDefined();
+  expect(outcome!.status, `${workflowName}: outcome.status 不应为 error`).toMatch(
+    /^(ok|partial)$/,
+  );
+}
+
+// ── 超时：真实 worker 启动 + 多轮 agent mock，30s 足够 ─────────────────────
+const RUN_TIMEOUT_MS = 30_000;
+
+// ── tests ────────────────────────────────────────────────────────────────
+
+describe("内置 workflow E2E（真实 worker thread + mock LLM runner）", () => {
+  it(
+    "parallel workflow：多视角并行分析 → 聚合，reason=completed, outcome.status != error",
+    async () => {
+      const deps = makeDeps();
+      const result = await runAndWait(
+        "parallel",
+        { target: "src/auth/login.ts" },
+        deps,
+        undefined,
+        RUN_TIMEOUT_MS,
+      );
+      assertCompleted(result, "parallel");
+      const outcome = result.scriptResult as {
+        status: string;
+        perspectives_analyzed: number;
+        per_perspective: unknown[];
+      };
+      expect(outcome.perspectives_analyzed).toBe(3); // 默认 3 视角
+      expect(outcome.per_perspective).toHaveLength(3);
+    },
+    RUN_TIMEOUT_MS,
+  );
+
+  it(
+    "chain workflow：analyze → transform → synthesize 顺序三步，reason=completed, outcome.status != error",
+    async () => {
+      const deps = makeDeps();
+      const result = await runAndWait(
+        "chain",
+        { task: "把这段需求文档拆成技术任务" },
+        deps,
+        undefined,
+        RUN_TIMEOUT_MS,
+      );
+      assertCompleted(result, "chain");
+      const outcome = result.scriptResult as {
+        status: string;
+        phases_run: string[];
+        final: { summary: string; recommendation: string };
+      };
+      expect(outcome.phases_run).toEqual(["analyze", "transform", "synthesize"]);
+      expect(outcome.final.summary).toBe("mock"); // mock runner 生成 string→"mock"
+    },
+    RUN_TIMEOUT_MS,
+  );
+
+  it(
+    "map-reduce workflow：parallel map → reduce 两段，reason=completed, outcome.status != error",
+    async () => {
+      const deps = makeDeps();
+      const result = await runAndWait(
+        "map-reduce",
+        { operation: "审查代码风格", items: ["file1.ts", "file2.ts"] },
+        deps,
+        undefined,
+        RUN_TIMEOUT_MS,
+      );
+      assertCompleted(result, "map-reduce");
+      const outcome = result.scriptResult as {
+        status: string;
+        phases_run: string[];
+        items_total: number;
+        items_mapped: number;
+      };
+      expect(outcome.phases_run).toEqual(["map", "reduce"]);
+      expect(outcome.items_total).toBe(2);
+      expect(outcome.items_mapped).toBe(2);
+    },
+    RUN_TIMEOUT_MS,
+  );
+
+  it(
+    "scatter-gather workflow：scatter 拆分 → parallel 处理 → gather 合并 三段，reason=completed, outcome.status != error",
+    async () => {
+      const deps = makeDeps();
+      const result = await runAndWait(
+        "scatter-gather",
+        { task: "重构认证模块，涉及 session/jwt/oauth 三块" },
+        deps,
+        undefined,
+        RUN_TIMEOUT_MS,
+      );
+      assertCompleted(result, "scatter-gather");
+      const outcome = result.scriptResult as {
+        status: string;
+        phases_run: string[];
+        subtasks_total: number;
+        subtasks_processed: number;
+      };
+      expect(outcome.phases_run).toEqual(["scatter", "process", "gather"]);
+      // mock runner 的 subtasks 对象数组给 2 项
+      expect(outcome.subtasks_total).toBe(2);
+      expect(outcome.subtasks_processed).toBe(2);
+    },
+    RUN_TIMEOUT_MS,
+  );
+});

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

@@ -49,21 +49,43 @@
 export function buildWorkerScript(userScript: string): string {
   return [
     '"use strict";',
-    '// Module-scope: accessible to the outer .catch() for surfacing logs on errors.',
+    '// Module-scope helpers: accessible to BOTH the IIFE body AND the outer',
+    '// .then()/.catch() handlers (which run outside the IIFE). _workerLogs/',
+    '// _pushWorkerLog/_safePost + the parentPort/workerData handles must all live',
+    '// here — a previous version declared _safePost inside the IIFE, so the',
+    '// .then()/.catch() return/error handlers threw ReferenceError: _safePost is',
+    '// not defined, crashing the Worker on EVERY script return (exit code 1) and',
+    '// losing all diagnostics. require() is cached, so destructuring once at module',
+    '// load and reusing everywhere avoids the redundant require calls that used to',
+    '// appear in the IIFE and the outer .then/.catch.',
+    'const { parentPort: _parentPort, workerData: _workerData } = require("node:worker_threads");',
     'const _workerLogs = [];',
     'function _pushWorkerLog(level, args) {',
     '  try { _workerLogs.push({ level, message: args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") }); } catch (e) { /* swallow */ }',
     '}',
+    '// ── safePostMessage wrapper: 统一 postMessage 防御（DataCloneError 等）──',
+    '// Module-scope so the outer .then/.catch return/error handlers can use it.',
+    '// context 取值约定（诊断标识）：固定为消息类型字面量——',
+    '// "agent-call" / "workflow-call" / "return" / "error"，调用方据此在日志里',
+    '// 一眼定位是哪类 postMessage 失败。新增调用点必须传对应 context。',
+    '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;',
+    '  }',
+    '}',
     '(async () => {',
-    '  const { parentPort, workerData } = require("node:worker_threads");',
+    '  const parentPort = _parentPort;',
+    '  const workerData = _workerData;',
     '',
     '  if (!parentPort) {',
     '    throw new Error("Workflow worker: parentPort is null — not running in a Worker thread");',
     '  }',
     '',
     '  // ── Intercept console.* to avoid leaking worker diagnostics into the input area ──',
-    '  // _workerLogs + _pushWorkerLog are declared at module scope (above the IIFE)',
-    '  // so the outer .catch() can include them on script errors.',
     '  console.log = function (...args) { _pushWorkerLog("log", args); };',
     '  console.warn = function (...args) { _pushWorkerLog("warn", args); };',
     '  console.error = function (...args) { _pushWorkerLog("error", args); };',
@@ -201,7 +223,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 });',
     '    });',
@@ -212,14 +236,34 @@ export function buildWorkerScript(userScript: string): string {
     // 不拖垮整批。rejected 结果降级为错误消息字符串（与 agent() 的 error→content 回退一致，
     // parseResult(string) → null → 脚本 soft-fail）。B1 之后 agent() 不再因 agent 失败 reject，
     // 这里作为纵深防御保留。
+    //
+    // **Promise 项处理**：CC-compatible 写法 `parallel([agent({...}), ...])` 传入的是已实例化
+    // 的 Promise 数组（agent() 同步返回 Promise）。Promise 是 object 但无 .then 鸭辨分支时
+    // 会落到 `agent(c)` 把 Promise 当 opts 传 → postMessage DataCloneError。必须在函数/opts
+    // 分支前用 thenable 鸭辨直接返回 in-flight Promise，让 allSettled 接管。
     '  async function parallel(calls) {',
     '    if (typeof calls === "function") { return calls(); }',
     '    const settled = await Promise.allSettled(calls.map((c) => {',
+    '      if (c && typeof c.then === "function") { return c; }',
     '      if (typeof c === "function") { return c(); }',
     '      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 +271,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 +312,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 });',
     '    });',
@@ -270,13 +328,11 @@ export function buildWorkerScript(userScript: string): string {
     '    return await module.exports.execute({ agent, parallel, pipeline, phase, log, workflow, $ARGS, $WORKSPACE, $BUDGET });',
     '  }',
     '})().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 });',
+    '  const runId = (_workerData.args && typeof _workerData.args === "object" && _workerData.args._runId) || "";',
+    '  _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 });',
+    '  const runId = (_workerData.args && typeof _workerData.args === "object" && _workerData.args._runId) || "";',
+    '  _safePost({ type: "error", runId, error: err.message || String(err), workerLogs: _workerLogs }, "error");',
     '});',
   ].join("\n");
 }