niceeval 0.11.4-canary.21 → 0.12.0

package/src/report/slices/content.ts

@@ -1,11 +1,57 @@
 // 指标视图 TableContent 投影:compute *Data → Table 原语可直接消费的形状。
 
 import type { Cell, TableContent, TableContentRow } from "../definition/cell.ts";
-import type { DeltaData, StabilityMatrixCell, StabilityMatrixData } from "../model/types.ts";
+import type { DeltaData, StabilityMatrixCell, StabilityMatrixData, StaleConclusionReference } from "../model/types.ts";
 import type { AttemptLocator } from "../../record/locator.ts";
-import { localizedMessage } from "../model/locale.ts";
+import { DEFAULT_REPORT_LOCALE, localizedMessage, type ReportLocale } from "../model/locale.ts";
+import { formatMetricValue, formatPlainNumber, formatPoints, formatTimeDistance, verdictMark } from "../model/format.ts";
 
-export function deltaTableContent(data: DeltaData): TableContent {
+/**
+ * 带符号的美元/tokens 差值:复用 `formatMetricValue` 折终值(内建 unit 格式不分 locale,
+ * presentation.md「unit 决定格式」),只在外面补一个恒定的正负号——负值 `formatMetricValue`
+ * 已经自带 "-",这里只需要给非负值补 "+"。
+ */
+function signedMetricText(value: number, unit: "tokens" | "$"): string {
+  const sign = value > 0 ? "+" : "";
+  return `${sign}${formatMetricValue(value, unit)}`;
+}
+
+/** 带符号的挣分差值("+4 pts" / "-4 pts");`formatPointsSuffix` 恒加 "+" 号,不适用于可能为负的差值。 */
+function signedPointsText(value: number): string {
+  const sign = value > 0 ? "+" : value < 0 ? "-" : "";
+  const abs = Math.abs(value);
+  return `${sign}${formatPlainNumber(abs)} ${abs === 1 ? "pt" : "pts"}`;
+}
+
+/**
+ * 一格的判定读法(docs/feature/reports/show/compare.md):有数据时通过制只留判定符(`bare`,
+ * 历史执行再接相对时距)、计分制显示挣分;该条件缺席这道题时,记录里有过期结论参考才给
+ * `— <判定符> <时距>`(`—` 不被参考替换,它标记「这一格没有可聚合的结果」,参考只是附注),
+ * 没有参考就是纯 `notApplicable`。参考不进任何计数——它压根不出现在 `cells` 里,只在这一格
+ * 的显示上多一句附注。
+ */
+function conditionVerdictCell(
+  cell: DeltaData["rows"][number]["cells"][string] | undefined,
+  reference: StaleConclusionReference | undefined,
+  locale: ReportLocale,
+): Cell {
+  if (!cell) {
+    if (!reference) return { kind: "notApplicable" };
+    const mark = verdictMark(reference.verdict === "skipped" ? "skipped" : reference.verdict);
+    return { kind: "text", text: `— ${mark} ${formatTimeDistance(reference.staleSinceMs, locale)}` };
+  }
+  if (cell.evaluationKind === "points") {
+    return { kind: "text", text: cell.totalScore !== undefined ? formatPoints(cell.totalScore) : "—" };
+  }
+  return {
+    kind: "verdict",
+    verdict: cell.verdict,
+    bare: true,
+    ...(cell.historical && cell.staleSinceMs !== undefined ? { staleSinceMs: cell.staleSinceMs } : {}),
+  };
+}
+
+export function deltaTableContent(data: DeltaData, locale: ReportLocale = DEFAULT_REPORT_LOCALE): TableContent {
   const conditionColumns = data.conditions.flatMap((condition) => [
     { key: `${condition}:verdict` },
     { key: `${condition}:tokens` },
@@ -25,31 +71,24 @@ export function deltaTableContent(data: DeltaData): TableContent {
       };
       for (const condition of data.conditions) {
         const cell = row.cells[condition];
-        cells[`${condition}:verdict`] = cell
-          ? cell.evaluationKind === "points"
-            ? {
-                kind: "text",
-                text: cell.totalScore !== undefined ? String(cell.totalScore) : "—",
-              }
-            : { kind: "verdict", verdict: cell.verdict }
-          : { kind: "notApplicable" };
+        cells[`${condition}:verdict`] = conditionVerdictCell(cell, row.references?.[condition], locale);
         cells[`${condition}:tokens`] =
           cell?.totalTokens !== undefined
-            ? { kind: "text", text: String(cell.totalTokens) }
+            ? { kind: "metric", metric: { value: cell.totalTokens, unit: "tokens", basis: "eval", samples: 1, total: 1, refs: cell.attempts } }
             : { kind: "notApplicable" };
         cells[`${condition}:cost`] =
           cell?.totalCostUSD !== undefined
-            ? { kind: "text", text: String(cell.totalCostUSD) }
+            ? { kind: "metric", metric: { value: cell.totalCostUSD, unit: "$", basis: "eval", samples: 1, total: 1, refs: cell.attempts } }
             : { kind: "notApplicable" };
       }
       for (const condition of data.conditions.slice(1)) {
         const delta = row.delta?.[condition];
         cells[`${condition}:Δscore`] =
-          delta?.score !== undefined ? { kind: "text", text: String(delta.score) } : { kind: "notApplicable" };
+          delta?.score !== undefined ? { kind: "text", text: signedPointsText(delta.score) } : { kind: "notApplicable" };
         cells[`${condition}:Δtokens`] =
-          delta?.tokens !== undefined ? { kind: "text", text: String(delta.tokens) } : { kind: "notApplicable" };
+          delta?.tokens !== undefined ? { kind: "text", text: signedMetricText(delta.tokens, "tokens") } : { kind: "notApplicable" };
         cells[`${condition}:Δcost`] =
-          delta?.costUSD !== undefined ? { kind: "text", text: String(delta.costUSD) } : { kind: "notApplicable" };
+          delta?.costUSD !== undefined ? { kind: "text", text: signedMetricText(delta.costUSD, "$") } : { kind: "notApplicable" };
       }
       return { key: row.key, cells };
     }),

package/src/report/slices/delta-table.test.ts

@@ -1,16 +1,21 @@
 // cases: docs/engineering/testing/unit/reports.md
-// 「show 的范围 × 切片正交」deltaTableData 判据段。
+// 「show 的范围 × 切片正交」deltaTableData 判据段,与「对照矩阵的时效与过期结论参考」判据段。
 // deltaTableData(对照矩阵):配对身份是 eval id、翻转标记的数据面、逐行 Δ 为原始差值且缺失不为
 // 0、runs>1 的格内折叠(verdict 按默认报告口径、tokens/成本合计)、totals 与 pairedDelta 两个不同分母
 // 的口径(fixture 让两侧覆盖不同,抓出直接相减各自 totals 的错误算法)、混型分段、conditionsByFlag
-// 派生(单一可比性桶、0 候选空态、by 非 experiment 报错)。show/compare.md 示例数字复算作 fixture。
+// 派生(单一可比性桶、0 候选空态、by 非 experiment 报错)、historical 格的 staleSinceMs 与缺席格的
+// 过期结论参考(不进任何聚合)。show/compare.md 示例数字复算作 fixture。
 
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import type { EvalResult, ScoreEntry, Usage, Verdict } from "../../types.ts";
 import { completeEvidenceCoverage } from "../../assertions/coverage.ts";
 import type { AttemptHandle, Run } from "../../record/index.ts";
+import { encodeAttemptLocator } from "../../record/locator.ts";
 import { attemptHandleOf, scopeOf } from "../components/scope.harness.ts";
+import { makeSample } from "../../sample/index.ts";
 import { conditionsByFlag, deltaTableData } from "./compute.ts";
+import { deltaTableContent } from "./content.ts";
+import { formatCellText } from "../definition/cell.ts";
 import { validateDeltaData } from "./validate.ts";
 
 let seq = 0;
@@ -192,6 +197,136 @@ describe("deltaTableData", () => {
     expect(data.rows.find((r) => r.key === "q")!.cells["exp/cond"]!.historical).toBe(true);
   });
 
+  describe("对照矩阵的时效与过期结论参考(show/compare.md)", () => {
+    it("historical 格带 staleSinceMs;text 面经 formatTimeDistance 投影,不再是布尔叠加的 ↩ 符号", async () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date("2026-01-03T00:00:00.000Z"));
+      try {
+        // res() 默认 startedAt 是固定的 fixture 常量,时距断言需要显式指定 startedAt。
+        const older = snap("exp/cond", [res("q", "passed", { startedAt: "2026-01-01T00:00:00.000Z" })], {
+          runStartedAt: "2026-01-01T00:00:00.000Z",
+        });
+        const newer = snap("exp/cond", [res("q2", "passed")], { runStartedAt: "2026-01-02T00:00:00.000Z" });
+        const base = snap("exp/base", [res("q", "passed")]);
+        const data = await deltaTableData([base, older, newer], { by: "experiment", conditions: ["exp/base", "exp/cond"] });
+
+        const cell = data.rows.find((r) => r.key === "q")!.cells["exp/cond"]!;
+        expect(cell.historical).toBe(true);
+        expect(cell.staleSinceMs).toBe(2 * 86_400_000); // 2026-01-01 → 2026-01-03,恰好 2 天
+
+        const content = deltaTableContent(data, "en");
+        const row = content.rows.find((r) => r.key === "q")!;
+        const text = formatCellText(row.cells["exp/cond:verdict"], "en");
+        expect(text).not.toContain("↩");
+        expect(text).toBe("✓ 2d"); // 只留判定符 + 相对时距,不带判定词
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("同一格内折叠多条历史执行时取最旧一条的距今毫秒数", async () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date("2026-01-10T00:00:00.000Z"));
+      try {
+        const veryOld = snap("exp/cond", [res("q", "failed", { attempt: 0, startedAt: "2026-01-01T00:00:00.000Z" })], {
+          runStartedAt: "2026-01-01T00:00:00.000Z",
+        });
+        const lessOld = snap("exp/cond", [res("q", "passed", { attempt: 1, startedAt: "2026-01-08T00:00:00.000Z" })], {
+          runStartedAt: "2026-01-08T00:00:00.000Z",
+        });
+        const newest = snap("exp/cond", [res("other", "passed")], { runStartedAt: "2026-01-09T00:00:00.000Z" });
+        const base = snap("exp/base", [res("q", "passed")]);
+        const data = await deltaTableData([base, veryOld, lessOld, newest], { by: "experiment", conditions: ["exp/base", "exp/cond"] });
+
+        const cell = data.rows.find((r) => r.key === "q")!.cells["exp/cond"]!;
+        expect(cell.historical).toBe(true);
+        // 两条都历史执行(早于水位基准 newest);取更旧的 veryOld(2026-01-01)算距今,不是 lessOld(2026-01-08)。
+        expect(cell.staleSinceMs).toBe(9 * 86_400_000);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    /**
+     * 区分力场景:evalId "b" 只在 exp/base 一份旧 configHash 快照下跑过(与当前基准不可比),
+     * 且那次判定是 "passed"——比 exp/base 真实结果(仅 "a" failed)更「好看」。把它计入聚合的
+     * 错误实现会让 exp/base 的 totals 多算出一次 passed、commonEvalIds 多算出一道共同题。
+     */
+    function referenceScope(opts: { fresh?: boolean } = {}): { scope: import("../../record/index.ts").Sample; staleForB: Run } {
+      const current = snap("exp/base", [res("a", "failed")]);
+      current.configHash = "cfg-current";
+      const cond = snap("exp/cond", [res("a", "passed"), res("b", "passed")]);
+      const staleForB = snap("exp/base", [res("b", "passed", { startedAt: "2026-01-01T00:00:00.000Z" })]);
+      staleForB.configHash = "cfg-old";
+      const scope = makeSample(
+        "current",
+        [current, cond],
+        [...current.attempts, ...cond.attempts],
+        [],
+        [],
+        opts.fresh ?? false,
+        [...current.attempts, ...cond.attempts, ...staleForB.attempts],
+      );
+      return { scope, staleForB };
+    }
+
+    it("缺席格带过期结论参考:判定符、locator 与相对时距俱全,text 面按 — ✓ 12d 形态渲染", async () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date("2026-01-13T00:00:00.000Z"));
+      try {
+        const { scope, staleForB } = referenceScope();
+        const data = await deltaTableData(scope, { by: "experiment", conditions: ["exp/base", "exp/cond"] });
+
+        const rowB = data.rows.find((r) => r.key === "b")!;
+        expect(rowB.cells["exp/base"]).toBeUndefined();
+        const reference = rowB.references?.["exp/base"];
+        expect(reference).toBeDefined();
+        expect(reference!.verdict).toBe("passed");
+        expect(reference!.locator).toBe(encodeAttemptLocator({ runId: staleForB.runId, evalId: "b", attempt: 0 }));
+        expect(reference!.staleSinceMs).toBe(12 * 86_400_000);
+
+        const content = deltaTableContent(data, "en");
+        const text = formatCellText(content.rows.find((r) => r.key === "b")!.cells["exp/base:verdict"], "en");
+        expect(text).toBe("— ✓ 12d");
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("参考不进 汇总、Δ 与配对覆盖三处聚合的任何一个数", async () => {
+      const { scope } = referenceScope();
+      const data = await deltaTableData(scope, { by: "experiment", conditions: ["exp/base", "exp/cond"] });
+
+      // 汇总:exp/base 只有 "a" 一道真实结果(failed),分母是 1、passed 是 0——参考的 "passed" 没被计入
+      // (错误实现会把它算成 passed:1、denominator:2)。
+      expect(data.totals["exp/base"]).toMatchObject({ passed: 0, denominator: 1 });
+      // 配对覆盖:共同题只有 "a"，"b" 因为 exp/base 侧没有真实结果而不算共同。
+      expect(data.pairedDelta["exp/cond"]!.commonEvalIds).toEqual(["a"]);
+      // Δ:"b" 这一行任一侧缺数据本就不产出 delta,参考不能让它凭空出现。
+      expect(data.rows.find((r) => r.key === "b")!.delta).toBeUndefined();
+    });
+
+    it("sample.fresh 为 true 时缺席格不带过期结论参考", async () => {
+      const { scope } = referenceScope({ fresh: true });
+      const data = await deltaTableData(scope, { by: "experiment", conditions: ["exp/base", "exp/cond"] });
+      expect(data.rows.find((r) => r.key === "b")!.references).toBeUndefined();
+    });
+
+    it("deltaTableContent 的文本形态:计分制显示挣分、tokens/成本经 formatMetricValue 折算,不落原始数字字符串", async () => {
+      const base = snap("exp/base", [res("q", "passed", { usage: usage(512_300, 0.71) })]);
+      const cond = snap("exp/cond", [res("q", "passed", { usage: usage(305_100, 0.44) })]);
+      const data = await deltaTableData(scopeOf([base, cond]), { by: "experiment", conditions: ["exp/base", "exp/cond"] });
+      const content = deltaTableContent(data, "en");
+      const row = content.rows.find((r) => r.key === "q")!;
+
+      expect(formatCellText(row.cells["exp/base:verdict"], "en")).toBe("✓"); // 通过制只留判定符,不带判定词
+      expect(formatCellText(row.cells["exp/base:tokens"], "en")).toBe("512.3k tokens");
+      expect(formatCellText(row.cells["exp/base:cost"], "en")).toBe("$0.71");
+      expect(formatCellText(row.cells["exp/cond:Δtokens"], "en")).toBe("-207.2k tokens");
+      expect(formatCellText(row.cells["exp/cond:Δcost"], "en")).toBe("-$0.27");
+    });
+  });
+
   it("空 rows 零输出;conditions 长度 < 2 或含重复值按完整用户反馈报错", async () => {
     const s = snap("exp/only", []);
     await expect(deltaTableData(scopeOf([s]), { by: "experiment", conditions: ["exp/only"] as unknown as [string, string] })).rejects.toThrow(

package/src/report/slices/validate.test.ts

@@ -173,6 +173,35 @@ describe("validateDeltaData", () => {
     const bad = { ...valid, pairedDelta: { "agents-md": { commonEvalIds: "coding/a" } } };
     expect(validateDeltaData(bad)).toMatch(/"pairedDelta\.agents-md\.commonEvalIds"/);
   });
+
+  it("cells.<condition>.staleSinceMs 非数字报错;rows[i].references 缺 verdict 定位到该条件", () => {
+    const badStale = {
+      ...valid,
+      rows: [{ ...valid.rows[0], cells: { ...valid.rows[0].cells, baseline: { ...validDeltaCell, staleSinceMs: "2d" } } }],
+    };
+    expect(validateDeltaData(badStale)).toMatch(/"rows\[0\]\.cells\.baseline\.staleSinceMs"/);
+
+    const badReference = {
+      ...valid,
+      rows: [{ ...valid.rows[0], references: { baseline: { locator: "@1abcdef2", staleSinceMs: 1000 } } }],
+    };
+    expect(validateDeltaData(badReference)).toMatch(/"rows\[0\]\.references\.baseline\.verdict"/);
+  });
+
+  it("rows[i].references 合规时通过", () => {
+    const withReference = {
+      ...valid,
+      rows: [
+        {
+          key: "coding/b",
+          flipped: false,
+          cells: {},
+          references: { baseline: { locator: "@1abcdef2", verdict: "passed", staleSinceMs: 1_036_800_000 } },
+        },
+      ],
+    };
+    expect(validateDeltaData(withReference)).toBeNull();
+  });
 });
 
 describe("validateStabilityMatrixData", () => {

package/src/report/slices/validate.ts

@@ -91,6 +91,15 @@ function deltaCellProblem(value: unknown, path: string): string | null {
   if (value.totalTokens !== undefined && typeof value.totalTokens !== "number") return `"${path}.totalTokens" must be a number`;
   if (value.totalCostUSD !== undefined && typeof value.totalCostUSD !== "number") return `"${path}.totalCostUSD" must be a number`;
   if (typeof value.historical !== "boolean") return `"${path}.historical" must be a boolean`;
+  if (value.staleSinceMs !== undefined && typeof value.staleSinceMs !== "number") return `"${path}.staleSinceMs" must be a number`;
+  return null;
+}
+/** 缺席格的过期结论参考(与 experiment-table 占位行同一份 StaleConclusionReference 形状)。 */
+function staleReferenceProblem(value: unknown, path: string): string | null {
+  if (!isObject(value)) return `"${path}" must be an object { locator, verdict, staleSinceMs }`;
+  if (typeof value.locator !== "string") return `"${path}.locator" must be a string`;
+  if (typeof value.verdict !== "string") return `"${path}.verdict" must be a string`;
+  if (typeof value.staleSinceMs !== "number") return `"${path}.staleSinceMs" must be a number`;
   return null;
 }
 function deltaTotalsProblem(value: unknown, path: string): string | null {
@@ -148,6 +157,13 @@ export const validateDeltaData: Validator = (data) => {
         if (d.costUSD !== undefined && typeof d.costUSD !== "number") return `"${path}.delta.${condition}.costUSD" must be a number`;
       }
     }
+    if (row.references !== undefined) {
+      if (!isObject(row.references)) return `"${path}.references" must be an object`;
+      for (const [condition, reference] of Object.entries(row.references)) {
+        const problem = staleReferenceProblem(reference, `${path}.references.${condition}`);
+        if (problem !== null) return problem;
+      }
+    }
     return null;
   });
   if (rowsProblem !== null) return rowsProblem;

package/src/runner/gate-lease.test.ts

@@ -24,10 +24,33 @@ import {
 // 在任何测试调用 vi.useFakeTimers() 之前捕获真实的 setTimeout:vi.advanceTimersByTimeAsync 只
 // 推进假时钟触发到期的定时器回调,不等待回调里新发起的真实 fs I/O 真正 settle(踩坑同
 // lock.test.ts 顶部注释)。用真实 setTimeout 排一次宏任务放行真实 I/O。
+// CI 并行时 fs 线程池会饿,flush 要给够真实 wall-clock。
 const realSetTimeout = globalThis.setTimeout;
 function realDelay(ms: number): Promise<void> {
   return new Promise((resolve) => realSetTimeout(resolve, ms));
 }
+async function flushRealIo(rounds = 50, ms = 10): Promise<void> {
+  for (let i = 0; i < rounds; i += 1) {
+    await realDelay(ms);
+  }
+}
+async function stepAndFlush(advanceMs: number): Promise<void> {
+  await vi.advanceTimersByTimeAsync(advanceMs);
+  await flushRealIo();
+}
+async function stepUntil(
+  advanceMs: number,
+  predicate: () => boolean,
+  opts: { rounds?: number; ms?: number } = {},
+): Promise<void> {
+  await vi.advanceTimersByTimeAsync(advanceMs);
+  const rounds = opts.rounds ?? 100;
+  const ms = opts.ms ?? 20;
+  for (let i = 0; i < rounds; i += 1) {
+    if (predicate()) return;
+    await realDelay(ms);
+  }
+}
 
 const EXP = "compare/bub-e2b";
 
@@ -355,28 +378,25 @@ describe("acquireGateSlot: 等待路径", () => {
           },
         },
       );
-      resultPromise.then(() => {
-        resolved = true;
-      });
+      // 吞掉提前失败时的 reject,避免 afterEach 清目录后 in-flight 轮询变成 unhandled rejection。
+      resultPromise.then(
+        () => {
+          resolved = true;
+        },
+        () => {},
+      );
 
       const holders = await firstWaitStartPromise; // 纯微任务同步点,不依赖假时钟
       expect(holders).toHaveLength(1);
       expect(holders[0]!.pid).toBe(1);
       expect(waitStartCalls).toBe(1);
 
-      async function stepAndFlush(ms: number): Promise<void> {
-        await vi.advanceTimersByTimeAsync(ms);
-        for (let i = 0; i < 10; i += 1) {
-          await realDelay(5);
-        }
-      }
-
       await stepAndFlush(pollIntervalMs); // 累计 25s,仍在阈值内:继续等,onWaitStart 不重复触发
       expect(resolved).toBe(false);
       expect(waitStartCalls).toBe(1);
       expect(waitHolders).toHaveLength(1);
 
-      await stepAndFlush(pollIntervalMs); // 累计 50s,越过 30s 阈值:接管取位
+      await stepUntil(pollIntervalMs, () => resolved); // 累计 50s,越过 30s 阈值:接管取位
       expect(resolved).toBe(true);
 
       const result = await resultPromise;
@@ -486,12 +506,14 @@ describe("acquireGateSlot / claim.release: 释放", () => {
 });
 
 describe("acquireGateSlot / claim.release: 释放与在飞心跳的竞态", () => {
-  it("回归 memory/lock-heartbeat-resurrects-released-lock.md:释放时若有一次心跳已读完记录、还没写回,写回不会把已删的租约文件复活", async () => {
+  it(
+    "回归 memory/lock-heartbeat-resurrects-released-lock.md:释放时若有一次心跳已读完记录、还没写回,写回不会把已删的租约文件复活",
+    async () => {
     // 与用例锁(lock.ts)同一条竞态:心跳的「读—改—写」与 release() 的 `rm` 之间原本没有
     // 互斥。极短心跳周期(1ms)配合真实定时器重复多轮,让每轮释放大概率撞上一次在飞的
     // 心跳,能稳定复现(台账记录:修复前 40 次释放 39 次复活)。这里断言修复后不管重复
     // 多少轮,释放后租约目录始终为空。每轮用不同的 slot(经不同 experimentId)避免相邻
-    // 轮次互相抢位排队,纯粹考验单条持有者的释放-心跳竞态。
+    // 轮次互相抢位排队,纯粹考验单条持有者的释放-心跳竞态。CI 并行时 40 轮可能超过默认 5s。
     const root = await makeRoot();
 
     for (let i = 0; i < 40; i += 1) {
@@ -508,7 +530,9 @@ describe("acquireGateSlot / claim.release: 释放与在飞心跳的竞态", () =
     }
 
     expect(await leaseFileCount(root)).toBe(0);
-  });
+  },
+  30_000,
+  );
 });
 
 describe("drainHeldGateLeases / pendingHeldGateLeaseCount", () => {

package/src/runner/lock.test.ts

@@ -25,10 +25,35 @@ import {
 // 推进假时钟触发到期的定时器回调,不等待回调里新发起的真实 fs I/O(线程池完成通过事件循环的
 // poll 阶段回来,micro-task 级的 process.nextTick 不足以放行)真正 settle。用真实 setTimeout
 // 排一次宏任务,才能确定性地让真实 I/O 有机会在下一步推进前落地。
+// CI 上 unit 项目并行时 fs 线程池会饿,flush 要给够真实 wall-clock,不能只靠 10×5ms。
 const realSetTimeout = globalThis.setTimeout;
 function realDelay(ms: number): Promise<void> {
   return new Promise((resolve) => realSetTimeout(resolve, ms));
 }
+/** 推进假时钟后放行真实 fs I/O;rounds/ms 按 CI 并行饿载调高。 */
+async function flushRealIo(rounds = 50, ms = 10): Promise<void> {
+  for (let i = 0; i < rounds; i += 1) {
+    await realDelay(ms);
+  }
+}
+async function stepAndFlush(advanceMs: number): Promise<void> {
+  await vi.advanceTimersByTimeAsync(advanceMs);
+  await flushRealIo();
+}
+/** 推进一轮后等谓词成立(仍用真实时间轮询),避免「I/O 晚几拍」的假失败。 */
+async function stepUntil(
+  advanceMs: number,
+  predicate: () => boolean,
+  opts: { rounds?: number; ms?: number } = {},
+): Promise<void> {
+  await vi.advanceTimersByTimeAsync(advanceMs);
+  const rounds = opts.rounds ?? 100;
+  const ms = opts.ms ?? 20;
+  for (let i = 0; i < rounds; i += 1) {
+    if (predicate()) return;
+    await realDelay(ms);
+  }
+}
 
 let roots: string[] = [];
 async function makeRoot(): Promise<string> {
@@ -310,31 +335,26 @@ describe("acquireCaseLock: 等待路径", () => {
           },
         },
       );
-      resultPromise.then(() => {
-        resolved = true;
-      });
+      // 吞掉提前失败时的 reject,避免 afterEach 清目录后 in-flight 轮询变成 unhandled rejection。
+      resultPromise.then(
+        () => {
+          resolved = true;
+        },
+        () => {},
+      );
 
       const holder = await firstWaitStartPromise; // 纯微任务同步点,不依赖假时钟
       expect(holder.pid).toBe(1);
       expect(waitHolderPid).toBe(1);
       expect(waitStartCalls).toBe(1);
 
-      async function stepAndFlush(ms: number): Promise<void> {
-        await vi.advanceTimersByTimeAsync(ms);
-        // 真实 setTimeout(0) 排宏任务,给真实 fs I/O 的线程池完成回调机会真正落地;多轮小
-        // 步比一次性大延时更快、也更贴近"刚好够用"的量。
-        for (let i = 0; i < 10; i += 1) {
-          await realDelay(5);
-        }
-      }
-
       // 第一步推进 25s:仍在 30s 阈值内,应继续等待,onWaitStart 不重复触发
       await stepAndFlush(pollIntervalMs);
       expect(resolved).toBe(false);
       expect(waitStartCalls).toBe(1);
 
       // 第二步再推进 25s(累计 50s,越过 30s 阈值):应该取得并标记为接管
-      await stepAndFlush(pollIntervalMs);
+      await stepUntil(pollIntervalMs, () => resolved);
       expect(resolved).toBe(true);
 
       const result = await resultPromise;
@@ -425,12 +445,14 @@ describe("acquireCaseLock / claim.release: 释放", () => {
 });
 
 describe("acquireCaseLock / claim.release: 释放与在飞心跳的竞态", () => {
-  it("回归 memory/lock-heartbeat-resurrects-released-lock.md:释放时若有一次心跳已读完记录、还没写回,写回不会把已删的锁文件复活", async () => {
+  it(
+    "回归 memory/lock-heartbeat-resurrects-released-lock.md:释放时若有一次心跳已读完记录、还没写回,写回不会把已删的锁文件复活",
+    async () => {
     // 心跳的「读—改—写」与 release() 的 `rm` 之间原本没有互斥:心跳读完记录、还没来得及
     // writeEntryFile 写回时,release() 先把文件 rm 掉,随后心跳的写回会把原路径重新创建
     // 出来。极短心跳周期(1ms)让每次释放大概率撞上一次在飞的心跳,配合真实定时器重复
     // 多轮,能稳定复现(台账记录:修复前 40 次释放 39 次复活)。这里断言修复后不管重复
-    // 多少轮,释放后锁目录始终为空。
+    // 多少轮,释放后锁目录始终为空。CI 并行时 40 轮真实 I/O 可能超过默认 5s。
     const root = await makeRoot();
     const niceevalRoot = join(root, ".niceeval");
 
@@ -448,7 +470,9 @@ describe("acquireCaseLock / claim.release: 释放与在飞心跳的竞态", () =
     }
 
     expect(await readdir(locksDirOf(niceevalRoot))).toEqual([]);
-  });
+  },
+  30_000,
+  );
 });
 
 describe("drainHeldCaseLocks / pendingHeldCaseLockCount", () => {

package/src/sandbox/compose.ts

@@ -25,7 +25,6 @@ import type {
   SandboxResourceGroup,
   ServiceController,
 } from "./case-types.ts";
-import { classifyProvisionError, DockerSandbox } from "./docker.ts";
 import {
   computeBuildKey,
   digestOf,
@@ -866,6 +865,9 @@ export async function materializeDockerComposeProviderCase(
       throw abortError(opts.ctx.signal);
     }
 
+    // dockerode 是 optional peer：compose 实现在 materialize 热路径才加载 docker.ts。
+    const { classifyProvisionError, DockerSandbox } = await import("./docker.ts");
+
     // 构建:协调器 locator 命中时仍跑一次 compose build——BuildKit cache 很快,
     // 且把 BuildKey tag 对齐回本 eval 的 image: 插值名(避免多题共用 provider env 时串镜像)。
     const buildServices = collection.inspection.services.filter((s) => s.build !== undefined).map((s) => s.name);

package/src/sandbox/dockerfile-build.ts

@@ -5,7 +5,6 @@
 import { spawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { isAbsolute, resolve as resolvePath } from "node:path";
-import { Template } from "e2b";
 import type { SandboxBuildExecutionContext, SandboxBuildProvider, SandboxBuildWork } from "./build-coordinator.ts";
 import { detectDockerBuildPlatform, normalizeBuildPlatform } from "./compose.ts";
 import { computeCaseKey, type BuildKey, type CaseKey } from "./identity.ts";
@@ -202,6 +201,8 @@ async function defaultRunDockerBuild(
 }
 
 async function defaultE2BTemplateExists(name: string, signal: AbortSignal): Promise<boolean> {
+  // e2b 是 optional peer；仅 E2B Dockerfile 构建路径加载。
+  const { Template } = await import("e2b");
   return await Template.exists(name, { signal });
 }
 
@@ -216,6 +217,8 @@ async function defaultBuildE2BTemplate(
   if (details.target !== undefined) {
     throw new Error("E2B Dockerfile builds do not support a target stage; make the desired stage the final stage");
   }
+  // e2b 是 optional peer；仅 E2B Dockerfile 构建路径加载。
+  const { Template } = await import("e2b");
   const ignore = await dockerIgnorePatterns(details.contextDir);
   const template = Template({
     fileContextPath: details.contextDir,

package/src/sandbox/runtime.ts

@@ -1,7 +1,6 @@
 // ProviderModule 的唯一运行入口：core 只调用 plan 私绑的闭包，不解释 adapter 名或 JSON runtime input。
 
 import { randomUUID } from "node:crypto";
-import Docker from "dockerode";
 import { Data, Effect, Option, type Scope } from "effect";
 import type { ProvisionSlot } from "./retry.ts";
 import { withProvisionRetry } from "./retry.ts";
@@ -366,6 +365,8 @@ export function materializeDockerfileProviderPlan(
 
 async function defaultDockerImageExists(locator: string): Promise<boolean> {
   try {
+    // dockerode 是 optional peer；只在 Dockerfile Agent 缓存路径真查镜像时加载。
+    const { default: Docker } = await import("dockerode");
     await new Docker().getImage(locator).inspect();
     return true;
   } catch {
@@ -452,6 +453,8 @@ const liveDockerfileAgentImageProvisionServices: DockerfileAgentImageProvisionSe
     return { operations: sandbox, sandboxId: sandbox.sandboxId, stop: () => sandbox.stop() };
   },
   commit: async (sandboxId: string, derivedLocator: string) => {
+    // dockerode 是 optional peer；commit 派生镜像时才加载（与 keep/orphans 同模式）。
+    const { default: Docker } = await import("dockerode");
     await new Docker().getContainer(sandboxId).commit(dockerCommitReference(derivedLocator));
   },
 });