@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/orchestration/error-recovery.ts

@@ -4,7 +4,7 @@
  * Worker 失败处理 free functions（D-12）。
  *
  * 4 个导出函数（domain-models.md §失败处理矩阵）：
- * - handleWorkerMessage(run, raw, deps, handlers) — 路由 agent_call/return/error
+ * - handleWorkerMessage(run, raw, deps, handlers) — 路由 agent_call/return/error/log
  * - handleWorkerError(run, err, deps, handlers) — worker uncaught error
  * - handleWorkerExit(run, code, handle, deps, handlers) — worker exit
  * - handleScriptError(run, msg, deps, handlers) — type:"error" from worker
@@ -13,6 +13,11 @@
  * - worker error/exit（非零）→ 3 次重试 + 指数退避 1s/2s/4s；超限 failed
  * - script error → 3 次重试 + 指数退避；超限 failed
  * - 重试前 rebuildRuntime（G3-001：整个 RunRuntime 重建：worker+controller）
+ * - [OR-2] 重建动作本身失败（workerHost.start 抛错）回灌本矩阵：计入
+ *   workerErrorCount，未超限再走退避+重建，超限收敛 done,failed（见
+ *   scheduleRebuild / handleRebuildStartFailure）——恢复机制不得在它自己的
+ *   恢复路径上开口（旧实现裸调 rebuildRuntime → run 永久 running +
+ *   rejection 经 void 变 unhandledRejection）
  *
  * 关键不变式：
  * - 重试前必须 rebuildRuntime（worker+controller 整体重建，避免孤儿资源）。
@@ -66,6 +71,22 @@ const MAX_ERROR_LOGS = 500;
 /** malformed agent-call 日志中 opts JSON 的预览截断长度（字符）。 */
 const MALFORMED_MSG_LOG_PREVIEW_CHARS = 200;
 
+/**
+ * [OR-8] run 到达 done 终态时残留 in-flight call 的收口文案。
+ *
+ * trace/call 状态枚举封闭（无 "cancelled" 态），以 failed + 本固定文案表达
+ * 「run 终态前被收口」——GUI/快照侧不再出现 done run 含 running 节点的不一致。
+ */
+const IN_FLIGHT_CALL_CANCELLED_MSG =
+  "Cancelled: run reached terminal state while this call was in flight";
+
+/**
+ * [P-SD/S-D] 测试钩子 env（设计 §7.3 P-SD）：设为正整数 N 时 rebuildRuntime
+ * 第 N 次及以后的每次调用抛错，供 S-D「worker 崩溃后重建失败」验收注入。
+ * 安全约束：仅显式设置时激活 + 激活即 warn 留痕（见 resolveRebuildFailureInjectionThreshold）。
+ */
+const REBUILD_FAILURE_INJECT_ENV = "XYZ_SUBAGENT_TEST_INJECT_REBUILD_FAILURE";
+
 /**
  * [F1] worker 交付前退出（无终态消息）的归因文案。
  *
@@ -114,7 +135,14 @@ interface WorkflowCallMsg {
   args: Record<string, unknown>;
 }
 
-type WorkerMsg = AgentCallMsg | WorkflowCallMsg | ReturnMsg | ErrorMsg;
+/** 脚本 log() 全局发出的独立诊断消息（协议见 worker-script-builder 头注释，OR-6）。 */
+interface LogMsg {
+  type: "log";
+  phase?: string;
+  message: string;
+}
+
+type WorkerMsg = AgentCallMsg | WorkflowCallMsg | ReturnMsg | ErrorMsg | LogMsg;
 
 // ── 内部 helper ──────────────────────────────────────────────
 
@@ -178,8 +206,105 @@ function delay(ms: number): Promise<void> {
   });
 }
 
+/**
+ * [OR-4][B-4] pending:unregister emit 围栏（M12 同款 try 围栏）。
+ *
+ * eventBus 是通知总线（pending-notifications 注销信号灯）——listener 同步抛错不得
+ * 经 worker-host 绑定处的 `void handlers.onXxx(...)` 变 unhandledRejection 崩宿主。
+ * catch 后 error 留痕，调用方继续。lifecycle.terminateRunningRuns 的 emit（无
+ * onRunDone 的终态路径）也消费本函数——围栏语义两处单源。
+ */
+export function emitPendingUnregister(run: WorkflowRun, deps: LifecycleDeps, context: string): void {
+  try {
+    deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister", { runId: run.runId, reason: run.state.reason });
+    deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: run.state.reason ?? "completed" });
+    deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister done", { runId: run.runId });
+  } catch (err) {
+    const m = err instanceof Error ? err.message : String(err);
+    logger.error(`[workflow] pending:unregister emit failed (${context}): ${m}`);
+  }
+}
+
+/**
+ * [OR-4] 终态收尾副作用围栏：emit pending:unregister + onRunDone，各自独立 M12 同款
+ * try 围栏。
+ *
+ * 这两个是真实副作用（通知注销 + Interface 层完成回调，后者内部含 evictDoneRunsBeyondCap
+ * 内存淘汰）——任一同步抛错不得经 worker-host 绑定处的 `void handlers.onXxx(...)`
+ * 变 unhandledRejection 崩宿主，各自 catch 后 error 留痕，调用方继续。
+ *
+ * [B-4] 拆分为两个独立围栏（旧实现同一 try：emit 抛错会跳过 onRunDone）——通知总线
+ * 故障不得吞掉 Interface 层完成回调（runAndWait 轮询依赖 onRunDone 语义收口，被跳过
+ * 即悬挂）。本函数自身不重试不上抛。
+ *
+ * 旧实现四处裸调（handleReturn / handleWorkerError / handleScriptError /
+ * handleWorkerExit 的终态路径）与 budget 分支的内联围栏不对称——统一收敛到本函数。
+ */
+export function emitTerminalSideEffects(run: WorkflowRun, deps: LifecycleDeps, context: string): void {
+  emitPendingUnregister(run, deps, context);
+  try {
+    deps.onRunDone?.(run);
+  } catch (err) {
+    const m = err instanceof Error ? err.message : String(err);
+    logger.error(`[workflow] onRunDone failed (${context}): ${m}`);
+  }
+}
+
 // ── rebuildRuntime（G3-001 整重建） ─────────────────────────
 
