@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/orchestration/lifecycle.ts

@@ -10,6 +10,9 @@
  * - evictDoneRunsBeyondCap(runs, keepDone) → number（done run 内存淘汰）
  * - scheduleTimeBudget(runId, deps, budgetTimeMs) → timer（C.7 时间预算）
  *
+ * 第 6 个导出：recoverCrashedRuns(store, runs, reason, hooks?) —— 崩溃恢复四步
+ * 装配（loadAll→failed→save→evict，D8/B1），宿主专属事件经 hooks 外置。
+ *
  * 私有 makeHandlers(run, deps) → WorkerHandlers：
  * - onMessage → handleWorkerMessage(run, raw, deps, handlers)
  * - onError → handleWorkerError(run, err, deps, handlers) + workerErrorCount++
@@ -38,12 +41,15 @@ import { getLogger } from "../core/logger.ts";
 import { assertSafeTimerDelay } from "../shared/timer-delay.ts";
 import { validateRunArgs } from "./args-validator.ts";
 import {
+  closeOutInFlightCalls,
+  emitPendingUnregister,
+  emitTerminalSideEffects,
   handleWorkerError,
   handleWorkerExit,
   handleWorkerMessage,
 } from "./error-recovery.ts";
 import { Budget } from "./models/budget.ts";
-import type { LifecycleDeps, WorkerHandlers } from "./models/ports.ts";
+import type { LifecycleDeps, RunStore, WorkerHandlers } from "./models/ports.ts";
 import { RunRuntime } from "./models/run-runtime.ts";
 import type { RunSpec } from "./models/run-spec.ts";
 import { Trace } from "./models/trace.ts";
@@ -73,6 +79,52 @@ function generateRunId(): string {
   return `wf-${Date.now()}-${Math.random().toString(RUNID_RADIX).slice(RUNID_SLICE_START, RUNID_SLICE_END)}`;
 }
 
