niceeval 0.10.3-canary.7 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.10.3-canary.7",
+  "version": "0.11.0",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -93,6 +93,8 @@
     "autoevals": "0.0.132",
     "effect": "^3.21.4",
     "mermaid": "^11.16.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "tar-stream": "^3.1.7",
     "tsx": "^4.19.2"
   },
@@ -121,8 +123,6 @@
     "mixpanel-browser": "^2.80.0",
     "next": "16.2.10",
     "prism-react-renderer": "^2.4.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
     "react-grab": "^0.1.48",
     "shiki": "^4.3.0",
     "tailwind-merge": "^3.6.0",
@@ -139,9 +139,7 @@
     "ai": ">=5.0.0",
     "braintrust": ">=0.0.150",
     "dockerode": ">=4.0.0",
-    "e2b": ">=2.0.0",
-    "react": ">=18",
-    "react-dom": ">=18"
+    "e2b": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/otel": {
@@ -167,12 +165,6 @@
     },
     "e2b": {
       "optional": true
-    },
-    "react": {
-      "optional": true
-    },
-    "react-dom": {
-      "optional": true
     }
   },
   "scripts": {

package/src/agents/ai-sdk.test.ts

@@ -0,0 +1,26 @@
+// cases: docs/engineering/testing/unit/results.md
+// 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:AI SDK 的 inputTokens 是含缓存明细的
+// 输入总量,落桶前扣掉在场的 cacheRead / cacheWrite 明细。
+// bug: memory/estimatecost-openai-inclusive-cache-double-billed.md
+
+import { describe, expect, it } from "vitest";
+
+import { fromAiSdk } from "./ai-sdk.ts";
+
+describe("fromAiSdk usage 归一(含明细口径)", () => {
+  it("v5 形状:cachedInputTokens 从 inputTokens 里扣出", () => {
+    const turn = fromAiSdk({
+      text: "ok",
+      usage: { inputTokens: 1000, outputTokens: 20, cachedInputTokens: 900 },
+    });
+    expect(turn.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 900, outputTokens: 20 });
+  });
+
+  it("v7 形状:inputTokenDetails 的 cacheRead 与 cacheWrite 都从总量里扣出", () => {
+    const turn = fromAiSdk({
+      text: "ok",
+      usage: { inputTokens: 1000, outputTokens: 20, inputTokenDetails: { cacheReadTokens: 800, cacheWriteTokens: 100 } },
+    });
+    expect(turn.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 800, cacheCreationTokens: 100 });
+  });
+});

package/src/agents/ai-sdk.ts

