@zhushanwen/pi-subagent-workflow 0.4.2 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "0.4.2",
+  "version": "2.0.0",
   "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.",
@@ -46,8 +46,8 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-tui": "*",
-    "@sinclair/typebox": "*",
-    "@zhushanwen/pi-structured-output": "0.3.5"
+    "typebox": "*",
+    "@zhushanwen/pi-structured-output": "2.0.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/src/execution/__tests__/crash-recovery.test.ts

@@ -29,7 +29,7 @@ vi.mock("@earendil-works/pi-ai", () => ({
 vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: string[]) => ({ type: "string", enum: values }),
 }));
-vi.mock("@sinclair/typebox", () => ({
+vi.mock("typebox", () => ({
   Type: {
     Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
     Optional: (schema: unknown) => ({ ...(schema as object), optional: true }),

package/src/execution/__tests__/index-session-start.test.ts

@@ -51,7 +51,7 @@ vi.mock("@earendil-works/pi-ai", () => ({
 vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: string[]) => ({ type: "string", enum: values }),
 }));
-vi.mock("@sinclair/typebox", () => ({
+vi.mock("typebox", () => ({
   Type: {
     Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
     Optional: (schema: unknown) => ({ ...(schema as object), optional: true }),

package/src/execution/__tests__/sdk-contract.test.ts

@@ -12,19 +12,19 @@
 // 不导入 index.ts（它经 getAgentDir 值导入触发 alias 解析失败——alias 指向
 // .d.ts-only stub）。改测叶子注册函数。session_start 的
 // (event, ctx) 双参数契约由 tsconfig 的精确 stub 类型在编译期强制（见
-// shared/types/mariozechner/index.d.ts 注释：modelRegistry/cwd/ui 不在 event 上）。
+// 注释：modelRegistry/cwd/ui 不在 event 上）。
 
 import { describe, expect, it, vi } from "vitest";
 
 // registerSubagentTool 经 subagent-tool.ts 值导入 StringEnum（pi-ai）+ Type（typebox）。
-// shared/types stub 是 .d.ts（仅类型），pnpm optional-peer-dep 插件拦截值导入 → vi.mock 兜底。
+// stub 是 .d.ts（仅类型），pnpm optional-peer-dep 插件拦截值导入 → vi.mock 兜底。
 vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: string[]) => ({ type: "string", enum: values }),
 }));
 vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: string[]) => ({ type: "string", enum: values }),
 }));
-vi.mock("@sinclair/typebox", () => ({
+vi.mock("typebox", () => ({
   Type: {
     Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
     Optional: (schema: unknown) => ({ ...schema as object, optional: true }),
@@ -263,7 +263,7 @@ describe("subagent tool contract [MANDATORY]", () => {
 // ============================================================
 describe("session_start handler signature (compile-time guarantee)", () => {
   it("ExtensionHandler<SessionStartEvent> is (event, ctx) two-param — enforced by stub type", () => {
-    // 此测试是编译期断言：shared/types/mariozechner/index.d.ts:111 声明
+    // 此测试是编译期断言：stub 类型声明
     //   ExtensionHandler<E, R> = (event: E, ctx: ExtensionContext) => Promise<R|void> | R | void;
     // 且 SessionStartEvent 注释明确 modelRegistry/cwd/ui 不在 event 上（在 ctx）。
     // index.ts:66 `pi.on("session_start", (_event, ctx) => {...})` 通过此类型检查即证明契约。

package/src/execution/__tests__/session-start-reaper.test.ts

@@ -21,7 +21,7 @@ vi.mock("@earendil-works/pi-ai", () => ({
 vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: string[]) => ({ type: "string", enum: values }),
 }));
-vi.mock("@sinclair/typebox", () => ({
+vi.mock("typebox", () => ({
   Type: {
     Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
     Optional: (schema: unknown) => ({ ...schema as object, optional: true }),

package/src/execution/dialog-queue.ts

@@ -144,7 +144,7 @@ interface QueueItem {
  *
  * 单 session 假设（M-2，与 index.ts lastSessionId 同源）：本队列是进程级单例（实例挂在
  * globalThis[Symbol.for("@zhushanwen/pi-subagents.dialogQueue")]，见 getOrCreateDialogQueue）。
- * rejectAll()/clear() 清空所有 pending dialog——无 per-session 隔离。Pi 当前架构保证单进程
+ * rejectAll() 清空所有 pending dialog——无 per-session 隔离。Pi 当前架构保证单进程
  * 单 session 串行（同进程不会并发多个 session），故 session_shutdown 调 rejectAll() 只会清掉
  * 当前 session 的 pending。若未来 Pi 支持同进程多 session 并发，session A 退出会误清 session B
  * 的 pending dialog——届时需改为 per-session 隔离（入队项 QueueItem 带 sessionId，rejectAll
@@ -314,9 +314,10 @@ export class DialogGlobalQueue {
     this.processing = false;
   }
 
-  /** 清空队列（dispose 用）。pending 项的 Promise 不 settle（dispose 时调用方已不关心）。
-   *  如需 settle，dispose 前应先 rejectChildDialogs 或 rejectAll。 */
-  clear(): void {
+  /** 清空队列状态（仅在 rejectAll 之后调用）。pending Promise 必须先由 rejectAll settle。
+   *  不 settle Promise 的纯状态重置——单独调用会导致 Promise 永挂（footgun），故设为 private。
+   *  外部调用方应使用 rejectAll()（它 settle 所有 pending + 重置状态，是原子操作）。 */
+  private resetState(): void {
     this.queue = [];
     this.current = undefined;
     this.processing = false;

package/src/execution/host-mode.ts

@@ -16,7 +16,11 @@
 //     集中到单一修改点，未来 Pi 新增 mode 值时只改本文件。
 //   - 业务语义命名（"gui"/"headless"）比原始枚举值更清晰表达意图。
 
-import type { ExtensionMode } from "@earendil-works/pi-coding-agent";
+// ExtensionMode 在 Pi SDK 的 core/extensions/types.d.ts 中定义为
+// `"tui" | "rpc" | "json" | "print"`（ExtensionContext.mode 的类型），但未从包根
+// 导出。这里定义与 SDK 同构的本地别名（ctx.mode 的字面量联合），由同包其他模块复用，
+// 避免依赖未导出的内部类型。
+export type ExtensionMode = "tui" | "rpc" | "json" | "print";
 
 /** 主进程运行模式分类。基于 ExtensionMode 聚合为业务语义。
  *  - "tui"：纯 Pi TUI，ctx.ui.custom 可用，用户在终端交互

package/src/execution/model-resolver.ts

@@ -10,7 +10,7 @@
 
 /**
  * ModelRegistry 的最小接口（duck-typed，测试可 mock）。
- * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐（见 shared/types stub）。
+ * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐。
  */
 export interface ModelRegistryLike {
   /** 返回所有已配置鉴权的可用模型。 */

package/src/execution/session-runner.ts

@@ -9,7 +9,7 @@
 import { type ChildProcess,execFileSync, spawn } from "node:child_process";
 import * as fs from "node:fs";
 
-import type { ExtensionMode } from "@earendil-works/pi-coding-agent";
+import type { ExtensionMode } from "./host-mode.ts";
 
 import { type MirrorFlags, mirrorMainProcessFlags } from "./argv-mirror.ts";
 import { writeAliveMarker } from "./alive-store.ts";

package/src/execution/subagent-service.ts

@@ -4,7 +4,7 @@
 
 import { AsyncLocalStorage } from "node:async_hooks";
 
-import type { ExtensionMode } from "@earendil-works/pi-coding-agent";
+import type { ExtensionMode } from "./host-mode.ts";
 
 import type { AgentResult as WorkflowAgentResult } from "../orchestration/models/types.ts";
 // D-A10: workflow 侧 AgentResult 映射（executeAndAwait 出口）

package/src/execution/ui-request-observability.ts

@@ -3,7 +3,7 @@
 // UI 请求可观测性状态（从 subagent-service.ts 提取，降低主文件行数）。
 // 持有 sessionMode + handler 缺失告警去重集合，供 SubagentService 委托调用。
 
-import type { ExtensionMode } from "@earendil-works/pi-coding-agent";
+import type { ExtensionMode } from "./host-mode.ts";
 
 // ── 跨模块桥接（ui-request-queue 无 ctx.service 引用时走这里） ──
 //

package/src/index.ts

@@ -17,7 +17,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import type { ExtensionAPI, ExtensionContext, ModelSelectEvent, ResourcesDiscoverEvent, ResourcesDiscoverResult, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 import type { AgentRegistry } from "./execution/agent-registry.ts";
@@ -90,7 +90,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // resources_discover：不再注入额外 skill 目录（ADR-031 废弃 discovery.json）。
   // pi 核心 auto-discovery 已覆盖 .agents/skills 等标准目录，子 session 的
   // --skill 由 agent({skill}) 调用方显式传入，无需 extension 额外补充。
-  pi.on("resources_discover", (_event: ResourcesDiscoverEvent, _ctx: ExtensionContext): ResourcesDiscoverResult => {
+  pi.on("resources_discover", (_event, _ctx: ExtensionContext) => {
     return {};
   });
 
@@ -342,7 +342,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // ════════════════════════════════════════════════════════════
   //  model_select：用户切换 model 时刷新缓存
   // ════════════════════════════════════════════════════════════
-  pi.on("model_select", (event: ModelSelectEvent, ctx: ExtensionContext) => {
+  pi.on("model_select", (event, ctx: ExtensionContext) => {
     const service = getModelConfigService();
     if (service && typeof service.setCtxModel === "function") {
       service.setCtxModel(event.model);
@@ -396,10 +396,9 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     }
 
     // M2: 清理 dialog queue 运行时状态（queue/current/processing）。
-    // [#10] 先 rejectAll() settle 所有 pending dialog Promise（防闭包泄漏：未 settle 的
+    // [#10] rejectAll() settle 所有 pending dialog Promise（防闭包泄漏：未 settle 的
     // Promise 持有 resolve/reject 闭包及 handler 上下文，session 退出后仍挂在全球队列上），
-    // 再 clear() 重置 queue/current/processing（防异常退出后 processing=true 卡死下次 session）。
-    // rejectAll() 由 dialog-queue.ts 提供（Group B 新增）；若其内部已 reset 状态，此处 clear() 为幂等兜底。
+    // 并内部重置 queue/current/processing（原子操作，无 footgun）。
     // 单 session 假设（M-2，同 lastSessionId）：rejectAll() 清空进程级单例的所有 pending，
     // 依赖 Pi 单进程单 session 串行保证——不会误清其他 session。多 session 并发的迁移策略
     // 见 DialogGlobalQueue 类注释（rejectAllForSession）。
@@ -407,7 +406,6 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     // 在 /new /resume /fork 时不丢失注册）。
     const dialogQueue = getOrCreateDialogQueue();
     dialogQueue.rejectAll();
-    dialogQueue.clear();
   });
 
   // ════════════════════════════════════════════════════════════

package/src/interface/commands.ts

@@ -66,6 +66,36 @@ export function registerWorkflowsCommand(
 ): void {
   api.registerCommand("workflows", {
     description: "Open workflow panel. /workflows [runId] | /workflows pause|resume|abort <runId>",
+    getArgumentCompletions(prefix: string) {
+      const trimmed = prefix.trimStart();
+      const parts = trimmed.split(/\s+/).filter(Boolean);
+
+      // 第一级：lifecycle 动词（带尾随空格，选中后继续补 runId）
+      if (parts.length <= 1) {
+        return [
+          { label: "pause", value: "pause ", description: "Pause a workflow run" },
+          { label: "resume", value: "resume ", description: "Resume a paused workflow run" },
+          { label: "abort", value: "abort ", description: "Abort a workflow run" },
+        ].filter((opt) => opt.label.startsWith(trimmed.toLowerCase()));
+      }
+
+      // 第二级：lifecycle 动词后补全当前 session 的 runId
+      if (parts[0] === "pause" || parts[0] === "resume" || parts[0] === "abort") {
+        try {
+          const runs = sortedRuns(getRuns());
+          if (runs.length === 0) return null;
+          return runs.map((r) => ({
+            label: r.runId,
+            value: r.runId,
+            description: `${r.spec.scriptName} [${r.state.status}]`,
+          }));
+        } catch {
+          // 拿不到运行时数据（getRuns 抛错）→ 静默降级，补全失败不影响 command
+          return null;
+        }
+      }
+      return null;
+    },
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       // ── RPC 模式（xyz-agent GUI）：解析 lifecycle action 直接执行，不打开 TUI ──
       // hasUI 在 TUI 和 RPC 都为 true，不能用于区分；用 ctx.mode === "rpc" 判定 GUI 通道。

package/src/interface/subagent-tool.ts

@@ -12,7 +12,7 @@
 import type { Component } from "@earendil-works/pi-tui";
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
+import { type Static, Type } from "typebox";
 
 import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
 import { getSubagentService } from "../execution/subagent-service.ts";
@@ -27,44 +27,15 @@ import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./t
 // ============================================================
 
 /**
- * execute 回调的 params 类型（手写副本——stub registerTool 是 unknown，
- * 无法从 SubagentParams schema 反向推断参数类型）。
+ * execute 回调的 params 类型由 SubagentParams schema 经 Static 投影得出（见下方 cb 签名）。
  * action 与对应 param 不匹配时 handler 内 throw。
  */
-interface ListParam {
-  includeFinished?: boolean;
-  limit?: number;
-}
-
-interface CancelParam {
-  subagentId: string;
-}
-
-interface SubagentExecuteParams {
-  action: "start" | "list" | "cancel";
-  // action:"start" 的 13 字段拍平到顶层（弱模型常省略 startParam 嵌套层导致调用失败）。
-  // 拍平后这些字段直接在顶层（全部 optional——schema flat 无法表达「action 条件必填」，
-  // 由 startHandler runtime 校验 task/slug 必填）。
-  task?: string;
-  slug?: string;
-  agent?: string;
-  model?: string;
-  thinkingLevel?: string;
-  skillPath?: string;
-  appendSystemPrompt?: string[];
-  schema?: Record<string, unknown>;
-  maxTurns?: number;
-  graceTurns?: number;
-  fork?: boolean;
-  worktree?: boolean;
-  cwd?: string;
-  listParam?: ListParam;
-  cancelParam?: CancelParam;
-}
-
 type SubagentExecuteCb = (
   toolCallId: string,
-  params: SubagentExecuteParams,
+  // Pi SDK 从 parameters schema 反向推断 params 类型。typebox v1 的 StringEnum
+  // 在 Static 投影下退化为 string（非字面量联合），因此 action 在 cb 入参里是 string，
+  // 由下方 isSubagentAction 类型守卫收窄到字面量联合后再 switch。
+  params: Static<typeof SubagentParams>,
   signal: AbortSignal | undefined,
   onUpdate?: (partialResult: AgentToolResult<SubagentToolResult>) => void,
   // ctx 在 SDK 契约里必填；此处保持 optional 以兼容 onUpdate? 在前（TS 参数顺序约束），
@@ -166,6 +137,16 @@ function assertNever(value: never): string {
   return String(value);
 }
 
+/** Subagent action 字面量联合（与 parameters schema 的 StringEnum 取值一致）。 */
+type SubagentAction = "start" | "list" | "cancel";
+
+/** 类型守卫：把 schema 投影出的 string 形式 action 收窄回字面量联合。
+ *  typebox v1 的 StringEnum Static 退化为 string，需运行时校验 + 类型收窄
+ *  才能恢复 switch 的 exhaustiveness 约束。 */
+function isSubagentAction(value: string): value is SubagentAction {
+  return value === "start" || value === "list" || value === "cancel";
+}
+
 /** unknown 是否为含 model/thinkingLevel 的对象（类型守卫，替代全可选结构 `as`）。 */
 function isModelOverrideObj(a: unknown): a is { model?: unknown; thinkingLevel?: unknown } {
   return typeof a === "object" && a !== null;
@@ -324,6 +305,11 @@ const executeSubagent: SubagentExecuteCb = async (
   const service = getSubagentService();
   if (!service) throw new Error("subagents runtime not initialized");
 
+  // typebox v1 的 StringEnum 在 Static 投影下退化为 string，此处类型守卫收窄回
+  // 字面量联合，恢复 switch 的 exhaustiveness 约束（default 分支 = never）。
+  if (!isSubagentAction(params.action)) {
+    throw new Error(`Unknown subagent action: ${params.action}`);
+  }
   switch (params.action) {
     case "start":
       // 拍平后直接传顶层 params（StartHandlerInput 是 SubagentExecuteParams 子集，

package/src/interface/subagents.ts

@@ -9,12 +9,45 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 
 import { getSubagentService } from "../execution/subagent-service.ts";
 import { parseSubagentRpcCommand } from "./command-actions.ts";
+import { LIST_LIMIT } from "./list-shared.ts";
 import { createSubagentsView } from "./list-view.ts";
 
 /** 注册 /subagents 命令（= list overlay）。 */
 export function registerSubagentsCommand(pi: ExtensionAPI): void {
   pi.registerCommand("subagents", {
     description: "Subagents: /subagents [<id>] | /subagents cancel <id>",
+    getArgumentCompletions(prefix: string) {
+      const trimmed = prefix.trimStart();
+      const parts = trimmed.split(/\s+/).filter(Boolean);
+
+      // 第一级：cancel 动词（带尾随空格，选中后继续补 record id）
+      if (parts.length <= 1) {
+        return [
+          { label: "cancel", value: "cancel ", description: "Cancel a running subagent" },
+        ].filter((opt) => opt.label.startsWith(trimmed.toLowerCase()));
+      }
+
+      // 第二级：cancel 后补全当前 session 的 record id
+      if (parts[0] === "cancel") {
+        try {
+          const service = getSubagentService();
+          if (!service) return null;
+          // collectRecords 合并内存(running) + 磁盘重建 record，按 session 过滤。
+          // cancel 只对 running 有效，但全部列出便于用户辨认（终态 record 会被 service 拒绝）。
+          const records = service.collectRecords(LIST_LIMIT);
+          if (records.length === 0) return null;
+          return records.map((r) => ({
+            label: r.id,
+            value: r.id,
+            description: `${r.agent} [${r.status}]`,
+          }));
+        } catch {
+          // 拿不到运行时数据（service disposed 等）→ 静默降级，补全失败不影响 command
+          return null;
+        }
+      }
+      return null;
+    },
     handler: async (argsStr: string, ctx: ExtensionCommandContext) => {
       const service = getSubagentService();
       if (!service) {

package/src/interface/views/WorkflowsView.ts

@@ -109,7 +109,7 @@ function walled(theme: ThemeLike, content: string, contentWidth: number): string
 }
 
 // ── Minimal TUI duck-types（避免直接 import TUI/KeybindingsManager 类型 ──
-// 共享类型 fallback shared/types/mariozechner/index.d.ts 不导出 TUI 类，
+// 共享类型 fallback 不导出 TUI 类，
 // workspace 跨包 typecheck 会报 "no exported member 'TUI'"。
 // 此处用结构化接口替代——只声明 view 实际用到的成员（requestRender + terminal）。
 

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

@@ -0,0 +1,347 @@
+/**
+ * buildWorkerScript — 运行时执行回归测试。
+ *
+ * 现有的 worker-script-builder.test.ts 全是字符串 toContain 断言，无法捕获生成的
+ * worker 源码在「真实 Worker 线程里执行」时的运行时错误。曾因此漏掉 _safePost 作用域
+ * bug（定义在 async IIFE 内、却在 IIFE 外的 .then()/.catch() 里使用）：脚本每次正常
+ * return 都触发 ReferenceError → Worker exit code 1 → 所有 workflow 100% 失败。
+ *
+ * 本测试起真实的 node:worker_threads.Worker 执行 buildWorkerScript 产物，覆盖：
+ * - 脚本正常 return → {type:"return"} 消息（非 exit code 1 崩溃）
+ * - 脚本 throw → {type:"error"} 消息 + workerLogs（诊断不丢）
+ * - agent() 调用链路：postMessage(agent-call) ↔ postMessage(agent-result)
+ * - abort 消息：pending agent() reject → WorkflowAbortedError
+ * - workflow() 嵌套调用链路
+ * - module.exports.execute() 自动调用入口
+ * - _safePost 的 DataCloneError 防御分支
+ *
+ * 这是回归防线：任何让 .then/.catch 访问不到 module-scope helper 的重构都会被这里抓住。
+ */
+import { Worker } from "node:worker_threads";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { buildWorkerScript } from "../worker-script-builder.ts";
+
+// ── 判别联合：Worker → Main 消息类型（S3：用判别联合替代可选字段 + 非空断言）──
+
+/** agent-call 消息：worker 请求主线程执行一个 agent。 */
+interface AgentCallMsg {
+  type: "agent-call";
+  callId: number;
+  opts: { prompt: string; description?: string; schema?: unknown; [k: string]: unknown };
+  phase?: string;
+}
+/** workflow-call 消息：worker 请求主线程执行嵌套 workflow。 */
+interface WorkflowCallMsg {
+  type: "workflow-call";
+  callId: number;
+  name: string;
+  args: Record<string, unknown>;
+}
+/** return 消息：脚本正常结束，带回结果。 */
+interface ReturnMsg {
+  type: "return";
+  runId?: string;
+  result: unknown;
+  workerLogs?: unknown[];
+}
+/** error 消息：脚本抛错（含 _safePost 的 DataCloneError 防御路径）。 */
+interface ErrorMsg {
+  type: "error";
+  runId?: string;
+  error: string;
+  workerLogs?: unknown[];
+}
+
+// ── 类型守卫：从 unknown 收窄到判别联合 ──
+// 共享 hasType 辅助：避免每个守卫重复 `(m as {type?:string})` 断言（taste/no-unsafe-catch）。
+
+function hasType<T extends string>(m: unknown, type: T): boolean {
+  return typeof m === "object" && m !== null
+    && (m as { type: unknown }).type === type;
+}
+
+function isAgentCall(m: unknown): m is AgentCallMsg {
+  return hasType(m, "agent-call");
+}
+function isWorkflowCall(m: unknown): m is WorkflowCallMsg {
+  return hasType(m, "workflow-call");
+}
+function isReturn(m: unknown): m is ReturnMsg {
+  return hasType(m, "return");
+}
+function isError(m: unknown): m is ErrorMsg {
+  return hasType(m, "error");
+}
+
+// ── 测试辅助：起一个真实 Worker 跑 buildWorkerScript 产物 ──────────────
+
+interface RunResult {
+  /** 收到的 return 消息的 result 字段（脚本正常结束时）。 */
+  returnValue?: unknown;
+  /** 收到的 error 消息的 error 字段（脚本 throw 时）。 */
+  errorMessage?: string;
+  /** error 消息带回的 workerLogs（验证诊断不丢）。 */
+  errorWorkerLogs?: unknown[];
+  /** Worker exit code（0=正常，1=崩溃）。 */
+  exitCode?: number;
+  /** Worker 'error' 事件的错误消息（uncaught exception，正常应为 undefined）。 */
+  workerError?: string;
+  /** 收到的 agent-call 消息列表。 */
+  agentCalls: AgentCallMsg[];
+  /** 收到的 workflow-call 消息列表。 */
+  workflowCalls: WorkflowCallMsg[];
+}
+
+interface RunOptions {
+  /** $ARGS。 */
+  args?: Record<string, unknown>;
+  /** 按 agent-call 顺序回发的 parsedOutput（默认每个回发 {ok:true}）。 */
+  agentResults?: unknown[];
+  /** 主线程对收到的 workflow-call 的处理：回发 workflow-result。 */
+  handleWorkflowCall?: (msg: WorkflowCallMsg) => unknown;
+  /** 是否在收到首个 agent-call 后立即发 abort（测 abort 路径）。 */
+  abortAfterFirstAgentCall?: { reason: string };
+  /** 超时（S9：CI 环境放宽，规避真实 Worker 启动慢导致的假阳）。 */
+  timeoutMs?: number;
+  /** workerData.callCache 预填（测缓存命中路径）。 */
+  callCache?: Map<number, unknown>;
+}
+
+/**
+ * 起 Worker 执行 userScript，主线程模拟 workflow runtime 回发 agent-result。
+ *
+ * @param userScript 用户 workflow 脚本源码
+ */
+function runWorker(userScript: string, opts: RunOptions = {}): Promise<RunResult> {
+  const timeoutMs = opts.timeoutMs ?? (process.env.CI ? 5000 : 2000);
+  return new Promise((resolve, reject) => {
+    const workerCode = buildWorkerScript(userScript);
+    const worker = new Worker(workerCode, {
+      eval: true,
+      workerData: {
+        scriptPath: "test.js",
+        args: opts.args ?? {},
+        workspace: process.cwd(),
+        budget: { maxTokens: 0, usedTokens: 0, usedCost: 0 },
+        callCache: opts.callCache instanceof Map
+          ? Object.fromEntries(opts.callCache)
+          : opts.callCache ?? {},
+      },
+    });
+    // S8：创建后立即登记，afterEach 兜底清理（防止 promise 泄漏导致 Worker 未终止）
+    createdWorkers.push(worker);
+
+    const result: RunResult = { agentCalls: [], workflowCalls: [] };
+    let agentCallIdx = 0;
+    let resolved = false;
+    const timer = setTimeout(() => {
+      worker.terminate().catch(() => {});
+      reject(new Error(`Worker timed out after ${timeoutMs}ms — likely hung`));
+    }, timeoutMs);
+
+    const finish = (r: RunResult): void => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      resolve(r);
+    };
+
+    worker.on("message", (raw: unknown) => {
+      if (isAgentCall(raw)) {
+        result.agentCalls.push(raw);
+        if (opts.abortAfterFirstAgentCall) {
+          worker.postMessage({ type: "abort", reason: opts.abortAfterFirstAgentCall.reason });
+          return;
+        }
+        const parsed = opts.agentResults?.[agentCallIdx] ?? { ok: true };
+        agentCallIdx++;
+        worker.postMessage({
+          type: "agent-result",
+          callId: raw.callId,
+          result: { content: "fallback", parsedOutput: parsed },
+          cached: false,
+        });
+      } else if (isWorkflowCall(raw)) {
+        result.workflowCalls.push(raw);
+        const wfResult = opts.handleWorkflowCall ? opts.handleWorkflowCall(raw) : { ok: true };
+        worker.postMessage({ type: "workflow-result", callId: raw.callId, result: wfResult });
+      } else if (isReturn(raw)) {
+        result.returnValue = raw.result;
+        finish(result);
+      } else if (isError(raw)) {
+        result.errorMessage = raw.error;
+        result.errorWorkerLogs = raw.workerLogs;
+        finish(result);
+      }
+    });
+    worker.on("error", (err: Error) => {
+      result.workerError = err.message;
+      // error 事件后 Worker 会 exit code 1，给 exit handler 一个 tick 记录 exitCode
+    });
+    worker.on("exit", (code: number) => {
+      result.exitCode = code;
+      // 若未通过 return/error 消息结束（即 Worker 崩溃），以 exit 结果收尾
+      if (result.returnValue === undefined && result.errorMessage === undefined) {
+        finish(result);
+      }
+    });
+  });
+}
+
+// 记录所有创建的 Worker，afterEach 兜底清理（防止泄漏）——S8
+const createdWorkers: Worker[] = [];
+
+afterEach(() => {
+  for (const w of createdWorkers.splice(0)) {
+    w.terminate().catch(() => {});
+  }
+});
+
+// ── 回归测试：_safePost 作用域 bug（核心防线） ──────────────────────
+
+describe("buildWorkerScript runtime — _safePost scope regression (exit code 1 bug)", () => {
+  it("脚本正常 return 时发出 return 消息，Worker 不崩溃（exit code 0）", async () => {
+    const script = `return { status: "ok", value: 42 };`;
+    const res = await runWorker(script);
+    expect(res.workerError).toBeUndefined();
+    expect(res.errorMessage).toBeUndefined();
+    expect(res.returnValue).toEqual({ status: "ok", value: 42 });
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("脚本 throw 时发出 error 消息并带回 workerLogs，Worker 不裸崩", async () => {
+    const script = `
+      console.log("before throw");
+      throw new Error("script boom");
+    `;
+    const res = await runWorker(script);
+    expect(res.workerError).toBeUndefined();
+    expect(res.errorMessage).toBe("script boom");
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("agent() → result → return 完整链路：parallel 风格脚本正常完成", async () => {
+    const script = `
+      phase("analyze");
+      const results = await parallel([
+        () => agent({ prompt: "task-1", description: "a1" }),
+        () => agent({ prompt: "task-2", description: "a2" }),
+      ]);
+      const ok = results.filter((r) => r && r.ok).length;
+      return { status: "ok", analyzed: results.length, ok };
+    `;
+    const res = await runWorker(script, { agentResults: [{ ok: true }, { ok: true }] });
+    expect(res.agentCalls).toHaveLength(2);
+    expect(res.workerError).toBeUndefined();
+    expect(res.returnValue).toEqual({ status: "ok", analyzed: 2, ok: 2 });
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("脚本 return 后 Worker 不发 workerError 事件（_safePost 在 .then 可达）", async () => {
+    const script = `return "done";`;
+    const res = await runWorker(script);
+    expect(res.workerError).toBeUndefined();
+    expect(res.returnValue).toBe("done");
+  });
+
+  it("parallel([agent(...), ...]) Promise 数组：CC 兼容写法不触发 DataCloneError", async () => {
+    // parallel.js/map-reduce.js/scatter-gather.js 都用 `parallel([agent({...}), ...])`——
+    // 传入已实例化的 Promise 数组（agent() 同步返回 Promise）。旧 parallel() 实现把
+    // Promise 当 opts 传给 agent() → postMessage DataCloneError → allSettled 全 rejected
+    // → 脚本返回 error。修复：parallel() 用 thenable 鸭辨直接返回 in-flight Promise。
+    // 此测试用真实的 Promise 数组写法（而非函数数组），对应内置脚本的真实用法。
+    const script = `
+      const results = await parallel([
+        agent({ prompt: "p1", description: "a1" }),
+        agent({ prompt: "p2", description: "a2" }),
+      ]);
+      return { count: results.length, ok: results.every((r) => r && r.ok) };
+    `;
+    const res = await runWorker(script, { agentResults: [{ ok: true }, { ok: true }] });
+    expect(res.agentCalls).toHaveLength(2);
+    expect(res.workerError).toBeUndefined();
+    expect(res.errorMessage).toBeUndefined();
+    expect(res.returnValue).toEqual({ count: 2, ok: true });
+    expect(res.exitCode).not.toBe(1);
+  });
+});
+
+// ── S4-S7：覆盖此前缺失的运行时路径 ──────────────────────────────────
+
+describe("buildWorkerScript runtime — 之前缺失的路径覆盖", () => {
+  it("S4 abort 消息：pending agent() 被 reject → WorkflowAbortedError", async () => {
+    // 脚本 await 一个 agent()，主线程回发 abort → agent reject → 脚本抛错进 .catch
+    const script = `
+      await agent({ prompt: "will-be-aborted" });
+    `;
+    const res = await runWorker(script, { abortAfterFirstAgentCall: { reason: "user cancel" } });
+    // abort 让 pending reject → 脚本 throw WorkflowAbortedError → .catch 发 type:error
+    expect(res.agentCalls).toHaveLength(1);
+    expect(res.workerError).toBeUndefined();
+    expect(res.errorMessage).toMatch(/Workflow aborted/);
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("S5 workflow() 嵌套调用：workflow-call ↔ workflow-result 链路正常", async () => {
+    const script = `
+      const r = await workflow("sub-wf", { x: 1 });
+      return { nested: r };
+    `;
+    const res = await runWorker(script, {
+      handleWorkflowCall: (msg) => ({ echo: msg.args, name: msg.name }),
+    });
+    expect(res.workflowCalls).toHaveLength(1);
+    expect(res.workflowCalls[0]!.name).toBe("sub-wf");
+    expect(res.workerError).toBeUndefined();
+    expect(res.returnValue).toEqual({ nested: { echo: { x: 1 }, name: "sub-wf" } });
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("S6 module.exports.execute() 自动调用入口：ctx 注入完整、return 正常", async () => {
+    const script = `
+      const meta = { name: "exec-mode" };
+      module.exports = {
+        meta,
+        execute: async (ctx) => {
+          const r = await ctx.agent({ prompt: "via-execute" });
+          return { viaExecute: true, agentResult: r, hasGlobals: typeof ctx.parallel === "function" };
+        },
+      };
+    `;
+    const res = await runWorker(script, { agentResults: [{ ok: true, source: "exec" }] });
+    expect(res.agentCalls).toHaveLength(1);
+    expect(res.workerError).toBeUndefined();
+    expect(res.returnValue).toEqual({
+      viaExecute: true,
+      agentResult: { ok: true, source: "exec" },
+      hasGlobals: true,
+    });
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("S7 _safePost 的 .catch 路径带回 workerLogs：脚本 throw 时诊断不丢", async () => {
+    // _safePost 的价值两半：(1) return 路径成功发消息（S1-S3 覆盖）；
+    // (2) error 路径（.catch）发 type:error + workerLogs，让主线程拿到诊断。
+    // 本例验证 .catch 里的 _safePost 正常工作——脚本 throw → console.* 被劫持进
+    // _workerLogs → .catch 用 _safePost 发回 {type:"error", workerLogs}。
+    // 修复前 .catch 里的 _safePost 是 ReferenceError，workerLogs 发不回（errorLogs 全空）。
+    const script = `
+      console.log("step-1");
+      console.warn("step-2-warning");
+      throw new Error("diagnostic-test-error");
+    `;
+    const res = await runWorker(script);
+    expect(res.workerError).toBeUndefined();
+    expect(res.errorMessage).toBe("diagnostic-test-error");
+    expect(res.errorWorkerLogs).toBeDefined();
+    expect(res.errorWorkerLogs).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ level: "log", message: "step-1" }),
+        expect.objectContaining({ level: "warn", message: "step-2-warning" }),
+      ]),
+    );
+    expect(res.exitCode).not.toBe(1);
+  });
+});

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

@@ -67,7 +67,9 @@ describe("buildWorkerScript — W1 postMessage defense & parallel degrade", () =
     });
 
     it("_safePost wraps postMessage in try/catch", () => {
-      expect(script).toMatch(/_safePost[\s\S]*?try \{ parentPort\.postMessage\(msg\)/);
+      // _safePost 在 module scope（parentPort 解析为 _parentPort），
+      // 用宽松正则匹配「try { <something>.postMessage(msg)」避免绑死变量名。
+      expect(script).toMatch(/_safePost[\s\S]*?try \{ _parentPort\.postMessage\(msg\)/);
     });
 
     it("_safePost logs failure with context to workerLogs", () => {

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/worker-script-builder.ts

@@ -49,37 +49,48 @@
 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); };',
     '  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;',
@@ -225,9 +236,15 @@ 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);',
@@ -311,12 +328,10 @@ 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) || "";',
+    '  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) || "";',
+    '  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");