+// ── OR-7：signal abort listener 终态移除 ─────────────────────
+
+/**
+ * run → signal abort listener 收口句柄注册表。
+ *
+ * [OR-7] 旧实现 `{ once: true }` 只在 abort 触发时自清——run 经 return / error /
+ * abortRun / terminate 等任何终态路径收敛后，listener 仍挂在（可能长生命周期的）
+ * 外部 signal 上，同 signal 连续跑多 run 时每次泄漏一个（超 11 个触发
+ * MaxListeners 告警；tool-workflow 的 run action 传的是 pi 会话级 signal，泄漏
+ * 真实可达）。对齐 launcher.ts L-2 修复形态：命名 handler + run 终态
+ * removeEventListener。
+ *
+ * WeakMap：run 被 GC 时条目随之消亡——即使未来新增终态路径漏调 dispose，
+ * 注册表本身也不成为新的无界泄漏面。
+ */
+const signalAbortDisposers = new WeakMap<WorkflowRun, () => void>();
+
+/** 移除 run 关联的 signal abort listener（幂等；未注册 run 为 no-op）。 */
+function disposeSignalAbortListener(run: WorkflowRun): void {
+  const dispose = signalAbortDisposers.get(run);
+  if (!dispose) return;
+  signalAbortDisposers.delete(run);
+  dispose();
+}
+
+/**
+ * [OR-3] 向 worker 广播 {type:"abort"}——终止 run 时先于 transition（= releaseRuntime
+ * → worker.terminate）通知 worker 优雅解阻：worker 侧 pending Map 全部 reject
+ * （WorkflowAbortedError，worker-script-builder 既有 abort 分支），脚本 catch 后自然
+ * 收尾退出，不再依赖 terminate 硬杀。
+ *
+ * P-T3 语义：广播与 worker 自然退出交错不产 unhandledRejection——postMessage 同步抛错
+ * （worker 已退出/通道关闭）只 debug 留痕不中断 abort 主流程（pendings 随 worker 死亡
+ * 清理；WorkerHandle.postMessage 对已 terminate handle 本身 no-op）；transition 必须继续。
+ */
+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);
+    logger.debug(
+      `[workflow] abort broadcast to worker failed (runId=${run.runId}, worker likely already exited): ${msg}`,
+    );
+  }
+}
+
 // ── makeHandlers（路由 worker 事件到 error-recovery handle* 函数） ──────
 
 /**
@@ -91,20 +143,32 @@ function generateRunId(): string {
  * 实际 handleWorkerError 会做最终计数（含重试上限判断），onError 不重复递增。
  */
 function makeHandlers(run: WorkflowRun, deps: LifecycleDeps): WorkerHandlers {
- // 自引用——error-recovery rebuildRuntime 需要 handlers 参数（handlers 引用自身）
+  // [OR-7] per-run deps 视图：包装 onRunDone，把「run 终态」转译为「移除 signal abort
+  // listener」。error-recovery 全部终态路径（handleReturn / handleWorkerError /
+  // handleScriptError / handleWorkerExit / 预算终止 / time_limited / [OR-2] rebuild
+  // 失败收敛）都经 handlers 调用链消费本视图——消息面终态在此统一收口；
+  // abortRun / terminateRunningRuns 两个 lifecycle 自有终态路径另行显式 dispose。
+  const depsWithTerminalCleanup: LifecycleDeps = {
+    ...deps,
+    onRunDone: (doneRun: WorkflowRun): void => {
+      disposeSignalAbortListener(run);
+      deps.onRunDone?.(doneRun);
+    },
+  };
+  // 自引用——error-recovery rebuildRuntime 需要 handlers 参数（handlers 引用自身）
   const handlers: WorkerHandlers = {
     async onMessage(raw: unknown): Promise<void> {
-      await handleWorkerMessage(run, raw, deps, handlers);
+      await handleWorkerMessage(run, raw, depsWithTerminalCleanup, handlers);
     },
     async onError(err: Error): Promise<void> {
-      await handleWorkerError(run, err, deps, handlers);
+      await handleWorkerError(run, err, depsWithTerminalCleanup, handlers);
     },
     async onExit(code: number, handle: WorkerHandle): Promise<void> {
- // H-2：用 worker-host 传入的 handle（即真正触发 exit 的那个 handle），而非
- // run.runtime?.worker——重试竞态下 runtime.worker 可能已被 replaceRuntime 替换
- // 为新 handle，导致 handleWorkerExit 内的 isCurrent 检查误判（漏判 stale exit 或
- // 误杀新 worker）。G-025 检查仍在 handleWorkerExit 内（handle.isCurrent）。
-      await handleWorkerExit(run, code, handle, deps, handlers);
+      // H-2：用 worker-host 传入的 handle（即真正触发 exit 的那个 handle），而非
+      // run.runtime?.worker——重试竞态下 runtime.worker 可能已被 replaceRuntime 替换
+      // 为新 handle，导致 handleWorkerExit 内的 isCurrent 检查误判（漏判 stale exit 或
+      // 误杀新 worker）。G-025 检查仍在 handleWorkerExit 内（handle.isCurrent）。
+      await handleWorkerExit(run, code, handle, depsWithTerminalCleanup, handlers);
     },
   };
   return handlers;
@@ -139,13 +203,127 @@ export function scheduleTimeBudget(
       },
     );
   }, budgetTimeMs);
- // unref：不阻止 Node 退出（workflow 是后台任务，不应因计时器持有事件循环）。
+  // unref：不阻止 Node 退出（workflow 是后台任务，不应因计时器持有事件循环）。
   timer.unref();
   return timer;
 }
 
 // ── runWorkflow ──────────────────────────────────────────────
 
