niceeval 0.8.0 → 0.9.0

package/dist/report/scope-warnings.js

@@ -0,0 +1,101 @@
+// ScopeWarnings 的聚合层:把 Scope 警告按「下一步动作」组织成组,web / text 两面共用
+// (docs/feature/reports/library/site-components.md「聚合轴是动作,不是发生顺序」)。
+// message 是完整叙述的单源,这里只组织、不改写;徽标 / 组头文案按 kind 表登记的模板
+// (docs/feature/results/library.md「警告 kind 全集」)经 locale 词典渲染,未登记的 kind
+// 回退为单独成组、逐条 message 原样。
+import { gapParts } from "../results/select.js";
+import { localeText } from "./locale.js";
+const CATEGORY = {
+    "partial-coverage": "integrity",
+    "unfinished-snapshot": "integrity",
+    "unreadable-snapshot": "integrity",
+    "stale-snapshot": "freshness",
+};
+/** 实验作用域且登记了徽标模板的 kind 才进实验组;其余(含未登记 kind)按 kind 聚合。 */
+const EXPERIMENT_KINDS = new Set(["partial-coverage", "stale-snapshot", "unfinished-snapshot"]);
+function pluralText(locale, base, n) {
+    return localeText(locale, `${base}.${n === 1 ? "one" : "other"}`, { n });
+}
+/** 明细折叠块的标签(「N 条原始警告」)。 */
+export function warningDetailsLabel(locale, n) {
+    return pluralText(locale, "warnings.details", n);
+}
+function gapText(locale, fromIso, toIso) {
+    const { n, unit } = gapParts(fromIso, toIso);
+    return localeText(locale, `warnings.gap.${unit}.${n === 1 ? "one" : "other"}`, { n });
+}
+function badgeText(w, locale) {
+    switch (w.kind) {
+        case "partial-coverage":
+            return localeText(locale, "warnings.badge.partialCoverage", {
+                covered: String(w.covered),
+                total: String(w.total),
+            });
+        case "stale-snapshot":
+            return localeText(locale, "warnings.badge.staleSnapshot", {
+                gap: gapText(locale, String(w.startedAt), String(w.latestStartedAt)),
+            });
+        case "unfinished-snapshot":
+            return localeText(locale, "warnings.badge.unfinishedSnapshot");
+        default:
+            return null;
+    }
+}
+/** 组内命令去重:恰一条时它就是「复制即推进整组」的组头命令。 */
+function dedupeCommand(members) {
+    const commands = new Set(members.map((w) => w.command).filter((c) => typeof c === "string" && c !== ""));
+    return commands.size === 1 ? [...commands][0] : null;
+}
+function groupCategory(members) {
+    return members.some((w) => (CATEGORY[w.kind] ?? "integrity") === "integrity") ? "integrity" : "freshness";
+}
+export function groupScopeWarnings(input, locale) {
+    const warnings = input;
+    const byExperiment = new Map();
+    const byKind = new Map();
+    for (const w of warnings) {
+        if (EXPERIMENT_KINDS.has(w.kind) && typeof w.experimentId === "string") {
+            const members = byExperiment.get(w.experimentId) ?? [];
+            members.push(w);
+            byExperiment.set(w.experimentId, members);
+        }
+        else {
+            const members = byKind.get(w.kind) ?? [];
+            members.push(w);
+            byKind.set(w.kind, members);
+        }
+    }
+    const groups = [];
+    for (const [experimentId, members] of byExperiment) {
+        groups.push({
+            category: groupCategory(members),
+            title: experimentId,
+            badges: members
+                .map((w) => ({ kind: w.kind, text: badgeText(w, locale) }))
+                .filter((b) => b.text !== null),
+            headCommand: dedupeCommand(members),
+            warnings: members,
+        });
+    }
+    for (const [kind, members] of byKind) {
+        groups.push({
+            category: CATEGORY[kind] ?? "integrity",
+            title: kind === "unreadable-snapshot" ? pluralText(locale, "warnings.group.unreadableSnapshot", members.length) : kind,
+            badges: [],
+            headCommand: dedupeCommand(members),
+            warnings: members,
+        });
+    }
+    // 稳定排序:integrity 在前,同类别保持首次出现顺序。
+    const rank = (c) => (c === "integrity" ? 0 : 1);
+    groups.sort((a, b) => rank(a.category) - rank(b.category));
+    const parts = [];
+    if (byExperiment.size > 0)
+        parts.push(pluralText(locale, "warnings.summary.experiments", byExperiment.size));
+    for (const [kind, members] of byKind) {
+        parts.push(kind === "unreadable-snapshot"
+            ? pluralText(locale, "warnings.group.unreadableSnapshot", members.length)
+            : `${kind} ×${members.length}`);
+    }
+    return { summary: parts.join(" · "), groups, detailsOpen: warnings.length <= 3 };
+}

