@zhushanwen/pi-subagent-workflow 2.0.1 → 3.0.0

package/src/execution/session-runner.ts

@@ -9,6 +9,8 @@
 import { type ChildProcess,execFileSync, spawn } from "node:child_process";
 import * as fs from "node:fs";
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import type { ExtensionMode } from "./host-mode.ts";
 
 import { type MirrorFlags, mirrorMainProcessFlags } from "./argv-mirror.ts";
@@ -45,6 +47,8 @@ import type {
 import { createTurnLimiter, WRAP_UP_HINT } from "./turn-limiter.ts";
 import { createUiRequestQueue } from "./ui-request-queue.ts";
 
+const logger = getLogger("subagents");
+
 /**
  * 运行时 guard：subscribe 回调收到的 event 形状未知，校验 type 字段后再交给 handle。
  * 防止 SDK 事件结构变化时 switch(raw.type) 静默失配（全走 default 不报错）。
@@ -908,8 +912,10 @@ export async function runSpawn(
           );
         } catch (err) {
           // best-effort：identity 写入失败不影响执行结果，但会影响 /subagents list 重建。
-          // 记录到 stderr（非阻断）—— 终态 record 会从 list 消失，这是可观测的退化信号。
-          console.error(`[subagents] identity append failed for ${record.sessionFile}:`, err);
+          // 记录到 logger（非阻断）—— 终态 record 会从 list 消失，这是可观测的退化信号。
+          logger.error(`[subagents] identity append failed for ${record.sessionFile}`, {
+            detail: err instanceof Error ? err.message : String(err),
+          });
         }
       }
     }

package/src/execution/stdin-writer.ts

@@ -10,8 +10,12 @@
 import type { ChildProcess } from "node:child_process";
 import * as crypto from "node:crypto";
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import type { UiResponse } from "./dialog-queue.ts";
 
+const logger = getLogger("subagents");
+
 /**
  * 按 UiResponse 形状构造 Pi 原生 extension_ui_response 并写 stdin。
  *
@@ -37,7 +41,9 @@ export function respond(child: ChildProcess, id: string, out: UiResponse, signal
     else if ("cancelled" in out) line = JSON.stringify({ type: "extension_ui_response", id, cancelled: true });
   } catch (err) {
     // [R2] out.value 含循环引用/BigInt 等不可序列化结构——降级 cancelled，避免父进程崩溃。
-    console.warn(`[subagents] JSON.stringify failed for ui response ${id}, degrading to cancelled:`, err);
+    logger.warn(`[subagents] JSON.stringify failed for ui response ${id}, degrading to cancelled`, {
+      detail: err instanceof Error ? err.message : String(err),
+    });
     line = JSON.stringify({ type: "extension_ui_response", id, cancelled: true });
   }
   // ack: fire-and-forget，不写 stdin（SR-5）
@@ -102,5 +108,5 @@ export function sendGetStateCommand(child: ChildProcess): string {
 function writeStdinLine(child: ChildProcess, line: string, warnTag: string): void {
   if (!child.stdin || child.stdin.destroyed) return;
   const ok = child.stdin.write(line + "\n");
-  if (!ok) console.warn(`[subagents] stdin backpressure on ${warnTag}`);
+  if (!ok) logger.warn(`[subagents] stdin backpressure on ${warnTag}`);
 }

package/src/execution/subagent-service.ts

@@ -4,6 +4,8 @@
 
 import { AsyncLocalStorage } from "node:async_hooks";
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import type { ExtensionMode } from "./host-mode.ts";
 
 import type { AgentResult as WorkflowAgentResult } from "../orchestration/models/types.ts";
@@ -51,6 +53,8 @@ import { DEFAULT_AGENT_NAME } from "./types.ts";
 import { registerGlobalObservability, UiRequestObservability } from "./ui-request-observability.ts";
 import { WorktreeManager } from "./worktree-manager.ts";
 
+const logger = getLogger("subagents");
+
 /** dispose 后注入的 stub UI 请求 handler。
  *
  * [背景] Pi 单进程 session 串行接管。session A shutdown 时 SIGTERM 子进程后、
@@ -58,7 +62,7 @@ import { WorktreeManager } from "./worktree-manager.ts";
  * 子进程的 trailing extension_ui_request 仍可能被父进程 pump 解析，调到 A 的 handler 闭包。
  * 若 dispose 不清 uiRequestHandler，旧 handler 闭包仍持有 A 的 ctx，触发
  * ui-request-queue.ts 的 catch 分支打 `[subagents] uiRequestHandler threw` 误导性
- * console.error（看起来像 bug，实际是预期竞态；三层兜底已确保功能正确）。
+ * logger.error（看起来像 bug，实际是预期竞态；三层兜底已确保功能正确）。
  *
  * stub 始终返回 {cancelled:true}，不调 ctx.ui、不捕获任何 ctx，让 trailing ui_request
  * 干净降级为 cancelled（等价于子进程主动取消）。
@@ -519,6 +523,15 @@ export class SubagentService {
       );
     }
 
+    // [MF#7] worktree:true requires fork:true — symmetric with execute() guard.
+    // Fails fast before any side effect (record creation / worktree creation).
+    if (opts.worktree === true && !opts.fork) {
+      throw new Error(
+        "worktree:true requires fork:true (worktree isolation only applies to forked sessions). " +
+          "Set fork:true together with worktree:true.",
+      );
+    }
+
     // ── 步骤 1: IDENTITY 解析 ──
     const identity = await this.resolveIdentity(opts);
 
@@ -526,6 +539,27 @@ export class SubagentService {
     const record = this.createRecordForMode(identity, opts, "background");
     emitPendingRegister(this.pi, record.id, record.agent);
 
+    // ── 步骤 2.5: worktree creation (only worktree===true; handle injection is execute()'s path) ──
+    // Workflow path receives boolean only (AgentCallOpts.worktree: boolean) — WorktreeHandle is a
+    // main-thread non-serializable object that cannot cross worker postMessage, so no object branch
+    // here (unlike execute() :445-447 which serves the subagent-tool path). MF#7 guard above ensures
+    // fork===true when worktree===true. On create failure, finalizeFailed cleans up the record, then
+    // throw lets SAR.run() convert it to an AgentResult.error (not return-handle like execute()).
+    let worktreeHandle: WorktreeHandle | undefined;
+    if (opts.worktree === true) {
+      try {
+        worktreeHandle = this.worktreeManager.create(this.cwd, record.id);
+        record.worktreeHandle = worktreeHandle;
+      } catch (err) {
+        // finalizeFailed: CAS→finalizeRecord→emitUnregister (record already registered above).
+        // throw (not return-handle): executeAndAwait's caller SAR.run() catches and wraps into
+        // AgentResult.error. Diverges from execute() :455-456 which returns buildEarlyFailedHandle
+        // because the two methods have different return types.
+        await this.finalizeFailed(record, err);
+        throw err;
+      }
+    }
+
     // ── 步骤 3: SessionRunnerContext ──
     const ctx = this.buildSessionRunnerContext(opts.cwd);
 
@@ -535,7 +569,7 @@ export class SubagentService {
     // 步骤 5: runAndFinalize（await，不 detached）。onUpdate=undefined（BC-11），onEvent 独立传，stream 透传。
     const result = await this.runAndFinalize(
       record,
-      { ...opts, onUpdate: undefined },
+      { ...opts, onUpdate: undefined, worktree: worktreeHandle },
       ctx,
       identity,
       effectiveSignal,
@@ -550,7 +584,24 @@ export class SubagentService {
     //   - CAS 失败（cancel/finalizeFailed/dispose 抢先转终态）→ 那些路径各自已 emit
     //     （cancelBackground L709 / finalizeFailed→finalizeRecord / dispose L240）
     // 旧实现无条件 emit 一次 → CAS 成功分支重复 emit（双注销）。
-    return mapToWorkflowAgentResult(result);
+    const wfResult = mapToWorkflowAgentResult(result);
+    // W2 改动 7：注入 worktreePath（worktree 隔离激活时来自 step 2.5 的 worktreeHandle）。
+    // mapToWorkflowAgentResult 不感知 worktree（它只做 subagents AgentResult → workflow AgentResult
+    // 的 DTO 映射），故在 caller 侧 mutate 刚新建的产物对象（无共享引用，安全）。
+    //
+    // ⚠️ worktreePath is diagnostic only, may not exist — see AgentResult.worktreePath JSDoc
+    // （orchestration/models/types.ts）。下方诊断标识符语义（not cwd）说明同源。
+    //
+    // 诊断标识符语义（not cwd）：
+    //   - runAndFinalize 内的 finalizeRecord 在 return 前已 cleanup（git worktree remove --force），
+    //     worktreePath 指向的目录已被删除，不保证存在。
+    //   - worktreePath 仅供日志/trace 关联（如定位某条 session jsonl 的 worktree 来源），无运行时语义。
+    //   - **不可作为后续 agent 的 cwd**——目录已删，复用会 ENOENT。
+    //   - wave 内 worktree 复用（spec-w §2 "wave 内 8 action 共享 worktree"）在 pi 当前架构下
+    //     不可行：worktree 绑定单次 agent() record，每次 executeAndAwait 结束 finalizeRecord
+    //     无条件 cleanup，worktree 无法跨 action 存活。wave 改用主 cwd（见 recursive-split.js）。
+    wfResult.worktreePath = record.worktreeHandle?.path;
+    return wfResult;
   }
 
   // ── 状态查询（TUI 调）──────────────────────────────────
@@ -750,12 +801,12 @@ export class SubagentService {
       })
       .catch((err: unknown) => {
         // detached 吞错：runAndFinalize 内部已 finalize record（含 emitPendingUnregister），
-        // 且 finalizeRecord 的 manifest 写入已降级为 best-effort（失败仅 console.error + appendEntry，
+        // 且 finalizeRecord 的 manifest 写入已降级为 best-effort（失败仅 logger.error + appendEntry，
         // 不外抛）。因此此处不应走到——但作为最后一道兼底，记录调试日志后吞下，不外抛。
         // 完成通知由 finalizeRecord 内的 emitPendingUnregister 承担（pending-notifications 消费）。
         // cancel 抢先时 status=cancelled，cancelBackground 自己 emit，此处无需重复。
         if (err instanceof Error) {
-          console.debug(`[subagent] background finalize error (record=${record.id}): ${err.message}`);
+          logger.debug(`[subagent] background finalize error (record=${record.id}): ${err.message}`);
         }
       });
   }

package/src/execution/ui-request-handler-factory.ts

@@ -19,12 +19,15 @@
 //   setUiRequestHandler——/resume /fork 复用 existingService 时旧 handler 可能已失效。
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import { DialogGlobalQueue, type UiRequest, type UiRequestHandler, type UiResponse } from "./dialog-queue.ts";
 import { type HostMode, resolveHostMode } from "./host-mode.ts";
 import type { UiChannelRegistry } from "./ui-channels.ts";
 import { isDialogMethod } from "./ui-interaction-model.ts";
 
+const logger = getLogger("subagents");
+
 /** 按 ctx.mode 创建 UI 请求 handler（透传 + 排队总控）。
  *
  *  透传矩阵（§一冲突 2）：
@@ -100,7 +103,7 @@ function createRealHandler(
  *    - 形状不匹配 → 降级 {cancelled:true}（保守，不阻塞队列） */
 function coerceUiResponse(raw: unknown, reqId: string): UiResponse {
   if (typeof raw !== "object" || raw === null) {
-    console.warn("[subagents] channel handler returned non-object, coercing to cancelled (req=", reqId, ")");
+    logger.warn("[subagents] channel handler returned non-object, coercing to cancelled", { detail: { reqId } });
     return { cancelled: true };
   }
   const obj = raw as Record<string, unknown>;
@@ -108,7 +111,7 @@ function coerceUiResponse(raw: unknown, reqId: string): UiResponse {
   if (typeof obj.confirmed === "boolean") return { confirmed: obj.confirmed };
   if (obj.cancelled === true) return { cancelled: true };
   if (obj.ack === true) return { ack: true };
-  console.warn("[subagents] channel handler returned unrecognized shape, coercing to cancelled (req=", reqId, ")");
+  logger.warn("[subagents] channel handler returned unrecognized shape, coercing to cancelled", { detail: { reqId } });
   return { cancelled: true };
 }
 
@@ -153,21 +156,18 @@ async function defaultDialogForward(
         const text = await ui.editor(req.title ?? "", req.prefill);
         return text === undefined ? { cancelled: true } : { value: text };
       } catch (err) {
-        console.warn(
-          "[subagents] ctx.ui.editor unavailable/threw, returning cancelled for",
-          req.id,
-          err,
+        logger.warn(
+          "[subagents] ctx.ui.editor unavailable/threw, returning cancelled",
+          { detail: { id: req.id, error: err instanceof Error ? err.message : String(err) } },
         );
         return { cancelled: true };
       }
     }
     default: {
       // 未知 dialog method（非 select/confirm/input/editor）——保守 cancelled 不阻塞子进程
-      console.warn(
+      logger.warn(
         "[subagents] defaultDialogForward: unknown dialog method",
-        req.method,
-        "for",
-        req.id,
+        { detail: { method: req.method, id: req.id } },
       );
       return { cancelled: true };
     }

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

@@ -3,8 +3,12 @@
 // UI 请求可观测性状态（从 subagent-service.ts 提取，降低主文件行数）。
 // 持有 sessionMode + handler 缺失告警去重集合，供 SubagentService 委托调用。
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import type { ExtensionMode } from "./host-mode.ts";
 
+const logger = getLogger("subagents");
+
 // ── 跨模块桥接（ui-request-queue 无 ctx.service 引用时走这里） ──
 //
 // ui-request-queue.handleUiRequest 在 ctx.uiRequestHandler 缺失时需要触发去重告警，
@@ -32,7 +36,7 @@ export function notifyMissingHandlerGlobal(sessionId: string): void {
   if (obs) {
     obs.notifyMissingHandler(sessionId);
   } else {
-    console.warn(
+    logger.warn(
       `[subagents] uiRequestHandler missing (session=${sessionId}, global observability not registered)`,
     );
   }
@@ -72,6 +76,6 @@ export class UiRequestObservability {
       this.warnedMissingHandlerSessions.clear();
     }
     this.warnedMissingHandlerSessions.add(sessionId);
-    console.warn(`[subagents] uiRequestHandler missing (session=${sessionId}, mode=${this.sessionMode})`);
+    logger.warn(`[subagents] uiRequestHandler missing (session=${sessionId}, mode=${this.sessionMode})`);
   }
 }

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

@@ -13,6 +13,8 @@
 
 import type { ChildProcess } from "node:child_process";
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import type { UiRequest } from "./dialog-queue.ts";
 // 类型再导出：dialog-queue.ts 是 UiRequest/UiResponse/UiRequestHandler 的规范来源，
 // 本模块再导出供测试 import（避免测试直接依赖 dialog-queue 内部实现）。
@@ -23,6 +25,8 @@ import { respond } from "./stdin-writer.ts";
 import { parseChannel } from "./ui-channels.ts";
 import { notifyMissingHandlerGlobal } from "./ui-request-observability.ts";
 
+const logger = getLogger("subagents");
+
 /**
  * 创建 UI 请求队列。返回 enqueue 函数，调用方将 extension_ui_request 入队。
  *
@@ -142,7 +146,9 @@ async function handleUiRequest(
   } catch (err) {
     // [R3] 子进程已退出，跳过写入
     if (signal?.aborted) return;
-    console.error("[subagents] uiRequestHandler threw:", err);
+    logger.error("[subagents] uiRequestHandler threw", {
+      detail: err instanceof Error ? err.message : String(err),
+    });
     respond(child, id, { cancelled: true }, signal);
   }
 }

package/src/index.ts

@@ -19,6 +19,7 @@ import * as path from "node:path";
 
 import type { ExtensionAPI, ExtensionContext, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 
 import type { AgentRegistry } from "./execution/agent-registry.ts";
 import { bestEffort } from "./execution/best-effort.ts";
@@ -73,7 +74,14 @@ declare module "@earendil-works/pi-coding-agent" {
 
 // ── Factory ──────────────────────────────────────────────────
 
+// 模块级 logger（setPiHandle 注入后自动走 appendEntry）
+const logger = getLogger("subagents");
+
 export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
+  // 注入 pi handle 给全局 extension-logger，让深层代码（best-effort / error-recovery）
+  // 的 getLogger("subagents") 也能走 appendEntry。
+  setPiHandle(pi);
+
   // ════════════════════════════════════════════════════════════
   //  subagents 域：tool + command + messageRenderer
   // ════════════════════════════════════════════════════════════
@@ -260,8 +268,9 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     try {
       maybeCleanupExpiredSessionFiles(agentDir, cwd);
     } catch (err) {
-      void err;
-      console.warn("[subagents] expired session file cleanup failed:", err);
+      logger.warn("[subagents] expired session file cleanup failed", {
+        reason: err instanceof Error ? err.message : String(err),
+      });
     }
 
     // ADR-035 启动恢复：扫描 manifest tmp 残留（崩溃打断的 writeManifest 留下），
@@ -269,19 +278,21 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     try {
       const recovered = await service.recoverManifestTmpFiles();
       if (recovered.recovered > 0 || recovered.deleted > 0) {
-        console.warn(`[subagents] manifest tmp recovery: ${recovered.recovered} promoted, ${recovered.deleted} deleted`);
+        logger.warn(`[subagents] manifest tmp recovery: ${recovered.recovered} promoted, ${recovered.deleted} deleted`);
       }
     } catch (err) {
-      void err;
-      console.warn("[subagents] manifest tmp recovery failed:", err);
+      logger.warn("[subagents] manifest tmp recovery failed", {
+        reason: err instanceof Error ? err.message : String(err),
+      });
     }
 
     try {
       const wtm = new WorktreeManager(agentDir);
       wtm.scan();
     } catch (err) {
-      void err;
-      console.warn("[subagents] worktree reaper scan failed:", err);
+      logger.warn("[subagents] worktree reaper scan failed", {
+        reason: err instanceof Error ? err.message : String(err),
+      });
     }
 
     // ── workflow 域：per-session store + runs ──
@@ -315,7 +326,9 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       }
     } catch (err) {
       // QMF-4 fix: store.loadAll 失败是关键路径错误，workflow 域将未初始化
-      console.error("[subagent-workflow] store.loadAll failed, workflow domain uninitialized:", err);
+      logger.error("[subagent-workflow] store.loadAll failed, workflow domain uninitialized", {
+        reason: err instanceof Error ? err.message : String(err),
+      });
       storeHealthy = false;
     }
 

package/src/interface/subagent-tool.ts

@@ -12,6 +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 { getLogger } from "@zhushanwen/pi-extension-logger";
 import { type Static, Type } from "typebox";
 
 import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
@@ -236,9 +237,10 @@ A subagent MAY call the \`subagent\` tool itself (each level spawns its own chil
 // 回调实现（模块级 const）
 // ============================================================
 
-// ponytail: renderCall 每次 TUI invalidate 都触发，同一解析错误会重复刷屏。
-// 按错误消息去重（Set），session 内只报第一次。错误消息含 modelStr，足够区分。
-const reportedRenderErrors = new Set<string>();
+// ponytail: renderCall 每次 TUI invalidate 都触发。streaming 中 args 是 partial JSON
+// 解析结果（如 model="deep" 来自未流完的 "deepseek-router/ds-pro"），解析失败是预期。
+// 不走 appendEntry（非真实错误），只走 logger.debug（默认 no-op，PI_EXT_DEBUG=1 写文件）。
+const renderCallLogger = getLogger("subagents");
 
 const subagentRenderCall: SubagentRenderCallCb = (args, theme, ctx) => {
   // 预解析 model（同步）：让标题行能显示 model/thinking，不必等 execute。
@@ -256,14 +258,11 @@ const subagentRenderCall: SubagentRenderCallCb = (args, theme, ctx) => {
     const r = service?.resolveModel(agent, override);
     if (r) resolved = { model: `${r.model.provider}/${r.model.id}`, thinkingLevel: r.thinkingLevel };
   } catch (err) {
-    // service 未注册 / modelRegistry 未注入 / 无可用 model → 降级不显示 model（renderCall 不应崩）。
-    // 去重：同一 err.message 只 console.debug 一次，避免 TUI invalidate 反复刷屏。
-    const msg = err instanceof Error ? err.message : String(err);
-    if (!reportedRenderErrors.has(msg)) {
-      reportedRenderErrors.add(msg);
-      void err; // 显式确认忽略：renderCall 降级是设计意图，不阻断渲染
-      console.debug("[subagents] renderCall model resolution failed, degrading:", err);
-    }
+    // streaming 中间态（partial JSON）或 service 未就绪 → 降级不显示 model（renderCall 不应崩）。
+    // 不阻断渲染，不污染 TUI。开发期开 PI_EXT_DEBUG=1 可写文件日志排查。
+    renderCallLogger.debug("renderCall model resolution failed, degrading", {
+      reason: err instanceof Error ? err.message : String(err),
+    });
   }
   return renderSubagentCall(args, theme, ctx, resolved);
 };

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

@@ -23,6 +23,19 @@ import { fileURLToPath } from "node:url";
 
 import { describe, expect, it, vi } from "vitest";
 
+// Mock 共享 logger，让 logger.error 可被 spy（源码已从 console.error 改为 logger.error）
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+  },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => loggerMock,
+}));
+
 import { handleWorkerMessage, postBudgetUpdate } from "../error-recovery.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
 import type { WorkflowRun } from "../models/workflow-run.ts";
@@ -98,10 +111,12 @@ function postedAt(postMessage: ReturnType<typeof vi.fn>, idx: number): PostedMsg
   return postMessage.mock.calls[idx]![0] as PostedMsg;
 }
 
-/** 静默 console.error（防御路径会打印诊断，避免污染测试输出）。 */
+/** 清空 logger.error 调用记录（防御路径会打印诊断，避免污染跨用例断言）。 */
 function silenceConsoleError(): () => void {
-  const spy = vi.spyOn(console, "error").mockImplementation(() => {});
-  return () => spy.mockRestore();
+  loggerMock.error.mockClear();
+  return () => {
+    loggerMock.error.mockClear();
+  };
 }
 
 // ── W2a: postBudgetUpdate try/catch ──
@@ -140,8 +155,8 @@ describe("W2a: postBudgetUpdate 防御 DataCloneError", () => {
 
       postBudgetUpdate(run);
 
-      expect(console.error).toHaveBeenCalledTimes(1);
-      const diag = (console.error as ReturnType<typeof vi.fn>).mock.calls[0]![0] as string;
+      expect(loggerMock.error).toHaveBeenCalledTimes(1);
+      const diag = loggerMock.error.mock.calls[0]![0] as string;
       expect(diag).toContain("postBudgetUpdate failed");
       expect(diag).toContain("Could not clone object");
     } finally {
@@ -243,7 +258,7 @@ describe("W2b: dispatchWorkflowCall postResult 防御 DataCloneError", () => {
 
       // 至少 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);
+      const errorCalls = loggerMock.error.mock.calls.map((c) => c[0] as string);
       expect(errorCalls.some((s) => s.includes("fallback also failed"))).toBe(true);
     } finally {
       restore();
@@ -345,7 +360,7 @@ describe("W2c: postAgentResult 行为测试（cached replay 路径）", () => {
 
       // 至少 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);
+      const errorCalls = loggerMock.error.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 {

package/src/orchestration/__tests__/error-recovery-serialize-failed-result.test.ts

@@ -0,0 +1,56 @@
+// src/orchestration/__tests__/error-recovery-serialize-failed-result.test.ts
+//
+// makeSerializeFailedResult 独立单测（W2 防御关键纯函数）。
+//
+// 背景：postMessage 序列化失败时，主线程需回发「必可克隆」的 fallback result
+// 让 worker 内 pending Promise resolve（否则 agent()/workflow() 永久挂起，只能靠
+// timeout 兜底）。两条 fallback 路径（postAgentResult / dispatchWorkflowCall.postResult）
+// 共享 makeSerializeFailedResult 构造逻辑——本测试锁住其返回 shape，确保两条路径
+// 不漂移。
+//
+// 验证点：
+//   1. content 恒为 ""（纯字符串 fallback，必可克隆——不含 function/Symbol/循环引用）
+//   2. error 形如 "<prefix>: <errMsg>"（前缀区分调用方，便于诊断定位）
+//   3. prefix / errMsg 各自原样透传（含空串、特殊字符、多行）
+
+import { describe, expect, it } from "vitest";
+
+import { makeSerializeFailedResult } from "../error-recovery.ts";
+
+describe("makeSerializeFailedResult", () => {
+  it("返回 {content:'', error:'<prefix>: <errMsg>'} 形状（必可克隆 fallback）", () => {
+    const result = makeSerializeFailedResult("Result serialization failed", "DataCloneError: ...");
+    expect(result).toEqual({
+      content: "",
+      error: "Result serialization failed: DataCloneError: ...",
+    });
+  });
+
+  it("content 恒为空串（纯字符串 fallback，不含不可克隆成员）", () => {
+    // 无论入参如何，content 必为 ""——postMessage 必须能克隆这个 fallback result。
+    const result = makeSerializeFailedResult("any prefix", "any error");
+    expect(result.content).toBe("");
+  });
+
+  it("error 由 prefix + ': ' + errMsg 拼接（前缀区分调用方，便于诊断）", () => {
+    const result = makeSerializeFailedResult("Workflow result serialization failed", "boom");
+    expect(result.error).toBe("Workflow result serialization failed: boom");
+    // 分隔符固定为 ": "——两条 fallback 路径共享同一构造逻辑。
+    expect(result.error).toContain(": ");
+  });
+
+  it("prefix 与 errMsg 原样透传（含空串、特殊字符、多行）", () => {
+    // 空串 prefix
+    expect(makeSerializeFailedResult("", "err").error).toBe(": err");
+    // 空串 errMsg
+    expect(makeSerializeFailedResult("prefix", "").error).toBe("prefix: ");
+    // 含冒号 / 换行 / unicode 的 errMsg（原样透传，不做转义）
+    const weird = "err: with: colons\nand newline 中文 🚀";
+    expect(makeSerializeFailedResult("P", weird).error).toBe(`P: ${weird}`);
+  });
+
+  it("返回对象字段仅 content + error（无多余字段，shape 稳定不漂移）", () => {
+    const result = makeSerializeFailedResult("p", "e");
+    expect(Object.keys(result).sort()).toEqual(["content", "error"]);
+  });
+});