@@ -327,13 +327,16 @@ function unwrapToolOutput(output: unknown): { output?: JsonValue; status: "compl
 function readUsage(result: AiSdkResultLike, stepCount: number): Usage | undefined {
   const u = result.totalUsage ?? result.usage;
   if (!u) return undefined;
-  const inputTokens = num(u.inputTokens) ?? num(u.promptTokens) ?? 0;
+  const rawInput = num(u.inputTokens) ?? num(u.promptTokens) ?? 0;
   const outputTokens = num(u.outputTokens) ?? num(u.completionTokens) ?? 0;
-  if (inputTokens === 0 && outputTokens === 0) return undefined;
+  if (rawInput === 0 && outputTokens === 0) return undefined;
+  const cacheRead = num(u.cachedInputTokens) ?? num(u.inputTokenDetails?.cacheReadTokens) ?? 0;
+  const cacheCreation = num(u.inputTokenDetails?.cacheWriteTokens) ?? 0;
+  // AI SDK 的 inputTokens 是含缓存明细的输入总量,落互斥桶前扣掉在场的明细
+  // (docs/feature/adapters/sdk/ai-sdk/cost.md)
+  const inputTokens = Math.max(0, rawInput - cacheRead - cacheCreation);
   const usage: Usage = { inputTokens, outputTokens, requests: Math.max(stepCount, 1) };
-  const cacheRead = num(u.cachedInputTokens) ?? num(u.inputTokenDetails?.cacheReadTokens);
   if (cacheRead) usage.cacheReadTokens = cacheRead;
-  const cacheCreation = num(u.inputTokenDetails?.cacheWriteTokens);
   if (cacheCreation) usage.cacheCreationTokens = cacheCreation;
   const reasoning = num(u.reasoningTokens);
   if (reasoning) usage.reasoningTokens = reasoning;

package/src/agents/index.ts

@@ -9,11 +9,13 @@ export type { Shared } from "./shared.ts";
 export { completeCoverage } from "../scoring/coverage.ts";
 export type { CoverageStatus, CoverageDeclaration, EvidenceCoverage } from "../types.ts";
 
-// turn 级瞬时错误分类:`Agent.classifyTurnError` 认的输入/输出形状 + 摘要取值器
-// (与 turn-failed 报错文案同源)。分类判据、分类链与重试执行体见
+// 执行失败分类:`Agent.classifyTurnError` 认的输入/输出形状 + 摘要取值器(与 turn-failed
+// 报错文案同源)。两轴词表(FailureClass / FailureScope)与包根导出的是同一个形状——adapter
+// 作者与 eval 作者各自的入口拿到同一份类型。判据、分类链与重试执行体见
 // docs/feature/error-classification/architecture.md。
 export { turnErrorText } from "../context/turn-errors.ts";
-export type { TurnErrorClass, TurnErrorClassifier, TurnFailure } from "../context/turn-errors.ts";
+export type { TurnErrorClassifier, TurnFailure } from "../context/turn-errors.ts";
+export type { FailureClass, FailureScope } from "../shared/failure-class.ts";
 
 // span → canonical GenAI 归一(只服务瀑布图,不喂断言)。私有埋点写自己的 spanMapper 时用:
 // tagSpan 把判定写回 span(原属性只增不改),heuristicTag 是通用兜底判定;mapCodexSpans 是

package/src/agents/langgraph.test.ts

@@ -0,0 +1,30 @@
+// cases: docs/engineering/testing/unit/results.md
+// 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:LangChain usage_metadata 的 input_tokens
+// 是含缓存读写的输入总量,落桶前扣掉 input_token_details 的 cache_read / cache_creation。
+// bug: memory/estimatecost-openai-inclusive-cache-double-billed.md
+
+import { describe, expect, it } from "vitest";
+
+import { fromLangGraphEvents } from "./langgraph.ts";
+
+describe("fromLangGraphEvents usage 归一(含明细口径)", () => {
+  it("cache_read 与 cache_creation 都从 input_tokens 里扣出", () => {
+    const stream = fromLangGraphEvents();
+    stream.add({
+      channel: "messages",
+      event: "finish",
+      data: {
+        message: {
+          role: "assistant",
+          content: "ok",
+          usage_metadata: {
+            input_tokens: 1000,
+            output_tokens: 20,
+            input_token_details: { cache_read: 800, cache_creation: 100 },
+          },
+        },
+      },
+    });
+    expect(stream.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 800, cacheCreationTokens: 100, outputTokens: 20 });
+  });
+});

package/src/agents/langgraph.ts

@@ -152,12 +152,15 @@ export function fromLangGraphEvents(): LangGraphStream {
       }
       return 0;
     };
-    const input = num("input_tokens", "inputTokens");
+    const rawInput = num("input_tokens", "inputTokens");
     const output = num("output_tokens", "outputTokens");
-    if (input === 0 && output === 0) return;
+    if (rawInput === 0 && output === 0) return;
     const details = isRecord(raw.input_token_details) ? raw.input_token_details : undefined;
     const cacheRead = typeof details?.cache_read === "number" ? details.cache_read : 0;
     const cacheCreation = typeof details?.cache_creation === "number" ? details.cache_creation : 0;
+    // LangChain usage_metadata 的 input_tokens 是含缓存读写的输入总量,落互斥桶前扣掉明细
+    // (docs/feature/adapters/sdk/langgraph/cost.md)
+    const input = Math.max(0, rawInput - cacheRead - cacheCreation);
     // LangChain UsageMetadata.output_token_details.reasoning:推理模型经 LangGraph 透传时带回。
     const outputDetails = isRecord(raw.output_token_details) ? raw.output_token_details : undefined;
     const reasoning = typeof outputDetails?.reasoning === "number" ? outputDetails.reasoning : 0;

package/src/agents/openai-compat.test.ts