+/**
+ * rfl 仪表（tier-1 §7.1）：向 spec.args 原地注入稳定 _runId。runAndWait 与
+ * executeNestedWorkflow 两个 args 入口都经 runWorkflow 这一 choke point；
+ * rebuildRuntime 复用 run.spec.args 同一对象（error-recovery.ts），worker rebuild
+ * 后脚本侧 $ARGS._runId 不漂移——修复「rebuild 回退 run-<Date.now()> 导致同一
+ * 逻辑 run 碎裂到多个 state 目录」。注入在 validateRunArgs 之后，不参与脚本
+ * 参数 schema 校验（引擎内部字段）。
+ */
+function injectRunId(spec: RunSpec, runId: string): void {
+  if (spec.args && typeof spec.args === "object") {
+    spec.args._runId = runId;
+  }
+}
+
+/** P1-2: pre-aborted signal → fail fast（run 创建前抛，zero side effects）。 */
+function assertSignalNotAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new Error("Workflow run aborted before start");
+  }
+}
+
+/** 创建 running 态 WorkflowRun（budget 共享引用优先，否则按 spec 上限新建）。 */
+function createRunningRun(runId: string, spec: RunSpec): WorkflowRun {
+  return new WorkflowRun(
+    runId,
+    spec,
+    {
+      status: "running",
+      budget: spec.budgetRef ?? new Budget({
+        maxTokens: spec.budgetTokens,
+        maxTimeMs: spec.budgetTimeMs,
+      }),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+    },
+    { startedAt: new Date().toISOString() },
+  );
+}
+
+/**
+ * C.7：run 级时间预算计时器（spec.budgetTimeMs > 0 时启用，到期 abortRun
+ * time_limited）。OR-1 顺序修复（unbounded-wait-audit §4.1）：调度先于
+ * workerHost.start——budgetTimeMs 越界（>2^31-1）的 fail-fast throw
+ * （assertSafeTimerDelay）发生在任何副作用（worker 启动、runs 注册）之前，
+ * 杜绝「worker 已跑、run 永不可达」的孤儿窗口（此前 runs.set 在最末，
+ * fail-fast 后连 abortRun 都抛 not found）。
+ */
+function armTimeBudgetTimer(
+  runId: string,
+  deps: LifecycleDeps,
+  spec: RunSpec,
+): ReturnType<typeof setTimeout> | undefined {
+  return spec.budgetTimeMs && spec.budgetTimeMs > 0
+    ? scheduleTimeBudget(runId, deps, spec.budgetTimeMs)
+    : undefined;
+}
+
+/**
+ * 启动 worker；失败时清理已挂的 timeBudget timer——前移的代价：start 抛错时
+ * 已挂的 timer 会残留，到期对从未注册的 runId 触发 abortRun（必抛 not found）
+ * ——该路径 runs.set 未到，须就地清理。
+ */
+function startWorkerGuarded(
+  spec: RunSpec,
+  deps: LifecycleDeps,
+  handlers: WorkerHandlers,
+  timeBudgetTimer: ReturnType<typeof setTimeout> | undefined,
+): WorkerHandle {
+  try {
+    return deps.workerHost.start(spec, spec.args, handlers);
+  } catch (err) {
+    if (timeBudgetTimer) clearTimeout(timeBudgetTimer);
+    throw err;
+  }
+}
+
+/**
+ * signal abort → abortRun（[OR-7] 命名 listener + run 终态移除，注册表
+ * signalAbortDisposers；触发时自移除 = 显式 once 语义）。
+ * [B-2] 注册点后移到全部 fail-fast throw（assertSafeTimerDelay / workerHost.start）
+ * 成功之后——旧实现先注册 listener，scheduleTimeBudget/start 两条 throw 路径 run
+ * 永不到终态，disposeSignalAbortListener 永不被调，同 signal 重试每次泄漏一个
+ * listener（MaxListeners 告警面）。移后 throw 路径天然未注册，零泄漏；首个真正
+ * 副作用前完成校验的语义保持（addEventListener 本身也是设计意义上的副作用）。
+ * 注册点到 store.save 之间无 await（同步段），signal 在此窗口 abort 不可能丢失。
+ */
+function registerSignalAbortListener(
+  run: WorkflowRun,
+  runId: string,
+  deps: LifecycleDeps,
+  signal: AbortSignal | undefined,
+): void {
+  if (!signal) return;
+  const onAbort = (): void => {
+    disposeSignalAbortListener(run);
+    void abortRun(runId, deps, "External signal aborted").catch((err: unknown) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.error(`[workflow] abortRun on signal failed: ${msg}`);
+    });
+  };
+  signal.addEventListener("abort", onAbort);
+  signalAbortDisposers.set(run, () => signal.removeEventListener("abort", onAbort));
+}
+
+/** pending-notifications: run 启动 → 注册（所有 workflow 启动路径的单一汇聚点）。 */
+function emitPendingRegister(runId: string, deps: LifecycleDeps, spec: RunSpec): void {
+  deps.eventBus?.emit("pending:register", {
+    id: runId,
+    type: "workflow",
+    name: spec.slug || spec.scriptName || runId,
+  });
+}
+
 /**
  * 启动一个 workflow run。
  *
@@ -172,81 +350,37 @@ export async function runWorkflow(
   validateRunArgs(spec);
 
   const runId = generateRunId();
-  // rfl 仪表（tier-1 §7.1）：注入稳定 _runId。runAndWait 与 executeNestedWorkflow
-  // 两个 args 入口都经本 choke point；rebuildRuntime 复用 run.spec.args 同一对象
-  // （error-recovery.ts），worker rebuild 后脚本侧 $ARGS._runId 不漂移——修复
-  // 「rebuild 回退 run-<Date.now()> 导致同一逻辑 run 碎裂到多个 state 目录」。
-  // 注入在 validateRunArgs 之后，不参与脚本参数 schema 校验（引擎内部字段）。
-  if (spec.args && typeof spec.args === "object") {
-    spec.args._runId = runId;
-  }
+  injectRunId(spec, runId);
   deps.log?.("debug", "workflow:lifecycle", "runWorkflow start", { runId, scriptName: spec.scriptName });
 
- // P1-2: pre-aborted signal → fail fast
-  if (signal?.aborted) {
-    throw new Error("Workflow run aborted before start");
-  }
-
-  const run = new WorkflowRun(
-    runId,
-    spec,
-    {
-      status: "running",
-      budget: spec.budgetRef ?? new Budget({
-        maxTokens: spec.budgetTokens,
-        maxTimeMs: spec.budgetTimeMs,
-      }),
-      calls: new Map(),
-      trace: new Trace(),
-      errorLogs: [],
-    },
-    { startedAt: new Date().toISOString() },
-  );
+  // P1-2: pre-aborted signal → fail fast
+  assertSignalNotAborted(signal);
 
- // signal abort → abortRun（一次性监听）
-  if (signal) {
-    signal.addEventListener(
-      "abort",
-      () => {
-        void abortRun(runId, deps, "External signal aborted").catch((err: unknown) => {
-          const msg = err instanceof Error ? err.message : String(err);
-          logger.error(`[workflow] abortRun on signal failed: ${msg}`);
-        });
-      },
-      { once: true },
-    );
-  }
+  const run = createRunningRun(runId, spec);
 
- // 构造 handlers + runtime（worker + controller）
+  // 构造 handlers + runtime（worker + controller）
   const handlers = makeHandlers(run, deps);
   const controller = new AbortController();
-  const worker = deps.workerHost.start(spec, spec.args, handlers);
- // C.7：run 级时间预算计时器（spec.budgetTimeMs > 0 时启用，到期 abortRun time_limited）。
-  const timeBudgetTimer =
-    spec.budgetTimeMs && spec.budgetTimeMs > 0
-      ? scheduleTimeBudget(runId, deps, spec.budgetTimeMs)
-      : undefined;
+  const timeBudgetTimer = armTimeBudgetTimer(runId, deps, spec);
+  const worker = startWorkerGuarded(spec, deps, handlers, timeBudgetTimer);
   const runtime = new RunRuntime(worker, controller, timeBudgetTimer);
 
- // assignRuntime（注入 runtime，恢复 I1：running ⟺ runtime!==undefined）
+  // assignRuntime（注入 runtime，恢复 I1：running ⟺ runtime!==undefined）
   run.assignRuntime(runtime);
 
- // 注册到 deps.runs（assignRuntime 之后——构造到 assignRuntime 之间 run 处于
- // I1 跳过窗口（running 而 runtime undefined），后移保证窗口对外不可见；
- // worker.start 抛错时 run 未注册，无孤儿 run 残留）
+  // 注册到 deps.runs（assignRuntime 之后——构造到 assignRuntime 之间 run 处于
+  // I1 跳过窗口（running 而 runtime undefined），后移保证窗口对外不可见；
+  // scheduleTimeBudget/worker.start 抛错时 run 未注册，无孤儿 run 残留）
   deps.runs.set(runId, run);
 
+  registerSignalAbortListener(run, runId, deps, signal);
+
   await deps.store.save(run);
   deps.log?.("debug", "workflow:lifecycle", "run saved", { runId, status: run.state.status });
 
- // pending-notifications: run 启动 → 注册（所有 workflow 启动路径的单一汇聚点：
- // runAndWait / actionRun / 未来入口全覆盖）
+  // pending-notifications: run 启动 → 注册（runAndWait / actionRun / 未来入口全覆盖）
   deps.log?.("debug", "workflow:lifecycle", "emit pending:register", { runId });
-  deps.eventBus?.emit("pending:register", {
-    id: runId,
-    type: "workflow",
-    name: spec.slug || spec.scriptName || runId,
-  });
+  emitPendingRegister(runId, deps, spec);
   deps.log?.("debug", "workflow:lifecycle", "emit pending:register done", { runId });
 
   return runId;
@@ -279,25 +413,33 @@ export async function abortRun(
 
   deps.log?.("debug", "workflow:lifecycle", "abortRun", { runId, status: run.state.status, reason, doneReason });
 
- // done 状态 no-op
+  // done 状态 no-op
   if (run.state.status === "done") {
     deps.log?.("debug", "workflow:lifecycle", "abortRun no-op: already done", { runId });
     return;
   }
 
- // 记录中止原因
+  // 记录中止原因
   if (reason) {
     run.state.error = reason;
   }
- // A4: transition 内部 releaseRuntime（cleanup before mutate）
+  // [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 入口的收口）
+  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 层
-  deps.log?.("debug", "workflow:lifecycle", "emit pending:unregister", { runId, reason: run.state.reason });
-  deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: run.state.reason ?? "completed" });
-  deps.log?.("debug", "workflow:lifecycle", "emit pending:unregister done", { runId });
-  deps.onRunDone?.(run);
+  // 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})`);
 }
 
 // ── terminateRunningRuns（session 切换/关闭：终止全部 running run） ────────
@@ -336,11 +478,20 @@ export async function terminateRunningRuns(
     try {
       deps.log?.("debug", "workflow:lifecycle", "terminateRunningRuns", { runId: run.runId, reason });
       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——本路径显式收口）
+      disposeSignalAbortListener(run);
+      // [OR-8] 终态收口残留 in-flight call（先收口再落盘）
+      closeOutInFlightCalls(run);
       await deps.store.save(run);
-      // C-4: run 到达 done 终态 → 注销 pending-notification（reason 固定 "failed"）
-      deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: "failed" });
+      // C-4: run 到达 done 终态 → 注销 pending-notification（reason 固定 "failed"）。
+      // [B-4] M12 同款围栏：emit 单独 try（listener 同步抛错 error 留痕不中断本 run
+      // 收尾日志与其余 run 的终止；本路径不调 onRunDone——session 离开语境不发完成通知）。
+      emitPendingUnregister(run, deps, "terminateRunningRuns");
       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);
@@ -397,3 +548,128 @@ export function evictDoneRunsBeyondCap(
   }
   return excess;
 }
+
+// ── recoverCrashedRuns（kill-9/崩溃恢复四步装配，D8/B1） ────────────────
+
+/**
+ * 崩溃恢复循环的宿主事件外置 hooks（core 平台中立，宿主注入专属行为）。
+ *
+ * pi 宿主在 onRunRecovered 中发射 `pending:unregister` 事件（pending-notifications
+ * 扩展的注销信号灯）；zsw/第三宿主可接自己的通知通道。不注入 = 无宿主事件，
+ * 恢复语义（failed 转换 + 落盘 + 淘汰）不受影响。
+ */
+export interface RecoverCrashedRunsHooks {
+  /**
+   * 每个 running → done,failed 转换的 run 恰好调用一次。
+   *
+   * payload 形状对齐 pi `pending:unregister` 事件：`{ id: runId, reason: "failed" }`
+   * ——宿主可直接把 payload 转发到自己的事件总线。
+   *
+   * 错误围栏：回调同步 throw 经 core logger facade warn 留痕后被吞掉，恢复循环
+   * 继续其余 run（转换/落盘不受影响）——与 save 步骤「单 run 失败不中断其余」
+   * 容错口径对称。
+   */
+  onRunRecovered?: (payload: { id: string; reason: string }) => void;
+}
+
+/**
+ * recoverCrashedRuns 的计数结果（宿主启动日志/健康面用）。
+ *
+ * `recovered` 只计 running 遗留被转换为 done,failed 的条数；`loaded` 是 loadAll
+ * 重水合的全量数（含 done 历史快照）——两者分开口径，避免宿主把「重水合 N 条」
+ * 误报为「恢复 N 条」。
+ */
+export interface RecoverCrashedRunsResult {
+  /** loadAll 重水合的 run 总数（含 done 历史快照）。 */
+  loaded: number;
+  /** running 遗留被转换为 done,failed 的条数（0 = 无崩溃遗留）。 */
+  recovered: number;
+}
+
+/**
+ * 崩溃恢复四步装配（设计 D8/B1）：loadAll → failed → save → evict。
+ *
+ * 平移自 pi 壳 session_start 恢复循环（subagent-workflow index.ts:578-627）与
+ * zsw orchestration-host recoverOrphans（逐行同构，pending:unregister 为唯一
+ * 宿主差异点——经 {@link RecoverCrashedRunsHooks} 外置）。
+ *
+ * 步骤语义：
+ * 1. **loadAll**：从 store 全量重水合。失败向上抛——fail-fast 策略（pi 的
+ *    storeHealthy=false 停初始化）是宿主职责，调用方 catch 后自行决定；
+ * 2. **failed**：残留 running run（进程被杀，worker 必死）逐个
+ *    `state.error = reason` → `transition("done","failed")`（A4：transition 内部
+ *    先 releaseRuntime），并发宿主事件（hooks）；done run 原样保留；
+ * 3. **save**：转换后的 run 落盘（恢复终态必须持久化，不 save 则下次启动重水合
+ *    仍见 running，侧栏永久卡 running）。单 run save 失败仅记日志不中断其余
+ *    run——恢复天然幂等，下次启动重开重试；
+ * 4. **evict**：全量重水合后立即 `evictDoneRunsBeyondCap(runs,
+ *    MAX_RETAINED_DONE_RUNS)`（K=20）——done run 内存有界性；只 delete 内存
+ *    Map 条目，磁盘 state 文件不动（对齐 pi，历史审计保留）。
+ *
+ * 所有 loaded run（含 done）都注册进 runs Map（runId → WorkflowRun）——与 pi
+ * 一致，done run 也入 Map 供列表/查询消费。
+ *
+ * @param store RunStore port（loadAll/save）
+ * @param runs per-session 的 run 注册表（原地写入 + 淘汰）
+ * @param reason 恢复原因（写入 running run 的 state.error，如
+ *   "Process killed (kill-9 or crash recovery)"）
+ * @param hooks 宿主事件外置（可选）
+ * @returns 计数 `{ loaded, recovered }`——recovered 只计 running→failed 转换条数
+ * @throws store.loadAll 失败时原样抛出（步骤 1）
+ */
+export async function recoverCrashedRuns(
+  store: RunStore,
+  runs: Map<string, WorkflowRun>,
+  reason: string,
+  hooks?: RecoverCrashedRunsHooks,
+): Promise<RecoverCrashedRunsResult> {
+  // 步骤 1：loadAll（失败上抛，宿主决定 fail-fast 策略）
+  const loaded = await store.loadAll();
+  let recovered = 0;
+
+  for (const run of loaded) {
+    if (run.state.status === "running") {
+      // 步骤 2：running → done,failed（顺序对齐 pi：set error → transition → 宿主事件）
+      run.state.error = reason;
+      run.transition("done", "failed");
+      // [OR-8] 重水合 running 快照可携带 in-flight call（崩溃瞬间的 running 节点）——
+      // 终态收口为 cancelled，先收口再落盘
+      closeOutInFlightCalls(run);
+      recovered += 1;
+      // 宿主事件外置点：pi 发 pending:unregister，位置在 transition 后、save 前
+      // （对齐 pi emit 位置——先解除挂起通知再落盘，事件观察者不依赖落盘完成）。
+      // 错误围栏：宿主回调同步 throw 只 warn 不中断循环——与步骤 3 save 的
+      // 「单 run 失败不中断其余」容错口径对称（通知通道故障不等价于恢复失败；
+      // 恢复天然幂等，未送达的通知随下次启动重试，见步骤 3 注释）。
+      try {
+        hooks?.onRunRecovered?.({ id: run.runId, reason: "failed" });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(
+          `[workflow] recoverCrashedRuns onRunRecovered hook failed for run ${run.runId} (recovery continues): ${msg}`,
+        );
+      }
+      // 步骤 3：恢复终态落盘（单 run 失败不中断其余 run——幂等恢复，下次重试）
+      try {
+        await store.save(run);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(
+          `[workflow] recoverCrashedRuns store.save failed for run ${run.runId}: ${msg} (reason: ${reason})`,
+        );
+      }
+    }
+    runs.set(run.runId, run);
+  }
+
+  // 步骤 4：done run 内存有界性（K=20）。kill-9 恢复转换出的 failed run
+  // completedAt 为 transition 时刻（全局最新）必在保留端；多条恢复 run 同 ms
+  // completedAt → tie 稳定排序（evictDoneRunsBeyondCap 契约）。
+  const evicted = evictDoneRunsBeyondCap(runs, MAX_RETAINED_DONE_RUNS);
+  if (evicted > 0) {
+    logger.debug(
+      `[workflow] recoverCrashedRuns evicted ${evicted} done runs beyond cap (keep=${MAX_RETAINED_DONE_RUNS})`,
+    );
+  }
+  return { loaded: loaded.length, recovered };
+}

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