+/** [P-SD] rebuildRuntime 进程级调用计数（注入阈值「第 N 次」的判定基准）。 */
+let rebuildRuntimeInvocationCount = 0;
+/** [P-SD] 钩子激活/非法值 warn 是否已发（多轮 rebuild 只留痕一次，防刷屏）。 */
+let rebuildFailureHookWarned = false;
+
+/**
+ * [P-SD/S-D] 读取重建失败注入阈值：env XYZ_SUBAGENT_TEST_INJECT_REBUILD_FAILURE=<N>
+ * 使 rebuildRuntime 第 N 次及以后的每次调用抛错（配合脚本内 process.exit 制造
+ * 「worker 崩溃后重建失败」的 S-D 验收场景）。
+ *
+ * 安全约束（设计 §7.3 P-SD，对齐 T7① 可见性原则）：
+ * - 仅显式设置时激活；未设置/空串 = 钩子完全不激活（零行为差）；
+ * - 首次读取到该 env（无论合法非法）即 logger.warn 留痕一次，杜绝静默生效；
+ * - 非法值（非正整数）不激活且 warn 指明原值，杜绝「以为注入了、实际没有」的
+ *   静默失效（LC-7 同族教训）。
+ *
+ * 语义取「第 N 次及以后每次」而非「仅第 N 次」：S-D 验收要求 run 收敛 done,failed——
+ * 仅注入一次会在重试预算（MAX_WORKER_RETRIES）耗尽前放行后续重建，run 可能正常完成，
+ * 验收不可证伪。连续注入让重试矩阵确定性走完：耗尽后经 handleRebuildStartFailure
+ * 收敛 done,failed。
+ *
+ * @returns 注入阈值（调用序数 >= 阈值的 rebuild 抛错）；undefined = 未激活
+ */
+function resolveRebuildFailureInjectionThreshold(): number | undefined {
+  const raw = process.env[REBUILD_FAILURE_INJECT_ENV];
+  if (raw === undefined || raw === "") return undefined;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    if (!rebuildFailureHookWarned) {
+      rebuildFailureHookWarned = true;
+      logger.warn(
+        `[workflow] ${REBUILD_FAILURE_INJECT_ENV}="${raw}" is not a positive integer — ` +
+          "test hook INACTIVE, no rebuild failure will be injected",
+      );
+    }
+    return undefined;
+  }
+  if (!rebuildFailureHookWarned) {
+    rebuildFailureHookWarned = true;
+    logger.warn(
+      `[workflow] ${REBUILD_FAILURE_INJECT_ENV}=${raw} ACTIVE — rebuildRuntime invocations ` +
+        `#${parsed} and later will throw (S-D test hook; NEVER set in production)`,
+    );
+  }
+  return parsed;
+}
+
+/** 测试辅助：重置注入计数与 warn 状态（仅 __tests__ 导入，生产勿用）。 */
+export function resetRebuildFailureInjectionForTest(): void {
+  rebuildRuntimeInvocationCount = 0;
+  rebuildFailureHookWarned = false;
+}
+
 /**
  * 移除 run 中未真正完成的在飞 call（status !== "done"）及其 trace 节点。
  *
@@ -203,6 +328,50 @@ function discardInFlightCalls(run: WorkflowRun): number[] {
   return inFlight.sort((a, b) => a - b);
 }
 
+/**
+ * [OR-8] run 到达 done 终态时，把 calls Map 残留的 in-flight call（status !== "done"）
+ * 收口为取消终态（不删除条目——保留调用痕迹，快照/GUI 不再出现 done run 含
+ * running 节点的不一致）。
+ *
+ * 场景：脚本 fire-and-forget agent()（不 await）后 return；或 worker 死亡/abort 时
+ * 已 dispatch 未完成的 call。旧实现 trace 节点永久 "running" 并原样落盘
+ * （run-snapshot 序列化不做状态修正）。
+ *
+ * 收口语义（trace/call 状态枚举封闭，无 "cancelled" 态）：
+ * - AgentCall 补齐 pending→running→done 状态机（markDone 要求 running 前置），
+ *   result 以 IN_FLIGHT_CALL_CANCELLED_MSG 承载取消原因；
+ * - trace 节点置 failed + 固定取消文案 + completedAt（「failed + Cancelled 文案」
+ *   即取消的既有表达形态，不新增状态枚举）；
+ * - node.live 清除（终态 run 无 TUI 轮询，防 ExecutionRecord 滞留）。
+ *
+ * 调用点约定：每个 transition("done") 成功后、store.save 之前——先收口再落盘，
+ * 内存态与持久化快照在同一时点收敛（「run-snapshot 落盘前」的实现形态）。
+ * 返回被收口的 callId 数组（升序）供调用方记日志。
+ */
+export function closeOutInFlightCalls(run: WorkflowRun): number[] {
+  const inFlight: number[] = [];
+  for (const [callId, call] of run.state.calls) {
+    if (call.status !== "done") inFlight.push(callId);
+  }
+  const completedAt = new Date().toISOString();
+  for (const callId of inFlight) {
+    const call = run.state.calls.get(callId);
+    if (!call) continue; // 防御：迭代后被删（正常路径不可达）
+    if (call.status === "pending") call.markRunning();
+    if (call.status === "running") {
+      call.markDone({ content: "", error: IN_FLIGHT_CALL_CANCELLED_MSG });
+    }
+    call.traceNode.live = undefined;
+    run.state.trace.update(callId, {
+      status: "failed",
+      result: { content: "", error: IN_FLIGHT_CALL_CANCELLED_MSG },
+      error: IN_FLIGHT_CALL_CANCELLED_MSG,
+      completedAt,
+    });
+  }
+  return inFlight.sort((a, b) => a - b);
+}
+
 /**
  * 计算 run 的剩余时间预算（ms）[race-F3]。
  *
@@ -244,12 +413,11 @@ async function finalizeTimeBudgetExhausted(run: WorkflowRun, deps: LifecycleDeps
     void te;
   }
   if (!transitioned) return;
-  await deps.store.save(run).catch((e: unknown) => {
-    const m = e instanceof Error ? e.message : String(e);
-    logger.error(`[workflow] store.save failed (time budget exhausted): ${m}`);
-  });
-  deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: run.state.reason ?? "time_limited" });
-  deps.onRunDone?.(run);
+  // [OR-8] 终态收口残留 in-flight call（先收口再落盘）
+  closeOutInFlightCalls(run);
+  await saveRunBestEffort(run, deps, "finalizeTimeBudgetExhausted (done,time_limited)");
+  // [OR-4] M12 同款围栏（终态副作用不经 void 变 unhandledRejection）
+  emitTerminalSideEffects(run, deps, "finalizeTimeBudgetExhausted (done,time_limited)");
 }
 
 /**
@@ -275,26 +443,36 @@ export function rebuildRuntime(
   deps: LifecycleDeps,
   handlers: WorkerHandlers,
 ): void {
- // OB3（可观察性）：rebuild 关键节点 debug 日志——此前函数体 0 处 deps.log，
- // 崩溃自愈只能靠行为证据诊断（L1 入口 / L2 重排 / L3 discard / L4 完成）。
+  // [P-SD] 测试钩子注入点：先于任何副作用（模拟 workerHost.start 抛错）。抛错由
+  // scheduleRebuild 的 catch 接住回灌重试矩阵（[OR-2]），不再裸抛。
+  rebuildRuntimeInvocationCount += 1;
+  const injectThreshold = resolveRebuildFailureInjectionThreshold();
+  if (injectThreshold !== undefined && rebuildRuntimeInvocationCount >= injectThreshold) {
+    throw new Error(
+      `[S-D test hook] injected rebuildRuntime failure ` +
+        `(invocation #${rebuildRuntimeInvocationCount}, ${REBUILD_FAILURE_INJECT_ENV}>=${injectThreshold})`,
+    );
+  }
+  // OB3（可观察性）：rebuild 关键节点 debug 日志——此前函数体 0 处 deps.log，
+  // 崩溃自愈只能靠行为证据诊断（L1 入口 / L2 重排 / L3 discard / L4 完成）。
   deps.log?.("debug", "workflow:error-recovery", "runtime rebuild start", {
     runId: run.runId,
     budgetTimeMs: run.spec.budgetTimeMs,
   });
   const controller = new AbortController();
   const worker = deps.workerHost.start(run.spec, run.spec.args, handlers);
- // D-12 regression fix (round-2 #2)：重新调度 run 级墙钟预算计时器。
- // replaceRuntime 释放旧 runtime 时 clearTimeout 了旧计时器（run-runtime.release），
- // 新 runtime 必须重排，否则带 budgetTimeMs 的 run 命中一次 worker/script 错误重试后
- // 时间预算静默失效（直到 rebuildRuntime 才重排——本函数即唯一重排点）。
- // deps.scheduleTimeBudget 由 Interface 层注入；未注入时（旧测试）跳过重排（兼容，
- // 不影响无时间预算的 run）。
- // 重排分支改为 if——语义与原三元一致（同一条件调 scheduleTimeBudget），仅为在
- // 分支内记 L2 日志，控制流/异常语义零变化。
- // [race-F3] 重排值改为剩余墙钟（remainingTimeBudgetMs）而非满额——重试不重置预算；
- // L2 日志 payload 同步报实际重排值（排障时与 setTimeout 对得上）。remaining > 0
- // 由调用方 scheduleRebuild 保证（耗尽在那里转 time_limited，不进本函数）；本处
- // remaining <= 0 时不挂 timer（防御直调，宁可不挂也不能挂出 0ms 立即触发）。
+  // D-12 regression fix (round-2 #2)：重新调度 run 级墙钟预算计时器。
+  // replaceRuntime 释放旧 runtime 时 clearTimeout 了旧计时器（run-runtime.release），
+  // 新 runtime 必须重排，否则带 budgetTimeMs 的 run 命中一次 worker/script 错误重试后
+  // 时间预算静默失效（直到 rebuildRuntime 才重排——本函数即唯一重排点）。
+  // deps.scheduleTimeBudget 由 Interface 层注入；未注入时（旧测试）跳过重排（兼容，
+  // 不影响无时间预算的 run）。
+  // 重排分支改为 if——语义与原三元一致（同一条件调 scheduleTimeBudget），仅为在
+  // 分支内记 L2 日志，控制流/异常语义零变化。
+  // [race-F3] 重排值改为剩余墙钟（remainingTimeBudgetMs）而非满额——重试不重置预算；
+  // L2 日志 payload 同步报实际重排值（排障时与 setTimeout 对得上）。remaining > 0
+  // 由调用方 scheduleRebuild 保证（耗尽在那里转 time_limited，不进本函数）；本处
+  // remaining <= 0 时不挂 timer（防御直调，宁可不挂也不能挂出 0ms 立即触发）。
   let timeBudgetTimer: ReturnType<typeof setTimeout> | undefined;
   const remainingBudgetMs = remainingTimeBudgetMs(run);
   if (remainingBudgetMs !== undefined && remainingBudgetMs > 0 && deps.scheduleTimeBudget) {
@@ -305,21 +483,21 @@ export function rebuildRuntime(
     });
   }
   run.replaceRuntime(new RunRuntime(worker, controller, timeBudgetTimer));
- // 清除被旧 runtime abort 的在飞 call——必须在 replaceRuntime 之后同步执行（无
- // await 间隔）：replaceRuntime 同步 abort 旧 controller + terminate 旧 worker，
- // 在飞 executeAgentCall 的 finalize 发生在 `await runner.run` resolve 后的
- // microtask，此刻在飞 call 仍为 "running"/"pending"（status !== "done"）可精确
- // 清理；genuinely-done 的 call 保留（重跑 replay）。放 delay 退避之前会误删退避
- // 期间自然完成的真结果（重跑重复耗 token）；放任何 await 之后，假失败已 finalize
- // 为 "done" 挡不住——重跑 replay 会把 abort 错误当真结果回放，静默污染输出。
- // 注意：discard 只清 Map/trace 条目，旧 executeAgentCall 的 promise 链仍会醒来
- // finalize。markDone 在孤儿实例上无害，但后续投递并非 no-op——postAgentResult
- // 会投给 run.runtime（已是新 worker）的同 callId pending，劫持重跑调用（实测
- // S7-second 竞态：旧失败结果被 worker 侧 resolve 为空串 → 脚本假成功）；
- // finalizeCall 的 trace.update 在重跑已 append 同 stepIndex 新节点时命中新节点
- // （瞬时污染，由重跑完成时的 update 覆盖）。该投递由 dispatchAgentCall 的
- // 孤儿守卫（isOrphanedCall）拦截，trace.update 的瞬时污染由 executeAgentCall
- // 的 isOrphaned 谓词（OB2）拦截，此处不重复设防。
+  // 清除被旧 runtime abort 的在飞 call——必须在 replaceRuntime 之后同步执行（无
+  // await 间隔）：replaceRuntime 同步 abort 旧 controller + terminate 旧 worker，
+  // 在飞 executeAgentCall 的 finalize 发生在 `await runner.run` resolve 后的
+  // microtask，此刻在飞 call 仍为 "running"/"pending"（status !== "done"）可精确
+  // 清理；genuinely-done 的 call 保留（重跑 replay）。放 delay 退避之前会误删退避
+  // 期间自然完成的真结果（重跑重复耗 token）；放任何 await 之后，假失败已 finalize
+  // 为 "done" 挡不住——重跑 replay 会把 abort 错误当真结果回放，静默污染输出。
+  // 注意：discard 只清 Map/trace 条目，旧 executeAgentCall 的 promise 链仍会醒来
+  // finalize。markDone 在孤儿实例上无害，但后续投递并非 no-op——postAgentResult
+  // 会投给 run.runtime（已是新 worker）的同 callId pending，劫持重跑调用（实测
+  // S7-second 竞态：旧失败结果被 worker 侧 resolve 为空串 → 脚本假成功）；
+  // finalizeCall 的 trace.update 在重跑已 append 同 stepIndex 新节点时命中新节点
+  // （瞬时污染，由重跑完成时的 update 覆盖）。该投递由 dispatchAgentCall 的
+  // 孤儿守卫（isOrphanedCall）拦截，trace.update 的瞬时污染由 executeAgentCall
+  // 的 isOrphaned 谓词（OB2）拦截，此处不重复设防。
   const discardedCallIds = discardInFlightCalls(run);
   deps.log?.("debug", "workflow:error-recovery", "in-flight calls discarded", {
     runId: run.runId,
@@ -339,6 +517,11 @@ export function rebuildRuntime(
  * agent_call → 派发 executeAgentCall（异步，不 await——立即返回让 worker 继续发消息）
  * return → transition done,completed（脚本正常返回）
  * error → handleScriptError（脚本主动抛错）
+ * log → 计入 run.state.errorLogs + debug 留痕（[OR-6/T7④] 主线程半边——worker 侧
+ *   log() 双通路的独立消息面消费点；u-m0a 已接 workerLogs 随 return/error 带回，
+ *   本 case 消费独立 {type:"log"} 消息，与 worker-script-builder 协议注释对齐）
+ * default → warn 留痕后丢弃（[OR-6/T7④] 协议漂移防线——协议文档与实现漂移零
+ *   可观测的反面；未知类型静默丢弃会让协议单方面演化不可发现）
  *
  * 终态（done）下的 stale 消息丢弃（P0-1）。
  */
