niceeval 0.10.3-canary.7 → 0.11.0

package/dist/agents/types.d.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/dist/context/turn-errors.d.ts

@@ -1,17 +1,5 @@
 import type { Turn } from "../types.ts";
-/**
- * 一次 send 失败的分类结果:`retryable` 是执行体唯一消费的决策轴;`reason` 是开放词表的
- * 细分诊断,只进 activity 与耗尽摘要,不参与策略。内建兜底产出 reason `"rate_limit"` /
- * `"network"`;adapter 分类器可自造词。`retryable: true` 时 `reason` 必填——可重试的失败
- * 一定会出现在 activity 行与可能的耗尽摘要里,那里需要一个给人读的词。
- */
-export type TurnErrorClass = {
-    readonly retryable: true;
-    readonly reason: string;
-} | {
-    readonly retryable: false;
-    readonly reason?: string;
-};
+import { type AttemptFailureClassifier, type FailureClass } from "../shared/failure-class.ts";
 /** 一次 send 失败的两种浮出形态:`send()` 抛出异常,或返回 `status: "failed"` 的 Turn。 */
 export type TurnFailure = {
     readonly type: "thrown";
@@ -21,10 +9,10 @@ export type TurnFailure = {
     readonly turn: Turn;
 };
 /**
- * adapter 可选分类器:返回 `undefined` 表示「不认识,交给保守兜底」。分类器必须快、纯、
- * 不抛错——执行体按「抛错等价于不可重试」处理,自身错误被吞掉,不会掩盖原始失败。
+ * adapter 可选分类器:返回 `undefined` 表示「不认识,交给后续链路」。分类器必须快、纯、
+ * 不抛错——抛错按 `undefined` 回落处理,自身错误被吞掉,不会掩盖原始失败。
  */
-export type TurnErrorClassifier = (failure: TurnFailure) => TurnErrorClass | undefined;
+export type TurnErrorClassifier = (failure: TurnFailure) => FailureClass | undefined;
 /**
  * 失败 Turn 的错误摘要:取 `events` 里最后一个 `type: "error"` 事件的 message。
  * 与 `context.turnFailed` 报错文案、保守兜底分类器读的同一段文本同源——不出现
@@ -35,15 +23,31 @@ export declare function turnErrorText(turn: Turn): string | undefined;
 /** 两种 `TurnFailure` 形态统一取「给人读也给分类器看」的那段文本。 */
 export declare function turnFailureText(failure: TurnFailure): string;
 /**
- * 保守兜底分类器:三道分类链里的第二道。对失败文本做正则匹配,认不出的一律 `{ retryable: false }`
- * ——宁可判死一个 attempt,不产出不可信的 verdict(判据见 README「分类」)。
+ * 保守兜底分类器:turn 链里的第四道。对失败文本做正则匹配,认不出的一律 `{ retryable: false }`
+ * ——宁可判死一个 attempt,不产出不可信的 verdict(判据见 README「分类」)。兜底永不给出超出
+ * `"attempt"` 的 scope:框架无法从文案证明兄弟必死,扩 scope 只属于携带作者知识的通道。
  */
-export declare function classifyTurnError(failure: TurnFailure): TurnErrorClass;
+export declare function classifyTurnError(failure: TurnFailure): FailureClass;
 /** 受理证据门:失败 Turn 的 events 里已出现任何 agent 侧产出,即证明 agent 已受理并开始工作。 */
 export declare function hasAgentEvidence(turn: Turn): boolean;
+/** turn 链上两个可选声明通道;都省略时链退化成「抛出点 → 兜底 → 证据门」。 */
+export interface TurnClassifiers {
+    /** 实验作者的 `ExperimentDef.classifyFailure`,按自家坐标识别共享基建死因。 */
+    experiment?: AttemptFailureClassifier;
+    /** adapter 作者的 `Agent.classifyTurnError`,识别自家协议的错误形状。 */
+    adapter?: TurnErrorClassifier;
+}
 /**
- * 三道分类链的完整决议:adapter 分类器(可选,抛错按不可重试处理并吞掉)→ 保守兜底 →
- * 受理证据门(否决权,失败 Turn 带 agent 产出事件时强制降级)。执行体只需要调这一个函数,
- * 不必自己拼三道链的顺序。
+ * turn 失败分类链的完整决议(五道,先给出非 `undefined` 结果的一道定分类):
+ *
+ * 1. 抛出点携带的分类(`failureClassOf`,含 cause 链穿透)——作者知识优先级最高;
+ * 2. 实验分类器——按自家坐标(host、路径)过滤,特异性高于协议通用形状,排在 adapter 之前
+ *    保证「两者同时认领时 scope 赢」(裁决见 memory/failure-chain-experiment-before-adapter.md);
+ * 3. adapter 分类器;
+ * 4. 保守兜底正则;
+ * 5. 受理证据门(执行体的否决权,只裁时间轴):失败 Turn 里已有 agent 产出事件时 `retryable`
+ *    强制降为 `false`,`reason` 与 `scope` 原样保留——门裁的是重发安全性,不是波及范围。
+ *
+ * 分类器抛错按 `undefined` 回落(继续问后续通道),分类是旁路,不得用新错误掩盖原始失败。
  */
-export declare function resolveTurnErrorClass(failure: TurnFailure, adapterClassifier?: TurnErrorClassifier): TurnErrorClass;
+export declare function resolveTurnFailureClass(failure: TurnFailure, classifiers?: TurnClassifiers): FailureClass;

package/dist/i18n/en.d.ts

@@ -55,6 +55,11 @@ export declare const en: {
     "runner.setupReturnedCleanup": string;
     "runner.experimentTeardownLate": string;
     "runner.teardownRegistrationWriteFailed": string;
+    "runner.lockTakenOver": string;
+    "runner.gateLeaseTakenOver": string;
+    "runner.gateLeaseWaiting": string;
+    "runner.dispatchHaltedExperiment": string;
+    "runner.dispatchHaltedEval": string;
     "judge.modelMissing": string;
     "loaders.yamlMissing": string;
     "cli.flag.parseError": string;
@@ -130,6 +135,7 @@ export declare const en: {
     "define.experimentFlagNotJson": string;
     "define.experimentLabelInvalid": string;
     "define.experimentSetupNotFunction": string;
+    "define.experimentClassifyFailureNotFunction": string;
     "define.experimentIdRejected": string;
     "define.sandboxAgentNameRequired": string;
     "define.sandboxCreateRequired": string;
@@ -176,6 +182,14 @@ export declare const en: {
     "feedback.human.hookFailed": string;
     "feedback.human.precheckJudge": string;
     "feedback.human.precheckJudgeDone": string;
+    "feedback.human.countsWithElsewhere": string;
+    "feedback.human.waitingOnAnotherRun": string;
+    "feedback.human.lockWaitDetail": string;
+    "feedback.human.lockWaitStarted": string;
+    "feedback.human.lockWaitResolved": string;
+    "feedback.human.lockWaitCarried": string;
+    "feedback.human.lockWaitDispatched": string;
+    "feedback.human.lockedRowSuffix": string;
     "feedback.phase.sandboxSetup": string;
     "feedback.phase.scoring": string;
     "feedback.phase.teardown": string;

package/dist/i18n/en.js

@@ -60,6 +60,11 @@ export const en = {
     "runner.setupReturnedCleanup": "{{layer}} returned a function. setup does not carry cleanup and the returned value will not be executed — put the cleanup in the paired teardown of the same layer ({{hint}}); see the experiments tutorial on docs-site or docs/runner.md.\n",
     "runner.experimentTeardownLate": "experiment {{experimentId}}'s teardown was not triggered by the normal countdown path; it has been executed by the end-of-run sweep instead. Results are unaffected; seeing this line means an unlocated intermittent scheduling issue fired — please record this run in the memory ledger.\n",
     "runner.teardownRegistrationWriteFailed": "writing the crash-recovery teardown registration for experiment {{experimentId}} failed: {{message}}. The run continues normally, but a SIGKILL during this run cannot be recovered via `niceeval exp --teardown` or the startup self-heal — check disk space/permissions under .niceeval/teardowns/.\n",
+    "runner.lockTakenOver": "took over an expired case lock for {{experimentId}}/{{evalId}} (previously held by pid {{pid}} on {{host}}; its heartbeat went stale) — that run likely died without releasing it; this run now owns dispatching this case.\n",
+    "runner.gateLeaseTakenOver": "took over an expired concurrency-slot lease for experiment {{experimentId}} (slot {{slot}}, previously held by pid {{pid}} on {{host}}; its heartbeat went stale) — that run likely died without releasing it; this run now owns the slot.\n",
+    "runner.gateLeaseWaiting": "waiting on another run for experiment {{experimentId}}'s concurrency slots: all {{effectiveN}} in use ({{holders}}). Concurrent runs share this experiment's slots, and the smallest maxConcurrency in play wins — this run declared {{declaredN}}. Nothing dispatches until a slot frees up; the other run's slots release when its attempts finish, or 30s after it dies.\n",
+    "runner.dispatchHaltedExperiment": "experiment halted (dispatch-halted): {{message}}\n",
+    "runner.dispatchHaltedEval": "eval halted: {{message}}\n",
     "judge.modelMissing": "No judge model configured. Set it in defineConfig({ judge: { model: \"...\" } }), the eval's judge config, or the NICEEVAL_JUDGE_MODEL environment variable (there is no built-in default model).\n" +
         "  Docs: node_modules/niceeval/docs-site/zh/tutorials/scoring-guide.mdx",
     "loaders.yamlMissing": "loadYaml(\"{{path}}\") needs a YAML parser: run `pnpm add yaml` first (or switch to loadJson with a JSON dataset).",
@@ -198,6 +203,7 @@ export const en = {
     "define.experimentFlagNotJson": "experiment.flags.{{key}} is not JSON-serializable (functions / undefined / cycles / bigint are not allowed); flags are persisted verbatim into result snapshots and must be plain JSON.",
     "define.experimentLabelInvalid": "experiment.labels.{{key}} must be a string or a finite number; labels are report-side grouping coordinates persisted verbatim into result snapshots.",
     "define.experimentSetupNotFunction": "experiment.setup must be a function ((ctx) => void); use experiment.teardown for cleanup; to prepare the in-sandbox environment per experiment, chain .setup() hooks on the sandbox spec instead.",
+    "define.experimentClassifyFailureNotFunction": "experiment.classifyFailure must be a function ((failure) => FailureClass | undefined); it classifies failures that surface as third-party errors and must return undefined for anything it does not recognize.",
     "define.experimentIdRejected": "defineExperiment does not accept id; ids are derived from file paths.",
     "define.sandboxAgentNameRequired": "defineSandboxAgent requires name.",
     "define.sandboxCreateRequired": "defineSandbox requires a create() function.",
@@ -211,7 +217,7 @@ export const en = {
     "feedback.human.active": "ACTIVE",
     "feedback.human.budgetExhausted": "budget exhausted for {{experimentId}} (spent {{spent}}, unstarted {{unstarted}})",
     "feedback.human.compare": "Compare: niceeval view",
-    "feedback.human.counts": "{{total}} total · {{reused}} reused · {{running}} running · {{queued}} queued · {{completed}} completed",
+    "feedback.human.counts": "{{total}} total · {{reused}} reused · {{running}} running · {{queued}} queued · {{passed}} passed · {{failed}} failed · {{errored}} errored · {{skipped}} skipped",
     "feedback.human.diffHint": "Diff:    niceeval show {{locator}} --diff",
     "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --source",
     "feedback.human.failuresHeader": "FAILURES",
@@ -244,6 +250,14 @@ export const en = {
     "feedback.human.hookFailed": "failed",
     "feedback.human.precheckJudge": "prechecking judge config",
     "feedback.human.precheckJudgeDone": "judge config ok",
+    "feedback.human.countsWithElsewhere": "{{total}} total · {{reused}} reused · {{running}} running · {{elsewhere}} elsewhere · {{queued}} queued · {{passed}} passed · {{failed}} failed · {{errored}} errored · {{skipped}} skipped",
+    "feedback.human.waitingOnAnotherRun": "waiting on another run",
+    "feedback.human.lockWaitDetail": "{{count}} evals · pid {{pid}}",
+    "feedback.human.lockWaitStarted": "waiting on another run · {{experimentId}} ({{count}} evals, pid {{pid}})",
+    "feedback.human.lockWaitResolved": "lock wait resolved · {{experimentId}} ({{summary}}, {{elapsed}})",
+    "feedback.human.lockWaitCarried": "{{count}} carried",
+    "feedback.human.lockWaitDispatched": "{{count}} to run",
+    "feedback.human.lockedRowSuffix": "locked",
     "feedback.phase.sandboxSetup": "sandbox setup",
     "feedback.phase.scoring": "scoring",
     "feedback.phase.teardown": "cleaning up",

package/dist/i18n/zh-CN.d.ts

@@ -55,6 +55,11 @@ export declare const zhCN: {
     readonly "runner.setupReturnedCleanup": "{{layer}} 返回了一个函数。setup 不承载收尾,返回值不会被执行——收尾写在同层成对的 teardown 里({{hint}});见 docs-site 的实验教程或 docs/runner.md「环境预置」。\n";
     readonly "runner.experimentTeardownLate": "实验 {{experimentId}} 的 teardown 未被正常计数路径触发,已在运行收尾兜底执行。结果不受影响;这行出现说明命中了一个未定位的调度间歇问题,请把本次运行信息记入 memory 台账。\n";
     readonly "runner.teardownRegistrationWriteFailed": "实验 {{experimentId}} 的强杀恢复收尾登记写入失败:{{message}}。本次运行照常继续,但这次运行期间若被 SIGKILL,`niceeval exp --teardown` 与启动自愈都无法找到它——检查 .niceeval/teardowns/ 下的磁盘空间或权限。\n";
+    readonly "runner.lockTakenOver": "接管了 {{experimentId}}/{{evalId}} 的过期用例锁(原持有者 pid {{pid}}@{{host}},心跳已过期)——那次运行大概率没能正常释放它;本次运行现在接手派发这条用例。\n";
+    readonly "runner.gateLeaseTakenOver": "接管了实验 {{experimentId}} 的过期并发名额租约(槽位 {{slot}},原持有者 pid {{pid}}@{{host}},心跳已过期)——那次运行大概率没能正常释放它;本次运行现在接手这个名额。\n";
+    readonly "runner.gateLeaseWaiting": "在等别的运行让出实验 {{experimentId}} 的并发名额:生效的 {{effectiveN}} 个位子全被占着({{holders}})。并行运行共用同一实验的名额,生效值取在场声明里最小的那个——本次运行声明的是 {{declaredN}}。名额腾出来之前不会派发任何 attempt;对方的名额会在它的 attempt 跑完时释放,它若已死则 30s 后过期被接管。\n";
+    readonly "runner.dispatchHaltedExperiment": "实验已止损(dispatch-halted):{{message}}\n";
+    readonly "runner.dispatchHaltedEval": "eval 已止损:{{message}}\n";
     readonly "judge.modelMissing": string;
     readonly "loaders.yamlMissing": "loadYaml(\"{{path}}\") 需要 YAML 解析器:请先 `pnpm add yaml`(或改用 loadJson + JSON 数据集)。";
     readonly "cli.flag.parseError": "{{message}}\n运行 `niceeval --help` 查看用法。\n";
@@ -130,6 +135,7 @@ export declare const zhCN: {
     readonly "define.experimentFlagNotJson": "experiment.flags.{{key}} 不是可 JSON 序列化的值(函数 / undefined / 循环引用 / bigint 不允许);flags 会原样进入结果快照,必须是纯 JSON。";
     readonly "define.experimentLabelInvalid": "experiment.labels.{{key}} 必须是字符串或有限数字;labels 是报告侧的归类坐标,会原样进入结果快照。";
     readonly "define.experimentSetupNotFunction": "experiment.setup 必须是函数((ctx) => void);要清理请挂 experiment.teardown;要按实验准备沙箱内环境请挂 sandbox spec 的 .setup() 钩子链。";
+    readonly "define.experimentClassifyFailureNotFunction": "experiment.classifyFailure 必须是函数((failure) => FailureClass | undefined):它识别以第三方错误形态浮出的失败,认不出的一律返回 undefined 交给后续链路。";
     readonly "define.experimentIdRejected": "defineExperiment 不接受 id —— id 由文件路径推导。";
     readonly "define.sandboxAgentNameRequired": "defineSandboxAgent 需要 name。";
     readonly "define.sandboxCreateRequired": "defineSandbox 需要一个 create() 函数。";
@@ -143,7 +149,7 @@ export declare const zhCN: {
     readonly "feedback.human.active": "ACTIVE";
     readonly "feedback.human.budgetExhausted": "{{experimentId}} 预算已耗尽(已花 {{spent}},未跑 {{unstarted}})";
     readonly "feedback.human.compare": "Compare: niceeval view";
-    readonly "feedback.human.counts": "共 {{total}} · 复用 {{reused}} · 运行中 {{running}} · 排队 {{queued}} · 已完成 {{completed}}";
+    readonly "feedback.human.counts": "共 {{total}} · 复用 {{reused}} · 运行中 {{running}} · 排队 {{queued}} · 通过 {{passed}} · 失败 {{failed}} · 出错 {{errored}} · 跳过 {{skipped}}";
     readonly "feedback.human.diffHint": "Diff:    niceeval show {{locator}} --diff";
     readonly "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --source";
     readonly "feedback.human.failuresHeader": "FAILURES";
@@ -176,6 +182,14 @@ export declare const zhCN: {
     readonly "feedback.human.hookFailed": "失败";
     readonly "feedback.human.precheckJudge": "预检 judge 配置";
     readonly "feedback.human.precheckJudgeDone": "judge 配置就绪";
+    readonly "feedback.human.countsWithElsewhere": "共 {{total}} · 复用 {{reused}} · 运行中 {{running}} · 等待中 {{elsewhere}} · 排队 {{queued}} · 通过 {{passed}} · 失败 {{failed}} · 出错 {{errored}} · 跳过 {{skipped}}";
+    readonly "feedback.human.waitingOnAnotherRun": "等待另一个并行 run";
+    readonly "feedback.human.lockWaitDetail": "{{count}} 条用例 · pid {{pid}}";
+    readonly "feedback.human.lockWaitStarted": "等待另一个并行 run · {{experimentId}}({{count}} 条用例,pid {{pid}})";
+    readonly "feedback.human.lockWaitResolved": "等待结束 · {{experimentId}}({{summary}},{{elapsed}})";
+    readonly "feedback.human.lockWaitCarried": "{{count}} 条携入";
+    readonly "feedback.human.lockWaitDispatched": "{{count}} 条自跑";
+    readonly "feedback.human.lockedRowSuffix": "locked";
     readonly "feedback.phase.sandboxSetup": "沙箱预置";
     readonly "feedback.phase.scoring": "评分";
     readonly "feedback.phase.teardown": "清理中";

package/dist/i18n/zh-CN.js

@@ -60,6 +60,11 @@ export const zhCN = {
     "runner.setupReturnedCleanup": "{{layer}} 返回了一个函数。setup 不承载收尾,返回值不会被执行——收尾写在同层成对的 teardown 里({{hint}});见 docs-site 的实验教程或 docs/runner.md「环境预置」。\n",
     "runner.experimentTeardownLate": "实验 {{experimentId}} 的 teardown 未被正常计数路径触发,已在运行收尾兜底执行。结果不受影响;这行出现说明命中了一个未定位的调度间歇问题,请把本次运行信息记入 memory 台账。\n",
     "runner.teardownRegistrationWriteFailed": "实验 {{experimentId}} 的强杀恢复收尾登记写入失败:{{message}}。本次运行照常继续,但这次运行期间若被 SIGKILL,`niceeval exp --teardown` 与启动自愈都无法找到它——检查 .niceeval/teardowns/ 下的磁盘空间或权限。\n",
+    "runner.lockTakenOver": "接管了 {{experimentId}}/{{evalId}} 的过期用例锁(原持有者 pid {{pid}}@{{host}},心跳已过期)——那次运行大概率没能正常释放它;本次运行现在接手派发这条用例。\n",
+    "runner.gateLeaseTakenOver": "接管了实验 {{experimentId}} 的过期并发名额租约(槽位 {{slot}},原持有者 pid {{pid}}@{{host}},心跳已过期)——那次运行大概率没能正常释放它;本次运行现在接手这个名额。\n",
+    "runner.gateLeaseWaiting": "在等别的运行让出实验 {{experimentId}} 的并发名额:生效的 {{effectiveN}} 个位子全被占着({{holders}})。并行运行共用同一实验的名额,生效值取在场声明里最小的那个——本次运行声明的是 {{declaredN}}。名额腾出来之前不会派发任何 attempt;对方的名额会在它的 attempt 跑完时释放,它若已死则 30s 后过期被接管。\n",
+    "runner.dispatchHaltedExperiment": "实验已止损(dispatch-halted):{{message}}\n",
+    "runner.dispatchHaltedEval": "eval 已止损:{{message}}\n",
     "judge.modelMissing": "judge 未配置模型:在 defineConfig({ judge: { model: \"...\" } })、eval 的 judge 配置或环境变量 NICEEVAL_JUDGE_MODEL 里指定裁判模型(没有内置默认模型)。\n" +
         "  文档:node_modules/niceeval/docs-site/zh/tutorials/scoring-guide.mdx",
     "loaders.yamlMissing": "loadYaml(\"{{path}}\") 需要 YAML 解析器:请先 `pnpm add yaml`(或改用 loadJson + JSON 数据集)。",
@@ -194,6 +199,7 @@ export const zhCN = {
     "define.experimentFlagNotJson": "experiment.flags.{{key}} 不是可 JSON 序列化的值(函数 / undefined / 循环引用 / bigint 不允许);flags 会原样进入结果快照,必须是纯 JSON。",
     "define.experimentLabelInvalid": "experiment.labels.{{key}} 必须是字符串或有限数字;labels 是报告侧的归类坐标,会原样进入结果快照。",
     "define.experimentSetupNotFunction": "experiment.setup 必须是函数((ctx) => void);要清理请挂 experiment.teardown;要按实验准备沙箱内环境请挂 sandbox spec 的 .setup() 钩子链。",
+    "define.experimentClassifyFailureNotFunction": "experiment.classifyFailure 必须是函数((failure) => FailureClass | undefined):它识别以第三方错误形态浮出的失败,认不出的一律返回 undefined 交给后续链路。",
     "define.experimentIdRejected": "defineExperiment 不接受 id —— id 由文件路径推导。",
     "define.sandboxAgentNameRequired": "defineSandboxAgent 需要 name。",
     "define.sandboxCreateRequired": "defineSandbox 需要一个 create() 函数。",
@@ -207,7 +213,7 @@ export const zhCN = {
     "feedback.human.active": "ACTIVE",
     "feedback.human.budgetExhausted": "{{experimentId}} 预算已耗尽(已花 {{spent}},未跑 {{unstarted}})",
     "feedback.human.compare": "Compare: niceeval view",
-    "feedback.human.counts": "共 {{total}} · 复用 {{reused}} · 运行中 {{running}} · 排队 {{queued}} · 已完成 {{completed}}",
+    "feedback.human.counts": "共 {{total}} · 复用 {{reused}} · 运行中 {{running}} · 排队 {{queued}} · 通过 {{passed}} · 失败 {{failed}} · 出错 {{errored}} · 跳过 {{skipped}}",
     "feedback.human.diffHint": "Diff:    niceeval show {{locator}} --diff",
     "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --source",
     "feedback.human.failuresHeader": "FAILURES",
@@ -240,6 +246,14 @@ export const zhCN = {
     "feedback.human.hookFailed": "失败",
     "feedback.human.precheckJudge": "预检 judge 配置",
     "feedback.human.precheckJudgeDone": "judge 配置就绪",
+    "feedback.human.countsWithElsewhere": "共 {{total}} · 复用 {{reused}} · 运行中 {{running}} · 等待中 {{elsewhere}} · 排队 {{queued}} · 通过 {{passed}} · 失败 {{failed}} · 出错 {{errored}} · 跳过 {{skipped}}",
+    "feedback.human.waitingOnAnotherRun": "等待另一个并行 run",
+    "feedback.human.lockWaitDetail": "{{count}} 条用例 · pid {{pid}}",
+    "feedback.human.lockWaitStarted": "等待另一个并行 run · {{experimentId}}({{count}} 条用例,pid {{pid}})",
+    "feedback.human.lockWaitResolved": "等待结束 · {{experimentId}}({{summary}},{{elapsed}})",
+    "feedback.human.lockWaitCarried": "{{count}} 条携入",
+    "feedback.human.lockWaitDispatched": "{{count}} 条自跑",
+    "feedback.human.lockedRowSuffix": "locked",
     "feedback.phase.sandboxSetup": "沙箱预置",
     "feedback.phase.scoring": "评分",
     "feedback.phase.teardown": "清理中",

package/dist/o11y/derive.js

@@ -46,10 +46,16 @@ function pickExitCode(output) {
 }
 // ───────────────────────── deriveRunFacts ─────────────────────────
 export function deriveRunFacts(events) {
-    const toolCallMap = new Map();
-    const toolCallOrder = [];
-    const subagentMap = new Map();
-    const subagentOrder = [];
+    // 折叠是逐条按发生顺序进行的:called 追加一条新调用,result 回填「当前还没配上 result 的
+    // 同 callId 调用」。callId 只在一个 called→result 配对内保证稳定,不保证跨轮唯一——adapter
+    // 常按轮各自编号(OpenAI 兼容协议、transcript 归一都会复用 c1/c2…)。所以一个 callId 在其
+    // result 之后再次以 called 出现,是新的一次调用,起一条新记录,不覆盖前一轮那条(否则跨轮
+    // 聚合会把前面几轮的工具调用抹成「只剩最后一轮」)。用 open*ByCallId 只跟踪各 callId 当前
+    // 敞口的那条,配上 result 即关闭。
+    const toolCalls = [];
+    const openToolByCallId = new Map();
+    const subagentCalls = [];
+    const openSubagentByCallId = new Map();
     const inputRequests = [];
     let messageCount = 0;
     let compactions = 0;
@@ -63,9 +69,8 @@ export function deriveRunFacts(events) {
                 contextInjections += 1;
                 break;
             case "action.called": {
-                if (!toolCallMap.has(ev.callId))
-                    toolCallOrder.push(ev.callId);
-                toolCallMap.set(ev.callId, {
+                openToolByCallId.set(ev.callId, toolCalls.length);
+                toolCalls.push({
                     callId: ev.callId,
                     name: ev.tool ?? "unknown",
                     originalName: ev.name,
@@ -76,15 +81,15 @@ export function deriveRunFacts(events) {
                 break;
             }
             case "action.result": {
-                const existing = toolCallMap.get(ev.callId);
-                if (existing) {
-                    existing.output = ev.output;
-                    existing.status = ev.status;
+                const idx = openToolByCallId.get(ev.callId);
+                if (idx !== undefined) {
+                    toolCalls[idx].output = ev.output;
+                    toolCalls[idx].status = ev.status;
+                    openToolByCallId.delete(ev.callId);
                 }
                 else {
                     // 只有结果、没配上调用:补一条占位 ToolCall。
-                    toolCallOrder.push(ev.callId);
-                    toolCallMap.set(ev.callId, {
+                    toolCalls.push({
                         callId: ev.callId,
                         name: "unknown",
                         input: null,
@@ -95,9 +100,8 @@ export function deriveRunFacts(events) {
                 break;
             }
             case "subagent.called": {
-                if (!subagentMap.has(ev.callId))
-                    subagentOrder.push(ev.callId);
-                subagentMap.set(ev.callId, {
+                openSubagentByCallId.set(ev.callId, subagentCalls.length);
+                subagentCalls.push({
                     callId: ev.callId,
                     name: ev.name,
                     remoteUrl: ev.remoteUrl,
@@ -107,14 +111,14 @@ export function deriveRunFacts(events) {
                 break;
             }
             case "subagent.completed": {
-                const existing = subagentMap.get(ev.callId);
-                if (existing) {
-                    existing.output = ev.output;
-                    existing.status = ev.status;
+                const idx = openSubagentByCallId.get(ev.callId);
+                if (idx !== undefined) {
+                    subagentCalls[idx].output = ev.output;
+                    subagentCalls[idx].status = ev.status;
+                    openSubagentByCallId.delete(ev.callId);
                 }
                 else {
-                    subagentOrder.push(ev.callId);
-                    subagentMap.set(ev.callId, {
+                    subagentCalls.push({
                         callId: ev.callId,
                         name: "unknown",
                         output: ev.output,
@@ -143,8 +147,8 @@ export function deriveRunFacts(events) {
         break;
     }
     return {
-        toolCalls: toolCallOrder.map((id) => toolCallMap.get(id)),
-        subagentCalls: subagentOrder.map((id) => subagentMap.get(id)),
+        toolCalls,
+        subagentCalls,
         inputRequests,
         parked,
         messageCount,

package/dist/o11y/types.d.ts

@@ -2,18 +2,21 @@ import type { JsonValue, SourceLoc } from "../shared/types.ts";
 /**
  * 一次运行的 token 用量(沙箱型从 transcript/OTel span 的 `gen_ai.usage.*` 属性抠,remote 由
  * send 的 `Turn.usage` 直接返回)。每个字段只在协议真实提供该值时存在——原始协议没有 usage 时
- * 省略,不编造数值;不存在「默认 0」或「默认 1」的字段(docs/feature/results/architecture.md#usage)。
+ * 省略,不编造数值;不存在「默认 0」或「默认 1」的字段。三个输入侧桶恒互斥:相加才是送进模型的
+ * 完整上下文量;把协议原生口径归一到互斥是 adapter 的落值义务——OpenAI 系报「含缓存的输入总量 +
+ * 缓存命中子集」,落 inputTokens 前先扣掉子集(docs/feature/results/architecture.md#usage,
+ * 各协议明细见 docs/feature/adapters/sdk/<name>/cost.md)。
  */
 export interface Usage {
-    /** 计费口径的输入 token 总量(协议报什么记什么,含 cache read 时如实包含,不换算)。 */
+    /** 未命中缓存、按全价计费的输入 token;与两个 cache 桶互斥。 */
     inputTokens?: number;
     /** 输出(completion)token 数。 */
     outputTokens?: number;
-    /** 从缓存命中的输入部分;与 inputTokens 同一计量口径(省略表示该 agent 不上报此项)。 */
+    /** 从提示缓存命中的输入 token;独立计价桶,不包含在 inputTokens 里(省略表示该 agent 不上报此项)。 */
     cacheReadTokens?: number;
-    /** 写入 prompt 缓存创建的 token 数(省略表示该 agent 不上报此项)。 */
+    /** 写入提示缓存的输入 token;独立计价桶,不包含在 inputTokens 里(省略表示该 agent 不上报此项)。 */
     cacheCreationTokens?: number;
-    /** 推理(thinking)token 数,只在协议真实提供时存在(省略表示该 agent 不上报此项)。 */
+    /** 推理(thinking)token 数,outputTokens 的已含明细,单列展示用;只在协议真实提供时存在。 */
     reasoningTokens?: number;
     /** 真实发生的模型请求数。协议不提供请求计数就省略,绝不写 1 凑数。 */
     requests?: number;

package/dist/report/components/attempt-detail/UsageTable.js

@@ -9,13 +9,10 @@ export function UsageTable({ data, className }) {
         rows.push(["turns", String(data.turns)]);
     if (data.toolCalls !== undefined)
         rows.push(["tool calls", String(data.toolCalls)]);
-    // 未缓存输入是消费端派生量,只在两个输入都在场时显示;缺任一个回退显示原始
-    // inputTokens(不猜 0),两种来源用不同行标签区分。
-    if (data.uncachedInputTokens !== undefined) {
-        rows.push(["uncached in", data.uncachedInputTokens.toLocaleString()]);
-    }
-    else if (usage?.inputTokens !== undefined) {
-        rows.push(["in", usage.inputTokens.toLocaleString()]);
+    // 桶恒互斥,inputTokens 就是未缓存输入;"uncached in" 标签只在 cache 拆分在场时用,
+    // cache 桶缺席的数字不贴标注。
+    if (usage?.inputTokens !== undefined) {
+        rows.push([usage.cacheReadTokens !== undefined ? "uncached in" : "in", usage.inputTokens.toLocaleString()]);
     }
     if (usage?.cacheReadTokens !== undefined)
         rows.push(["cache read", usage.cacheReadTokens.toLocaleString()]);

package/dist/report/components/attempt-detail/compute.d.ts

@@ -30,8 +30,8 @@ export declare function attemptDiagnosticsData(evidence: AttemptEvidence): Attem
  * identity 字段(locator/experimentId/evalId/attempt/verdict)恒有;turns/toolCalls 是 events
  * 派生(与 o11y.json 行为摘要同源,buildO11ySummary 与 o11y.json 落盘走同一份纯函数),没有
  * events 就整对省略——不因为其中一个恰好是 0 就当作"缺失"处理,0 是观测到的事实。
- * uncachedInputTokens 只在 inputTokens 与 cacheReadTokens 都存在时派生,缺任一个不猜 0
- * (text 面回退显示原始 inputTokens)。turns/toolCalls/usage 三者全部缺失时返回 null——
+ * token 桶恒互斥,inputTokens 本身就是未缓存输入,不派生第二个字段。
+ * turns/toolCalls/usage 三者全部缺失时返回 null——
  * 没有任何用量事实可摆,与其余叶子同一条"没有 usage 时零输出"规则。
  */
 export declare function usageTableData(evidence: AttemptEvidence): UsageTableData | null;

package/dist/report/components/attempt-detail/compute.js

@@ -441,8 +441,8 @@ export function attemptDiagnosticsData(evidence) {
  * identity 字段(locator/experimentId/evalId/attempt/verdict)恒有;turns/toolCalls 是 events
  * 派生(与 o11y.json 行为摘要同源,buildO11ySummary 与 o11y.json 落盘走同一份纯函数),没有
  * events 就整对省略——不因为其中一个恰好是 0 就当作"缺失"处理,0 是观测到的事实。
- * uncachedInputTokens 只在 inputTokens 与 cacheReadTokens 都存在时派生,缺任一个不猜 0
- * (text 面回退显示原始 inputTokens)。turns/toolCalls/usage 三者全部缺失时返回 null——
+ * token 桶恒互斥,inputTokens 本身就是未缓存输入,不派生第二个字段。
+ * turns/toolCalls/usage 三者全部缺失时返回 null——
  * 没有任何用量事实可摆,与其余叶子同一条"没有 usage 时零输出"规则。
  */
 export function usageTableData(evidence) {
@@ -453,9 +453,6 @@ export function usageTableData(evidence) {
     const usage = result.usage;
     if (turns === undefined && toolCalls === undefined && usage === undefined)
         return null;
-    const uncachedInputTokens = usage && typeof usage.inputTokens === "number" && typeof usage.cacheReadTokens === "number"
-        ? usage.inputTokens - usage.cacheReadTokens
-        : undefined;
     const estimatedCostUSD = attemptCostUSD(result);
     return {
         locator: evidence.locator,
@@ -466,7 +463,6 @@ export function usageTableData(evidence) {
         ...(turns !== undefined ? { turns } : {}),
         ...(toolCalls !== undefined ? { toolCalls } : {}),
         ...(usage !== undefined ? { usage } : {}),
-        ...(uncachedInputTokens !== undefined ? { uncachedInputTokens } : {}),
         ...(estimatedCostUSD !== null ? { estimatedCostUSD } : {}),
     };
 }

package/dist/report/components/attempt-detail/faces.js

@@ -293,13 +293,13 @@ export function usageTableText(data, _ctx) {
     if (data === null)
         return "";
     const usage = data.usage;
-    // 未缓存输入是消费端派生量,只在两个输入都在场时显示;缺任一个回退显示原始 inputTokens
-    // (不猜 0),这里用 label 区分"派生值"与"原始值",不假装两者是同一件事。
-    const inFragment = data.uncachedInputTokens !== undefined
-        ? `${formatMetricValue(data.uncachedInputTokens)} uncached in`
-        : usage?.inputTokens !== undefined
-            ? `${formatMetricValue(usage.inputTokens)} in`
-            : undefined;
+    // 桶恒互斥,inputTokens 就是未缓存输入;"uncached" 标注只在 cache 拆分真实在场时给,
+    // cache 桶缺席的数字不贴标注——不给没有拆分事实的数字暗示拆分。
+    const inFragment = usage?.inputTokens !== undefined
+        ? usage.cacheReadTokens !== undefined
+            ? `${formatMetricValue(usage.inputTokens)} uncached in`
+            : `${formatMetricValue(usage.inputTokens)} in`
+        : undefined;
     const cacheFragment = usage?.cacheReadTokens !== undefined ? `${formatMetricValue(usage.cacheReadTokens)} cache read` : undefined;
     const outFragment = usage?.outputTokens !== undefined ? `${formatMetricValue(usage.outputTokens)} out` : undefined;
     const inCache = [inFragment, cacheFragment].filter((s) => s !== undefined).join(" + ");

package/dist/report/components/attempt-detail/index.js

@@ -596,9 +596,6 @@ export function validateUsageData(data) {
         if (usageProb !== null)
             return usageProb;
     }
-    if (data.uncachedInputTokens !== undefined && typeof data.uncachedInputTokens !== "number") {
-        return '"uncachedInputTokens" must be a number';
-    }
     if (data.estimatedCostUSD !== undefined && typeof data.estimatedCostUSD !== "number") {
         return '"estimatedCostUSD" must be a number';
     }

package/dist/report/components/metric-views/compute.js

@@ -283,7 +283,7 @@ export async function metricLineData(input, options) {
                 "Fix of() to read experiment-level configuration (numericFlag()/numericRunConfig() do this by construction).");
         }
         const series = options.series ? seriesKey(options.series, item) : undefined;
-        const bucketKey = `${series ?? ""}${x === null ? "null" : String(x)}`;
+        const bucketKey = `${series ?? ""}\u0000${x === null ? "null" : String(x)}`;
         const bucket = buckets.get(bucketKey);
         if (bucket)
             bucket.items.push(item);

package/dist/report/model/types.d.ts

@@ -750,9 +750,9 @@ export interface AttemptDiagnosticsData {
  *
  * - `turns`/`toolCalls`:events 派生(与 `o11y.json` 行为摘要同源),只在有非空 events 时出现,
  *   哪怕派生值恰好是 0(有 events 但零轮/零工具调用是观测到的事实,不是缺失)。
- * - `usage`:落盘 `Usage` 原样,只在 `result.usage` 存在时出现。
- * - `uncachedInputTokens`:`usage.inputTokens − usage.cacheReadTokens`,只在两个输入都存在时派生;
- *   缺任一个不回退猜 0,整字段省略(text 面回退显示原始 `inputTokens`)。
+ * - `usage`:落盘 `Usage` 原样,只在 `result.usage` 存在时出现。桶恒互斥,`inputTokens` 本身
+ *   就是未缓存输入(契约见 docs/feature/results/architecture.md#usage);"uncached in" 标注只在
+ *   `cacheReadTokens` 在场时由 face 层给出,不派生第二个字段。
  * - `estimatedCostUSD`:能算出成本(`usage.costUSD` 或 `result.estimatedCostUSD`)时才出现。
  *
  * `turns`/`toolCalls`/`usage` 三者全部缺失时(没有 events 也没有落盘 usage)整个 data 为
@@ -767,7 +767,6 @@ export interface UsageTableData {
     turns?: number;
     toolCalls?: number;
     usage?: Usage;
-    uncachedInputTokens?: number;
     estimatedCostUSD?: number;
 }
 /** `AttemptTrace` 的 data:不与 runner 节点合并的原始 OTel span 列表;没有 trace 时 null。 */

package/dist/results/select.d.ts

@@ -87,6 +87,12 @@ export declare function dedupeAttempts(attempts: AttemptHandle[]): {
 };
 /** 快照新旧比较:startedAt 优先,同刻按快照目录名(时间戳 + 随机后缀,字典序即时序)。 */
 export declare function isNewerSnapshot(a: Snapshot, b: Snapshot): boolean;
+/**
+ * isNewerSnapshot 的原始口径,供还没组装成 Snapshot 的读取面共用同一判定(收窄读
+ * `loadLatestResultsForCase` 只拿到目录名 + snapshot.json 的 startedAt)。同一份磁盘在两条
+ * 读取面上必须给出同一个「哪份最新」的答案,否则携带与报告会分叉。
+ */
+export declare function isNewerSnapshotPlacement(a: Pick<Snapshot, "startedAt" | "dir">, b: Pick<Snapshot, "startedAt" | "dir">): boolean;
 /**
  * experiment 选择器过滤(--exp / latest({ experiments }) 同一语义,与 `niceeval exp` 位置参数
  * 共用 matchExperimentSelector,见 docs/feature/experiments/cli.md「实验选择器怎样解析」);

package/dist/results/select.js

@@ -317,6 +317,14 @@ export function dedupeAttempts(attempts) {
 }
 /** 快照新旧比较:startedAt 优先,同刻按快照目录名(时间戳 + 随机后缀,字典序即时序)。 */
 export function isNewerSnapshot(a, b) {
+    return isNewerSnapshotPlacement(a, b);
+}
+/**
+ * isNewerSnapshot 的原始口径,供还没组装成 Snapshot 的读取面共用同一判定(收窄读
+ * `loadLatestResultsForCase` 只拿到目录名 + snapshot.json 的 startedAt)。同一份磁盘在两条
+ * 读取面上必须给出同一个「哪份最新」的答案,否则携带与报告会分叉。
+ */
+export function isNewerSnapshotPlacement(a, b) {
     const byStart = a.startedAt.localeCompare(b.startedAt);
     if (byStart !== 0)
         return byStart > 0;

package/dist/runner/feedback/sink.d.ts

@@ -7,8 +7,13 @@ import type { AttemptLocator } from "../../results/locator.ts";
 export interface DiagnosticInput {
     /** 稳定去重 key —— 同一种 warning/error 用同一个 key(见 cli.md「同一 dedupeKey 并发出现时
      *  只留一条并显示次数」),不要把可变的实例细节(如具体 sandbox id)编进 key 本身,
-     *  那些细节放 `data`。 */
+     *  那些细节放 `data`。折叠身份(实验 / eval)可以编进 key,那是「折叠到多细」的表达;
+     *  对外展示的稳定词由 `code` 单独给,不从 key 反推。 */
     key: string;
+    /** 对外的稳定词法:`--json` 的 `warning.code`、human 诊断行的标题都读它(见 cli.md
+     *  `WarningEvent`,如 `lock-taken-over` / `dispatch-halted`)。省略 = 与 `key` 相同——
+     *  折叠身份不进 key 的那些诊断天生就是干净字面量,不必重复写一遍。 */
+    code?: string;
     severity: "warning" | "error";
     /** 一句话人类可读摘要;renderer 的 appendDurable 直接展示,不需要再解析。 */
     message: string;
@@ -52,6 +57,21 @@ export interface PrecheckInput {
     status: "started" | "done";
     durationMs?: number;
 }
+/** `sink.lockWait()` 的输入 —— 与 `DurableFeedbackEvent` 的 "lock-wait" 变体字段一致,省略
+ *  `type`/`at`(由 coordinator 补上)。调用方(run.ts)只在真正探测到撞上新鲜锁、需要等待时才
+ *  调一次 "started"(取锁立即成功或接管成功都不调用这个函数);等待解决(锁释放/接管后重查
+ *  携带完毕)时调一次 "resolved"。 */
+export interface LockWaitInput {
+    experimentId: string;
+    evalId: string;
+    status: "started" | "resolved";
+    holderPid?: number;
+    holderHost?: string;
+    attempts?: number;
+    carried?: number;
+    dispatched?: number;
+    waitedMs?: number;
+}
 /** `sink.kept()` 的输入 —— 与 `DurableFeedbackEvent` 的 "kept" 变体字段一致,省略 type/at。 */
 export interface KeptInput {
     locator: AttemptLocator;
@@ -84,6 +104,8 @@ export interface FeedbackSink {
     experimentHook(input: ExperimentHookInput): void;
     /** judge 预检的起止(见 `PrecheckInput`)。整次运行至多一次,发生在任何 attempt 派发之前。 */
     precheck(input: PrecheckInput): void;
+    /** 用例锁等待的起止(见 `LockWaitInput`)。 */
+    lockWait(input: LockWaitInput): void;
     /** 实验级 `ctx.progress` 的短命投影:只更新运行级行的 detail。与 `lifecycle` 同级别的
      *  「只服务正在画着的 dashboard」信号,没有活跃 coordinator 时静默丢弃是安全的。 */
     experimentProgress(input: ExperimentProgressInput): void;
@@ -123,6 +145,9 @@ export declare function reportExperimentProgress(input: ExperimentProgressInput)
 /** judge 预检的起止(见 `PrecheckInput`)。没有活跃 coordinator 时退回一行 stderr ——
  *  慢预检的可见性正是这条通道存在的理由,不能像 lifecycle 那样静默丢弃。 */
 export declare function reportPrecheck(input: PrecheckInput): void;
+/** 用例锁等待的起止(见 `LockWaitInput`)。没有活跃 coordinator 时退回一行 stderr ——
+ *  长等待期间的可见性正是这条通道存在的理由,不能像 lifecycle 那样静默丢弃。 */
+export declare function reportLockWait(input: LockWaitInput): void;
 export declare function reportBudgetExhausted(input: BudgetExhaustedInput): void;
 /** 用户中断(Ctrl+C)。没有活跃 coordinator 时的兜底文案与迁移前的 `runner.interrupted` 完全
  *  相同 —— 调用方(run.ts)不再需要自己持有这段 i18n 文案。 */