niceeval 0.10.3-canary.2 → 0.10.3-canary.4

package/INDEX.md

@@ -26,6 +26,7 @@
 - `docs-site/zh/tutorials/dataset-fanout.mdx` — 数据驱动测试（dataset fan-out）：用多份数据运行同一套评估用例:从 .eval.ts 文件导出数组或 keyed record，将一套评估逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部数据集，并获得稳定 ID。
 - `docs-site/zh/tutorials/experiments.mdx` — 实验矩阵：用运行矩阵比较 agents 和 models:使用 NiceEval experiments 让同一批评估用例横跨多个 agents、models 和 flags，比较 pass rate、成本和延迟。
 - `docs-site/zh/tutorials/fixtures.mdx` — Sandbox Fixture：用任务评估 coding agents:用 .eval.ts 给 coding agent 准备隔离 workspace、发送真实任务，并用 Sandbox 文件、命令、diff 和 judge 验证结果。
+- `docs-site/zh/tutorials/local-iteration.mdx` — 本地批跑提速：复用一个热 Sandbox:用 --reuse-sandbox 让一批评估共用一个装好的 Sandbox 串行跑，把重复安装折成一次；并按生命周期把安装写对层，让每道题几乎立即开跑。
 - `docs-site/zh/tutorials/publish-report.mdx` — 通过 CI 发布报告:把经过 copySnapshots 大小预检的结果目录提交进仓库,CI 用一行 view --results 导出报告站;超大文件在 commit 前就会得到可执行错误。
 - `docs-site/zh/tutorials/quickstart.mdx` — 为你的 Agent 项目设置评估:安装 NiceEval，写三个文件，10 分钟内对你自己的应用跑通第一条评估用例。
 - `docs-site/zh/tutorials/reporters.mdx` — 把结果上报到 Braintrust 与其它目的地:用内置 reporters 把评估用例结果送到 Braintrust 实验、JUnit XML 或自定义目的地。

package/dist/agents/types.d.ts

@@ -1,6 +1,7 @@
 import type { DiagnosticInput, ProgressUpdate } from "../shared/types.ts";
 import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
 import type { Sandbox } from "../sandbox/types.ts";
+import type { TurnErrorClassifier } from "../context/turn-errors.ts";
 /**
  * 本地 stdio 形态的 MCP server:沙箱内起子进程,按 stdio 说 MCP 协议。
  * 与 {@link McpHttpServer} 按形状判别(有 `command` 的是 stdio,有 `url` 的是 HTTP)。
@@ -360,6 +361,13 @@ export interface Agent {
     /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */
     spanMapper?: SpanMapper;
     send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
+    /**
+     * 可选 turn 失败分类器:按重试安全性归类一次 send 失败(抛出或返回 `status: "failed"` 的
+     * Turn),返回 `undefined` 回落保守兜底。分类器只声明决策与诊断词,不影响重试策略(次数、
+     * 退避对所有 agent 一致);抛错按不可重试处理并被吞掉。形状与分类链、执行体时序见
+     * docs/feature/error-classification/architecture.md。
+     */
+    classifyTurnError?: TurnErrorClassifier;
     teardown?: AgentTeardown;
 }
 /** `defineSandboxAgent()` 的入参形状(见 src/define.ts)——`kind: "sandbox"` 由 define 固定填入,不由用户声明。 */
