@zhushanwen/subagent-core 0.4.0 → 0.5.1

package/src/orchestration/execute-agent-call.ts

@@ -8,16 +8,23 @@
  * 职责：
  * - 重试：3 次 + 指数退避（BACKOFF_MS = [1000, 2000, 4000]）
  * - 预算：超限不重试（直接 markDone failed）
- * - stale-context：不重试（直接 markDone failed）
- * - [MF-1] 确定性 schema 失败：不重试（直接 markDone failed）
+ * - stale-context（result.failureKind="stale_context"）：不重试（直接 markDone failed）
+ * - [MF-1] 确定性 schema 失败（result.failureKind="schema_deterministic"）：不重试
+ *   （直接 markDone failed）
  * - 成功：consume usage + incrementCallCount + markDone + trace.update(completed)
  *
+ * [D5-③ 结构化分诊] 失败分诊读 AgentResult.failureKind 字段（产出侧唯一识别点 =
+ * execution/engine/engines/pi/output-collector.ts 的 classifyFailureKind，词表归属
+ * 见其文件头）。本模块不再扫 error 文案子串——**语义守恒（r1 MF4）**：unknown
+ * （含字段缺省）= 可重试，保持收敛前的默认重试语义；仅 stale_context（不重试、
+ * 换参重发场景由调用方编排）与 schema_deterministic 维持特判。
+ *
  * 关键设计：
  * - **usage 透传**：result.usage 直接交给 budget.consume，加权由 Budget 内部的权重常量
- * 处理（见 budget.ts）。此函数不再做 usage 形状的改写。
+ *   处理（见 budget.ts）。此函数不再做 usage 形状的改写。
  * - **参数显式化**：runner 直接传入（而非 ctx.getRun(runId).pool），无 runId 查找 / pool 守卫。
  * - **stale-state 检查**：signal.aborted 时早返回。WorkflowRun 状态由调用方 lifecycle
- * 持有，executeAgentCall 只关心单次 call 生命周期。
+ *   持有，executeAgentCall 只关心单次 call 生命周期。
  *
  * 层归属：Engine。零 infra 依赖（runner 是 AgentRunner port，budget/trace/call 是 Engine 模型）。
  *
@@ -41,69 +48,6 @@ const BACKOFF_EXPONENT_BASE = 2;
 /** 最大尝试次数（含首次）：initial + 2 retries = 3。 */
 const MAX_ATTEMPTS = 3;
 