@@ -0,0 +1,35 @@
+// cases: docs/engineering/testing/unit/results.md
+// 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:Chat Completions / Responses 两种形状的
+// cached_tokens 都是输入总量的子集,落 inputTokens 前扣掉;缺 cached 明细时总量原样保留。
+// bug: memory/estimatecost-openai-inclusive-cache-double-billed.md
+
+import { describe, expect, it } from "vitest";
+
+import { fromChatCompletion, fromResponses } from "./openai-compat.ts";
+
+describe("openai-compat usage 归一(OpenAI 口径)", () => {
+  it("Chat Completions:prompt_tokens 扣掉 prompt_tokens_details.cached_tokens", () => {
+    const turn = fromChatCompletion({
+      choices: [{ message: { role: "assistant", content: "ok" } }],
+      usage: { prompt_tokens: 1000, completion_tokens: 20, prompt_tokens_details: { cached_tokens: 900 } },
+    });
+    expect(turn.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 900, outputTokens: 20 });
+  });
+
+  it("Responses:input_tokens 扣掉 input_tokens_details.cached_tokens", () => {
+    const turn = fromResponses({
+      output: [{ type: "message", role: "assistant", content: [{ type: "output_text", text: "ok" }] }],
+      usage: { input_tokens: 500, output_tokens: 10, input_tokens_details: { cached_tokens: 200 } },
+    });
+    expect(turn.usage).toMatchObject({ inputTokens: 300, cacheReadTokens: 200, outputTokens: 10 });
+  });
+
+  it("缺 cached 明细时输入总量原样保留,不虚构扣减,cache 桶省略", () => {
+    const turn = fromChatCompletion({
+      choices: [{ message: { role: "assistant", content: "ok" } }],
+      usage: { prompt_tokens: 1000, completion_tokens: 20 },
+    });
+    expect(turn.usage?.inputTokens).toBe(1000);
+    expect(turn.usage?.cacheReadTokens).toBeUndefined();
+  });
+});

package/src/agents/openai-compat.ts