@@ -380,6 +388,8 @@ export interface SandboxAgentDef {
     spanMapper?: SpanMapper;
     /** 每轮一次:跑 prompt(fresh / resume)+ 解析成 events。 */
     send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
+    /** 可选 turn 失败分类器:见 `Agent.classifyTurnError`。 */
+    classifyTurnError?: TurnErrorClassifier;
     /** Sandbox 销毁前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),
      * 在 finally 里跑一次。 */
     teardown?: AgentTeardown;
@@ -402,6 +412,8 @@ export interface RemoteAgentDef {
     spanMapper?: SpanMapper;
     /** 每轮一次:把一轮 prompt 发给远程被测对象(HTTP/SDK 等),解析响应成 events。 */
     send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
+    /** 可选 turn 失败分类器:见 `Agent.classifyTurnError`。 */
+    classifyTurnError?: TurnErrorClassifier;
     /** 运行结束前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),
      * 在 finally 里跑一次。 */
     teardown?: AgentTeardown;

package/dist/context/turn-errors.d.ts

@@ -0,0 +1,49 @@
+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;
+};
+/** 一次 send 失败的两种浮出形态:`send()` 抛出异常,或返回 `status: "failed"` 的 Turn。 */
+export type TurnFailure = {
+    readonly type: "thrown";
+    readonly error: unknown;
+} | {
+    readonly type: "turn-failed";
+    readonly turn: Turn;
+};
+/**
+ * adapter 可选分类器:返回 `undefined` 表示「不认识,交给保守兜底」。分类器必须快、纯、
+ * 不抛错——执行体按「抛错等价于不可重试」处理,自身错误被吞掉,不会掩盖原始失败。
+ */
+export type TurnErrorClassifier = (failure: TurnFailure) => TurnErrorClass | undefined;
+/**
+ * 失败 Turn 的错误摘要:取 `events` 里最后一个 `type: "error"` 事件的 message。
+ * 与 `context.turnFailed` 报错文案、保守兜底分类器读的同一段文本同源——不出现
+ * 「报错说 A、分类看 B」。没有 error 事件(status: "failed" 但 adapter 没吐错误事件)时
+ * 返回 `undefined`。
+ */
+export declare function turnErrorText(turn: Turn): string | undefined;
+/** 两种 `TurnFailure` 形态统一取「给人读也给分类器看」的那段文本。 */
+export declare function turnFailureText(failure: TurnFailure): string;
+/**
+ * 保守兜底分类器:三道分类链里的第二道。对失败文本做正则匹配,认不出的一律 `{ retryable: false }`
+ * ——宁可判死一个 attempt,不产出不可信的 verdict(判据见 README「分类」)。
+ */
+export declare function classifyTurnError(failure: TurnFailure): TurnErrorClass;
+/** 受理证据门:失败 Turn 的 events 里已出现任何 agent 侧产出,即证明 agent 已受理并开始工作。 */
+export declare function hasAgentEvidence(turn: Turn): boolean;
+/**
+ * 三道分类链的完整决议:adapter 分类器(可选,抛错按不可重试处理并吞掉)→ 保守兜底 →
+ * 受理证据门(否决权,失败 Turn 带 agent 产出事件时强制降级)。执行体只需要调这一个函数,
+ * 不必自己拼三道链的顺序。
+ */
+export declare function resolveTurnErrorClass(failure: TurnFailure, adapterClassifier?: TurnErrorClassifier): TurnErrorClass;

package/dist/context/types.d.ts

@@ -94,26 +94,40 @@ export interface DiffView {
     /** 正则是否命中 diff 里任意文件的路径或内容。 */
     matches(re: RegExp): boolean;
 }
-/** 工具匹配小语言。 */
+/**
+ * 工具匹配小语言。一条调用的全部可断面——入参、次数、输出、状态——都在这一个对象里表达:
+ * `input` / `output` / `status` 之间是 AND,且作用在同一笔调用上;`count` 数的是满足这些
+ * 条件的调用笔数,不存在「一笔满足 input、另一笔满足 output」也算命中的读法。
+ */
 export interface ToolMatch {
     /**
-     * 只匹配入参包含这些键值的调用:**深度部分匹配**——嵌套对象逐键下钻,数组按值比较;
-     * 值可以是 RegExp(对字符串字段测试,不命中时再对整个 input 的序列化串兜底测一次)
-     * 或谓词函数。不要求深度相等,多余的入参键不影响命中。
+     * 入参匹配:对象做**深度部分匹配**(写出的键值要求出现且相等,未写的忽略,嵌套递归比较;
+     * 值位置可以放 RegExp 匹配该字段的字符串值,不命中时再对整个 input 的序列化串兜底测一次,
+     * 或放谓词函数拿该字段原始值判断);顶层直接给 RegExp 则匹配序列化后的**完整输入**;
+     * 顶层给谓词函数 `(input) => boolean` 拿原始输入值自行判断。三种顶层形态互斥,不会退化
+     * 成深比对——RegExp / 函数不是"键值对象",不会被当成 plain object 逐键枚举。
      */
-    input?: Record<string, unknown>;
-    /** 精确匹配调用次数,省略则只要求「至少一次」。 */
-    count?: number;
-    /** 只匹配处于该状态的调用(如 HITL 场景下的 rejected)。 */
-    status?: "completed" | "failed" | "rejected";
+    input?: Record<string, unknown> | RegExp | ((input: unknown) => boolean);
+    /** 数字精确匹配调用次数;谓词对命中次数自行判定(如 `(n) => n >= 2`);省略则只要求「至少一次」。 */
+    count?: number | ((n: number) => boolean);
+    /**
+     * 输出匹配,值语义同 `input` 的值位置:RegExp 对字符串输出测试(非字符串先序列化再测);
+     * 谓词函数拿原始输出自行判断;对象做深度部分匹配;其余值严格相等。
+     */
+    output?: unknown;
+    /** 只匹配处于该状态的调用。`pending` 是已发起、尚无结果的调用——典型是 HITL 停在审批上的那一笔。 */
+    status?: "pending" | "completed" | "failed" | "rejected";
 }
 /** calledSubagent 的匹配小语言,语义同 ToolMatch。 */
 export interface SubagentMatch {
-    /** 精确匹配调用次数,省略则只要求「至少一次」。 */
-    count?: number;
-    status?: "completed" | "failed";
-    /** 只匹配指向该远程地址的子 agent 调用。 */
-    remoteUrl?: string | RegExp;
+    /** 数字精确匹配调用次数;谓词对命中次数自行判定;省略则只要求「至少一次」。 */
+    count?: number | ((n: number) => boolean);
+    /** 子 agent 委派没有 rejected 状态(subagent.completed 只报 completed / failed)。 */
+    status?: "pending" | "completed" | "failed";
+    /** 只匹配指向该远程地址的子 agent 调用:字符串精确匹配、RegExp 测试、或谓词函数自行判断。 */
+    remoteUrl?: string | RegExp | ((url: string) => boolean);
+    /** 匹配子 agent 的返回,值语义同 ToolMatch.output。 */
+    output?: unknown;
 }
 /** requireInputRequest 的过滤条件;多个字段之间是 AND 关系。 */
 export interface InputRequestFilter {
@@ -252,8 +266,10 @@ export interface TestContext {
     /** 取默认会话里等待中的 HITL 输入请求;不传 filter 要求恰好一条,拿不到就抛。 */
     requireInputRequest(filter?: InputRequestFilter): InputRequest;
     /**
-     * 回答默认会话里等待中的输入请求,返回续接的 TurnHandle。字符串形式按顺序对应各请求;
-     * 多个请求并停、需要指名回答哪一条时用 RespondAnswer 对象形式(见其类型注释)。
+     * 回答默认会话里等待中的输入请求,返回续接的 TurnHandle。字符串形式只在恰好一条待处理请求时
+     * 才能自动对位——命中该请求 `options` 里的某个 id 就是 `optionId`,否则整句落自由文本;
+     * 多个请求并停时字符串形式无法消歧,直接抛 `hitl.stringAmbiguous`,要求改用
+     * `{ request, optionId }` / `{ request, text }` 对象形式(RespondAnswer,见其类型注释)显式指名。
      */
     respond(...responses: (string | RespondAnswer)[]): Promise<TurnHandle>;
     /** 用同一个 optionId 批量回答默认会话里全部等待中的输入请求。 */

package/dist/i18n/en.d.ts

@@ -238,6 +238,9 @@ export declare const en: {
     "session.tools": string;
     "session.turn.primary": string;
     "session.turn.secondary": string;
+    "session.turnRetry": string;
+    "session.turnRetryBudgetExhausted": string;
+    "session.turnRetrySendExhausted": string;
     "util.requiredEnv": string;
     "vercel.fileNotFound": string;
     "vercel.rotateFailed": string;

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

@@ -238,6 +238,9 @@ export declare const zhCN: {
     readonly "session.tools": "{{count}} 工具";
     readonly "session.turn.primary": "第{{turn}}轮";
     readonly "session.turn.secondary": "会话{{session}}·第{{turn}}轮";
+    readonly "session.turnRetry": "turn 重试 {{attempt}}/{{maxAttempts}}({{reason}})——等待 {{seconds}}s";
+    readonly "session.turnRetryBudgetExhausted": " · attempt 重试预算已耗尽({{maxRetries}} 次重试,{{reason}})";
+    readonly "session.turnRetrySendExhausted": " · 重试已耗尽({{maxAttempts}} 次尝试,{{reason}})";
     readonly "util.requiredEnv": "缺少必需的环境变量 {{name}}(请在 .env 里配置)。";
     readonly "vercel.fileNotFound": "File not found: {{path}}";
     readonly "vercel.rotateFailed": "[VercelSandbox] session rotate failed ({{seconds}}s): {{error}}";

package/dist/o11y/execution-tree.d.ts

@@ -18,6 +18,16 @@ export interface ExecutionThinkingNode extends ExecutionNodeBase {
     kind: "thinking";
     text: string;
 }
+/**
+ * 被测系统内部机制注入进上下文的文本,不属于任何一方"说的话",不并进 `message`
+ * (见 docs/feature/adapters/architecture/events.md「不变量 9」)。与 thinking / compaction
+ * 同一档次的直通节点,不参与 callId 关联。
+ */
+export interface ExecutionContextInjectedNode extends ExecutionNodeBase {
+    kind: "context.injected";
+    text: string;
+    source?: string;
+}
 /** Skill 加载节点——一等,直接来自 StreamEvent 的 "skill.loaded",不靠工具名/文本猜。 */
 export interface ExecutionSkillNode extends ExecutionNodeBase {
     kind: "skill.loaded";
@@ -79,7 +89,7 @@ export interface ExecutionTelemetryNode {
     id: string;
     span: TraceSpan;
 }
-export type ExecutionNode = ExecutionMessageNode | ExecutionThinkingNode | ExecutionSkillNode | ExecutionActionNode | ExecutionSubagentNode | ExecutionInputRequestedNode | ExecutionCompactionNode | ExecutionErrorNode | ExecutionTelemetryNode;
+export type ExecutionNode = ExecutionMessageNode | ExecutionThinkingNode | ExecutionContextInjectedNode | ExecutionSkillNode | ExecutionActionNode | ExecutionSubagentNode | ExecutionInputRequestedNode | ExecutionCompactionNode | ExecutionErrorNode | ExecutionTelemetryNode;
 export interface ExecutionTree {
     /**
      * 骨架节点在前,顺序 = 事件出现顺序;telemetry-only 节点(未能唯一关联的 span)

package/dist/o11y/types.d.ts

@@ -110,6 +110,16 @@ export type StreamEvent = {
     type: "thinking";
     text: string;
 }
+/**
+ * 被测系统内部注入的、不披着 `message` 外衣的上下文文本(如 Claude Code 的 SessionStart /
+ * UserPromptSubmit hook 在下一轮开始前前置进模型上下文的文本)。只承载带实际文本内容的注入;
+ * `source` 是可选的原始来源标记(如 hook 名),adapter 按各自协议原样透传,不强行归一到封闭枚举。
+ */
+ | {
+    type: "context.injected";
+    text: string;
+    source?: string;
+}
 /** 上下文被压缩/摘要(如超长会话截断历史);`reason` 是可选的压缩原因说明。 */
  | {
     type: "compaction";
@@ -120,21 +130,26 @@ export type StreamEvent = {
     type: "error";
     message: string;
 });
-/** core 从事件流折叠出的结构化事实(deriveRunFacts)。 */
+/**
+ * core 从事件流折叠出的结构化事实(deriveRunFacts)。折叠按 callId 把 called 与 result 对成一条
+ * 调用:配上 result 的取 result 的状态;只有 called、尚未等到 result 的调用状态是 `pending`——
+ * HITL 停在审批上的调用就以这个状态被断言,不是容错分支(见 docs/feature/adapters/architecture/events.md)。
+ */
 export interface ToolCall {
     callId: string;
     name: ToolName;
     originalName?: string;
     input: JsonValue;
     output?: JsonValue;
-    status: "completed" | "failed" | "rejected";
+    status: "pending" | "completed" | "failed" | "rejected";
 }
 export interface SubagentCall {
     callId: string;
     name: string;
     remoteUrl?: string;
     output?: JsonValue;
-    status: "completed" | "failed";
+    /** 子 agent 委派没有 rejected 状态(subagent.completed 只报 completed / failed)。 */
+    status: "pending" | "completed" | "failed";
 }
 export interface DerivedFacts {
     readonly toolCalls: readonly ToolCall[];
@@ -143,6 +158,8 @@ export interface DerivedFacts {
     readonly parked: boolean;
     readonly messageCount: number;
     readonly compactions: number;
+    /** 事件流里 `context.injected` 事件的次数;只回答存在性问题,不替代逐条读取原文。 */
+    readonly contextInjections: number;
 }
 /**
  * span 的【语义角色】,从 OTel GenAI 语义约定的 gen_ai.operation.name 归一而来

package/dist/report/components/entity-lists/AttemptList.d.ts

@@ -2,6 +2,23 @@ import type { ReactElement } from "react";
 import type { AttemptListItem } from "../../model/types.ts";
 import type { AttemptLocator } from "../../../results/locator.ts";
 import { type ReportLocale } from "../../model/locale.ts";
+/**
+ * 时效标注(`↩` + 紧凑时距):历史执行(携带,或跨快照拼入)才渲染,新执行不标——subdued
+ * 行内事实,不占框、不用警示色(docs/feature/reports/library/entity-lists.md「时效标注」)。
+ * web 面 hover 显示完整执行时刻;ExperimentList / EvalList / AttemptList 三处共用。
+ */
+export declare function HistoricalMark({ item, locale, }: {
+    item: Pick<AttemptListItem, "startedAt" | "historical">;
+    locale?: ReportLocale;
+}): ReactElement | null;
+/**
+ * Eval 父行的时效标注:全部 attempt 均为历史执行时,标最近一次执行(startedAt 最大)的时距;
+ * 新旧混合时父行不标,子行各自可见(docs/feature/reports/library/entity-lists.md「时效标注」)。
+ * EvalList 与 ExperimentList 的 Eval 父行共用。
+ */
+export declare function EvalHistoricalMark({ attempts, }: {
+    attempts: readonly Pick<AttemptListItem, "startedAt" | "historical">[];
+}): ReactElement | null;
 /**
  * locator + 判定符,AttemptList/EvalList/ExperimentList 共用。没有 target(当前报告没有
  * declare attempt-input page,也没有显式 attemptHref)时是纯文本,不生成空 href 或假链接

package/dist/report/components/entity-lists/AttemptList.js

@@ -1,8 +1,29 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { DEFAULT_REPORT_LOCALE, countText, localeText } from "../../model/locale.js";
 import { colorClassForKey } from "../../assets/colors.js";
-import { formatDurationMs, formatUSD, verdictMark } from "../../model/format.js";
+import { formatDurationMs, formatHistoricalGap, formatReportDateTime, formatUSD, verdictMark } from "../../model/format.js";
 import { cx } from "../shared.js";
+/**
+ * 时效标注(`↩` + 紧凑时距):历史执行(携带,或跨快照拼入)才渲染,新执行不标——subdued
+ * 行内事实,不占框、不用警示色(docs/feature/reports/library/entity-lists.md「时效标注」)。
+ * web 面 hover 显示完整执行时刻;ExperimentList / EvalList / AttemptList 三处共用。
+ */
+export function HistoricalMark({ item, locale = DEFAULT_REPORT_LOCALE, }) {
+    if (!item.historical)
+        return null;
+    return (_jsxs("span", { className: "nre-historical", title: formatReportDateTime(item.startedAt, locale), children: ["\u21A9 ", formatHistoricalGap(item.startedAt)] }));
+}
+/**
+ * Eval 父行的时效标注:全部 attempt 均为历史执行时,标最近一次执行(startedAt 最大)的时距;
+ * 新旧混合时父行不标,子行各自可见(docs/feature/reports/library/entity-lists.md「时效标注」)。
+ * EvalList 与 ExperimentList 的 Eval 父行共用。
+ */
+export function EvalHistoricalMark({ attempts, }) {
+    if (attempts.length === 0 || !attempts.every((a) => a.historical))
+        return null;
+    const mostRecent = attempts.reduce((a, b) => (b.startedAt > a.startedAt ? b : a));
+    return _jsxs("span", { className: "nre-historical", children: ["\u21A9 ", formatHistoricalGap(mostRecent.startedAt)] });
+}
 /**
  * locator + 判定符,AttemptList/EvalList/ExperimentList 共用。没有 target(当前报告没有
  * declare attempt-input page,也没有显式 attemptHref)时是纯文本,不生成空 href 或假链接
@@ -24,7 +45,7 @@ export function failureSummaryText(item, locale) {
 /** 一条 Attempt 的比较卡片;完整 assertions 通过 locator 下钻,不在列表内展开。 */
 export function AttemptRow({ item, attemptHref, locale = DEFAULT_REPORT_LOCALE, }) {
     const reason = failureSummaryText(item, locale);
-    return (_jsxs("li", { className: cx("nre-attempt", `nre-attempt-${item.verdict}`), "data-nre-verdict": item.verdict, children: [_jsxs("div", { className: "nre-attempt-head", children: [_jsx(AttemptLocatorBadge, { item: item, attemptHref: attemptHref }), _jsx("span", { className: "nre-attempt-eval", children: item.evalId }), _jsx("span", { className: "nre-attempt-experiment", children: item.experimentId }), _jsx("span", { className: cx("nre-attempt-agent", "nre-key", colorClassForKey(item.agent)), children: item.agent }), _jsx("span", { className: "nre-attempt-duration", children: formatDurationMs(item.durationMs) }), item.costUSD !== null && _jsx("span", { className: "nre-attempt-cost", children: formatUSD(item.costUSD) })] }), reason && _jsx("p", { className: "nre-attempt-result", children: reason })] }));
+    return (_jsxs("li", { className: cx("nre-attempt", `nre-attempt-${item.verdict}`), "data-nre-verdict": item.verdict, children: [_jsxs("div", { className: "nre-attempt-head", children: [_jsx(AttemptLocatorBadge, { item: item, attemptHref: attemptHref }), _jsx(HistoricalMark, { item: item, locale: locale }), _jsx("span", { className: "nre-attempt-eval", children: item.evalId }), _jsx("span", { className: "nre-attempt-experiment", children: item.experimentId }), _jsx("span", { className: cx("nre-attempt-agent", "nre-key", colorClassForKey(item.agent)), children: item.agent }), _jsx("span", { className: "nre-attempt-duration", children: formatDurationMs(item.durationMs) }), item.costUSD !== null && _jsx("span", { className: "nre-attempt-cost", children: formatUSD(item.costUSD) })] }), reason && _jsx("p", { className: "nre-attempt-result", children: reason })] }));
 }
 export function AttemptList({ data, total, filter = false, attemptHref, className, locale = DEFAULT_REPORT_LOCALE, }) {
     const remaining = (total ?? data.length) - data.length;

package/dist/report/components/entity-lists/ExperimentList.js

@@ -1,7 +1,7 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { shortestUniqueLabels } from "../../model/format.js";
 import { DEFAULT_REPORT_LOCALE, localeText } from "../../model/locale.js";
-import { AttemptLocatorBadge, failureSummaryText } from "./AttemptList.js";
+import { AttemptLocatorBadge, EvalHistoricalMark, HistoricalMark, failureSummaryText } from "./AttemptList.js";
 import { MetricCellView } from "../cell.js";
 import { colorClassForKey } from "../../assets/colors.js";
 import { formatDurationMs, formatUSD, verdictMark } from "../../model/format.js";
@@ -35,12 +35,21 @@ function VerdictSummary({ item, locale }) {
 }
 function ExperimentAttemptRow({ attempt, last, attemptHref, locale, }) {
     const reason = failureSummaryText(attempt, locale);
-    return (_jsxs("li", { className: cx("nre-experiment-attempt-row", `nre-eval-${attempt.verdict}`), children: [_jsx("span", { className: "nre-attempt-branch", "aria-hidden": "true", children: last ? "└─" : "├─" }), _jsx("span", { className: "nre-eval-attempt-badges", children: _jsx(AttemptLocatorBadge, { item: attempt, attemptHref: attemptHref }) }), _jsxs("span", { className: "nre-eval-attempt-metrics", children: [formatDurationMs(attempt.durationMs), attempt.costUSD !== null && _jsxs(_Fragment, { children: [" \u00B7 ", formatUSD(attempt.costUSD)] })] }), _jsx("span", { className: "nre-eval-reason", children: reason ?? "—" })] }));
+    return (_jsxs("li", { className: cx("nre-experiment-attempt-row", `nre-eval-${attempt.verdict}`), children: [_jsx("span", { className: "nre-attempt-branch", "aria-hidden": "true", children: last ? "└─" : "├─" }), _jsxs("span", { className: "nre-eval-attempt-badges", children: [_jsx(AttemptLocatorBadge, { item: attempt, attemptHref: attemptHref }), _jsx(HistoricalMark, { item: attempt, locale: locale })] }), _jsxs("span", { className: "nre-eval-attempt-metrics", children: [formatDurationMs(attempt.durationMs), attempt.costUSD !== null && _jsxs(_Fragment, { children: [" \u00B7 ", formatUSD(attempt.costUSD)] })] }), _jsx("span", { className: "nre-eval-reason", children: reason ?? "—" })] }));
 }
 function EvalAttempts({ row, attemptHref, locale, }) {
     const duration = row.durationMs.value === null ? localeText(locale, "cell.missing") : formatDurationMs(row.durationMs.value);
     const cost = row.costUSD.value === null ? localeText(locale, "cell.missing") : formatUSD(row.costUSD.value);
-    return (_jsxs("li", { className: "nre-experiment-eval", children: [_jsxs("div", { className: cx("nre-experiment-eval-header", `nre-eval-${row.verdict}`), children: [_jsx("span", { className: cx("nre-eval-verdict", `nre-verdict-${row.verdict}`), children: verdictMark(row.verdict) }), _jsx("span", { className: "nre-eval-id", children: row.evalId }), _jsx("span", { className: "nre-eval-attempt-count", children: localeText(locale, "overview.attemptsCount", { n: row.attempts.length }) }), _jsxs("span", { className: "nre-eval-rollup", children: [localeText(locale, "entityList.average", { value: duration }), " · ", localeText(locale, "entityList.average", { value: cost })] })] }), _jsx("ul", { className: "nre-experiment-attempts", children: row.attempts.map((attempt, index) => (_jsx(ExperimentAttemptRow, { attempt: attempt, last: index === row.attempts.length - 1, attemptHref: attemptHref, locale: locale }, attempt.locator))) })] }));
+    return (_jsxs("li", { className: "nre-experiment-eval", children: [_jsxs("div", { className: cx("nre-experiment-eval-header", `nre-eval-${row.verdict}`), children: [_jsx("span", { className: cx("nre-eval-verdict", `nre-verdict-${row.verdict}`), children: verdictMark(row.verdict) }), _jsx("span", { className: "nre-eval-id", children: row.evalId }), _jsx(EvalHistoricalMark, { attempts: row.attempts }), _jsx("span", { className: "nre-eval-attempt-count", children: localeText(locale, "overview.attemptsCount", { n: row.attempts.length }) }), _jsxs("span", { className: "nre-eval-rollup", children: [localeText(locale, "entityList.average", { value: duration }), " · ", localeText(locale, "entityList.average", { value: cost })] })] }), _jsx("ul", { className: "nre-experiment-attempts", children: row.attempts.map((attempt, index) => (_jsx(ExperimentAttemptRow, { attempt: attempt, last: index === row.attempts.length - 1, attemptHref: attemptHref, locale: locale }, attempt.locator))) })] }));
+}
+/**
+ * 覆盖缺口的占位行:状态列为 —,结果列为「当前配置下无结果」+ 可复制的补跑命令,无 attempt
+ * 子行,不参与任何指标聚合——只把分母缺口摆进读者正在看的表里
+ * (docs/feature/reports/library/entity-lists.md「ExperimentList」)。
+ */
+function MissingEvalRow({ evalId, experimentId, locale, }) {
+    const command = `niceeval exp ${experimentId}`;
+    return (_jsx("li", { className: "nre-experiment-eval nre-experiment-eval-missing", children: _jsxs("div", { className: "nre-experiment-eval-header", children: [_jsx("span", { className: "nre-eval-verdict", children: "\u2014" }), _jsx("span", { className: "nre-eval-id", children: evalId }), _jsxs("span", { className: "nre-eval-rollup", children: [localeText(locale, "experimentList.noResultsForConfig"), " \u00B7 ", _jsx("code", { children: command })] })] }) }));
 }
 function Flags({ flags, locale }) {
     if (!flags || Object.keys(flags).length === 0)
@@ -48,7 +57,14 @@ function Flags({ flags, locale }) {
     return (_jsxs("div", { className: "nre-experiment-flags", children: [_jsx("span", { children: localeText(locale, "experimentList.flags") }), Object.entries(flags).map(([key, value]) => (_jsxs("b", { children: [key, "=", typeof value === "string" ? value : JSON.stringify(value)] }, key)))] }));
 }
 function ExperimentRow({ item, label, attemptHref, locale, }) {
-    return (_jsxs("details", { className: "nre-experiment-entry", children: [_jsxs("summary", { className: "nre-experiment-summary", children: [_jsxs("span", { className: "nre-experiment-name", "data-sort-value": item.experimentId, children: [_jsx("b", { className: cx("nre-experiment-id", "nre-key"), children: label }), _jsxs("small", { children: [localeText(locale, "overview.evalsCount", { n: item.evals }), item.attempts > item.evals ? ` · ${localeText(locale, "overview.attemptsCount", { n: item.attempts })}` : "", ` · ${formatDate(item.lastRunAt, locale)}`] })] }), _jsx("span", { "data-sort-value": item.model ?? "", children: item.model ?? localeText(locale, "experimentList.defaultModel") }), _jsx("span", { "data-sort-value": item.agent, children: _jsx("span", { className: cx("nre-experiment-agent", "nre-key", colorClassForKey(item.agent)), children: item.agent }) }), _jsx("span", { className: "nre-num", "data-sort-value": item.durationMs.value ?? "", children: _jsx(MetricCellView, { cell: item.durationMs, locale: locale }) }), _jsx("span", { className: cx("nre-num", passRateTone(item.endToEndPassRate.value)), "data-sort-value": item.endToEndPassRate.value ?? "", children: _jsx(MetricCellView, { cell: item.endToEndPassRate, locale: locale }) }), _jsx("span", { className: "nre-num", "data-sort-value": item.tokens.value ?? "", children: _jsx(MetricCellView, { cell: item.tokens, locale: locale }) }), _jsx("span", { className: "nre-num", "data-sort-value": item.costUSD.value ?? "", children: _jsx(MetricCellView, { cell: item.costUSD, locale: locale }) }), _jsx("span", { "data-sort-value": item.evalVerdicts.passed, children: _jsx(VerdictSummary, { item: item, locale: locale }) })] }), _jsxs("div", { className: "nre-experiment-detail", children: [_jsx(Flags, { flags: item.flags, locale: locale }), _jsx("ul", { className: "nre-experiment-evals", children: item.evalRows.map((row) => (_jsx(EvalAttempts, { row: row, attemptHref: attemptHref, locale: locale }, row.evalId))) })] })] }));
+    return (_jsxs("details", { className: "nre-experiment-entry", children: [_jsxs("summary", { className: "nre-experiment-summary", children: [_jsxs("span", { className: "nre-experiment-name", "data-sort-value": item.experimentId, children: [_jsx("b", { className: cx("nre-experiment-id", "nre-key"), children: label }), _jsxs("small", { children: [item.missingEvalIds.length > 0
+                                        ? localeText(locale, "overview.evalsCountPartial", {
+                                            covered: item.evals,
+                                            total: item.evals + item.missingEvalIds.length,
+                                        })
+                                        : localeText(locale, "overview.evalsCount", { n: item.evals }), item.attempts > item.evals ? ` · ${localeText(locale, "overview.attemptsCount", { n: item.attempts })}` : "", item.historicalAttempts > 0
+                                        ? ` · ${localeText(locale, "experimentList.historicalAttempts", { n: item.historicalAttempts, m: item.attempts })}`
+                                        : "", ` · ${formatDate(item.lastRunAt, locale)}`] })] }), _jsx("span", { "data-sort-value": item.model ?? "", children: item.model ?? localeText(locale, "experimentList.defaultModel") }), _jsx("span", { "data-sort-value": item.agent, children: _jsx("span", { className: cx("nre-experiment-agent", "nre-key", colorClassForKey(item.agent)), children: item.agent }) }), _jsx("span", { className: "nre-num", "data-sort-value": item.durationMs.value ?? "", children: _jsx(MetricCellView, { cell: item.durationMs, locale: locale }) }), _jsx("span", { className: cx("nre-num", passRateTone(item.endToEndPassRate.value)), "data-sort-value": item.endToEndPassRate.value ?? "", children: _jsx(MetricCellView, { cell: item.endToEndPassRate, locale: locale }) }), _jsx("span", { className: "nre-num", "data-sort-value": item.tokens.value ?? "", children: _jsx(MetricCellView, { cell: item.tokens, locale: locale }) }), _jsx("span", { className: "nre-num", "data-sort-value": item.costUSD.value ?? "", children: _jsx(MetricCellView, { cell: item.costUSD, locale: locale }) }), _jsx("span", { "data-sort-value": item.evalVerdicts.passed, children: _jsx(VerdictSummary, { item: item, locale: locale }) })] }), _jsxs("div", { className: "nre-experiment-detail", children: [_jsx(Flags, { flags: item.flags, locale: locale }), _jsxs("ul", { className: "nre-experiment-evals", children: [item.evalRows.map((row) => (_jsx(EvalAttempts, { row: row, attemptHref: attemptHref, locale: locale }, row.evalId))), item.missingEvalIds.map((evalId) => (_jsx(MissingEvalRow, { evalId: evalId, experimentId: item.experimentId, locale: locale }, evalId)))] })] })] }));
 }
 export function ExperimentList({ data, attemptHref, filter = false, className, locale = DEFAULT_REPORT_LOCALE, }) {
     const experimentLabels = shortestUniqueLabels(data.map((item) => item.experimentId));

package/dist/report/components/entity-lists/compute.js

@@ -8,7 +8,7 @@
 // - core 中立:只认 Metric / Dimension 接口,不出现具体 agent 名的分支。
 import { comparabilityConfigOf, deepEqualJson } from "../../../results/select.js";
 import { foldEvalVerdict } from "../../../shared/verdict.js";
-import { collectItems, computeCell, evalIdOf, experimentIdOf, fullEvalKey, groupItems, locatorOf, resolveInput, } from "../../model/aggregate.js";
+import { collectItems, computeCell, evalIdOf, experimentIdOf, fullEvalKey, groupItems, historicalOf, locatorOf, resolveInput, } from "../../model/aggregate.js";
 import { attemptCostUSD, costUSD, durationMs, endToEndPassRate, examScore, tokens } from "../../model/metrics.js";
 import { compactAssertionSummary, primaryAssertionSummary, summaryText } from "../../../scoring/display.js";
 import { selectedEvalsOnly, summarizeItems } from "../shared-compute.js";
@@ -52,6 +52,11 @@ async function attemptListItemOf(item) {
         examScore: await computeCell(examScore, [item]),
         durationMs: result.durationMs,
         costUSD: attemptCostUSD(result),
+        // 缺 startedAt(legacy / 第三方落盘)时退化到所属快照的 startedAt——时效标注宁可粗一档
+        // 时距,不留空字段(与 dedupeAttempts「缺才不去重」同一条「不伪造」纪律,这里伪造的只是
+        // 展示粒度,不影响身份判定)。
+        startedAt: result.startedAt ?? item.snapshot.startedAt,
+        historical: historicalOf(item),
         locator: locatorOf(item),
     };
 }
@@ -100,8 +105,9 @@ export async function evalListData(input) {
  * 看跨配置演化用 snapshot 维度或 MetricLine,不把两套配置拼成一行冒充单一配置。
  */
 export async function experimentListData(input) {
-    const { snapshots: rawSnapshots } = resolveInput(input);
+    const { snapshots: rawSnapshots, coverage } = resolveInput(input);
     const snapshots = selectedEvalsOnly(rawSnapshots);
+    const coverageByExperiment = new Map(coverage.map((c) => [c.experimentId, c]));
     // 可比性配置单义检查:同一 experiment 的输入快照必须共享一套可比性配置。
     const configByExperiment = new Map();
     for (const snapshot of snapshots) {
@@ -151,6 +157,8 @@ export async function experimentListData(input) {
             tokens: await computeCell(tokens, group),
             evals: stats.evals,
             attempts: stats.attempts,
+            historicalAttempts: group.filter(historicalOf).length,
+            missingEvalIds: coverageByExperiment.get(experimentId)?.missingEvalIds ?? [],
             lastRunAt: stats.lastRunAt,
             evalRows,
         });

package/dist/report/components/entity-lists/faces.js

@@ -3,7 +3,7 @@
 // locator,中间不留空格)。ExperimentList / EvalList 逐 attempt 只列这一个标记 + 各自的
 // 摘要,不重复整段 niceeval show 命令;要看某个 attempt 的完整证据,agent 自己拼
 // `niceeval show <locator>`。零 react、零 IO、纯同步。
-import { fitFailureSummary, formatDurationMs, formatUSD, shortestUniqueLabels, verdictMark, } from "../../model/format.js";
+import { fitFailureSummary, formatDurationMs, formatHistoricalGap, formatUSD, shortestUniqueLabels, verdictMark, } from "../../model/format.js";
 import { countText, localeText } from "../../model/locale.js";
 import { stringWidth, wrapDisplay } from "../../model/text-layout.js";
 import { renderTableText } from "../../definition/table-text.js";
@@ -16,6 +16,21 @@ import { cellText, missingText, verdictTallyText, MISSING_MARK } from "../shared
 function locatorBadge(item) {
     return `${item.locator}${verdictMark(item.verdict)}`;
 }
+/**
+ * 时效标注(`↩` + 紧凑时距)的 text 面:历史执行(携带,或跨快照拼入)才输出,新执行为
+ * 空串;三面(ExperimentList / EvalList / AttemptList)共用
+ * (docs/feature/reports/library/entity-lists.md「时效标注」)。
+ */
+function historicalSuffix(item) {
+    return item.historical ? `   ↩ ${formatHistoricalGap(item.startedAt)}` : "";
+}
+/** Eval 父行的时效标注:全部 attempt 均为历史执行时,标最近一次执行的时距;新旧混合不标。 */
+function evalHistoricalSuffix(attempts) {
+    if (attempts.length === 0 || !attempts.every((a) => a.historical))
+        return "";
+    const mostRecent = attempts.reduce((a, b) => (b.startedAt > a.startedAt ? b : a));
+    return `   ↩ ${formatHistoricalGap(mostRecent.startedAt)}`;
+}
 /**
  * failureSummary + moreFailures 的展示形态:摘要在计算侧已按 Scoring display 契约折好,
  * 这里只加 "+N more failures" 计数与宽度收口,不重算摘要。
@@ -55,7 +70,23 @@ function experimentSummaryTable(items, ctx, labels) {
             cost: cellText(item.costUSD, locale),
         },
     }));
-    const metadata = items.flatMap((item) => wrapDisplay(`${labels.get(item.experimentId) ?? item.experimentId}: ${localeText(locale, "overview.evalsCount", { n: item.evals })} · ${localeText(locale, "overview.attemptsCount", { n: item.attempts })} · ${item.lastRunAt}`, Math.max(8, ctx.width - 2)).map((line) => `  ${line}`));
+    const metadata = items.flatMap((item) => {
+        const evalsText = item.missingEvalIds.length > 0
+            ? localeText(locale, "overview.evalsCountPartial", {
+                covered: item.evals,
+                total: item.evals + item.missingEvalIds.length,
+            })
+            : localeText(locale, "overview.evalsCount", { n: item.evals });
+        const parts = [
+            evalsText,
+            localeText(locale, "overview.attemptsCount", { n: item.attempts }),
+            ...(item.historicalAttempts > 0
+                ? [localeText(locale, "experimentList.historicalAttempts", { n: item.historicalAttempts, m: item.attempts })]
+                : []),
+            item.lastRunAt,
+        ];
+        return wrapDisplay(`${labels.get(item.experimentId) ?? item.experimentId}: ${parts.join(" · ")}`, Math.max(8, ctx.width - 2)).map((line) => `  ${line}`);
+    });
     return [renderTableText({ columns: columns, rows, locale }, ctx), metadata.join("\n")].join("\n");
 }
 function experimentDetailTable(item, ctx, label) {
@@ -80,7 +111,7 @@ function experimentDetailTable(item, ctx, label) {
             key: row.evalId,
             cells: {
                 status: `${verdictMark(row.verdict)} ${localeText(locale, `verdict.${row.verdict}`)}`,
-                entity: row.evalId,
+                entity: `${row.evalId}${evalHistoricalSuffix(row.attempts)}`,
                 result: "",
                 duration: localeText(locale, "entityList.average", { value: cellText(row.durationMs, locale) }),
                 cost: localeText(locale, "entityList.average", { value: cellText(row.costUSD, locale) }),
@@ -90,7 +121,7 @@ function experimentDetailTable(item, ctx, label) {
             key: attempt.locator,
             cells: {
                 status: `  ${verdictMark(attempt.verdict)}`,
-                entity: `${index === row.attempts.length - 1 ? "└─" : "├─"} ${attempt.locator}`,
+                entity: `${index === row.attempts.length - 1 ? "└─" : "├─"} ${attempt.locator}${historicalSuffix(attempt)}`,
                 result: attemptReasonText(attempt, locale, resultBudget) ?? MISSING_MARK,
                 duration: attempt.verdict === "skipped" && attempt.durationMs === 0 ? null : formatDurationMs(attempt.durationMs),
                 cost: attempt.costUSD === null ? null : formatUSD(attempt.costUSD),
@@ -98,6 +129,19 @@ function experimentDetailTable(item, ctx, label) {
         }));
         return [parent, ...attempts];
     });
+    // 覆盖缺口的占位行:状态列为 —,结果列为「当前配置下无结果」+ 可复制的补跑命令,
+    // 无 attempt 子行,duration/cost 留空(不参与任何指标聚合)。
+    const missingRows = item.missingEvalIds.map((evalId) => ({
+        key: evalId,
+        cells: {
+            status: MISSING_MARK,
+            entity: evalId,
+            result: `${localeText(locale, "experimentList.noResultsForConfig")} · niceeval exp ${item.experimentId}`,
+            duration: null,
+            cost: null,
+        },
+    }));
+    rows.push(...missingRows);
     const flags = item.flags && Object.keys(item.flags).length > 0
         ? `${localeText(locale, "experimentList.flags")} ${Object.entries(item.flags)
             .map(([key, value]) => `${key}=${typeof value === "string" ? value : JSON.stringify(value)}`)
@@ -124,14 +168,14 @@ export function experimentListText(items, ctx) {
 function evalListAttemptLine(item, ctx) {
     // 行式列表同守「Result 最多两行」:预算 = 两行终端宽,超出按尾截收口。
     const reason = attemptReasonText(item, ctx.locale, ctx.width * 2 - stringWidth(locatorBadge(item)) - 6);
-    return `  ${locatorBadge(item)}${reason ? ` · ${reason}` : ""}`;
+    return `  ${locatorBadge(item)}${historicalSuffix(item)}${reason ? ` · ${reason}` : ""}`;
 }
 export function evalListText(items, ctx) {
     const locale = ctx.locale;
     if (items.length === 0)
         return localeText(locale, "attemptList.empty");
     const blocks = items.map((item) => {
-        const identity = `${item.evalId} · ${item.experimentId} · ${localeText(locale, `verdict.${item.verdict}`)}`;
+        const identity = `${item.evalId}${evalHistoricalSuffix(item.attempts)} · ${item.experimentId} · ${localeText(locale, `verdict.${item.verdict}`)}`;
         const summary = [
             localeText(locale, "attemptList.score", { score: cellText(item.examScore, locale) }),
             localeText(locale, "overview.attemptsCount", { n: item.attempts.length }),
@@ -151,7 +195,7 @@ export function evalListText(items, ctx) {
 /** Attempt 比较卡片:只显示一条主失败摘要(至多两行终端宽);完整 assertions 走 locator 下钻。 */
 function attemptListItemText(item, ctx) {
     const head = [
-        `${verdictMark(item.verdict)} ${item.locator}`,
+        `${verdictMark(item.verdict)} ${item.locator}${historicalSuffix(item)}`,
         item.evalId,
         item.experimentId,
         formatDurationMs(item.durationMs),

package/dist/report/components/entity-lists/index.js

@@ -37,6 +37,10 @@ function attemptListItemProblem(value, path) {
         return `"${path}.durationMs" must be a number`;
     if (!(value.costUSD === null || typeof value.costUSD === "number"))
         return `"${path}.costUSD" must be a number or null`;
+    if (typeof value.startedAt !== "string")
+        return `"${path}.startedAt" must be a string`;
+    if (typeof value.historical !== "boolean")
+        return `"${path}.historical" must be a boolean`;
     if (typeof value.locator !== "string")
         return `"${path}.locator" must be a string`;
     return null;
@@ -67,6 +71,11 @@ export const validateExperimentListData = (data) => arrayProblem(data, "data", (
         return `"${path}.evals" must be a number`;
     if (typeof item.attempts !== "number")
         return `"${path}.attempts" must be a number`;
+    if (typeof item.historicalAttempts !== "number")
+        return `"${path}.historicalAttempts" must be a number`;
+    const missingProblem = arrayProblem(item.missingEvalIds, `${path}.missingEvalIds`, (id, idPath) => typeof id === "string" ? null : `"${idPath}" must be a string`);
+    if (missingProblem !== null)
+        return missingProblem;
     if (typeof item.lastRunAt !== "string")
         return `"${path}.lastRunAt" must be a string`;
     return arrayProblem(item.evalRows, `${path}.evalRows`, (row, rowPath) => {

package/dist/report/components/fixtures.d.ts

@@ -1,4 +1,4 @@
-import type { AttemptListItem, DeltaData, EvalListItem, ExperimentListItem, LineData, MatrixData, MetricColumn, ScatterData, ScopeSummaryData, ScoreboardData, TableData } from "../model/types.ts";
+import type { AttemptListItem, DeltaData, ExperimentListItem, LineData, MatrixData, MetricColumn, ScatterData, ScopeSummaryData, ScoreboardData, TableData } from "../model/types.ts";
 export declare const passRateColumn: MetricColumn;
 export declare const codeLinesColumn: MetricColumn;
 export declare const costColumn: MetricColumn;
@@ -11,5 +11,4 @@ export declare const scatterData: ScatterData;
 export declare const lineData: LineData;
 export declare const deltaData: DeltaData;
 export declare const attemptListItems: AttemptListItem[];
-export declare const evalListItems: EvalListItem[];
 export declare const experimentListItems: ExperimentListItem[];