@@ -348,10 +531,10 @@ export async function handleWorkerMessage(
   deps: LifecycleDeps,
   handlers: WorkerHandlers,
 ): Promise<void> {
- // 终态（done）丢弃 stale 消息（P0-1）
+  // 终态（done）丢弃 stale 消息（P0-1）
   if (isTerminal(run)) return;
 
- // M7: 形状校验——防畸形 IPC 消息（worker 崩溃/发非对象）导致下游 TypeError
+  // M7: 形状校验——防畸形 IPC 消息（worker 崩溃/发非对象）导致下游 TypeError
   if (typeof raw !== "object" || raw === null) return;
   const msg = raw as WorkerMsg;
   switch (msg.type) {
@@ -369,7 +552,7 @@ export async function handleWorkerMessage(
       await handleReturn(run, msg, deps);
       return;
     case "error":
- // M1: 传 handlers（rebuildRuntime 需要）
+      // M1: 传 handlers（rebuildRuntime 需要）
       // [F1] 同 return——error 也是终态消息，标记本代际已交付（同上防误判）。
       if (run.runtime) run.runtime.receivedTerminalMessage = true;
       await handleScriptError(
@@ -380,7 +563,44 @@ export async function handleWorkerMessage(
         handlers,
       );
       return;
+    case "log":
+      handleWorkerLog(run, msg, deps);
+      return;
+    default:
+      // [OR-6/T7④] 协议漂移防线：未知消息类型 warn 留痕后丢弃。畸形消息（M7 形状
+      // 校验之上、已知类型之外的 type）此前静默穿过 switch——协议注释新增消息类型
+      // 而主线程未接线时，这里提供可观测信号（而非零痕迹丢弃）。
+      logger.warn(
+        `[workflow] unknown worker message type dropped (runId=${run.runId}): ` +
+          `${JSON.stringify((msg as { type?: unknown }).type)}`,
+      );
+      deps.log?.("warn", "workflow:error-recovery", "unknown worker message type", {
+        runId: run.runId,
+        type: (msg as { type?: unknown }).type,
+      });
+      return;
+  }
+}
+
+/**
+ * 消费 worker 的独立 log 消息（[OR-6/T7④] 主线程半边）。
+ *
+ * 计入 run.state.errorLogs（与 workerLogs 通路的 L9 追加/上限语义一致——该容器
+ * 本就承载全级别 worker 日志，"log" 级条目已在其中）+ deps.log debug 留痕
+ * （含 phase，协议字段不落 WorkerLogEntry 但排查时可见）。
+ * 终态守卫（isTerminal）已由 handleWorkerMessage 前置——此处只管写入。
+ */
+function handleWorkerLog(run: WorkflowRun, msg: LogMsg, deps: LifecycleDeps): void {
+  const message = typeof msg.message === "string" ? msg.message : String(msg.message);
+  run.state.errorLogs.push({ level: "log", message });
+  if (run.state.errorLogs.length > MAX_ERROR_LOGS) {
+    run.state.errorLogs = run.state.errorLogs.slice(-MAX_ERROR_LOGS);
   }
+  deps.log?.("debug", "workflow:error-recovery", "worker log", {
+    runId: run.runId,
+    phase: msg.phase,
+    message,
+  });
 }
 
 /**
@@ -418,7 +638,7 @@ function dispatchAgentCall(
     return;
   }
 
- // 已缓存的调用直接 replay（跨 rebuild——崩溃重建后重跑脚本，已完成调用按 callId 命中缓存）
+  // 已缓存的调用直接 replay（跨 rebuild——崩溃重建后重跑脚本，已完成调用按 callId 命中缓存）
   const cached = run.state.calls.get(msg.callId);
   if (cached && cached.status === "done") {
     postAgentResult(run, msg.callId, cached.result!, true);
@@ -453,8 +673,8 @@ function dispatchAgentCall(
   };
   run.state.trace.append(node);
 
- // 构建 AgentCall（opts 形状对齐 AgentCallOpts；schema: unknown → Record）
- // 跨进程 IPC 边界的 schema 为 unknown，窄化前加 typeof guard 兜底。
+  // 构建 AgentCall（opts 形状对齐 AgentCallOpts；schema: unknown → Record）
+  // 跨进程 IPC 边界的 schema 为 unknown，窄化前加 typeof guard 兜底。
   const rawSchema = msg.opts.schema;
   const opts: AgentCallOpts = {
     ...msg.opts,
@@ -464,11 +684,11 @@ function dispatchAgentCall(
         : undefined,
   };
 
- // BL-1：解析 skill/schema → skillPath / schemaEnv / appendSystemPrompt。
- // M2 修正后 resolveAgentOpts 单参数，只处理 schema SO 指令（内容直传）+ skill。
- // agent ref 处理（systemPrompt/model/thinkingLevel）交 resolveIdentity（经
- // getAgentConfig + resolveModel 完整覆盖），消除双重注入与 model 层级混乱。
- // 解析失败（skill 未找到）走 error 路径，不发 slot、不 spawn。
+  // BL-1：解析 skill/schema → skillPath / schemaEnv / appendSystemPrompt。
+  // M2 修正后 resolveAgentOpts 单参数，只处理 schema SO 指令（内容直传）+ skill。
+  // agent ref 处理（systemPrompt/model/thinkingLevel）交 resolveIdentity（经
+  // getAgentConfig + resolveModel 完整覆盖），消除双重注入与 model 层级混乱。
+  // 解析失败（skill 未找到）走 error 路径，不发 slot、不 spawn。
   const resolved = resolveAgentOpts(opts);
   if (resolved.error) {
     const call = new AgentCall(msg.callId, opts, node);
@@ -493,14 +713,14 @@ function dispatchAgentCall(
   const call = new AgentCall(msg.callId, resolved.opts, node);
   run.state.calls.set(msg.callId, call);
 
- // C-3：agent call 执行入口。
- // （原经 gate.withSlot 包装，并发门闩 gate 已删——no-op 抽象，实际并发由
- // SubagentService ConcurrencyPool 管理；仅保留其 pre-abort 检查语义，见下方
- // dispatchCall 内 signal.aborted 分支。）executeAgentCall 管 retry/budget/stale-context；
- // runner（runner.run）管 spawn pi 子进程。
- // assignRuntime/replaceRuntime 保证 status==="running" ⟺ runtime defined，
- // 故 run.runtime 在此必存在（dispatchAgentCall 仅从 handleWorkerMessage 调用，
- // 后者已守 terminal（isTerminal）早期 return）。fallback new AbortController 已移除。
+  // C-3：agent call 执行入口。
+  // （原经 gate.withSlot 包装，并发门闩 gate 已删——no-op 抽象，实际并发由
+  // SubagentService ConcurrencyPool 管理；仅保留其 pre-abort 检查语义，见下方
+  // dispatchCall 内 signal.aborted 分支。）executeAgentCall 管 retry/budget/stale-context；
+  // runner（runner.run）管 spawn pi 子进程。
+  // assignRuntime/replaceRuntime 保证 status==="running" ⟺ runtime defined，
+  // 故 run.runtime 在此必存在（dispatchAgentCall 仅从 handleWorkerMessage 调用，
+  // 后者已守 terminal（isTerminal）早期 return）。fallback new AbortController 已移除。
   const runtime = run.runtime!;
   const signal = runtime.controller.signal;
   // D-005: onEvent 签名升级——executeAndAwait 直接出 AgentEvent（强类型，
@@ -516,8 +736,8 @@ function dispatchAgentCall(
   const stream = deps.streamSink
     ? new SubagentStream(`${run.runId}-${msg.callId}`, deps.streamSink)
     : undefined;
- // 原 gate.withSlot(fn, signal) 语义内联：pre-aborted 时 reject AbortError（
- // 下方 .catch 依赖此约定不记错），否则直接执行——并发调度归 ConcurrencyPool。
+  // 原 gate.withSlot(fn, signal) 语义内联：pre-aborted 时 reject AbortError（
+  // 下方 .catch 依赖此约定不记错），否则直接执行——并发调度归 ConcurrencyPool。
   const dispatchCall = async (): Promise<void> => {
     if (signal.aborted) {
       const abortErr = new Error("Operation aborted before start");
@@ -525,9 +745,9 @@ function dispatchAgentCall(
       throw abortErr;
     }
     try {
- // OB2（S7 残留）：isOrphaned 谓词注入——旧代际 finalize 在 trace.update 前被
- // 拦截（判定语义与下方 .then/.catch 守卫同一 isOrphanedCall，详见
- // execute-agent-call.ts finalizeCall 文档注释）。
+      // OB2（S7 残留）：isOrphaned 谓词注入——旧代际 finalize 在 trace.update 前被
+      // 拦截（判定语义与下方 .then/.catch 守卫同一 isOrphanedCall，详见
+      // execute-agent-call.ts finalizeCall 文档注释）。
       await executeAgentCall(call, deps.runner, run.state.budget, signal, run.state.trace, onEvent, stream, () => isOrphanedCall(run, msg.callId, call));
     } finally {
       stream?.dispose();
@@ -535,35 +755,35 @@ function dispatchAgentCall(
   };
   void dispatchCall()
     .then(() => {
- // 清除 live record：终态已由 executeAgentCall → finalizeCall 写入 node.result，
- // live 不再需要（且含可变状态，不保留）。无论 stale 与否都清，避免内存泄漏。
- // M4: 必须在 stale guard 之前清，否则跨 rebuild 的迟到 completion 会累积 live record。
+      // 清除 live record：终态已由 executeAgentCall → finalizeCall 写入 node.result，
+      // live 不再需要（且含可变状态，不保留）。无论 stale 与否都清，避免内存泄漏。
+      // M4: 必须在 stale guard 之前清，否则跨 rebuild 的迟到 completion 会累积 live record。
       node.live = undefined;
- // run 终止（终态）后到达的 stale completion 不写 state
+      // run 终止（终态）后到达的 stale completion 不写 state
       if (run.state.status !== "running") return;
- // 孤儿 call 守卫（S7-second 竞态）：rebuild 的 discardInFlightCalls 已移除本
- // call、或重跑 dispatch 已用新实例替换同 callId 条目时，本 completion 属于旧
- // runtime 代际。postAgentResult 的投递目标是 run.runtime（已是新 worker），
- // 迟到结果会劫持新 worker 内重跑 agent() 的 pending Promise——跳过投递 /
- // budget 同步 / 持久化，仅留日志。executeAgentCall 内 finalizeCall 的
- // trace.update 若已命中重跑新节点（瞬时污染），由重跑完成时的 update 覆盖。
+      // 孤儿 call 守卫（S7-second 竞态）：rebuild 的 discardInFlightCalls 已移除本
+      // call、或重跑 dispatch 已用新实例替换同 callId 条目时，本 completion 属于旧
+      // runtime 代际。postAgentResult 的投递目标是 run.runtime（已是新 worker），
+      // 迟到结果会劫持新 worker 内重跑 agent() 的 pending Promise——跳过投递 /
+      // budget 同步 / 持久化，仅留日志。executeAgentCall 内 finalizeCall 的
+      // trace.update 若已命中重跑新节点（瞬时污染），由重跑完成时的 update 覆盖。
       if (isOrphanedCall(run, msg.callId, call)) {
         deps.log?.("debug", "workflow:error-recovery", "orphan agent call completion dropped", { runId: run.runId, callId: msg.callId });
         return;
       }
       if (call.result) postAgentResult(run, msg.callId, call.result, false);
- // D-12 regression fix (round-2 #1)：executeAgentCall 内 consume/incrementCallCount
- // 后同步 worker $BUDGET（否则 $BUDGET.spent()/remaining() 恒为 0）
+      // D-12 regression fix (round-2 #1)：executeAgentCall 内 consume/incrementCallCount
+      // 后同步 worker $BUDGET（否则 $BUDGET.spent()/remaining() 恒为 0）
       postBudgetUpdate(run);
       deps.store.save(run).catch((e: unknown) => {
         const m = e instanceof Error ? e.message : String(e);
         logger.error(`[workflow] store.save failed (agent call ${msg.callId}): ${m}`);
       });
 
- // C-2：budget 超限 → 终止整个 run（避免继续 spawn 烧预算）
- // 内联 terminate（不调 lifecycle.abortRun 避免 engine 内循环依赖）：
- // 若 run 仍非终态，transition done,budget_limited + 持久化。
- // 上方 status !== "running" 已保证此处非 done（且 transition 内含 done no-op 守卫）。
+      // C-2：budget 超限 → 终止整个 run（避免继续 spawn 烧预算）
+      // 内联 terminate（不调 lifecycle.abortRun 避免 engine 内循环依赖）：
+      // 若 run 仍非终态，transition done,budget_limited + 持久化。
+      // 上方 status !== "running" 已保证此处非 done（且 transition 内含 done no-op 守卫）。
       if (run.state.budget.isExceeded()) {
         run.state.error = run.state.error ?? "Budget exceeded";
         deps.log?.("debug", "workflow:error-recovery", "budget exceeded, transition done", { runId: run.runId });
@@ -577,55 +797,50 @@ function dispatchAgentCall(
           void te;
         }
         if (transitioned) {
+          // [OR-8] 终态收口残留 in-flight call（先收口再落盘）
+          closeOutInFlightCalls(run);
           deps.store.save(run).catch((e: unknown) => {
             const m = e instanceof Error ? e.message : String(e);
             logger.error(`[workflow] store.save failed (budget done): ${m}`);
           });
           deps.log?.("debug", "workflow:error-recovery", "run saved after budget done", { runId: run.runId, reason: run.state.reason });
           // M12: onRunDone/emit 单独 try——这些是真实副作用，错误不应被静默吞掉
-          try {
-            deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister", { runId: run.runId, reason: run.state.reason });
-            deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: run.state.reason ?? "completed" });
-            deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister done", { runId: run.runId });
-            deps.onRunDone?.(run);
-          } catch (err) {
-            const m = err instanceof Error ? err.message : String(err);
-            logger.error(`[workflow] onRunDone/emit failed (budget done): ${m}`);
-          }
+          //（[OR-4] 围栏收敛到共享 helper，语义与原内联围栏一致）
+          emitTerminalSideEffects(run, deps, "budget done");
         }
       }
     })
     .catch((err: unknown) => {
- // pre-abort 检查（原 gate.withSlot 语义）在 dispatchCall 入口 reject AbortError——预期，不记错。
+      // pre-abort 检查（原 gate.withSlot 语义）在 dispatchCall 入口 reject AbortError——预期，不记错。
       if (err instanceof Error && err.name === "AbortError") return;
       const message = err instanceof Error ? err.message : String(err);
       logger.error(`[workflow] agent call ${msg.callId} failed: ${message}`);
- // 兜底回发：executeAgentCall 抛非 Abort 异常时（如 runner undefined 的 TypeError、
- // dispatchCall 内部 bug）原 catch 仅 console.error，worker 内对 callId 的 pending
- // Promise 永不 resolve → agent() 永久 await → worker 脚本挂死。构造 failed AgentResult
- //（与 resolveAgentOpts 失败路径 L262-275 一致的模式）postAgentResult 回 worker，
- // 让 pending Promise resolve（结果为 error），脚本可继续或失败退出。
- // 孤儿 call 守卫（与 .then 对称，S7-second 竞态）：rebuild 后本 call 已被 discard
- // 移除/替换——markDone 虽在孤儿实例上无害，但 trace.update 会污染重跑新建的同
- // stepIndex 节点、postAgentResult 会劫持新 worker 的同 callId pending。孤儿时只
- // 留日志，全部跳过。node.live 无条件先清（旧节点已脱离 trace，防御性统一）。
+      // 兜底回发：executeAgentCall 抛非 Abort 异常时（如 runner undefined 的 TypeError、
+      // dispatchCall 内部 bug）原 catch 仅 console.error，worker 内对 callId 的 pending
+      // Promise 永不 resolve → agent() 永久 await → worker 脚本挂死。构造 failed AgentResult
+      //（与 resolveAgentOpts 失败路径 L262-275 一致的模式）postAgentResult 回 worker，
+      // 让 pending Promise resolve（结果为 error），脚本可继续或失败退出。
+      // 孤儿 call 守卫（与 .then 对称，S7-second 竞态）：rebuild 后本 call 已被 discard
+      // 移除/替换——markDone 虽在孤儿实例上无害，但 trace.update 会污染重跑新建的同
+      // stepIndex 节点、postAgentResult 会劫持新 worker 的同 callId pending。孤儿时只
+      // 留日志，全部跳过。node.live 无条件先清（旧节点已脱离 trace，防御性统一）。
       node.live = undefined;
       if (isOrphanedCall(run, msg.callId, call)) {
         deps.log?.("debug", "workflow:error-recovery", "orphan agent call failure dropped", { runId: run.runId, callId: msg.callId });
         return;
       }
       const errorResult: AgentResult = { content: "", error: message };
- // call 已 done（executeAgentCall 内 finalizeCall 已 markDone）时跳过，避免重复 markDone。
- // status 理论上必为 running（executeAgentCall L130 markRunning 先于 reject），pending
- // 分支为防御性保护。非 running/done 意外态：跳过 markDone（markDone 要求 running）。
+      // call 已 done（executeAgentCall 内 finalizeCall 已 markDone）时跳过，避免重复 markDone。
+      // status 理论上必为 running（executeAgentCall L130 markRunning 先于 reject），pending
+      // 分支为防御性保护。非 running/done 意外态：跳过 markDone（markDone 要求 running）。
       if (call.status !== "done") {
         if (call.status === "pending") call.markRunning();
         call.markDone(errorResult);
       }
- // state 一致性三件套（与 resolveAgentOpts 失败 L268-276 / .then L319-325 对等）：
- // trace 标 failed + 清 live record（防泄漏）+ 持久化（catch 恰是最需留证的场景）。
- // stale 终态（run 已 done）时 run.runtime 为 undefined，postAgentResult 用
- // optional chaining 跳过 worker 回发；trace/state 写入仍执行（无害，终态快照已存）。
+      // state 一致性三件套（与 resolveAgentOpts 失败 L268-276 / .then L319-325 对等）：
+      // trace 标 failed + 清 live record（防泄漏）+ 持久化（catch 恰是最需留证的场景）。
+      // stale 终态（run 已 done）时 run.runtime 为 undefined，postAgentResult 用
+      // optional chaining 跳过 worker 回发；trace/state 写入仍执行（无害，终态快照已存）。
       run.state.trace.update(msg.callId, {
         status: "failed",
         result: errorResult,
@@ -795,7 +1010,7 @@ async function handleReturn(
   deps: LifecycleDeps,
 ): Promise<void> {
   deps.log?.("debug", "workflow:error-recovery", "handleReturn", { runId: run.runId, status: run.state.status });
- // 捕获 worker 诊断日志（P2-2）
+  // 捕获 worker 诊断日志（P2-2）
   // L9: 追加而非覆盖——保留重试历史的诊断日志（各 worker 实例的 console 输出）
   if (msg.workerLogs && msg.workerLogs.length > 0) {
     run.state.errorLogs.push(...msg.workerLogs);
@@ -805,14 +1020,15 @@ async function handleReturn(
   }
   run.state.scriptResult = msg.result;
   run.transition("done", "completed");
+  // [OR-8] 脚本 return 时可能仍有 fire-and-forget 的 in-flight call（不 await）——
+  // 终态收口为 cancelled，先收口再落盘（快照不再含 running 节点）
+  closeOutInFlightCalls(run);
   // [SW-DATA-3] save 失败不阻断终态推进（原 await 裸抛 → unhandledRejection + 幽灵注销）
   await saveRunBestEffort(run, deps, "handleReturn (done,completed)");
   deps.log?.("debug", "workflow:error-recovery", "run saved after return", { runId: run.runId, reason: run.state.reason });
- // C-4: run 到达 done 终态 → 注销 pending-notification + 通知 Interface 层
-  deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister", { runId: run.runId, reason: run.state.reason });
-  deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: run.state.reason ?? "completed" });
-  deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister done", { runId: run.runId });
-  deps.onRunDone?.(run);
+  // C-4: run 到达 done 终态 → 注销 pending-notification + 通知 Interface 层
+  // [OR-4] M12 同款围栏（此前裸调——listener 同步抛错经 void 变 unhandledRejection）
+  emitTerminalSideEffects(run, deps, "handleReturn (done,completed)");
 }
 
 // ── handleWorkerError ────────────────────────────────────────
@@ -835,18 +1051,18 @@ export async function handleWorkerError(
   deps: LifecycleDeps,
   handlers: WorkerHandlers,
 ): Promise<void> {
- // 与 handleWorkerMessage 对称——终态（done）丢弃 stale error。
- // 否则终态后到达的 worker error 仍会 workerErrorCount++（污染跨 runtime 计数）。
+  // 与 handleWorkerMessage 对称——终态（done）丢弃 stale error。
+  // 否则终态后到达的 worker error 仍会 workerErrorCount++（污染跨 runtime 计数）。
   if (isTerminal(run)) return;
 
- // [R4-F1] 同代际幂等守卫：worker 崩溃时 error + exit(1) 双事件各派发一次
- // handleWorkerError（onError 先到，exit 非 0 经 handleWorkerExit 委托二次到达）——
- // 旧实现单次崩溃 workerErrorCount +2、两个 scheduleRebuild 并行交错（双 rebuild
- // 各自 new Worker，旧 handle 的 terminate/exit 事件与新 handle 的生命周期互相踩踏）。
- // 复用 R4 的 receivedTerminalMessage 代际标志（RunRuntime 字段，rebuild 自然重置）：
- // 进入处理前置 true 标记「本代际已有 error/terminal 处理」，第二个事件（无论
- // onError 直达还是 exit(1) 委托）命中标志直接跳过。新代际的 handleWorkerError
- // 不受影响（新 RunRuntime 的标志为 false）。
+  // [R4-F1] 同代际幂等守卫：worker 崩溃时 error + exit(1) 双事件各派发一次
+  // handleWorkerError（onError 先到，exit 非 0 经 handleWorkerExit 委托二次到达）——
+  // 旧实现单次崩溃 workerErrorCount +2、两个 scheduleRebuild 并行交错（双 rebuild
+  // 各自 new Worker，旧 handle 的 terminate/exit 事件与新 handle 的生命周期互相踩踏）。
+  // 复用 R4 的 receivedTerminalMessage 代际标志（RunRuntime 字段，rebuild 自然重置）：
+  // 进入处理前置 true 标记「本代际已有 error/terminal 处理」，第二个事件（无论
+  // onError 直达还是 exit(1) 委托）命中标志直接跳过。新代际的 handleWorkerError
+  // 不受影响（新 RunRuntime 的标志为 false）。
   if (run.runtime?.receivedTerminalMessage) return;
   if (run.runtime) run.runtime.receivedTerminalMessage = true;
 
@@ -858,18 +1074,18 @@ export async function handleWorkerError(
     return;
   }
 
- // 超限 → failed
+  // 超限 → failed
   run.state.error = err.message;
   deps.log?.("debug", "workflow:error-recovery", "handleWorkerError retries exceeded, transition done", { runId: run.runId, count });
   run.transition("done", "failed");
+  // [OR-8] 终态收口残留 in-flight call（先收口再落盘）
+  closeOutInFlightCalls(run);
   // [SW-DATA-3] save 失败不阻断终态推进
   await saveRunBestEffort(run, deps, "handleWorkerError (done,failed)");
   deps.log?.("debug", "workflow:error-recovery", "run saved after worker error", { runId: run.runId, reason: run.state.reason });
- // C-4: run 到达 done 终态 → 注销 pending-notification + 通知 Interface 层
-  deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister", { runId: run.runId, reason: run.state.reason });
-  deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: run.state.reason ?? "completed" });
-  deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister done", { runId: run.runId });
-  deps.onRunDone?.(run);
+  // C-4: run 到达 done 终态 → 注销 pending-notification + 通知 Interface 层
+  // [OR-4] M12 同款围栏
+  emitTerminalSideEffects(run, deps, "handleWorkerError (done,failed)");
 }
 
 // ── handleWorkerExit ─────────────────────────────────────────
@@ -896,7 +1112,7 @@ export async function handleWorkerExit(
   deps: LifecycleDeps,
   handlers: WorkerHandlers,
 ): Promise<void> {
- // G-025: stale exit 事件丢弃（handle 已不是当前 runtime 的 worker）
+  // G-025: stale exit 事件丢弃（handle 已不是当前 runtime 的 worker）
   if (!handle.isCurrent) return;
   if (isTerminal(run)) return;
 
@@ -910,17 +1126,17 @@ export async function handleWorkerExit(
     deps.log?.("debug", "workflow:error-recovery", "worker exited without terminal message, transition done", { runId: run.runId });
     run.state.error = WORKER_EXITED_WITHOUT_RESULT_MSG;
     run.transition("done", "failed");
+    // [OR-8] 终态收口残留 in-flight call（先收口再落盘）
+    closeOutInFlightCalls(run);
     await saveRunBestEffort(run, deps, "handleWorkerExit (done,failed, no terminal message)");
     deps.log?.("debug", "workflow:error-recovery", "run saved after exit without result", { runId: run.runId, reason: run.state.reason });
     // C-4: run 到达 done 终态 → 注销 pending-notification + 通知 Interface 层
-    deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister", { runId: run.runId, reason: run.state.reason });
-    deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: run.state.reason ?? "completed" });
-    deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister done", { runId: run.runId });
-    deps.onRunDone?.(run);
+    // [OR-4] M12 同款围栏
+    emitTerminalSideEffects(run, deps, "handleWorkerExit (done,failed, no terminal message)");
     return;
   }
 
- // 非零 exit → 委托 handleWorkerError（C.3: onExit 传 handle 用于竞态防护）
+  // 非零 exit → 委托 handleWorkerError（C.3: onExit 传 handle 用于竞态防护）
   await handleWorkerError(
     run,
     new Error(`Worker exited with code ${code}`),
@@ -947,10 +1163,10 @@ export async function handleScriptError(
   deps: LifecycleDeps,
   handlers: WorkerHandlers,
 ): Promise<void> {
- // 与 handleWorkerMessage/handleWorkerError 对称——终态守卫前置。
+  // 与 handleWorkerMessage/handleWorkerError 对称——终态守卫前置。
   if (isTerminal(run)) return;
 
- // P2-2: 捕获 worker 诊断日志
+  // P2-2: 捕获 worker 诊断日志
   // L9: 追加而非覆盖
   if (workerLogs.length > 0) {
     run.state.errorLogs.push(...workerLogs);
@@ -967,18 +1183,18 @@ export async function handleScriptError(
     return;
   }
 
- // 超限 → failed
+  // 超限 → failed
   run.state.error = `Workflow failed after ${MAX_WORKER_RETRIES} retries: ${errorMsg}`;
   deps.log?.("debug", "workflow:error-recovery", "handleScriptError retries exceeded, transition done", { runId: run.runId, count });
   run.transition("done", "failed");
+  // [OR-8] 终态收口残留 in-flight call（先收口再落盘）
+  closeOutInFlightCalls(run);
   // [SW-DATA-3] save 失败不阻断终态推进
   await saveRunBestEffort(run, deps, "handleScriptError (done,failed)");
   deps.log?.("debug", "workflow:error-recovery", "run saved after script error", { runId: run.runId, reason: run.state.reason });
- // C-4: run 到达 done 终态 → 注销 pending-notification + 通知 Interface 层
-  deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister", { runId: run.runId, reason: run.state.reason });
-  deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: run.state.reason ?? "completed" });
-  deps.log?.("debug", "workflow:error-recovery", "emit pending:unregister done", { runId: run.runId });
-  deps.onRunDone?.(run);
+  // C-4: run 到达 done 终态 → 注销 pending-notification + 通知 Interface 层
+  // [OR-4] M12 同款围栏
+  emitTerminalSideEffects(run, deps, "handleScriptError (done,failed)");
 }
 
 // ── scheduleRebuild（退避 + 重建） ──────────────────────────
@@ -988,31 +1204,85 @@ export async function handleScriptError(
  *
  * 退避期间 run 可能被 abort（转终态 done）——rebuildRuntime 前重检状态，终态时
  * 跳过重建（避免给已终止的 run 启新 worker）。
+ *
+ * [OR-2] rebuildRuntime 抛错（workerHost.start 失败：线程/内存耗尽、eval 编译失败等）
+ * 不再裸抛——裸抛会沿 handleWorkerError/handleScriptError 的 await 链冒泡到
+ * worker-host 的 `void handlers.onXxx(...)` 变 unhandledRejection，且 run 卡 running
+ * （旧 worker 已死、新 worker 未建，再无任何事件可达）。本函数 catch 后回灌重试矩阵
+ * （handleRebuildStartFailure）：计入 workerErrorCount，未超限再退避重建，超限收敛
+ * done,failed——恢复机制在它自己的恢复路径上不再开口。
  */
 async function scheduleRebuild(
   run: WorkflowRun,
   deps: LifecycleDeps,
   handlers: WorkerHandlers,
 ): Promise<void> {
- // 用当前重试计数算退避（workerErrorCount 或 scriptErrorCount 已递增）
+  // 用当前重试计数算退避（workerErrorCount 或 scriptErrorCount 已递增）
   const retryIndex = Math.max(
     run.meta.workerErrorCount ?? 0,
     run.meta.scriptErrorCount ?? 0,
   );
   await delay(backoffDelay(retryIndex));
 
- // 退避期间状态可能变化——重检
+  // 退避期间状态可能变化——重检
   if (isTerminal(run)) return;
 
- // [race-F3] 时间预算折算后已耗尽 → 不再 rebuild 重试，直接 time_limited 终态。
- // 必须在退避 delay 之后、rebuildRuntime 之前检查：检查前移会在「退避期间耗尽」的
- // 窗口漏判（rebuild 挂不出 timer，run 预算静默失效）；检查点与 rebuildRuntime 的
- // 计时器挂载之间无 await，remaining > 0 判定不会失效。
+  // [race-F3] 时间预算折算后已耗尽 → 不再 rebuild 重试，直接 time_limited 终态。
+  // 必须在退避 delay 之后、rebuildRuntime 之前检查：检查前移会在「退避期间耗尽」的
+  // 窗口漏判（rebuild 挂不出 timer，run 预算静默失效）；检查点与 rebuildRuntime 的
+  // 计时器挂载之间无 await，remaining > 0 判定不会失效。
   const remainingMs = remainingTimeBudgetMs(run);
   if (remainingMs !== undefined && remainingMs <= 0) {
     await finalizeTimeBudgetExhausted(run, deps);
     return;
   }
 
-  rebuildRuntime(run, deps, handlers);
+  try {
+    rebuildRuntime(run, deps, handlers);
+  } catch (err) {
+    await handleRebuildStartFailure(run, err, deps, handlers);
+  }
+}
+
+/**
+ * [OR-2] rebuildRuntime 抛错回灌重试矩阵。
+ *
+ * 重建动作本身失败按 worker 家族计数（重建的就是 worker）——计入 run.meta.workerErrorCount
+ * （跨 runtime 存活的重试计数载体），与既有 handleWorkerError 共用同一上限
+ * MAX_WORKER_RETRIES 与退避序列：
+ * - count <= MAX → 递归 scheduleRebuild（天然复用退避 / isTerminal 重检 / 预算折算守卫；
+ *   每轮计数 +1，递归深度有界 ≤ MAX_WORKER_RETRIES）；
+ * - count > MAX → 收敛 done,failed（transition + 收口 in-flight + 持久化 + 围栏副作用），
+ *   run 不再卡 running。
+ *
+ * 终态路径顺序与其余 handle* 对齐：transition → closeOut → save → 围栏 emit/onRunDone。
+ */
+async function handleRebuildStartFailure(
+  run: WorkflowRun,
+  err: unknown,
+  deps: LifecycleDeps,
+  handlers: WorkerHandlers,
+): Promise<void> {
+  if (isTerminal(run)) return;
+  const message = err instanceof Error ? err.message : String(err);
+  const count = (run.meta.workerErrorCount ?? 0) + 1;
+  run.meta.workerErrorCount = count;
+  logger.error(
+    `[workflow] rebuildRuntime failed (runId=${run.runId}, attempt ${count}/${MAX_WORKER_RETRIES}): ${message}`,
+  );
+
+  if (count <= MAX_WORKER_RETRIES) {
+    await scheduleRebuild(run, deps, handlers);
+    return;
+  }
+
+  // 耗尽 → 收敛 done,failed（不卡 running）
+  run.state.error = `Runtime rebuild failed after ${MAX_WORKER_RETRIES} retries: ${message}`;
+  deps.log?.("debug", "workflow:error-recovery", "rebuild retries exhausted, transition done", { runId: run.runId, count });
+  run.transition("done", "failed");
+  // [OR-8] 终态收口残留 in-flight call（先收口再落盘）
+  closeOutInFlightCalls(run);
+  await saveRunBestEffort(run, deps, "handleRebuildStartFailure (done,failed)");
+  // [OR-4] M12 同款围栏
+  emitTerminalSideEffects(run, deps, "handleRebuildStartFailure (done,failed)");
 }