@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/orchestration/__tests__/lifecycle-abort-broadcast-signal.test.ts

@@ -0,0 +1,357 @@
+/**
+ * [OR-3] abort 广播（主线程半边）+ [OR-7] signal abort listener 终态移除 测试。
+ *
+ * 覆盖（unbounded-wait-audit §4.3 OR-7 / §7.2 T3③⑥ / §7.3 P-T3 主线程半边）：
+ * - abortRun / terminateRunningRuns 在 worker.terminate 之前向 worker 广播
+ *   {type:"abort", reason}（worker 侧 pending 优雅解阻，P-T3）；postMessage 抛错
+ *   （worker 已退出）不阻断 abort 主流程；runtime 缺失为 no-op
+ * - abort listener 注册后，run 经任意终态路径收敛时 removeEventListener：
+ *   abortRun（用户/预算/超时 abort）、terminateRunningRuns（session 切换）、
+ *   消息面终态（return → onRunDone 包装收口）——修复 {once:true} 只在 abort
+ *   触发时自清的泄漏（同 signal 连续多 run 泄漏 listener）
+ * - [OR-8] abortRun 收口残留 in-flight call（先收口再落盘）
+ */
+import { getEventListeners } from "node:events";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  abortRun,
+  runWorkflow,
+  terminateRunningRuns,
+} from "../lifecycle.ts";
+import { AgentCall } from "../models/agent-call.ts";
+import { RunRuntime } from "../models/run-runtime.ts";
+import { Trace } from "../models/trace.ts";
+import type { RunSpec } from "../models/run-spec.ts";
+import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
+import type { AgentResult, ExecutionTraceNode } from "../models/types.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+import type { WorkerHandle } from "../worker-handle.ts";
+
+// ── helpers ──────────────────────────────────────────────────
+
+function makeSpec(): RunSpec {
+  return {
+    scriptSource: "execute() {}",
+    args: {},
+    scriptName: "test-wf",
+    scriptPath: "/fake/test.js",
+  };
+}
+
+function makeDeps(): LifecycleDeps & {
+  store: { save: ReturnType<typeof vi.fn>; loadAll: ReturnType<typeof vi.fn> };
+  workerHost: { start: ReturnType<typeof vi.fn> };
+  eventBus: { emit: ReturnType<typeof vi.fn> };
+  onRunDone: ReturnType<typeof vi.fn>;
+  log: ReturnType<typeof vi.fn>;
+} {
+  return {
+    store: { save: vi.fn(async () => {}), loadAll: vi.fn(async () => []) },
+    workerHost: {
+      start: vi.fn(
+        () => ({ postMessage: vi.fn(), terminate: vi.fn(async () => {}) }) as unknown as WorkerHandle,
+      ),
+    },
+    runner: { run: vi.fn(async () => ({}) as AgentResult) },
+    runs: new Map(),
+    eventBus: { emit: vi.fn() },
+    onRunDone: vi.fn(),
+    log: vi.fn(),
+  } as unknown as ReturnType<typeof makeDeps>;
+}
+
+/** 从 mock worker 提取 postMessage spy。 */
+function postSpy(handle: unknown): ReturnType<typeof vi.fn> {
+  return (handle as { postMessage: ReturnType<typeof vi.fn> }).postMessage;
+}
+
+/** 从 workerHost.start mock 取第 n 次启动的 handle。 */
+function startedHandle(deps: ReturnType<typeof makeDeps>, n = 0): unknown {
+  return deps.workerHost.start.mock.results[n]?.value;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+// ── [OR-3] abort 广播（主线程半边） ──────────────────────────
+
+describe("[OR-3] abort 广播（abortRun / terminateRunningRuns）", () => {
+  it("abortRun：在 terminate 之前向 worker 广播 {type:\"abort\", reason}", async () => {
+    const deps = makeDeps();
+    const runId = await runWorkflow(makeSpec(), deps);
+    const handle = startedHandle(deps);
+    const post = postSpy(handle);
+    const terminate = (handle as { terminate: ReturnType<typeof vi.fn> }).terminate;
+    post.mockClear();
+
+    await abortRun(runId, deps, "user requested abort");
+
+    expect(post).toHaveBeenCalledWith({ type: "abort", reason: "user requested abort" });
+    // 顺序锚：广播先于 terminate（terminate 后广播发不进去）
+    expect(terminate).toHaveBeenCalledTimes(1);
+    expect(post.mock.invocationCallOrder[0]).toBeLessThan(terminate.mock.invocationCallOrder[0]);
+    expect(deps.runs.get(runId)?.state.reason).toBe("aborted");
+  });
+
+  it("abortRun 未传 reason：广播 reason 带 doneReason（time_limited 场景可归因）", async () => {
+    const deps = makeDeps();
+    const runId = await runWorkflow(makeSpec(), deps);
+    postSpy(startedHandle(deps)).mockClear();
+
+    await abortRun(runId, deps, undefined, "time_limited");
+
+    expect(postSpy(startedHandle(deps))).toHaveBeenCalledWith(
+      { type: "abort", reason: "Workflow aborted (time_limited)" },
+    );
+  });
+
+  it("postMessage 同步抛错（worker 已退出）：不阻断 abort 主流程（P-T3）", async () => {
+    const deps = makeDeps();
+    const runId = await runWorkflow(makeSpec(), deps);
+    const handle = startedHandle(deps);
+    postSpy(handle).mockImplementation(() => {
+      throw new Error("postMessage after worker exited");
+    });
+
+    await expect(abortRun(runId, deps, "abort despite dead worker")).resolves.toBeUndefined();
+
+    // transition / 持久化照常完成（save 2 次 = runWorkflow 启动 1 次 + abortRun 1 次）
+    expect(deps.runs.get(runId)?.state.reason).toBe("aborted");
+    expect(deps.store.save).toHaveBeenCalledTimes(2);
+    expect(deps.eventBus.emit).toHaveBeenCalledWith("pending:unregister", expect.anything());
+  });
+
+  it("runtime 缺失（无 worker）：广播 no-op，abort 照常", async () => {
+    const deps = makeDeps();
+    const runId = await runWorkflow(makeSpec(), deps);
+    const run = deps.runs.get(runId)!;
+    run.runtime = undefined;
+
+    await expect(abortRun(runId, deps, "no runtime")).resolves.toBeUndefined();
+    expect(run.state.reason).toBe("aborted");
+  });
+
+  it("terminateRunningRuns：每个 running run 各自广播（先于 terminate）", async () => {
+    const deps = makeDeps();
+    const idA = await runWorkflow(makeSpec(), deps);
+    const idB = await runWorkflow(makeSpec(), deps);
+    const handleA = startedHandle(deps, 0);
+    const handleB = startedHandle(deps, 1);
+    postSpy(handleA).mockClear();
+    postSpy(handleB).mockClear();
+
+    await terminateRunningRuns(deps, "Session switched: run terminated");
+
+    expect(postSpy(handleA)).toHaveBeenCalledWith({ type: "abort", reason: "Session switched: run terminated" });
+    expect(postSpy(handleB)).toHaveBeenCalledWith({ type: "abort", reason: "Session switched: run terminated" });
+    expect(deps.runs.get(idA)?.state.reason).toBe("failed");
+    expect(deps.runs.get(idB)?.state.reason).toBe("failed");
+  });
+
+  it("[OR-8] abortRun 收口残留 in-flight call：先收口再落盘，快照无 running 节点", async () => {
+    const deps = makeDeps();
+    const runId = await runWorkflow(makeSpec(), deps);
+    const run = deps.runs.get(runId)!;
+    // 注入 in-flight call（真实 AgentCall 实例：running + live record）
+    const node: ExecutionTraceNode = {
+      stepIndex: 1,
+      agent: "a",
+      task: "t",
+      model: "m",
+      status: "running",
+      live: { turns: [] } as never,
+    };
+    run.state.trace.append(node);
+    const call = new AgentCall(1, { prompt: "t" }, node);
+    call.markRunning();
+    run.state.calls.set(1, call);
+
+    await abortRun(runId, deps, "mid-flight abort");
+
+    // 收口：call done + trace failed（Cancelled 文案）+ live 清除
+    expect(call.status).toBe("done");
+    expect(call.result?.error).toContain("Cancelled");
+    expect(run.state.trace.find(1)?.status).toBe("failed");
+    // 落盘在收口之后：save 时 run 已无 running 节点
+    expect(run.state.trace.toArray().every((n) => n.status !== "running")).toBe(true);
+  });
+});
+
+// ── [OR-7] signal abort listener 终态移除 ────────────────────
+
+describe("[OR-7] signal abort listener run 终态移除", () => {
+  /** 构造带 spy 的 controller（记录 add/remove 的 listener，原行为保留）。 */
+  function makeSignal(): {
+    controller: AbortController;
+    added: Array<() => void>;
+    removed: Array<() => void>;
+  } {
+    const controller = new AbortController();
+    const added: Array<() => void> = [];
+    const removed: Array<() => void> = [];
+    const origAdd = controller.signal.addEventListener.bind(controller.signal);
+    const origRemove = controller.signal.removeEventListener.bind(controller.signal);
+    vi.spyOn(controller.signal, "addEventListener").mockImplementation(
+      (type: string, listener: EventListenerOrEventListenerObject, options?: unknown): void => {
+        added.push(listener as () => void);
+        origAdd(type as "abort", listener, options as never);
+      },
+    );
+    vi.spyOn(controller.signal, "removeEventListener").mockImplementation(
+      (type: string, listener: EventListenerOrEventListenerObject, options?: unknown): void => {
+        removed.push(listener as () => void);
+        origRemove(type as "abort", listener, options as never);
+      },
+    );
+    return { controller, added, removed };
+  }
+
+  it("abortRun 终止 run → removeEventListener（listener 不残留）", async () => {
+    const deps = makeDeps();
+    const { controller, added, removed } = makeSignal();
+
+    const runId = await runWorkflow(makeSpec(), deps, controller.signal);
+    expect(added).toHaveLength(1);
+    expect(removed).toHaveLength(0);
+
+    await abortRun(runId, deps, "user abort");
+
+    expect(removed).toEqual([added[0]]);
+    // 手动再派发 abort 事件：listener 已移除，无任何 abort 副作用
+    const emitSpy = deps.eventBus.emit;
+    emitSpy.mockClear();
+    controller.signal.dispatchEvent(new Event("abort"));
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+
+  it("消息面终态（worker return → onRunDone）→ removeEventListener（不再泄漏）", async () => {
+    const deps = makeDeps();
+    const { controller, added, removed } = makeSignal();
+
+    const runId = await runWorkflow(makeSpec(), deps, controller.signal);
+    const handle = startedHandle(deps);
+    // 捕获 makeHandlers 构造的 handlers（workerHost.start 的第 3 参）并投递 return
+    const handlers = deps.workerHost.start.mock.calls[0]?.[2] as WorkerHandlers;
+    await handlers.onMessage({ type: "return", result: { ok: true } });
+
+    expect(deps.runs.get(runId)?.state.reason).toBe("completed");
+    expect(removed).toEqual([added[0]]);
+    expect(postSpy(handle).mock.calls.some((c) => (c[0] as { type?: string })?.type === "abort")).toBe(false);
+  });
+
+  it("terminateRunningRuns 终止 → removeEventListener（不走 onRunDone 的路径也收口）", async () => {
+    const deps = makeDeps();
+    const { controller, added, removed } = makeSignal();
+
+    await runWorkflow(makeSpec(), deps, controller.signal);
+    expect(removed).toHaveLength(0);
+
+    await terminateRunningRuns(deps, "session switch");
+
+    expect(removed).toEqual([added[0]]);
+  });
+
+  it("signal 触发 abort → listener 自移除（显式 once 语义）且 run 转 aborted", async () => {
+    const deps = makeDeps();
+    const { controller, added, removed } = makeSignal();
+
+    const runId = await runWorkflow(makeSpec(), deps, controller.signal);
+    controller.abort();
+
+    await vi.advanceTimersByTimeAsync(0);
+    expect(deps.runs.get(runId)?.state.reason).toBe("aborted");
+    expect(removed).toEqual([added[0]]);
+  });
+
+  it("同一 signal 连续跑 12 个 run（逐一终态）→ 同时刻至多 1 个 listener（无累积）", async () => {
+    const deps = makeDeps();
+    const controller = new AbortController();
+    let live = 0;
+    let peak = 0;
+    const origAdd = controller.signal.addEventListener.bind(controller.signal);
+    const origRemove = controller.signal.removeEventListener.bind(controller.signal);
+    vi.spyOn(controller.signal, "addEventListener").mockImplementation(
+      (type: string, listener: EventListenerOrEventListenerObject, options?: unknown): void => {
+        live += 1;
+        peak = Math.max(peak, live);
+        origAdd(type as "abort", listener, options as never);
+      },
+    );
+    vi.spyOn(controller.signal, "removeEventListener").mockImplementation(
+      (type: string, listener: EventListenerOrEventListenerObject, options?: unknown): void => {
+        live -= 1;
+        origRemove(type as "abort", listener, options as never);
+      },
+    );
+
+    for (let i = 0; i < 12; i++) {
+      const runId = await runWorkflow(makeSpec(), deps, controller.signal);
+      await abortRun(runId, deps, `done ${i}`);
+    }
+
+    expect(peak).toBe(1);
+    expect(live).toBe(0);
+  });
+
+  it("终态后 listener 不再触发 abortRun（完成态不被迟到的 signal abort 改写）", async () => {
+    const deps = makeDeps();
+    const controller = new AbortController();
+    const runId = await runWorkflow(makeSpec(), deps, controller.signal);
+
+    // 正常完成
+    const handlers = deps.workerHost.start.mock.calls[0]?.[2] as WorkerHandlers;
+    await handlers.onMessage({ type: "return", result: "ok" });
+    expect(deps.runs.get(runId)?.state.reason).toBe("completed");
+
+    // 完成后外部 signal 才 abort——listener 已移除，run 保持 completed（不被改写）
+    controller.abort();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(deps.runs.get(runId)?.state.reason).toBe("completed");
+    expect(deps.store.save).toHaveBeenCalledTimes(2); // runWorkflow 启动 + return 各 1 次
+  });
+});
+
+// ── [B-2] fail-fast throw 路径不泄漏 signal abort listener ──────────────
+
+describe("[B-2] runWorkflow fail-fast throw 路径不泄漏 signal abort listener", () => {
+  /** signal 上当前真实挂载的 abort listener 数（EventTarget 权威查询，非 spy 计数）。 */
+  function liveListenerCount(signal: AbortSignal): number {
+    return getEventListeners(signal).length;
+  }
+
+  it("budgetTimeMs 越界 fail-fast 重试 12 次 → 每次拒绝后 listener 计数归零（无 MaxListeners 累积）", async () => {
+    const deps = makeDeps();
+    const controller = new AbortController();
+    // 越界值（>2^31-1）→ assertSafeTimerDelay 在 scheduleTimeBudget 内 fail-fast throw
+    const spec: RunSpec = { ...makeSpec(), budgetTimeMs: 3_000_000_000 };
+
+    for (let i = 0; i < 12; i++) {
+      await expect(runWorkflow(spec, deps, controller.signal)).rejects.toThrow(/2147483647/);
+      // 旧实现 listener 先注册、throw 路径不 dispose——12 次重试后泄漏 12 个
+      expect(liveListenerCount(controller.signal)).toBe(0);
+    }
+    expect(deps.runs.size).toBe(0); // fail-fast：无孤儿 run
+  });
+
+  it("workerHost.start 抛错重试 12 次 → 每次拒绝后 listener 计数归零", async () => {
+    const deps = makeDeps();
+    deps.workerHost.start = vi.fn(() => {
+      throw new Error("worker boot failed");
+    });
+    const controller = new AbortController();
+
+    for (let i = 0; i < 12; i++) {
+      await expect(runWorkflow(makeSpec(), deps, controller.signal)).rejects.toThrow("worker boot failed");
+      expect(liveListenerCount(controller.signal)).toBe(0);
+    }
+    expect(deps.runs.size).toBe(0);
+  });
+});

package/src/orchestration/__tests__/lifecycle-recover-crashed.test.ts

@@ -0,0 +1,289 @@
+// lifecycle-recover-crashed.test.ts —— recoverCrashedRuns 崩溃恢复四步装配测试（U7/D8/B1）。
+//
+// 四步序列 = loadAll → failed → save → evict（平移 pi session_start 恢复循环，
+// pending:unregister 宿主事件经 hooks 外置）。本文件用真实 WorkflowRun（真实
+// 状态机 + I1/I2 不变式）+ mock RunStore（可观察调用序列）。
+//
+// 覆盖：
+// - running 残留 → done,failed（state.error=reason）+ save 落盘 + runs Map 注册
+// - 序列：hooks 在 transition 后、save 前（对齐 pi emit 位置）；save 收到的已是终态 run
+// - done run 原样保留（不重复 save）但也注册进 runs Map
+// - hooks 每 running run 恰好一次、参数 {id, reason:"failed"}；无 hooks 不炸
+// - 单 run save 失败不中断其余 run（幂等恢复）；loadAll 失败向上抛
+// - onRunRecovered 同步 throw 被围栏捕获（warn 留痕），不中断其余 run 恢复
+// - evict 步：超 MAX_RETAINED_DONE_RUNS 的 done run 被淘汰（最旧优先）
+import { describe, expect, it, vi } from "vitest";
+
+import { configureCore, resetCoreForTests } from "../../core/host-services.ts";
+import {
+  MAX_RETAINED_DONE_RUNS,
+  recoverCrashedRuns,
+} from "../lifecycle.ts";
+import { Budget } from "../models/budget.ts";
+import type { RunStore } from "../models/ports.ts";
+import type { RunSpec } from "../models/run-spec.ts";
+import { Trace } from "../models/trace.ts";
+import type { DoneReason } from "../models/types.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+
+// ── helpers ──────────────────────────────────────────────────
+
+function makeSpec(name = "test-wf"): RunSpec {
+  return {
+    scriptSource: "execute() {}",
+    args: {},
+    scriptName: name,
+    scriptPath: "/fake/test.js",
+  };
+}
+
+/**
+ * 重水合形态构造（对齐 store.loadAll 真实产物：running 快照无 runtime——
+ * reconstruct 不恢复 worker，transition 的 releaseRuntime 对 undefined no-op）。
+ */
+function makeRun(
+  runId: string,
+  opts: {
+    status?: "running" | "done";
+    reason?: DoneReason;
+    completedAt?: string;
+    error?: string;
+    scriptName?: string;
+  } = {},
+): WorkflowRun {
+  const status = opts.status ?? "running";
+  const state = {
+    status,
+    ...(status === "done"
+      ? { reason: opts.reason ?? "completed" }
+      : {}),
+    budget: new Budget({ maxTokens: 1000 }),
+    calls: new Map(),
+    trace: new Trace(),
+    errorLogs: [],
+    ...(opts.error !== undefined ? { error: opts.error } : {}),
+  };
+  const meta = {
+    startedAt: "2026-08-30T00:00:00.000Z",
+    ...(opts.completedAt !== undefined ? { completedAt: opts.completedAt } : {}),
+  };
+  return WorkflowRun.reconstruct(runId, makeSpec(opts.scriptName), state, meta);
+}
+
+/** mock RunStore：loadAll 返回预置 runs，save 可观察（可注入失败）。 */
+function makeStore(loaded: WorkflowRun[], opts: { failSaveFor?: string } = {}) {
+  const saves: WorkflowRun[] = [];
+  const store: RunStore = {
+    loadAll: vi.fn(async () => loaded),
+    save: vi.fn(async (run: WorkflowRun) => {
+      if (opts.failSaveFor !== undefined && run.runId === opts.failSaveFor) {
+        throw new Error("disk full");
+      }
+      saves.push(run);
+    }),
+    stateFilePath: vi.fn((runId: string) => `/fake/workflow-state/${runId}.jsonl`),
+  };
+  return { store, saves, saveSpy: store.save as ReturnType<typeof vi.fn> };
+}
+
+// ── 四步序列：failed 转换 + save + 注册 ─────────────────────
+
+describe("recoverCrashedRuns — 四步序列（loadAll→failed→save→evict）", () => {
+  it("running 残留转 done,failed：state.error=reason + save 落盘 + 注册进 runs Map", async () => {
+    const running = makeRun("wf-1", { status: "running" });
+    const done = makeRun("wf-2", { status: "done", reason: "completed", completedAt: "2026-08-30T01:00:00.000Z" });
+    const { store, saves } = makeStore([running, done]);
+    const runs = new Map<string, WorkflowRun>();
+
+    const result = await recoverCrashedRuns(store, runs, "Process killed (kill-9 or crash recovery)");
+
+    // 返回计数口径：loaded 含 done 历史快照，recovered 只计 running→failed 转换
+    expect(result.loaded).toBe(2);
+    expect(result.recovered).toBe(1);
+
+    // 步骤 2：running → done,failed（I2：done 必有 reason）
+    expect(running.state.status).toBe("done");
+    expect(running.state.reason).toBe("failed");
+    expect(running.state.error).toBe("Process killed (kill-9 or crash recovery)");
+    expect(running.meta.completedAt).toBeDefined();
+    // done run 原样（未被二次转换）
+    expect(done.state.status).toBe("done");
+    expect(done.state.reason).toBe("completed");
+    expect(done.state.error).toBeUndefined();
+    // 步骤 3：仅转换的 run 落盘（done 不重复 save）
+    expect(saves).toHaveLength(1);
+    expect(saves[0].runId).toBe("wf-1");
+    // 全部 loaded run（含 done）注册进 runs Map
+    expect(runs.size).toBe(2);
+    expect(runs.get("wf-1")).toBe(running);
+    expect(runs.get("wf-2")).toBe(done);
+  });
+
+  it("序列：hooks 回调在 transition 后、save 前；save 收到的已是终态 run", async () => {
+    const run = makeRun("wf-seq", { status: "running" });
+    const calls: string[] = [];
+    const statusesAtSave: Array<string | undefined> = [];
+    const store: RunStore = {
+      loadAll: vi.fn(async () => [run]),
+      save: vi.fn(async (r: WorkflowRun) => {
+        calls.push(`save:${r.runId}`);
+        statusesAtSave.push(r.state.status);
+      }),
+      stateFilePath: vi.fn(() => "/fake"),
+    };
+
+    await recoverCrashedRuns(store, new Map(), "crashed", {
+      onRunRecovered: (payload) => calls.push(`hook:${payload.id}`),
+    });
+
+    // hook 先于 save（对齐 pi：emit 在 transition 后、save 前）
+    expect(calls).toEqual(["hook:wf-seq", "save:wf-seq"]);
+    // save 收到的 run 已是 done,failed（终态落盘语义）
+    expect(statusesAtSave).toEqual(["done"]);
+  });
+
+  it("多个 running run 全部恢复；hooks 每个恰好一次、参数 {id, reason:'failed'}", async () => {
+    const r1 = makeRun("wf-a", { status: "running" });
+    const r2 = makeRun("wf-b", { status: "running" });
+    const { store, saves } = makeStore([r1, r2]);
+    const hookPayloads: Array<{ id: string; reason: string }> = [];
+
+    await recoverCrashedRuns(store, new Map(), "test crash", {
+      onRunRecovered: (payload) => hookPayloads.push(payload),
+    });
+
+    expect(r1.state.status).toBe("done");
+    expect(r2.state.status).toBe("done");
+    expect(saves).toHaveLength(2);
+    expect(hookPayloads).toEqual([
+      { id: "wf-a", reason: "failed" },
+      { id: "wf-b", reason: "failed" },
+    ]);
+  });
+
+  it("无 hooks（缺省）不炸，恢复语义不受影响", async () => {
+    const run = makeRun("wf-nohooks", { status: "running" });
+    const { store, saves } = makeStore([run]);
+
+    await recoverCrashedRuns(store, new Map(), "crashed");
+
+    expect(run.state.status).toBe("done");
+    expect(saves).toHaveLength(1);
+  });
+
+  it("单 run save 失败不中断其余 run（warn + 继续恢复）", async () => {
+    const r1 = makeRun("wf-fail", { status: "running" });
+    const r2 = makeRun("wf-ok", { status: "running" });
+    const { store, saves } = makeStore([r1, r2], { failSaveFor: "wf-fail" });
+
+    await expect(
+      recoverCrashedRuns(store, new Map(), "crashed"),
+    ).resolves.toEqual({ loaded: 2, recovered: 2 });
+
+    // 失败 run 状态机转换已发生（内存终态），仅落盘失败
+    expect(r1.state.status).toBe("done");
+    expect(r2.state.status).toBe("done");
+    expect(saves.map((r) => r.runId)).toEqual(["wf-ok"]);
+  });
+
+  it("onRunRecovered 同步 throw 被围栏捕获（warn 留痕），不中断其余 run 恢复", async () => {
+    // warn 断言经宿主 log 端口 spy 捕获（logger facade 每次调用动态解析宿主实现，
+    // 对齐 file-run-store.test.ts 的配置态隔离模式）
+    resetCoreForTests();
+    const logSpy = vi.fn();
+    configureCore({ dataRoot: () => "/fake", log: logSpy });
+
+    const r1 = makeRun("wf-hook-throw", { status: "running" });
+    const r2 = makeRun("wf-after-throw", { status: "running" });
+    const { store, saves } = makeStore([r1, r2]);
+    const seen: string[] = [];
+
+    await expect(
+      recoverCrashedRuns(store, new Map(), "crashed", {
+        onRunRecovered: (payload) => {
+          seen.push(payload.id);
+          if (payload.id === "wf-hook-throw") {
+            throw new Error("host notification channel down");
+          }
+        },
+      }),
+    ).resolves.toEqual({ loaded: 2, recovered: 2 });
+
+    // 循环未中断：后续 run 的 hook 仍被调用；两 run 状态机转换 + 落盘照常
+    //（含 throw 的 r1——围栏包住整个迭代的宿主事件点，save 不受牵连）
+    expect(seen).toEqual(["wf-hook-throw", "wf-after-throw"]);
+    expect(r1.state.status).toBe("done");
+    expect(r2.state.status).toBe("done");
+    expect(saves.map((r) => r.runId)).toEqual(["wf-hook-throw", "wf-after-throw"]);
+    // 围栏可见性：warn 已发出且定位到出错的 run
+    expect(
+      logSpy.mock.calls.some(
+        (c) => c[0] === "warn" && String(c[2]).includes("wf-hook-throw"),
+      ),
+    ).toBe(true);
+
+    resetCoreForTests();
+  });
+
+  it("loadAll 失败向上抛（fail-fast 策归宿主决定）", async () => {
+    const store: RunStore = {
+      loadAll: vi.fn(async () => {
+        throw new Error("store corrupted");
+      }),
+      save: vi.fn(async () => {}),
+      stateFilePath: vi.fn(() => "/fake"),
+    };
+
+    await expect(
+      recoverCrashedRuns(store, new Map(), "crashed"),
+    ).rejects.toThrow("store corrupted");
+  });
+});
+
+// ── 步骤 4：evict（done run 内存有界性） ────────────────────
+
+describe("recoverCrashedRuns — evict 步", () => {
+  it("done run 超 MAX_RETAINED_DONE_RUNS 时淘汰最旧；恢复 run（completedAt 最新）必保留", async () => {
+    // cap=20：造 22 个 done（completedAt 各异）+ 1 个 running（恢复后 completedAt=当下最新）
+    const loaded: WorkflowRun[] = [];
+    for (let i = 0; i < MAX_RETAINED_DONE_RUNS + 2; i++) {
+      loaded.push(
+        makeRun(`wf-old-${i}`, {
+          status: "done",
+          reason: "completed",
+          // ISO 字典序=时间序：i 越小越旧
+          completedAt: `2026-08-01T00:00:${String(i).padStart(2, "0")}.000Z`,
+        }),
+      );
+    }
+    const running = makeRun("wf-recovered", { status: "running" });
+    loaded.push(running);
+    const { store } = makeStore(loaded);
+    const runs = new Map<string, WorkflowRun>();
+
+    await recoverCrashedRuns(store, runs, "crashed");
+
+    // 23 个 done（22 + 1 恢复）裁到 K=20：最旧 3 个被淘汰
+    expect(runs.size).toBe(MAX_RETAINED_DONE_RUNS);
+    expect(runs.has("wf-old-0")).toBe(false);
+    expect(runs.has("wf-old-1")).toBe(false);
+    expect(runs.has("wf-old-2")).toBe(false);
+    expect(runs.has("wf-old-3")).toBe(true);
+    // 恢复转换的 run completedAt 为 transition 时刻（全局最新）必在保留端
+    expect(runs.has("wf-recovered")).toBe(true);
+    expect(runs.get("wf-recovered")).toBe(running);
+  });
+
+  it("未超 cap 时 evict 为 no-op（全部保留）", async () => {
+    const loaded = [
+      makeRun("wf-d1", { status: "done", reason: "completed", completedAt: "2026-08-01T00:00:00.000Z" }),
+      makeRun("wf-r1", { status: "running" }),
+    ];
+    const { store } = makeStore(loaded);
+    const runs = new Map<string, WorkflowRun>();
+
+    await recoverCrashedRuns(store, runs, "crashed");
+
+    expect(runs.size).toBe(2);
+  });
+});