@@ -50,8 +50,14 @@ export interface ChatCompletionLike {
 
 function chatCompletionUsage(usage: ChatCompletionUsageLike | undefined): Usage | undefined {
   if (!usage) return undefined;
-  const u: Usage = { inputTokens: usage.prompt_tokens ?? 0, outputTokens: usage.completion_tokens ?? 0 };
-  if (usage.prompt_tokens_details?.cached_tokens) u.cacheReadTokens = usage.prompt_tokens_details.cached_tokens;
+  // prompt_tokens 含缓存命中,cached_tokens 是其子集;落互斥桶前扣掉
+  // (docs/feature/adapters/sdk/openai-compat/cost.md)
+  const cached = usage.prompt_tokens_details?.cached_tokens ?? 0;
+  const u: Usage = {
+    inputTokens: Math.max(0, (usage.prompt_tokens ?? 0) - cached),
+    outputTokens: usage.completion_tokens ?? 0,
+  };
+  if (cached) u.cacheReadTokens = cached;
   if (usage.completion_tokens_details?.reasoning_tokens) u.reasoningTokens = usage.completion_tokens_details.reasoning_tokens;
   return u;
 }
@@ -125,8 +131,14 @@ export interface ResponseLike {
 
 function responsesUsage(usage: ResponseUsageLike | undefined): Usage | undefined {
   if (!usage) return undefined;
-  const u: Usage = { inputTokens: usage.input_tokens ?? 0, outputTokens: usage.output_tokens ?? 0 };
-  if (usage.input_tokens_details?.cached_tokens) u.cacheReadTokens = usage.input_tokens_details.cached_tokens;
+  // input_tokens 含缓存命中,cached_tokens 是其子集;落互斥桶前扣掉
+  // (docs/feature/adapters/sdk/openai-compat/cost.md)
+  const cached = usage.input_tokens_details?.cached_tokens ?? 0;
+  const u: Usage = {
+    inputTokens: Math.max(0, (usage.input_tokens ?? 0) - cached),
+    outputTokens: usage.output_tokens ?? 0,
+  };
+  if (cached) u.cacheReadTokens = cached;
   if (usage.output_tokens_details?.reasoning_tokens) u.reasoningTokens = usage.output_tokens_details.reasoning_tokens;
   return u;
 }

package/src/agents/sdk-streams.test.ts

@@ -0,0 +1,66 @@
+// cases: docs/engineering/testing/unit/results.md
+// 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:codex(OpenAI 口径,cached ⊂ input)扣减、
+// Anthropic / pi(互斥口径)如实转发。fixture 数值刻意让「扣与不扣」结果可区分。
+// bug: memory/estimatecost-openai-inclusive-cache-double-billed.md
+
+import { describe, expect, it } from "vitest";
+
+import { fromClaudeSdkMessages, fromCodexThreadEvents, fromPiAgentEvents } from "./sdk-streams.ts";
+
+describe("fromCodexThreadEvents usage 归一(OpenAI 口径)", () => {
+  it("cached_input_tokens 是 input_tokens 子集:落 inputTokens 前扣掉,cache 单独成桶", () => {
+    const stream = fromCodexThreadEvents();
+    stream.add({ type: "turn.completed", usage: { input_tokens: 1000, cached_input_tokens: 900, output_tokens: 50 } });
+    expect(stream.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 900, outputTokens: 50, requests: 1 });
+  });
+
+  it("逐轮累加在扣减之后进行,总量仍互斥", () => {
+    const stream = fromCodexThreadEvents();
+    stream.add({ type: "turn.completed", usage: { input_tokens: 1000, cached_input_tokens: 900, output_tokens: 50 } });
+    stream.add({ type: "turn.completed", usage: { input_tokens: 2000, cached_input_tokens: 1700, output_tokens: 30 } });
+    expect(stream.usage).toMatchObject({ inputTokens: 400, cacheReadTokens: 2600, outputTokens: 80, requests: 2 });
+  });
+
+  it("协议报出 cached > input 的病态数据时扣减夹底到 0,不产生负 token", () => {
+    const stream = fromCodexThreadEvents();
+    stream.add({ type: "turn.completed", usage: { input_tokens: 100, cached_input_tokens: 200, output_tokens: 1 } });
+    expect(stream.usage?.inputTokens).toBe(0);
+    expect(stream.usage?.cacheReadTokens).toBe(200);
+  });
+});
+
+describe("fromClaudeSdkMessages usage 转发(Anthropic 互斥口径)", () => {
+  it("input_tokens 原生不含 cache read:如实转发,不做扣减", () => {
+    const stream = fromClaudeSdkMessages();
+    stream.add({
+      type: "result",
+      usage: { input_tokens: 100, output_tokens: 5, cache_read_input_tokens: 900, cache_creation_input_tokens: 50 },
+    });
+    expect(stream.usage).toMatchObject({
+      inputTokens: 100,
+      outputTokens: 5,
+      cacheReadTokens: 900,
+      cacheCreationTokens: 50,
+    });
+  });
+});
+
+describe("fromPiAgentEvents usage 转发(pi 互斥口径)", () => {
+  it("input 原生不含 cacheRead/cacheWrite:如实转发,cost.total 累进实测 costUSD", () => {
+    const stream = fromPiAgentEvents();
+    stream.add({
+      type: "message_end",
+      message: {
+        role: "assistant",
+        content: [],
+        usage: { input: 100, output: 5, cacheRead: 900, cacheWrite: 50, cost: { total: 0.42 } },
+      },
+    });
+    expect(stream.usage).toMatchObject({
+      inputTokens: 100,
+      cacheReadTokens: 900,
+      cacheCreationTokens: 50,
+      costUSD: 0.42,
+    });
+  });
+});

package/src/agents/sdk-streams.ts

@@ -484,7 +484,9 @@ export function fromCodexThreadEvents(): CodexThreadStream {
           if (isRecord(u)) {
             const num = (v: unknown): number => (typeof v === "number" ? v : 0);
             usage = {
-              inputTokens: (usage?.inputTokens ?? 0) + num(u.input_tokens),
+              // codex-rs TokenUsage 的 cached_input_tokens 是 input_tokens 的子集,
+              // 落互斥桶前扣掉(docs/feature/adapters/sdk/codex-sdk/cost.md)
+              inputTokens: (usage?.inputTokens ?? 0) + Math.max(0, num(u.input_tokens) - num(u.cached_input_tokens)),
               outputTokens: (usage?.outputTokens ?? 0) + num(u.output_tokens),
               cacheReadTokens: (usage?.cacheReadTokens ?? 0) + num(u.cached_input_tokens),
               // codex-rs TokenUsage 结构体同一份字段(与 o11y/parsers/codex.ts 的

package/src/agents/types.ts

@@ -369,10 +369,11 @@ export interface Agent {
   spanMapper?: SpanMapper;
   send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
   /**
-   * 可选 turn 失败分类器:按重试安全性归类一次 send 失败(抛出或返回 `status: "failed"` 的
-   * Turn),返回 `undefined` 回落保守兜底。分类器只声明决策与诊断词,不影响重试策略(次数、
-   * 退避对所有 agent 一致);抛错按不可重试处理并被吞掉。形状与分类链、执行体时序见
-   * docs/feature/error-classification/architecture.md。
+   * 可选 turn 失败分类器:归类一次 send 失败(抛出或返回 `status: "failed"` 的 Turn),
+   * 返回 `undefined` 表示不认识、回落保守兜底。链上排在实验的 `classifyFailure` 之后,
+   * 实验作者认领过的失败问不到这里。分类器只声明决策轴与诊断词,不影响重试策略(次数、
+   * 退避对所有 agent 一致);抛错按 `undefined` 回落并被吞掉,不掩盖原始失败。形状与分类链、
+   * 执行体时序见 docs/feature/error-classification/architecture.md。
    */
   classifyTurnError?: TurnErrorClassifier;
   teardown?: AgentTeardown;

package/src/cli.ts

@@ -19,6 +19,8 @@ import { fingerprintEvalsFilter, resolveExperimentEvals, selectedEvalsForRun, sp
 import { failureDetailFromResult } from "./runner/feedback/failure.ts";
 import { stopAllSandboxes, liveSandboxCount } from "./sandbox/registry.ts";
 import { drainExperimentTeardowns } from "./runner/experiment-cleanup-registry.ts";
+import { drainHeldCaseLocks, isCaseLockStale, readCaseLock } from "./runner/lock.ts";
+import { drainHeldGateLeases } from "./runner/gate-lease.ts";
 import { CLEANUP_TIMEOUT_MS, withCleanupTimeout } from "./runner/cleanup-timeout.ts";
 import type { ExperimentHookContext } from "./runner/types.ts";
 import { evalLevelStats } from "./shared/verdict.ts";
@@ -175,7 +177,7 @@ const FLAG_OPTIONS = {
   // 数字 `--attempt`,选哪个 attempt 由 locator 精确指名,不是「先选 eval 再挑第几次」。
   /** `show` 命令专用:该 attempt 运行时保存的 Eval 源码,gate/soft 断言标回源码行(证据切面)。 */
   source: { type: "boolean" },
-  /** `show` 命令专用:该 attempt 的标准执行事件流(消息、thinking、Skill load、工具调用/结果);有 OTel 时同一节点补时间(证据切面)。单张卡片正文超过 8 KiB 预览预算会被截断,截断尾巴自带 `--expand` 展开句柄。 */
+  /** `show` 命令专用:该 attempt 的标准执行事件流(消息、thinking、Skill load、工具调用/结果);有 OTel 时同一节点补时间(证据切面)。每个内容段最多预览前 3 行,截断尾巴自带 `--expand` 展开句柄。 */
   execution: { type: "boolean" },
   /** `show` 命令专用:整个 Attempt 的统一时间树;裸 `--timing` 给有界诊断投影,`--timing=full` 逐节点展开全部 runner/已关联 OTel 节点。 */
   timing: { type: "boolean" },
@@ -545,19 +547,32 @@ async function openBrowser(url: string): Promise<boolean> {
 function assembleInvocationCompletion(state: RunFeedbackState): InvocationCompletion {
   let unstarted = 0;
   let failFastSkipped = 0;
+  let haltedSkipped = 0;
   let interrupted = false;
   const reporterErrors: ReporterError[] = [];
   for (const d of state.diagnostics) {
-    if (d.key === "interrupted") {
+    // 归类按**稳定词法** `code`,不按 `key`:`key` 里编着折叠身份(experimentId / evalId /
+    // reporter 名),拿它做前缀匹配会在「把身份从 key 里摘出去」时静默失配——记账悄悄归零,
+    // 没有任何测试或类型会报警。`code` 省略时回落到 key 的首段:缺省 key 恒是
+    // `${code}:${identity}`(见 sink.ts 的 DiagnosticInput),首段即 code。
+    const code = d.code ?? d.key.split(":", 1)[0];
+    if (code === "interrupted") {
       interrupted = true;
-    } else if (d.key.startsWith("budget-exhausted:")) {
+    } else if (code === "budget-exhausted") {
       unstarted += d.count;
-    } else if (d.key.startsWith("fail-fast:")) {
+    } else if (code === "fail-fast") {
       // run 级 fail-fast 造成的未派发同样计入 unstarted(结论落 incomplete,见
       // docs/feature/experiments/architecture.md「Completion 与退出」)。
       unstarted += d.count;
       failFastSkipped += d.count;
-    } else if (d.key.startsWith("reporter-error:")) {
+    } else if (code === "dispatch-halted") {
+      // 止损闸停派发造成的未派发(见 docs/feature/error-classification/architecture.md
+      // 「记账」)。这条诊断的 count 是「同一死因被声明了几次」(重复声明折叠),不是未派发数——
+      // 未派发数由 emitter 累计后写在 data.unstarted 里(与 budget-exhausted 同一口径)。
+      const halted = typeof d.data?.unstarted === "number" ? d.data.unstarted : 0;
+      unstarted += halted;
+      haltedSkipped += halted;
+    } else if (code === "reporter-error") {
       // required 决定这条错误是否写进 InvocationCompletion.reporterErrors 并让 completion 非 complete
       // (见 docs/cli.md「required reporter」);best-effort reporter 的失败只保留为 diagnostic。
       if (d.data?.required !== true) continue;
@@ -571,9 +586,9 @@ function assembleInvocationCompletion(state: RunFeedbackState): InvocationComple
   // 中断造成的未派发(仍在 queued 的 attempt)同样计入 unstarted(见 docs/feature/experiments/
   // architecture.md「Completion 与退出」:budget 耗尽、fail-fast 或中断造成的未派发都不伪装成全绿)。
   if (interrupted) unstarted += state.queued;
-  // attempt:early-exit 计数含 fail-fast 的未派发(反馈层同一事件驱动计数守恒);
-  // 「省下的重复验证」= 总数减去 fail-fast 那部分。
-  const earlyExitUnstarted = Math.max(0, state.earlyExitSkipped - failFastSkipped);
+  // attempt:early-exit 计数含 fail-fast 与止损闸的未派发(反馈层同一事件驱动计数守恒);
+  // 「省下的重复验证」= 总数减去那两部分。
+  const earlyExitUnstarted = Math.max(0, state.earlyExitSkipped - failFastSkipped - haltedSkipped);
   const status: CompletionStatus = interrupted
     ? "interrupted"
     : unstarted > 0 || reporterErrors.length > 0
@@ -875,6 +890,9 @@ async function main(): Promise<void> {
         maxConcurrency: exp.maxConcurrency,
         setup: exp.setup,
         teardown: exp.teardown,
+        // 实验级失败分类器:随 AgentRun 进 attempt(turn 链与生命周期链共用同一份),
+        // 产出的 scope 由止损闸消费(见 docs/feature/error-classification/architecture.md)。
+        classifyFailure: exp.classifyFailure,
       });
     }
   } else {
@@ -926,21 +944,36 @@ async function main(): Promise<void> {
   // 人读 `--dry` 首行的携入摘要(见 docs/feature/experiments/cli.md 开头示例与「事件与计划
   // 文档的 TypeScript 形状」),口径必须与真正开跑时一致。
   const priorResults = flags.force ? undefined : await loadLatestResultsPerEval(join(cwd, ".niceeval"));
-  const carryPlan = priorResults?.length ? await planCarry(evals, agentRuns, priorResults, config.sandbox) : undefined;
+  const carryPlan = priorResults?.length
+    ? await planCarry(evals, agentRuns, priorResults, config.sandbox, config.timeoutMs)
+    : undefined;
 
   if (flags.dry) {
     // --dry 只按所选形态打印计划,不运行、不落盘——一次完成的读取,不是事件流
     // (见 docs/feature/experiments/cli.md「机器怎么读:--json」)。两种形态共用同一份摊平
     // 矩阵——(experimentId, evalId) 逐行,携带同一口径的 reused 预测——不是各自重算一遍。
     const dryRuns = Math.max(1, ...agentRuns.map((r) => r.runs));
-    const matrix: JsonPlanRow[] = [];
+    const rowInputs: { experimentId: string; evalId: string; reused: boolean }[] = [];
     for (let i = 0; i < agentRuns.length; i++) {
       const run = agentRuns[i]!;
       for (const e of matchedByRun[i]!) {
         const carriedCount = carryPlan?.carriedAttemptsByKey.get(cacheKey(run, e.id))?.size ?? 0;
-        matrix.push({ experimentId: run.experimentId ?? "", evalId: e.id, reused: carriedCount >= run.runs });
+        rowInputs.push({ experimentId: run.experimentId ?? "", evalId: e.id, reused: carriedCount >= run.runs });
       }
     }
+    // 只读锁目录,不取锁、不等待(见 docs/feature/experiments/architecture.md「并发
+    // Invocation:用例锁」);过期(无人续心跳)的锁不算"正被持锁运行",不标注。裸 run(没有
+    // experimentId)不参与锁,恒不标注。并行读——矩阵行数可能不小,不逐行串行等磁盘。
+    const niceevalRootForDry = resolvePath(cwd, ".niceeval");
+    const now = Date.now();
+    const lockedFlags = await Promise.all(
+      rowInputs.map(async (row) => {
+        if (!row.experimentId) return false;
+        const lock = await readCaseLock(niceevalRootForDry, row.experimentId, row.evalId).catch(() => undefined);
+        return lock !== undefined && !isCaseLockStale(lock, now);
+      }),
+    );
+    const matrix: JsonPlanRow[] = rowInputs.map((row, i) => ({ ...row, ...(lockedFlags[i] ? { locked: true } : {}) }));
     if (outputForm === "json") {
       process.stdout.write(
         renderJsonPlanDocument({
@@ -959,7 +992,7 @@ async function main(): Promise<void> {
           configs: agentRuns.length,
           runs: dryRuns,
           reused: carryPlan?.carriedResults.length ?? 0,
-          rows: matrix.map((row) => ({ experimentId: row.experimentId, evalId: row.evalId })),
+          rows: matrix.map((row) => ({ experimentId: row.experimentId, evalId: row.evalId, locked: row.locked })),
         }),
       );
     }
@@ -1025,6 +1058,8 @@ async function main(): Promise<void> {
       const settled = Promise.allSettled([
         ...(runInFlight ? [runInFlight] : []),
         drainExperimentTeardowns(),
+        drainHeldCaseLocks(),
+        drainHeldGateLeases(),
       ]);
       await Promise.race([
         settled.then(() => {}),
@@ -1101,9 +1136,12 @@ async function main(): Promise<void> {
   }
 
   // 正常返回(含被中断后走部分汇总)后再兜一刀:Scope finalizer 没停掉的残留沙箱、没被运行
-  // 路径消费的实验级 cleanup 在这里强清。跑顺利时两份登记表都已空,是 no-op。
+  // 路径消费的实验级 cleanup、没被 per-attempt Effect.ensuring 释放的用例锁与实验闸租约在这里
+  // 强清。跑顺利时四份登记表都已空,是 no-op。
   await stopAllSandboxes();
   await drainExperimentTeardowns();
+  await drainHeldCaseLocks();
+  await drainHeldGateLeases();
 
   // completion 要先算好,--junit 是否"这次真的写出"才有依据(见下)。
   const completion = assembleInvocationCompletion(coordinator.state);
@@ -1140,8 +1178,11 @@ async function main(): Promise<void> {
 
 main().catch(async (e) => {
   process.stderr.write(t("cli.error", { error: formatThrown(e) }));
-  // 真·崩溃路径也别留孤儿:强清还活着的沙箱(带超时)、排空实验级 cleanup 注册表,再退。
+  // 真·崩溃路径也别留孤儿:强清还活着的沙箱(带超时)、排空实验级 cleanup 注册表、用例锁与
+  // 实验闸租约,再退。
   await stopAllSandboxes();
   await drainExperimentTeardowns();
+  await drainHeldCaseLocks();
+  await drainHeldGateLeases();
   process.exit(2);
 });

package/src/context/context.test.ts

@@ -355,6 +355,40 @@ function baseScoringContext(state: ContextState) {
   };
 }
 
+describe("t.* 作用域断言聚合全部轮次(callId 跨轮复用)", () => {
+  // 回归:续轮场景下 adapter 常按轮各自编号(复用 c1)。第一轮读了 INDEX,第二轮才给答复;
+  // t.calledTool 聚合全部轮次,应命中第一轮的 read——旧折叠按 callId 覆盖会让它「只扫最后一轮」而 miss。
+  it("t.calledTool 命中发生在第一轮、callId 被第二轮复用的工具调用", async () => {
+    const agent = scriptedAgent([
+      {
+        status: "completed",
+        events: [
+          { type: "action.called", callId: "c1", name: "read", input: { path: "INDEX.md" } },
+          { type: "action.result", callId: "c1", output: "index contents", status: "completed" },
+          { type: "message", role: "assistant", text: "读完了 INDEX,继续" },
+        ],
+      },
+      {
+        status: "completed",
+        events: [
+          { type: "action.called", callId: "c1", name: "write", input: { path: "note.md" } },
+          { type: "action.result", callId: "c1", output: "ok", status: "completed" },
+          { type: "message", role: "assistant", text: "答复" },
+        ],
+      },
+    ]);
+    const { context, state } = makeContext(agent);
+    await context.send("第一轮"); // 读 INDEX
+    await context.send("第二轮"); // 续轮,复用 callId c1
+
+    context.calledTool("read", { input: { path: "INDEX.md" } });
+
+    const [result] = await state.collector.finalize(baseScoringContext(state));
+    expect(result.name).toBe("calledTool(read)");
+    expect(result.outcome).toBe("passed");
+  });
+});
+
 describe("TurnHandle scoped assertions (parked/loadedSkill/noFailedActions/maxTokens/maxCost)", () => {
   it("mirror t/session scope: turn.parked() reflects this turn's own waiting status", async () => {
     const agent = scriptedAgent([

package/src/context/context.ts

@@ -12,6 +12,7 @@ import * as Scoped from "../scoring/scoped.ts";
 import { buildJudge } from "../scoring/judge.ts";
 import { EvalSkipped, EvalRequirementFailed, TurnFailed } from "./control-flow.ts";
 import { turnErrorText } from "./turn-errors.ts";
+import { attachFailureClass, type FailureClass } from "../shared/failure-class.ts";
 import type { ConcurrencySlot } from "./send-retry.ts";
 import { deriveRunFacts } from "../o11y/derive.ts";
 import { diffIsEmpty, diffMatches, emptyDiffData } from "../scoring/diff.ts";
@@ -91,6 +92,8 @@ export interface ContextDeps {
   onTurn?: import("./session.ts").SessionDeps["onTurn"];
   /** turn 级重试退避期间释放/收回的全局并发槽位;透传给 SessionManager。 */
   concurrencySlot?: ConcurrencySlot;
+  /** 实验声明的失败分类器(`ExperimentDef.classifyFailure`);透传给 SessionManager。 */
+  experimentClassifier?: import("./session.ts").SessionDeps["experimentClassifier"];
   /** 仅供确定性单测注入:透传给 SessionManager 的 turn 重试随机数/睡眠(生产路径省略)。 */
   retryRandom?: import("./session.ts").SessionDeps["retryRandom"];
   retrySleep?: import("./session.ts").SessionDeps["retrySleep"];
@@ -131,6 +134,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     onTurn: deps.onTurn,
     ledgerHooks: deps.ledgerHooks,
     concurrencySlot: deps.concurrencySlot,
+    experimentClassifier: deps.experimentClassifier,
     retryRandom: deps.retryRandom,
     retrySleep: deps.retrySleep,
   });
@@ -332,11 +336,11 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
         const text = typeof input === "string" ? input : input.text;
         const files = typeof input === "string" ? undefined : input.files;
         const turn = await send(session, text, files);
-        return makeTurnHandle(turn, collector, deps, text, manager.resolveTurnCoverage(turn));
+        return makeTurnHandle(turn, collector, deps, text, manager.resolveTurnCoverage(turn), manager.resolveTurnFailureClass(turn));
       },
       sendFile: async (path, text) => {
         const turn = await send(session, text ?? "", [await readInputFile(path)]);
-        return makeTurnHandle(turn, collector, deps, text ?? "", manager.resolveTurnCoverage(turn));
+        return makeTurnHandle(turn, collector, deps, text ?? "", manager.resolveTurnCoverage(turn), manager.resolveTurnFailureClass(turn));
       },
       requireInputRequest: (filter) => requireInputRequest(session, filter),
       respond: async (...answers) => {
@@ -344,7 +348,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
         const built = buildRespondInput(session, answers);
         session.pendingInputRequests.length = 0;
         const turn = await send(session, built.text, undefined, built.responses);
-        return makeTurnHandle(turn, collector, deps, built.text, manager.resolveTurnCoverage(turn));
+        return makeTurnHandle(turn, collector, deps, built.text, manager.resolveTurnCoverage(turn), manager.resolveTurnFailureClass(turn));
       },
       respondAll: async (optionId) => {
         if (session.pendingInputRequests.length === 0) {
@@ -359,7 +363,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
         session.pendingInputRequests.length = 0;
         const input = requests.map(() => optionId).join("\n");
         const turn = await send(session, input, undefined, responses);
-        return makeTurnHandle(turn, collector, deps, input, manager.resolveTurnCoverage(turn));
+        return makeTurnHandle(turn, collector, deps, input, manager.resolveTurnCoverage(turn), manager.resolveTurnFailureClass(turn));
       },
       get reply() {
         return session.lastMessage;
@@ -565,6 +569,7 @@ function makeTurnHandle(
   deps: ContextDeps,
   input: string,
   coverage: ResolvedCoverage,
+  failureClass?: FailureClass,
 ): TurnHandle {
   const message = lastAssistantText(turn.events) ?? "";
   const facts = deriveRunFacts(turn.events);
@@ -598,7 +603,11 @@ function makeTurnHandle(
         // 与保守兜底分类器、turn 级重试摘要读的同一段文本(见 turn-errors.ts 的 turnErrorText)——
         // 不出现「报错说 A、分类看 B」。
         const message = turnErrorText(turn);
-        throw new TurnFailed(message !== undefined ? t("context.turnFailed", { message }) : undefined);
+        const error = new TurnFailed(message !== undefined ? t("context.turnFailed", { message }) : undefined);
+        // 终局失败的分类随错误浮出:attempt 封口据此落止损闸(见
+        // docs/feature/error-classification/architecture.md「止损执行体」)。没有分类
+        // (未经重试执行体的手工构造 Turn)时不标记,落缺省 attempt 档。
+        throw failureClass ? attachFailureClass(error, failureClass) : error;
       }
       return handle;
     },