-/**
- * Stale context 检测模式（P1-5；W4b 对齐 pi 0.84.x 真实文案）。
- *
- * pi session context 被 compact/cancel 时报告的模式。这种情况下重试无意义——
- * 同样的 call 会再次失败。直接 markDone failed 终止单次调用。
- *
- * W4b：原 "stale context"/"stalecontext" 与 pi 真实文案零匹配（真实文案为
- * "This extension ctx is stale after session replacement or reload. ..."——
- * runner.ts:544（dist runner.js:352），词序是 "ctx is stale" 而非 "stale context"），stale 分诊对
- * 真实文案失效。现对齐：
- * - "ctx is stale"：真实文案核心子串（词序修正）
- * - "stale after session replacement"：scheduler 已验证 marker（runtime.ts
- *   STALE_CTX_MARKER，同文案锚定）
- * - "context canceled"/"aborted"：保留——abort 族错误同样不重试（signal.aborted
- *   分支的先行分诊，防边界竞态漏网），删除会放宽重试语义。
- */
-export const STALE_CONTEXT_PATTERNS = [
-  "ctx is stale",
-  "stale after session replacement",
-  "context canceled",
-  "aborted",
-] as const;
-
-/**
- * 判断错误信息是否表示 stale/canceled pi session context。
- * 命中时不重试——重试只会再次失败（P1-5）。
- */
-export function isStaleContextErrorMsg(msg: string | undefined): boolean {
-  if (!msg) return false;
-  const lower = msg.toLowerCase();
-  return STALE_CONTEXT_PATTERNS.some((p) => lower.includes(p));
-}
-
-/**
- * [MF-1] 确定性 schema 失败标记（error 文本前缀，产出方 = output-collector 的
- * describeMissingParsedOutput）。
- *
- * 标记 SSOT 放本模块（与 STALE_CONTEXT_PATTERNS 同布局：orchestration 持表、
- * execution 值引用；反向引用会形成 execute-agent-call → output-collector →
- * execute-agent-call 运行时循环）。
- *
- * 标记词逐字核对不命中 STALE_CONTEXT_PATTERNS 任一 pattern 与
- * isStaleContextErrorMsg 的子串匹配（否则归因 error 被误诊 stale-context，
- * 虽然同样不重试但归因语义被污染；output-collector.test 有交叉锁定）。
- *
- * 三态可重试性矩阵（F-1 归因）：
- * | 归因态                     | 带本标记 | 可重试性 | 理由 |
- * |----------------------------|---------|---------|------|
- * | ① 从未调用 SO tool         | 是      | 不可重试 | 缺 extension 是环境确定性（C1 安装盲区），同环境重试必同结果 |
- * | ② SO 调用 isError（gate 终止/不可满足 schema） | 是 | 不可重试 | 同 schema 重试必同结果（第五轮实测：3 attempts/4 子进程/235s 纯烧钱） |
- * | ③ 调用过但无 details        | 否      | 可重试   | 可能瞬态（details 提取/序列化异常），保留既有重试语义 |
- */
-export const DETERMINISTIC_SCHEMA_FAILURE_PREFIX = "Structured output failed deterministically:";
-
-/**
- * [MF-1] 判断错误信息是否为确定性 schema 失败（命中标记前缀）。
- * 命中时不重试——同 schema 重试必同结果（矩阵见 DETERMINISTIC_SCHEMA_FAILURE_PREFIX）。
- */
-export function isDeterministicSchemaFailureMsg(msg: string | undefined): boolean {
-  if (!msg) return false;
-  return msg.includes(DETERMINISTIC_SCHEMA_FAILURE_PREFIX);
-}
-
 // ── 内部 helper ──────────────────────────────────────────────
 
 /**
@@ -124,7 +68,7 @@ function backoffDelay(retryIndex: number): number {
  * rebuild 竞态窗口中，重跑 dispatch 已 append 同 stepIndex 新节点，旧代际
  * finalize 的 update 会命中新节点，TUI/中间快照短暂可见错误终态。正确性论证：
  * 运行期 calls Map 写点仅 discardInFlightCalls 的 delete 与 dispatchAgentCall 的
- * set 两族（error-recovery.ts isOrphanedCall 文档注释既定），故实例不等 ⟺ 本
+ * set 两族（worker-message-pump.ts isOrphanedCall 文档注释既定），故实例不等 ⟺ 本
  * finalize 属于被丢弃/被替换的旧代际——与 dispatch 层 .then/.catch 守卫
  * （S7-second 修复，8353f6b60）同一判定语义，本守卫只是把它前移到 trace.update
  * 之前。markDone 与 sessionId/sessionFile 同步保留（markDone 在孤儿实例上无害，
@@ -208,16 +152,18 @@ export async function executeAgentCall(
     budget.consume(result.usage);
   }
 
-  // stale-context：不重试（P1-5）
-  if (result.error !== undefined && isStaleContextErrorMsg(result.error)) {
+  // stale-context（D5-③ 结构化分诊：读 failureKind 字段，词表识别在产出侧
+  // output-collector）：不重试（P1-5）
+  if (result.error !== undefined && result.failureKind === "stale_context") {
     finalizeCall(call, result, trace, isOrphaned);
     budget.incrementCallCount();
     return;
   }
 
-  // [MF-1] 确定性 schema 失败：不重试（gate 终止/不可满足 schema 同 schema 重试必同
-  // 结果——重试纯烧钱；三态可重试性矩阵见 DETERMINISTIC_SCHEMA_FAILURE_PREFIX）
-  if (result.error !== undefined && isDeterministicSchemaFailureMsg(result.error)) {
+  // [MF-1] 确定性 schema 失败（failureKind="schema_deterministic"）：不重试
+  // （gate 终止/不可满足 schema 同 schema 重试必同结果——重试纯烧钱；三态矩阵
+  // 见产出侧 output-collector 的确定性失败标记注释）
+  if (result.error !== undefined && result.failureKind === "schema_deterministic") {
     finalizeCall(call, result, trace, isOrphaned);
     budget.incrementCallCount();
     return;

package/src/orchestration/launcher.ts

@@ -31,7 +31,9 @@ import type { LifecycleDeps } from "./models/ports.ts";
 import type { RunSpec } from "./models/run-spec.ts";
 import type { DoneReason } from "./models/types.ts";
 import type { WorkflowRun } from "./models/workflow-run.ts";
+import type { WorkflowScript } from "./models/workflow-script.ts";
 import type { WorkflowScriptRegistry } from "./models/workflow-script-registry.ts";
+import type { LintResult } from "./script-lint.ts";
 import { assertSafeTimerDelay } from "../shared/timer-delay.ts";
 
 // ── 常量 ─────────────────────────────────────────────────────
@@ -106,6 +108,14 @@ function pollInterval(): Promise<void> {
   });
 }
 
+/** lint findings 摘要串（runAndWait / executeNestedWorkflow 共用同一错误文案格式）。 */
+function formatLintErrorSummary(lintResult: LintResult): string {
+  return lintResult.findings
+    .filter((f) => f.severity === "error")
+    .map((f) => `L${f.line}: ${f.message}`)
+    .join("; ");
+}
+
 /**
  * 从 WorkflowRun 构建 WorkflowRunResult（D-8）。
  *
@@ -243,11 +253,9 @@ export async function runAndWait(
   // 2. lint 校验（失败抛错——脚本本身有问题，不应静默吞）
   const lintResult = script.validate();
   if (!lintResult.valid) {
-    const errors = lintResult.findings
-      .filter((f) => f.severity === "error")
-      .map((f) => `L${f.line}: ${f.message}`)
-      .join("; ");
-    throw new Error(`Workflow script '${name}' has lint errors: ${errors}`);
+    throw new Error(
+      `Workflow script '${name}' has lint errors: ${formatLintErrorSummary(lintResult)}`,
+    );
   }
 
   // 3. 构建 RunSpec
@@ -312,19 +320,118 @@ async function safeAbort(
 
 // ── executeNestedWorkflow（workflow() 嵌套调用实现） ────────
 
+/** 父 run 的循环检测链：[...parentChain, parentScriptName]（顶层 run 无 chain 时前段为空）。 */
+function buildParentChain(parentRun: WorkflowRun): string[] {
+  return [...(parentRun.spec.parentWorkflowChain ?? []), parentRun.spec.scriptName];
+}
+
+/** Step 2 的 signal 继承产物（childController + 父 signal/回调——finally 移除 listener 用）。 */
+interface InheritedSignal {
+  childController: AbortController;
+  parentSignal: AbortSignal | undefined;
+  onParentAbort: () => void;
+}
+
+/**
+ * Step 2: signal 继承——子 run 响应父 run abort（parentController → childController）。
+ *
+ * [L-2] onParentAbort 提取为命名函数以便 finally removeEventListener，防子 run 完成后
+ * parentSignal 上残留 listener（多次嵌套调用会累积）。
+ */
+function inheritParentSignal(parentRun: WorkflowRun): InheritedSignal {
+  const childController = new AbortController();
+  const parentSignal = parentRun.runtime?.controller.signal;
+  const onParentAbort = (): void => childController.abort();
+  if (parentSignal) {
+    if (parentSignal.aborted) {
+      childController.abort();
+    } else {
+      parentSignal.addEventListener("abort", onParentAbort, { once: true });
+    }
+  }
+  return { childController, parentSignal, onParentAbort };
+}
+
+/**
+ * Step 4: 构建 RunSpec（共享父 Budget + 循环链）。
+ *
+ * budget 共享（F-7 方案 B）：子 run 直接复用父 Budget 引用（budgetRef），consume 实时
+ * 累加到父 Budget，消除并行嵌套下的超支窗口，无需 sync-back。
+ */
+function buildNestedSpec(
+  args: Record<string, unknown>,
+  parentRun: WorkflowRun,
+  script: WorkflowScript,
+  chain: string[],
+): RunSpec {
+  return {
+    scriptSource: script.toExecutable(),
+    args,
+    budgetRef: parentRun.state.budget,
+    // Run-level override 传播（与父 run 对齐）：子 run 继承父 run 的 model/thinkingLevel，
+    // 否则嵌套 workflow 丢失父 run 的模型指定，回落主 agent 模型。
+    model: parentRun.spec.model,
+    thinkingLevel: parentRun.spec.thinkingLevel,
+    scriptName: script.name,
+    scriptPath: script.path,
+    description: script.meta.description,
+    parameters: script.meta.parameters,
+    parentWorkflowChain: chain,
+  };
+}
+
+/**
+ * 嵌套 workflow timeout 从父 run 完整传导：父 spec.budgetTimeMs 显式设定时原样作为子 run
+ * 轮询 deadline（不 min(DEFAULT) 封顶——旧实现把父 time:2h 截断到 10min，违背「显式传参
+ * 完整生效」语义）；父未设 → undefined，无 deadline（不限）。
+ * [U2] 预算语义统一：父 budgetTimeMs <=0（含 0/负）与 undefined 同义 = 不限——与
+ * lifecycle.runWorkflow 的 budgetTimeMs 判定（>0 才挂 scheduleTimeBudget）对齐。
+ */
+function resolveNestedTimeoutMs(parentRun: WorkflowRun): number | undefined {
+  const raw = parentRun.spec.budgetTimeMs;
+  return raw !== undefined && raw > 0 ? raw : undefined;
+}
+
+/**
+ * Step 6: 结果转换（budget 已通过共享 budgetRef 实时同步，无需 sync-back）。
+ * completed → content = 字符串原样 / 其余 JSON.stringify；非 completed → error result。
+ */
+function toNestedCallResult(
+  name: string,
+  result: WorkflowRunResult,
+): { content: string; parsedOutput?: unknown; error?: string } {
+  if (result.reason === "completed") {
+    const scriptResult = result.scriptResult;
+    return {
+      content:
+        typeof scriptResult === "string"
+          ? scriptResult
+          : JSON.stringify(scriptResult ?? ""),
+      parsedOutput:
+        typeof scriptResult === "object" && scriptResult !== null
+          ? scriptResult
+          : undefined,
+    };
+  }
+  return {
+    content: "",
+    error: result.error ?? `Workflow '${name}' ended: ${result.reason}`,
+  };
+}
+
 /**
  * workflow() 嵌套调用的 Engine 实现。
  *
- * Worker 脚本内调 workflow(name, args) 时，error-recovery.dispatchWorkflowCall 路由
+ * Worker 脚本内调 workflow(name, args) 时，worker-message-pump.dispatchWorkflowCall 路由
  * 到 deps.onWorkflowCall，后者（Interface 层 makeDeps 注入）委托本函数。
  *
- * 流程（6 步）：
+ * 流程（6 步，Step 2-6 的机制细节见各 helper）：
  * 1. 循环检测——name 已在 parentWorkflowChain 中则拒绝（防 A→B→A 死循环）
- * 2. signal 继承——子 run 响应父 run abort（parentController → childController）
+ * 2. signal 继承——子 run 响应父 run abort（inheritParentSignal）
  * 3. registry.get + lint——失败返回 error result（不抛错，让脚本 soft-fail）
  * 4. 构建 RunSpec（共享父 Budget 引用 + parentWorkflowChain 延长）+ runWorkflow
  * 5. pollRunToResult 轮询至 done（复用 runAndWait 的轮询逻辑）
- * 6. 结果转换（budget 已通过共享引用实时同步）
+ * 6. 结果转换（toNestedCallResult）
  *
  * 不走 runAndWait：runAndWait 内部构建 RunSpec 不支持 parentWorkflowChain 与 budget
  * 共享引用，故直接构建 spec + runWorkflow + pollRunToResult。
@@ -342,10 +449,7 @@ export async function executeNestedWorkflow(
   deps: LauncherDeps,
 ): Promise<{ content: string; parsedOutput?: unknown; error?: string }> {
   // Step 1: 循环检测——parentWorkflowChain 不存在时为 []（顶层 run）
-  const chain = [
-    ...(parentRun.spec.parentWorkflowChain ?? []),
-    parentRun.spec.scriptName,
-  ];
+  const chain = buildParentChain(parentRun);
   if (chain.includes(name)) {
     return {
       content: "",
@@ -354,21 +458,10 @@ export async function executeNestedWorkflow(
   }
 
   // Step 2: signal 继承——子 run 响应父 run abort
-  // [L-2] 提取命名 onParentAbort 以便 finally removeEventListener，防子 run 完成后
-  //  parentSignal 上残留 listener（多次嵌套调用会累积）。
-  const childController = new AbortController();
-  const parentSignal = parentRun.runtime?.controller.signal;
-  const onParentAbort = (): void => childController.abort();
-  if (parentSignal) {
-    if (parentSignal.aborted) {
-      childController.abort();
-    } else {
-      parentSignal.addEventListener("abort", onParentAbort, { once: true });
-    }
-  }
+  const { childController, parentSignal, onParentAbort } = inheritParentSignal(parentRun);
 
   // Step 3+：registry 查找 + lint + RunSpec + runWorkflow + poll 全程 try（m3 E8——
-  // try 起点提到 Step 2 的 listener 注册之后，覆盖 Step 3-6。runWorkflow throw
+  // try 起点在 Step 2 的 listener 注册之后，覆盖 Step 3-6。runWorkflow throw
   // （含 chokepoint ArgsValidationError）与 not found/lint 早返回均走 finally 移除
   // parentSignal listener——修复原 try 外 runWorkflow 的泄漏路径）。
   try {
@@ -379,76 +472,30 @@ export async function executeNestedWorkflow(
     }
     const lintResult = script.validate();
     if (!lintResult.valid) {
-      const errors = lintResult.findings
-        .filter((f) => f.severity === "error")
-        .map((f) => `L${f.line}: ${f.message}`)
-        .join("; ");
       return {
         content: "",
-        error: `Workflow script '${name}' has lint errors: ${errors}`,
+        error: `Workflow script '${name}' has lint errors: ${formatLintErrorSummary(lintResult)}`,
       };
     }
 
-    // Step 4: 构建 RunSpec（共享父 Budget + 循环链）+ 启动子 workflow
-    // budget 共享（F-7 方案 B）：子 run 直接复用父 Budget 引用（budgetRef），consume 实时
-    // 累加到父 Budget，消除并行嵌套下的超支窗口，无需 Step 6 的 sync-back。
-    const spec: RunSpec = {
-      scriptSource: script.toExecutable(),
-      args,
-      budgetRef: parentRun.state.budget,
-      // Run-level override 传播（与父 run 对齐）：子 run 继承父 run 的 model/thinkingLevel，
-      // 否则嵌套 workflow 丢失父 run 的模型指定，回落主 agent 模型。
-      model: parentRun.spec.model,
-      thinkingLevel: parentRun.spec.thinkingLevel,
-      scriptName: script.name,
-      scriptPath: script.path,
-      description: script.meta.description,
-      parameters: script.meta.parameters,
-      parentWorkflowChain: chain,
-    };
+    // Step 4: 构建 RunSpec + 启动子 workflow
+    // budgetRef（共享 Budget）已在 spec 透传给子 run 处理 token/cost 预算，
+    // resolveNestedTimeoutMs 的 budgetTimeMs 只服务 pollRunToResult 的轮询 deadline
+    // （wall-clock 兜底）。
+    const spec = buildNestedSpec(args, parentRun, script, chain);
     const runId = await runWorkflow(spec, deps, childController.signal);
 
     // Step 5: 轮询至 done（复用 runAndWait 的轮询逻辑）
-    // [H-1] 嵌套 workflow timeout 从父 run 完整传导：父 spec.budgetTimeMs 显式设定时
-    //  原样作为子 run 轮询 deadline（不 min(DEFAULT) 封顶——旧实现把父 time:2h 截断到
-    //  10min，违背「显式传参完整生效」语义）；父未设 → undefined，无 deadline（不限）。
-    //  budgetRef（共享 Budget）已在 Step 4 透传给子 run 处理 token/cost 预算，
-    //  此处的 budgetTimeMs 只服务 pollRunToResult 的轮询 deadline（wall-clock 兜底）。
-    // [U2] 预算语义统一：父 budgetTimeMs <=0（含 0/负）与 undefined 同义 = 不限——
-    //  与 lifecycle.runWorkflow 的 budgetTimeMs 判定（>0 才挂 scheduleTimeBudget）对齐。
-    //  旧实现 0 传导给子 run 后 deadline=now 立即超时（"timed out after 0ms"），与
-    //  lifecycle 的 0=不限 语义分裂。pollRunToResult 内亦对非正值兜底归一（双写防漂移），
-    //  此处显式归一是传导语义的文档化表达。
-    const rawNestedTimeoutMs = parentRun.spec.budgetTimeMs;
-    const nestedTimeoutMs =
-      rawNestedTimeoutMs !== undefined && rawNestedTimeoutMs > 0 ? rawNestedTimeoutMs : undefined;
-
     const result = await pollRunToResult(
       runId,
       deps,
       childController.signal,
-      nestedTimeoutMs,
+      resolveNestedTimeoutMs(parentRun),
       "Aborted by parent signal",
     );
 
-    // Step 6: 结果转换（budget 已通过共享 budgetRef 实时同步，无需 sync-back）
-    if (result.reason === "completed") {
-      const scriptResult = result.scriptResult;
-      return {
-        content:
-          typeof scriptResult === "string"
-            ? scriptResult
-            : JSON.stringify(scriptResult ?? ""),
-        parsedOutput:
-          typeof scriptResult === "object" && scriptResult !== null
-            ? scriptResult
-            : undefined,
-      };
-    }
-    return {
-      content: "",
-      error: result.error ?? `Workflow '${name}' ended: ${result.reason}`,
-    };
+    // Step 6: 结果转换
+    return toNestedCallResult(name, result);
   } catch (err) {
     // m3：chokepoint 校验失败 → {error}（§5.3 指引文案），非 ArgsValidationError 保持传播
     // （dispatchWorkflowCall 的 .catch 兜底转 postResult，worker 不崩）。

package/src/orchestration/lifecycle.ts

@@ -24,7 +24,7 @@
  * 「releaseRuntime → 改 status」原子顺序。
  *
  * **G3-001**（run 一次性生命周期）：AbortController 一次性无法复用，runtime 释放后
- * 只有两类重建——rebuildRuntime（error-recovery，崩溃重试路径，run 保持 running、
+ * 只有两类重建——rebuildRuntime（worker-message-pump，崩溃重试路径，run 保持 running、
  * replaceRuntime 原子换新）与 abort/terminate 的终态释放（transition("done") 内
  * releaseRuntime，run 不再恢复）。
  * （旧并发门闩 gate 抽象已删——no-op 无生产语义，实际并发由 SubagentService
@@ -42,12 +42,11 @@ import { assertSafeTimerDelay } from "../shared/timer-delay.ts";
 import { validateRunArgs } from "./args-validator.ts";
 import {
   closeOutInFlightCalls,
-  emitPendingUnregister,
-  emitTerminalSideEffects,
+  finalizeRun,
   handleWorkerError,
   handleWorkerExit,
   handleWorkerMessage,
-} from "./error-recovery.ts";
+} from "./worker-message-pump.ts";
 import { Budget } from "./models/budget.ts";
 import type { LifecycleDeps, RunStore, WorkerHandlers } from "./models/ports.ts";
 import { RunRuntime } from "./models/run-runtime.ts";
@@ -56,6 +55,7 @@ import { Trace } from "./models/trace.ts";
 import type { DoneReason } from "./models/types.ts";
 import { WorkflowRun } from "./models/workflow-run.ts";
 import type { WorkerHandle } from "./worker-handle.ts";
+import { toErrorMessage } from "../core/error-message.ts";
 
 const logger = getLogger("subagents");
 
@@ -118,24 +118,24 @@ function broadcastAbortToWorker(run: WorkflowRun, reason: string): void {
   try {
     run.runtime?.worker.postMessage({ type: "abort", reason });
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
+    const msg = toErrorMessage(err);
     logger.debug(
       `[workflow] abort broadcast to worker failed (runId=${run.runId}, worker likely already exited): ${msg}`,
     );
   }
 }
 
-// ── makeHandlers（路由 worker 事件到 error-recovery handle* 函数） ──────
+// ── makeHandlers（路由 worker 事件到 worker-message-pump handle* 函数） ──────
 
 /**
  * 构造 WorkerHandlers——将 worker 的 onMessage/onError/onExit 事件路由到
- * error-recovery 的 handleWorker* 函数。
+ * worker-message-pump 的 handleWorker* 函数。
  *
  * 闭包捕获 run + deps。runtime 重建（replaceRuntime）后 run 实例不变、deps 不变，
- * 故 handlers 对新 worker 仍有效（lifecycle 与 error-recovery 共用 handlers）。
+ * 故 handlers 对新 worker 仍有效（lifecycle 与 worker-message-pump 共用 handlers）。
  *
  * **onExit G-025**：handleWorkerExit 内部检查 handle.isCurrent（stale exit 丢弃）。
- * 本函数不在 onExit 里重复检查——error-recovery.handleWorkerExit 是单一守卫点。
+ * 本函数不在 onExit 里重复检查——worker-message-pump.handleWorkerExit 是单一守卫点。
  *
  * **workerErrorCount**：onError 触发时递增（C.5 跨 runtime 存活的重试计数载体）。
  * 注意 handleWorkerError 内部也会递增——这里 onError 递增是 worker 事件层面的
@@ -144,10 +144,10 @@ function broadcastAbortToWorker(run: WorkflowRun, reason: string): void {
  */
 function makeHandlers(run: WorkflowRun, deps: LifecycleDeps): WorkerHandlers {
   // [OR-7] per-run deps 视图：包装 onRunDone，把「run 终态」转译为「移除 signal abort
-  // listener」。error-recovery 全部终态路径（handleReturn / handleWorkerError /
+  // listener」。worker-message-pump 全部终态路径（handleReturn / handleWorkerError /
   // handleScriptError / handleWorkerExit / 预算终止 / time_limited / [OR-2] rebuild
-  // 失败收敛）都经 handlers 调用链消费本视图——消息面终态在此统一收口；
-  // abortRun / terminateRunningRuns 两个 lifecycle 自有终态路径另行显式 dispose。
+  // 失败收敛——均经 finalizeRun）都经 handlers 调用链消费本视图——消息面终态在此
+  // 统一收口；abortRun / terminateRunningRuns 两个 lifecycle 自有终态路径另行显式 dispose。
   const depsWithTerminalCleanup: LifecycleDeps = {
     ...deps,
     onRunDone: (doneRun: WorkflowRun): void => {
@@ -155,7 +155,7 @@ function makeHandlers(run: WorkflowRun, deps: LifecycleDeps): WorkerHandlers {
       deps.onRunDone?.(doneRun);
     },
   };
-  // 自引用——error-recovery rebuildRuntime 需要 handlers 参数（handlers 引用自身）
+  // 自引用——worker-message-pump rebuildRuntime 需要 handlers 参数（handlers 引用自身）
   const handlers: WorkerHandlers = {
     async onMessage(raw: unknown): Promise<void> {
       await handleWorkerMessage(run, raw, depsWithTerminalCleanup, handlers);
@@ -198,7 +198,7 @@ export function scheduleTimeBudget(
   const timer = setTimeout(() => {
     void abortRun(runId, deps, "Time budget exceeded", "time_limited").catch(
       (err: unknown) => {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = toErrorMessage(err);
         logger.error(`[workflow] time budget abort failed: ${msg}`);
       },
     );
@@ -213,7 +213,7 @@ export function scheduleTimeBudget(
 /**
  * rfl 仪表（tier-1 §7.1）：向 spec.args 原地注入稳定 _runId。runAndWait 与
  * executeNestedWorkflow 两个 args 入口都经 runWorkflow 这一 choke point；
- * rebuildRuntime 复用 run.spec.args 同一对象（error-recovery.ts），worker rebuild
+ * rebuildRuntime 复用 run.spec.args 同一对象（worker-message-pump.ts），worker rebuild
  * 后脚本侧 $ARGS._runId 不漂移——修复「rebuild 回退 run-<Date.now()> 导致同一
  * 逻辑 run 碎裂到多个 state 目录」。注入在 validateRunArgs 之后，不参与脚本
  * 参数 schema 校验（引擎内部字段）。
@@ -307,7 +307,7 @@ function registerSignalAbortListener(
   const onAbort = (): void => {
     disposeSignalAbortListener(run);
     void abortRun(runId, deps, "External signal aborted").catch((err: unknown) => {
-      const msg = err instanceof Error ? err.message : String(err);
+      const msg = toErrorMessage(err);
       logger.error(`[workflow] abortRun on signal failed: ${msg}`);
     });
   };
@@ -426,20 +426,16 @@ export async function abortRun(
   // [OR-3] 先广播 abort 再 transition（transition 内 releaseRuntime→terminate，
   // terminate 之后广播发不进去）——worker 侧 pending 优雅解阻
   broadcastAbortToWorker(run, reason ?? `Workflow aborted (${doneReason})`);
-  // A4: transition 内部 releaseRuntime（cleanup before mutate）
-  run.transition("done", doneReason);
   // [OR-7] run 终态：移除 signal abort listener（幂等；abort 由 signal 触发时
-  // listener 已在 onAbort 内自移除，此处为其余 abort 入口的收口）
+  // listener 已在 onAbort 内自移除，此处为其余 abort 入口的收口；即使 finalizeRun
+  // 因并发终态化让位，WeakMap 条目也应清除，不依赖 transition 成败）
   disposeSignalAbortListener(run);
-  // [OR-8] 终态收口残留 in-flight call（先收口再落盘——快照不再含 running 节点）
-  closeOutInFlightCalls(run);
-  await deps.store.save(run);
-  deps.log?.("debug", "workflow:lifecycle", "abortRun transition done", { runId, reason: run.state.reason });
-  // C-4: run 到达 done 终态 → 注销 pending-notification + 通知 Interface 层
-  // [OR-4][B-4] M12 同款围栏（emit pending:unregister + onRunDone 各自独立 try）——
-  // listener 同步抛错不再跳过 onRunDone 或把错误抛给 abort 调用方；错误 error 留痕后
-  // 本函数仍按 abort 成功语义正常返回（内存态已终态）。
-  emitTerminalSideEffects(run, deps, `abortRun (done,${doneReason})`);
+  // A4 + C-4: transition 内部 releaseRuntime（cleanup before mutate）；到达 done 终态
+  // → 注销 pending-notification + 通知 Interface 层（D5-② 终态 coda 收敛为
+  // worker-message-pump 的 finalizeRun 单写点——OR-8 in-flight 收口 + save best-effort
+  // （SW-DATA-3）不再向上抛，内存态已终态，调用方无需因落盘失败收到 abort 异常；
+  // OR-4/B-4 unregister 与 onRunDone 各自独立围栏）
+  await finalizeRun(run, deps, doneReason, { context: `abortRun (${doneReason})` });
 }
 
 // ── terminateRunningRuns（session 切换/关闭：终止全部 running run） ────────
@@ -451,11 +447,12 @@ export async function abortRun(
  * done,failed 持久化落盘——重启后 kill-9 恢复不误判，也不再存在「挂起待恢复」
  * 的中间态。
  *
- * per-run 行为：`state.error = reason` → `transition("done","failed")`（内部先
- * releaseRuntime，A4）→ `await store.save(run)` → `eventBus.emit("pending:unregister",
- * {reason:"failed"})`。
+ * per-run 行为：`state.error = reason` → `finalizeRun(run, deps, "failed",
+ * {notifyDone:false})`（transition("done","failed") 内部先 releaseRuntime，A4 →
+ * save best-effort → `eventBus.emit("pending:unregister", {reason:"failed"})`）。
  *
- * **不调 deps.onRunDone**：对齐 session_start 恢复先例（index.ts kill-9 恢复只发
+ * **不调 deps.onRunDone**（经 finalizeRun 的 notifyDone:false 承载，D5-②）：
+ * 对齐 session_start 恢复先例（index.ts kill-9 恢复只发
  * unregister、不发 onRunDone）——session 切换/关闭语境下主 agent 已离开本 session，
  * 注入完成通知只会把消息发给已离开的 session。
  *
@@ -480,21 +477,22 @@ export async function terminateRunningRuns(
       run.state.error = reason;
       // [OR-3] 同 abortRun：先广播 abort 再 transition（worker 侧 pending 优雅解阻）
       broadcastAbortToWorker(run, reason);
-      // A4: transition 内部先 releaseRuntime（cleanup before mutate）
-      run.transition("done", "failed");
       // [OR-7] run 终态：移除 signal abort listener（terminateRunningRuns 不走
-      // onRunDone——本路径显式收口）
+      // onRunDone——本路径显式收口，不依赖 finalizeRun 的 notifyDone 分支）
       disposeSignalAbortListener(run);
-      // [OR-8] 终态收口残留 in-flight call（先收口再落盘）
-      closeOutInFlightCalls(run);
-      await deps.store.save(run);
-      // C-4: run 到达 done 终态 → 注销 pending-notification（reason 固定 "failed"）。
-      // [B-4] M12 同款围栏：emit 单独 try（listener 同步抛错 error 留痕不中断本 run
-      // 收尾日志与其余 run 的终止；本路径不调 onRunDone——session 离开语境不发完成通知）。
-      emitPendingUnregister(run, deps, "terminateRunningRuns");
+      // A4 + C-4: transition 内部 releaseRuntime（cleanup before mutate）；done 终态 →
+      // 注销 pending-notification（D5-② 终态 coda 收敛为 finalizeRun 单写点）。
+      // notifyDone: false——**不调 deps.onRunDone**（真差异经参数承载）：对齐
+      // session_start 恢复先例（index.ts kill-9 恢复只发 unregister、不发
+      // onRunDone）——session 切换/关闭语境下主 agent 已离开本 session，注入完成
+      // 通知只会把消息发给已离开的 session。OR-8 in-flight 收口由 finalizeRun 承载。
+      await finalizeRun(run, deps, "failed", {
+        context: "terminateRunningRuns",
+        notifyDone: false,
+      });
       deps.log?.("debug", "workflow:lifecycle", "run terminated", { runId: run.runId, reason: run.state.reason });
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
+      const msg = toErrorMessage(err);
       logger.error(
         `[workflow] terminateRunningRuns failed for run ${run.runId}: ${msg} (reason: ${reason})`,
       );
@@ -644,7 +642,7 @@ export async function recoverCrashedRuns(
       try {
         hooks?.onRunRecovered?.({ id: run.runId, reason: "failed" });
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = toErrorMessage(err);
         logger.warn(
           `[workflow] recoverCrashedRuns onRunRecovered hook failed for run ${run.runId} (recovery continues): ${msg}`,
         );
@@ -653,7 +651,7 @@ export async function recoverCrashedRuns(
       try {
         await store.save(run);
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = toErrorMessage(err);
         logger.error(
           `[workflow] recoverCrashedRuns store.save failed for run ${run.runId}: ${msg} (reason: ${reason})`,
         );

package/src/orchestration/models/ports.ts

@@ -5,7 +5,7 @@
  * 是真需要 mock 测试的依赖（子进程/文件系统/线程）。
  *
  * 编排层共享类型（WorkerHandlers / LifecycleDeps）——打破 lifecycle ↔
- * error-recovery 循环依赖：2 个 engine 函数文件各自独立，共用同一组
+ * worker-message-pump 循环依赖：2 个 engine 函数文件各自独立，共用同一组
  * 依赖签名（D-12）。
  *
  * 层归属：Engine。零 infra 依赖（AC-1）。
@@ -71,7 +71,7 @@ export interface WorkerHost {
 
 /**
  * Worker 线程事件回调集合——WorkerHost.start 的入参，由 lifecycle
- * 构造并注入。2 个 engine 文件（lifecycle / error-recovery）共用此签名，
+ * 构造并注入。2 个 engine 文件（lifecycle / worker-message-pump）共用此签名，
  * 避免各自定义形状不一致的 handler bag（打破循环依赖）。
  *
  * 所有回调返回 Promise——允许 engine 层在回调内做 await persistState 等异步操作。
@@ -88,7 +88,7 @@ export interface WorkerHandlers {
 // ── 编排层共享类型 2: LifecycleDeps ────────────────────────────
 
 /**
- * lifecycle / error-recovery 2 个 engine 函数文件的共同依赖 bag。
+ * lifecycle / worker-message-pump 2 个 engine 函数文件的共同依赖 bag。
  *
  * 取代旧 4 个 Context factory（errorHandlerContext / agentCallContext /
  * budgetCallbacks / 旧 terminate bag，AC-2 目标）。函数签名 `(deps: LifecycleDeps, ...)`
@@ -142,7 +142,7 @@ export interface LifecycleDeps {
  * workflow() 嵌套调用回调（可选）。Worker 脚本内调 workflow(name, args) 时触发。
  *
  * 由 Interface 层 makeDeps 注入（闭包捕获 registry + deps）。Engine 层的
- * error-recovery.handleWorkerMessage 收到 workflow-call 消息后调本回调，
+ * worker-message-pump.handleWorkerMessage 收到 workflow-call 消息后调本回调，
  * 拿到子 workflow 执行结果后 postMessage(workflow-result) 回 worker。
  *
  * 不注入时 workflow() 返回 error result（向后兼容，不影响非嵌套场景）。