@@ -34,11 +34,11 @@ export class AgentCall {
   status: AgentCallStatus = "pending";
   attempts = 0;
   result?: AgentResult;
- /** Pi subprocess session ID（uuidv7，G-017 归此）。 */
+  /** Pi subprocess session ID（uuidv7，G-017 归此）。 */
   sessionId?: string;
- /** Session JSONL 绝对路径（finalizeCall 后从 result.sessionFile 填入，对齐 sessionId 模式）。 */
+  /** Session JSONL 绝对路径（finalizeCall 后从 result.sessionFile 填入，对齐 sessionId 模式）。 */
   sessionFile?: string;
- /** 与 Trace 共享的节点引用（D-10 单源）。AgentCall 不直接改其字段。 */
+  /** 与 Trace 共享的节点引用（D-10 单源）。AgentCall 不直接改其字段。 */
   readonly traceNode: ExecutionTraceNode;
 
   constructor(id: number, opts: AgentCallOpts, traceNode: ExecutionTraceNode) {
@@ -47,7 +47,7 @@ export class AgentCall {
     this.traceNode = traceNode;
   }
 
- /**
+  /**
  * 标记进入 running 状态（dispatch 前）。attempts++（含首次）。
  * @throws 若已 done（不可重启）
  */
@@ -59,7 +59,7 @@ export class AgentCall {
     this.attempts += 1;
   }
 
- /**
+  /**
  * 标记完成（成功或失败均调用——result.error 区分）。
  * @throws 若当前非 running（pending 不能直接跳 done，必须先 markRunning）
  */
@@ -71,12 +71,12 @@ export class AgentCall {
     this.status = "done";
   }
 
- /** 记录 pi subprocess session ID（dispatch 成功后）。 */
+  /** 记录 pi subprocess session ID（dispatch 成功后）。 */
   setSessionId(sessionId: string): void {
     this.sessionId = sessionId;
   }
 
- /** 记录 session JSONL 绝对路径（finalizeCall 后，对齐 setSessionId 模式）。 */
+  /** 记录 session JSONL 绝对路径（finalizeCall 后，对齐 setSessionId 模式）。 */
   setSessionFile(sessionFile: string): void {
     this.sessionFile = sessionFile;
   }

package/src/orchestration/models/budget.ts

@@ -46,7 +46,7 @@ export class Budget {
   readonly maxTimeMs?: number;
   usedTokens = 0;
   usedCost = 0;
- /** 总调用计数（持久化/诊断用；execute-agent-call 每次 dispatch 后 increment）。 */
+  /** 总调用计数（持久化/诊断用；execute-agent-call 每次 dispatch 后 increment）。 */
   totalCallCount = 0;
 
   constructor(opts: {
@@ -65,7 +65,7 @@ export class Budget {
     this.totalCallCount = opts.totalCallCount ?? 0;
   }
 
- /**
+  /**
  * 累加一次 agent 调用的 usage（加权口径）。
  *
  * 四项 token 按各自权重（INPUT/CACHE_READ/CACHE_WRITE/OUTPUT_WEIGHT）折算后求和，
@@ -84,12 +84,12 @@ export class Budget {
     this.usedCost += numOrZero(usage.cost);
   }
 
- /** 累加调用计数（每次 agent dispatch 后调用；持久化快照同步）。 */
+  /** 累加调用计数（每次 agent dispatch 后调用；持久化快照同步）。 */
   incrementCallCount(): void {
     this.totalCallCount += 1;
   }
 
- /**
+  /**
  * 是否超 token / cost 预算（FR-3）。
  *
  * maxTokens===0 或 undefined 视为不限制（守卫）；
@@ -105,7 +105,7 @@ export class Budget {
     return this.maxCost !== undefined && this.maxCost > 0 && this.usedCost >= this.maxCost;
   }
 
- /**
+  /**
  * 剩余 token 预算。maxTokens 未设或 ≤0 时返回 undefined（视为不限制）。
  *
  * 嵌套 workflow() 调用时由 executeNestedWorkflow 消费：子 run 的 budgetTokens