package/dist/report/text/faces.d.ts

@@ -1,4 +1,5 @@
-import type { AttemptListItem, DeltaData, EvalListItem, ExperimentComparisonData, ExperimentListItem, LineData, MatrixData, MetricCell, ScatterData, ScopeSummaryData, ScoreboardData, TableData, VerdictTally } from "../types.ts";
+import type { AttemptListItem, DeltaData, EvalListItem, ExperimentComparisonData, ExperimentListItem, HeroData, LineData, MatrixData, MetricCell, ScatterData, ScopeSummaryData, ScopeWarning, ScoreboardData, TableData, TraceWaterfallRow, VerdictTally } from "../types.ts";
+import type { LocalizedText } from "../locale.ts";
 import type { TextContext } from "../tree.ts";
 import { type ReportLocale } from "../locale.ts";
 /** 格子的文本形态:缺数据 —,覆盖不全带 samples/total 角标;display 按 locale 解析。 */
@@ -25,3 +26,20 @@ export declare function deltaText(data: DeltaData, ctx: TextContext): string;
 export declare function experimentListText(items: readonly ExperimentListItem[], ctx: TextContext, relativeTo?: string): string;
 export declare function evalListText(items: readonly EvalListItem[], ctx: TextContext): string;
 export declare function attemptListText(items: readonly AttemptListItem[], total: number | undefined, ctx: TextContext): string;
+/**
+ * HeroCard 的 text 面:标题行 + meta 行(最后运行时间;空范围为内置「暂无运行」文案;
+ * 多快照时标注合成来源),不含品牌行(品牌行是纯 web 件,text 面零输出)。
+ */
+export declare function heroCardText(title: LocalizedText, data: HeroData, ctx: TextContext): string;
+/**
+ * ScopeWarnings 的 text 面:按动作聚合(../scope-warnings.ts,与 web 面共用),同构但不折叠——
+ * 多组时首行 "! <分类计数汇总>";每组一行组头 "! <标题> — <徽标> → <组头命令>",其下缩进
+ * 逐条原样打印 message(已以下一步收尾,不截断掉尾段)。空警告集零输出。
+ */
+export declare function scopeWarningsText(warnings: readonly ScopeWarning[], ctx: TextContext): string;
+/**
+ * TraceWaterfall 的 text 面:每 attempt 一行——locator、总耗时(缺 trace 如实显示缺失)、
+ * 顶层 span 计数与失败标记,行尾是可复制的 `--timing` 下钻命令(经宿主注入的
+ * attemptCommand 通道拼出,携带宿主上下文)。attempt 有选择器,索引终结于可执行命令。
+ */
+export declare function traceWaterfallText(rows: readonly TraceWaterfallRow[], ctx: TextContext): string;

package/dist/report/text/faces.js

@@ -3,6 +3,7 @@
 // 零 react、零 IO、纯同步 —— 这是 text 宿主不需要 react-dom 的那一半。
 // chrome 文案(注脚、verdict 词、截断提示)经 ctx.locale 查 locale 字典;
 // 数据 display 是 LocalizedText,按 LocalizedText 回退规则取值。
+import { groupScopeWarnings } from "../scope-warnings.js";
 import { experimentDisplayName, fitFailureSummary, formatDurationMs, formatMetricValue, formatPlainNumber, formatUSD, verdictMark, } from "../format.js";
 import { countText, localeText, resolveLocalizedText, resolveMetricLabel, } from "../locale.js";
 import { indentBlock, padDisplay, stringWidth, textBar, wrapDisplay } from "./layout.js";
@@ -608,3 +609,63 @@ export function attemptListText(items, total, ctx) {
         blocks.push(localeText(locale, "attemptList.truncatedText", { n: remaining }));
     return blocks.join("\n\n");
 }
+// ───────────────────────── 站点组件(HeroCard / ScopeWarnings / TraceWaterfall)─────────────────────────
+/**
+ * HeroCard 的 text 面:标题行 + meta 行(最后运行时间;空范围为内置「暂无运行」文案;
+ * 多快照时标注合成来源),不含品牌行(品牌行是纯 web 件,text 面零输出)。
+ */
+export function heroCardText(title, data, ctx) {
+    const locale = ctx.locale;
+    const meta = data.latestStartedAt === null
+        ? localeText(locale, "hero.noRuns")
+        : [
+            localeText(locale, "hero.lastRun", { time: formatDateTimeMinute(data.latestStartedAt) }),
+            ...(data.snapshots > 1 ? [localeText(locale, "hero.composedSnapshots", { n: data.snapshots })] : []),
+        ].join(" · ");
+    return `${resolveLocalizedText(title, locale)}\n${meta}`;
+}
+/**
+ * ScopeWarnings 的 text 面:按动作聚合(../scope-warnings.ts,与 web 面共用),同构但不折叠——
+ * 多组时首行 "! <分类计数汇总>";每组一行组头 "! <标题> — <徽标> → <组头命令>",其下缩进
+ * 逐条原样打印 message(已以下一步收尾,不截断掉尾段)。空警告集零输出。
+ */
+export function scopeWarningsText(warnings, ctx) {
+    if (warnings.length === 0)
+        return "";
+    const { summary, groups } = groupScopeWarnings(warnings, ctx.locale);
+    const lines = [];
+    // 汇总行只在多组时打印;单组时组头即汇总,不另起一行(web 面则恒以汇总行作外层 <summary>)。
+    if (groups.length > 1)
+        lines.push(`! ${summary}`);
+    for (const group of groups) {
+        const badges = group.badges.length > 0 ? ` — ${group.badges.map((b) => b.text).join(" · ")}` : "";
+        const command = group.headCommand !== null ? ` → ${group.headCommand}` : "";
+        lines.push(`! ${group.title}${badges}${command}`);
+        for (const w of group.warnings)
+            lines.push(`!   ${w.message}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * TraceWaterfall 的 text 面:每 attempt 一行——locator、总耗时(缺 trace 如实显示缺失)、
+ * 顶层 span 计数与失败标记,行尾是可复制的 `--timing` 下钻命令(经宿主注入的
+ * attemptCommand 通道拼出,携带宿主上下文)。attempt 有选择器,索引终结于可执行命令。
+ */
+export function traceWaterfallText(rows, ctx) {
+    const locale = ctx.locale;
+    if (rows.length === 0)
+        return localeText(locale, "traceWaterfall.empty");
+    return rows
+        .map((row) => {
+        const failedSpans = row.spans.filter((span) => span.failed).length;
+        const parts = [
+            row.locator,
+            row.evalId,
+            row.durationMs === null ? localeText(locale, "traceWaterfall.noTrace") : formatDurationMs(row.durationMs),
+            countText(locale, "traceWaterfall.spans", row.spans.length),
+            ...(failedSpans > 0 ? [`✗ ${countText(locale, "traceWaterfall.failedSpans", failedSpans)}`] : []),
+        ];
+        return `${parts.join(" · ")}   ${ctx.attemptCommand(row.locator)} --timing`;
+    })
+        .join("\n");
+}

package/dist/report/tree.js

@@ -187,7 +187,12 @@ async function resolveNode(node, state, path) {
         return node;
     }
     if (Array.isArray(node)) {
-        return Promise.all(node.map((child) => resolveNode(child, state, path)));
+        const resolved = await Promise.all(node.map((child) => resolveNode(child, state, path)));
+        // resolve 重建的 children 数组对 React 是动态列表(JSX 静态 children 的免 key 待遇随重建
+        // 丢失);声明序即身份,给缺 key 的元素补声明位 key,免得 web 面渲染刷 key 警告。
+        return resolved.map((child, i) => isReportElement(child) && (child.key === undefined || child.key === null)
+            ? { ...child, key: `.nre-${i}` }
+            : child);
     }
     if (!isReportElement(node))
         return node;

package/dist/report/types.d.ts

@@ -275,6 +275,51 @@ export interface ScopeSummaryData {
     /** costUSD 按 attempt 求和;缺失成本不伪造为 0。 */
     totalCostUSD: MetricCell;
 }
+/**
+ * `HeroCard` 的数据(docs/feature/reports/library/site-components.md):站点标题区的
+ * 运行 meta——最后运行时间与快照合成来源。标题不在 data 里,它是站点声明与 Scope 的合成物,
+ * 经 `HeroCardProps.title` 传入。
+ */
+export interface HeroData {
+    /** Scope 中最新快照的开始时间;空 Scope 为 null,不编造当前时间。 */
+    latestStartedAt: string | null;
+    /** 贡献当前水位的快照数;大于 1 时 web 面标注「由 N 次运行合成」。 */
+    snapshots: number;
+}
+/**
+ * `CopyFixPrompt` 的数据:resolve 期算好的修复 prompt 全文与参与的失败数
+ * (docs/feature/reports/library/site-components.md)。
+ */
+export interface CopyFixPromptData {
+    /** 修复 prompt 全文;失败逐条含 eval id、主失败摘要与 attempt 下钻命令。 */
+    prompt: string;
+    /** 参与 prompt 的失败 attempt 数(verdict 为 failed / errored)。 */
+    failures: number;
+}
+/** `TraceWaterfall` 一行里的一个顶层 span 摘要(canonical OTel 字段归一后的形态)。 */
+export interface TraceSpanSummary {
+    name: string;
+    /** 归一后的语义角色;turn 归入 agent,未识别落 other。 */
+    kind: "agent" | "model" | "tool" | "other";
+    /** 相对该 attempt trace 起点的偏移(毫秒)。 */
+    startOffsetMs: number;
+    durationMs: number;
+    /** span status 为 error 时 true(web 面失败标记的来源)。 */
+    failed: boolean;
+}
+/**
+ * `TraceWaterfall` 一行 = 一次 attempt 的执行时间瀑布摘要。只画被测 agent 的原始 span
+ * (trace.json);runner 生命周期节点(`result.phases`)不进瀑布,组合视图归 attempt 详情。
+ */
+export interface TraceWaterfallRow {
+    experimentId: string;
+    evalId: string;
+    locator: AttemptLocator;
+    /** trace.json 缺失或为空时 null;行照常出现,证据位置如实显示缺失,不猜值。 */
+    durationMs: number | null;
+    /** 顶层 span 摘要,按 startOffsetMs 升序。 */
+    spans: readonly TraceSpanSummary[];
+}
 /** 一个可比组的数据;三个子块都只消费本组快照,不能含其它父目录的引用。 */
 export interface ExperimentComparisonGroupData {
     /** experiment id 的完整父路径;根目录 experiment 使用完整 id。 */
@@ -359,13 +404,3 @@ export interface ExperimentListItem {
     lastRunAt: string;
     evalRows: ExperimentListEvalRow[];
 }
-/** 三个实体列表共用的计算选项。 */
-export interface EntityListDataOptions {
-    /**
-     * 展示层遮蔽:只改写这次组件数据中的自由文本——条目本身与任何嵌套 attempt 条目的
-     * `failureSummary`;身份与分类字段(experimentId、evalId、locator、数值指标)不经它。
-     * 只作用于这次计算产出的组件数据,不改盘上或任何导出目录里的 artifact;
-     * 发布 artifact 的脱敏用 copySnapshots({ redact })。
-     */
-    redact?: (text: string) => string;
-}

package/dist/report/web.d.ts

@@ -12,14 +12,15 @@ export interface StaticHtmlOptions {
 }
 /**
  * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
- * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面;Scope 有挑选警告时在报告顶部前置
- * 一块警告 HTML(宿主是 warning 的唯一呈现者,组件数据不复制 warning)。
+ * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面。宿主不在报告树外另设警告通道——
+ * 挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放是
+ * 作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
  */
 export declare function renderReportToStaticHtml(definition: ReportDefinition, ctx: ReportHostContext, options?: StaticHtmlOptions): Promise<string>;
 /**
  * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
- * Scope 有挑选警告时在页顶前置警告块(带 command 的警告渲染为可复制命令)——宿主是
- * warning 的唯一呈现者,组件数据不复制 warning。ctx.report 是宿主规范化后的声明。
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
+ * ctx.report 是宿主规范化后的声明。
  */
 export declare function renderReportTreeToStaticHtml(tree: import("./tree.ts").ReportNode, ctx: {
     scope: Scope;

package/dist/report/web.js

@@ -1,26 +1,15 @@
 // web 宿主(view --report)的装载入口:同一棵树走 web 面,renderToStaticMarkup 吐静态
 // HTML 烘进查看器的报告槽。只有这一侧真正 import react-dom(import 边界即运行时边界),
 // 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
-import * as React from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { resolveReportTree, runWithWebContext, validateReportTree, ResolveMemo, } from "./tree.js";
 import { DEFAULT_REPORT_LOCALE } from "./locale.js";
 import { buildReportMeta, pickReportPage } from "./report.js";
-/**
- * 挑选警告的 HTML 形态:宿主级前置块(`.nre nre-report-warnings` 外壳内一个
- * `ul.nre-warnings` + `li.nre-warning[data-kind]`,复用 styles.css 已有样式)。
- * 带 `command` 的警告把命令渲染为可复制块(`.nre-warning-command`);无 command 的
- * 只显示 message,不硬造动作。经 renderToStaticMarkup 走 React,文本自动转义。
- */
-function renderScopeWarningsHtml(scope) {
-    return renderToStaticMarkup(React.createElement("div", { className: "nre nre-report-warnings" }, React.createElement("ul", { className: "nre-warnings" }, scope.warnings.map((w, i) => React.createElement("li", { key: i, className: "nre-warning", "data-kind": w.kind }, w.message, "command" in w && w.command
-        ? React.createElement("code", { className: "nre-warning-command", "data-nre-copy": w.command }, w.command)
-        : null)))));
-}
 /**
  * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
- * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面;Scope 有挑选警告时在报告顶部前置
- * 一块警告 HTML(宿主是 warning 的唯一呈现者,组件数据不复制 warning)。
+ * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面。宿主不在报告树外另设警告通道——
+ * 挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放是
+ * 作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
  */
 export async function renderReportToStaticHtml(definition, ctx, options) {
     const page = pickReportPage(definition, options?.pageId);
@@ -36,14 +25,12 @@ export async function renderReportToStaticHtml(definition, ctx, options) {
         attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
         locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
     };
-    const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
-    const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
-    return warnings + body;
+    return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
 }
 /**
  * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
- * Scope 有挑选警告时在页顶前置警告块(带 command 的警告渲染为可复制命令)——宿主是
- * warning 的唯一呈现者,组件数据不复制 warning。ctx.report 是宿主规范化后的声明。
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
+ * ctx.report 是宿主规范化后的声明。
  */
 export async function renderReportTreeToStaticHtml(tree, ctx, options) {
     const resolved = await resolveReportTree(tree, {
@@ -57,7 +44,5 @@ export async function renderReportTreeToStaticHtml(tree, ctx, options) {
         attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
         locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
     };
-    const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
-    const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
-    return warnings + body;
+    return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
 }

package/dist/results/select.d.ts

@@ -1,7 +1,12 @@
 import type { AttemptHandle, DedupeWarning, Experiment, Results, Scope, ScopeWarning, Snapshot } from "./types.ts";
 import type { ExperimentRunInfo, JsonValue } from "../types.ts";
-/** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
-export declare function selectLatest(experiments: Experiment[], opts?: {
+/**
+ * Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。
+ * 收整个 `Results` 而不是裸 `Experiment[]`,是为了同时取 `skipped` / `root` 生成
+ * `unreadable-snapshot` 警告(非实验作用域,不受 `opts.experiments` 过滤 —— 那些落盘
+ * 本来就没能解析出 experimentId,没有前缀可过滤)。
+ */
+export declare function selectLatest(results: Pick<Results, "experiments" | "skipped" | "root">, opts?: {
     experiments?: string | string[];
 }): Scope;
 /** selectCurrentResults 的范围输入:experiment id 前缀与 eval id 前缀,都可缺省。 */
@@ -65,3 +70,11 @@ export declare function dedupeAttempts(attempts: AttemptHandle[]): {
 export declare function isNewerSnapshot(a: Snapshot, b: Snapshot): boolean;
 /** experiment id 分段前缀过滤(--experiment / latest({ experiments }) 同一语义);包内使用,不进公共 barrel。 */
 export declare function filterExperiments(experiments: Experiment[], filter?: string | string[]): Experiment[];
+/**
+ * stale 警告的人话时距:选粒度最大的单位,四舍五入。结构化形态是单源——message 的英文时距
+ * 与 ScopeWarnings 徽标的本地化时距都从这里出,阈值不写两份。
+ */
+export declare function gapParts(fromIso: string, toIso: string): {
+    n: number;
+    unit: "second" | "minute" | "hour" | "day";
+};

package/dist/results/select.js

@@ -4,9 +4,14 @@
 // 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Scope 走 ——
 // 渲染与否在消费方(message 是渲染好的英文句子,以下一步收尾),但缺口不静默。
 import { evalPrefixPredicate } from "../shared/aggregate.js";
-/** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
-export function selectLatest(experiments, opts) {
-    const selected = filterExperiments(experiments, opts?.experiments);
+/**
+ * Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。
+ * 收整个 `Results` 而不是裸 `Experiment[]`,是为了同时取 `skipped` / `root` 生成
+ * `unreadable-snapshot` 警告(非实验作用域,不受 `opts.experiments` 过滤 —— 那些落盘
+ * 本来就没能解析出 experimentId,没有前缀可过滤)。
+ */
+export function selectLatest(results, opts) {
+    const selected = filterExperiments(results.experiments, opts?.experiments);
     const snapshots = selected.map((exp) => exp.latest);
     const warnings = [];
     // stale 的基准:Scope 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
@@ -52,6 +57,7 @@ export function selectLatest(experiments, opts) {
             });
         }
     }
+    warnings.push(...unreadableSnapshotWarnings(results.skipped, results.root));
     return makeScope("latest-snapshots", snapshots, warnings);
 }
 /** 一个快照的可比性配置投影;pairsByFlag 与 experimentListData 复用同一字段集。 */
@@ -188,8 +194,61 @@ export function selectCurrentResults(results, scope = {}) {
             });
         }
     }
+    warnings.push(...unreadableSnapshotWarnings(results.skipped, results.root));
     return makeScope("current-evals", snapshots, warnings);
 }
+/**
+ * `results.skipped` 里每一条不可读落盘 → 一条 `unreadable-snapshot` ScopeWarning。
+ * 非实验作用域(没有 experimentId 字段):`latest()` / `current()` 都原样带上全部
+ * `skipped` 条目,不受 `opts.experiments` 前缀过滤影响(那些落盘本来就没能解析出
+ * experimentId,没有前缀可比);`makeScope().filter()` 按「非实验作用域的警告保留」
+ * 规则自动放行,不需要额外分支。
+ */
+function unreadableSnapshotWarnings(skipped, root) {
+    return skipped.map((s) => {
+        switch (s.reason) {
+            case "incompatible-version": {
+                const producer = s.producer;
+                const schemaText = s.schemaVersion !== undefined ? ` (schemaVersion ${s.schemaVersion})` : "";
+                if (producer?.name === "niceeval" && producer.version) {
+                    const command = `npx niceeval@${producer.version} show --results ${root}`;
+                    return {
+                        kind: "unreadable-snapshot",
+                        dir: s.dir,
+                        reason: s.reason,
+                        message: `snapshot at "${s.dir}" was written by niceeval ${producer.version}${schemaText} and cannot be read by this version; run \`${command}\` to open it`,
+                        command,
+                    };
+                }
+                const writtenBy = producer?.name
+                    ? `${producer.name}${producer.version ? ` ${producer.version}` : ""}`
+                    : "an incompatible tool version";
+                return {
+                    kind: "unreadable-snapshot",
+                    dir: s.dir,
+                    reason: s.reason,
+                    message: `snapshot at "${s.dir}" was written by ${writtenBy}${schemaText} and cannot be read by this version; open it with the tool version that produced it`,
+                };
+            }
+            case "malformed": {
+                const detail = s.detail ? ` (${s.detail})` : "";
+                return {
+                    kind: "unreadable-snapshot",
+                    dir: s.dir,
+                    reason: s.reason,
+                    message: `snapshot at "${s.dir}" is malformed${detail} and was skipped; inspect snapshot.json in that directory for corrupted JSON or a missing required field`,
+                };
+            }
+            case "incomplete":
+                return {
+                    kind: "unreadable-snapshot",
+                    dir: s.dir,
+                    reason: s.reason,
+                    message: `snapshot at "${s.dir}" has attempt data but no snapshot.json (likely interrupted before metadata was written) and was skipped; inspect ${s.dir} — completed attempts remain on disk for manual review`,
+                };
+        }
+    });
+}
 /**
  * Scope 构造:attempts 按口径物化(快照 attempts 的平铺);filter 只删不换 —— 快照删减,
  * attempts 随之同步修剪,warnings 修剪规则是「experimentId 不在幸存快照中的丢弃,
@@ -261,18 +320,24 @@ export function filterExperiments(experiments, filter) {
     const prefixes = (Array.isArray(filter) ? filter : [filter]).map((p) => p.replace(/\/+$/, ""));
     return experiments.filter((exp) => prefixes.some((p) => exp.id === p || exp.id.startsWith(p + "/")));
 }
-/** stale 警告的人话时距:选粒度最大的单位,四舍五入。 */
-function humanizeGap(fromIso, toIso) {
+/**
+ * stale 警告的人话时距:选粒度最大的单位,四舍五入。结构化形态是单源——message 的英文时距
+ * 与 ScopeWarnings 徽标的本地化时距都从这里出,阈值不写两份。
+ */
+export function gapParts(fromIso, toIso) {
     const ms = Math.max(0, Date.parse(toIso) - Date.parse(fromIso));
     const seconds = Math.round(ms / 1000);
     if (seconds < 90)
-        return `${seconds} second${seconds === 1 ? "" : "s"}`;
+        return { n: seconds, unit: "second" };
     const minutes = Math.round(seconds / 60);
     if (minutes < 90)
-        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+        return { n: minutes, unit: "minute" };
     const hours = Math.round(minutes / 60);
     if (hours < 36)
-        return `${hours} hour${hours === 1 ? "" : "s"}`;
-    const days = Math.round(hours / 24);
-    return `${days} day${days === 1 ? "" : "s"}`;
+        return { n: hours, unit: "hour" };
+    return { n: Math.round(hours / 24), unit: "day" };
+}
+function humanizeGap(fromIso, toIso) {
+    const { n, unit } = gapParts(fromIso, toIso);
+    return `${n} ${unit}${n === 1 ? "" : "s"}`;
 }

package/dist/results/types.d.ts

@@ -33,13 +33,6 @@ export interface SnapshotMeta {
     completedAt?: string;
     /** 写入时刻该实验已知的 eval 并集 —— 残缺检测的分母随数据走(copySnapshots 自动补记,writer 可声明)。 */
     knownEvalIds?: string[];
-    /**
-     * 发布拷贝的自描述标记:copySnapshots 补记,消毒函数 → "applied"、redact: false → "none";
-     * 本地事实根没有此字段。只声明流程,不证明无秘密;view --out 据此分级防呆。
-     */
-    publish?: {
-        redaction: "applied" | "none";
-    };
     /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
     name?: LocalizedText;
 }
@@ -117,10 +110,6 @@ export interface Snapshot {
     dir: string;
     /** 写入时刻该实验已知的 eval 并集(可选);copySnapshots 自动补记,writer.snapshot() 也可声明。 */
     knownEvalIds?: string[];
-    /** 发布拷贝的自描述标记(见 SnapshotMeta.publish);本地事实根没有此字段。 */
-    publish?: {
-        redaction: "applied" | "none";
-    };
 }
 /** 一个实验的全部历史:同一 experiment id 的历次快照归在一起。 */
 export interface Experiment {
@@ -153,6 +142,12 @@ export interface SkippedDir {
 }
 /** openResults 的返回:experiments 分层;skipped 不静默丢。 */
 export interface Results {
+    /**
+     * 结果根目录的绝对路径(`openResults()` 入参解析后的原样值,不论传入的是结果根、
+     * 实验目录、快照目录还是某个 snapshot.json)。`unreadable-snapshot` 警告拼版本化
+     * `command`(`npx niceeval@<version> show --results <root>`)时取它。
+     */
+    root: string;
     /** 每个实验一项,挂着自己的全部历史(id 字典序)。 */
     experiments: Experiment[];
     skipped: SkippedDir[];
@@ -229,6 +224,26 @@ export type ScopeWarning = {
     message: string;
     /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
     command: string;
+} | {
+    /**
+     * 扫描结果根遇到的不可读快照:schema 不兼容、JSON 损坏 / 必需字段错误(malformed)、
+     * attempt 已写入但缺 `snapshot.json`(incomplete)。该快照被跳过,不挡其余结果
+     * (非 niceeval JSON 静默忽略,不产生这个 kind)。非实验作用域(没有 experimentId
+     * 字段) —— `Scope.filter()` 修剪时恒保留。
+     */
+    kind: "unreadable-snapshot";
+    /** 该快照目录的绝对路径。 */
+    dir: string;
+    /** 与 `SkippedDir.reason` 同一取值集,原样透传。 */
+    reason: "incompatible-version" | "malformed" | "incomplete";
+    message: string;
+    /**
+     * 只有 reason 为 `incompatible-version` 且能确定是 niceeval 自己产出(`producer.name
+     * === "niceeval"` 且带 `producer.version`)时给出:`npx niceeval@<version> show --results
+     * <root>`。第三方 producer、版本信息缺失,或 reason 为 malformed / incomplete 时省略——
+     * 这些情况没有单条命令能解决,message 改给定位动作。
+     */
+    command?: string;
 };
 /** dedupeAttempts 的警告:身份键缺 startedAt,宁可不去重也不误删。 */
 export interface DedupeWarning {

package/dist/runner/fingerprint.d.ts

@@ -1,11 +1,11 @@
-import type { DiscoveredEval, EvalResult } from "../types.ts";
+import type { DiscoveredEval, EvalResult, SandboxOption } from "../types.ts";
 import type { AgentRun } from "./types.ts";
 export declare function cacheKey(run: AgentRun, evalId: string): string;
 /**
  * @param sourceCache 按 sourcePath 缓存文件内容:一个矩阵(实验 × eval)会对同一批源文件
  * 反复算指纹,不带缓存会在任何 attempt 起跑前做 E×N 次重复文件读。
  */
-export declare function computeFingerprint(evalDef: DiscoveredEval, run: AgentRun, sourceCache?: Map<string, Promise<string>>): Promise<string>;
+export declare function computeFingerprint(evalDef: DiscoveredEval, run: AgentRun, sourceCache?: Map<string, Promise<string>>, configSandbox?: SandboxOption): Promise<string>;
 export interface CarryPlan {
     /** `cacheKey(run, evalId)` → 本次规划出的指纹,供调用方按同一口径判断"这条要不要携入"。 */
     plannedFingerprints: Map<string, string>;
@@ -20,4 +20,4 @@ export interface CarryPlan {
  * 不一致,live 表格就会显示"还在等名额",而 run.ts 其实已经把它筛掉、根本不会调度这个 attempt
  * (见 memory 的 live-carry-row-shows-waiting-forever)。
  */
-export declare function planCarry(evals: DiscoveredEval[], agentRuns: AgentRun[], priorResults: EvalResult[] | undefined): Promise<CarryPlan>;
+export declare function planCarry(evals: DiscoveredEval[], agentRuns: AgentRun[], priorResults: EvalResult[] | undefined, configSandbox?: SandboxOption): Promise<CarryPlan>;

package/dist/runner/sandbox-selection.d.ts

@@ -0,0 +1,12 @@
+import type { DiscoveredEval, SandboxOption, SandboxRunInfo } from "../types.ts";
+import type { AgentRun } from "./types.ts";
+/** 该 eval 实际起步的 spec:未声明 environment 用基础 spec;声明了则查表派生并缓存。 */
+export declare function sandboxForEval(run: AgentRun, evalDef: DiscoveredEval, fallback?: SandboxOption): SandboxOption | undefined;
+/** 在 dry-run / carry / concurrency / attempt 展开之前一次性查表;全部缺项一次穷举,不等到花费发生后才出现。 */
+export declare function prepareRunSandboxes(evals: DiscoveredEval[], runs: AgentRun[], fallback?: SandboxOption): void;
+/** ExperimentRunInfo 的 sandbox 投影:顶层恒为基础 spec;sandboxByEval 只含声明了 environment 的选中 eval。 */
+export declare function sandboxProjection(run: AgentRun, fallback?: SandboxOption): {
+    sandbox?: SandboxRunInfo;
+    sandboxByEval?: Record<string, SandboxRunInfo>;
+};
+export declare function resolvedSandboxRecommendedConcurrency(evals: DiscoveredEval[], runs: AgentRun[], fallback?: SandboxOption): number;