niceeval 0.8.1 → 0.9.1

package/src/report/types.ts

@@ -299,6 +299,57 @@ export interface ScopeSummaryData {
   totalCostUSD: MetricCell;
 }
 
+// ───────────────────────── 站点组件(Hero / CopyFixPrompt / TraceWaterfall)─────────────────────────
+
+/**
+ * `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。 */

package/src/report/web.ts

@@ -2,7 +2,6 @@
 // HTML 烘进查看器的报告槽。只有这一侧真正 import react-dom(import 边界即运行时边界),
 // 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
 
-import * as React from "react";
 import type { ReactNode } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import type { AttemptLocator } from "../results/locator.ts";
@@ -26,39 +25,11 @@ export interface StaticHtmlOptions {
   locale?: ReportLocale;
 }
 
-/**
- * 挑选警告的 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: Scope): string {
-  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: ReportDefinition,
@@ -78,15 +49,13 @@ export async function renderReportToStaticHtml(
     attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
     locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
   };
-  const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
-  const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
-  return warnings + body;
+  return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
 }
 
 /**
  * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
- * Scope 有挑选警告时在页顶前置警告块(带 command 的警告渲染为可复制命令)——宿主是
- * warning 的唯一呈现者,组件数据不复制 warning。ctx.report 是宿主规范化后的声明。
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
+ * ctx.report 是宿主规范化后的声明。
  */
 export async function renderReportTreeToStaticHtml(
   tree: import("./tree.ts").ReportNode,
@@ -104,7 +73,5 @@ export async function renderReportTreeToStaticHtml(
     attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
     locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
   };
-  const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
-  const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
-  return warnings + body;
+  return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
 }

package/src/results/host-equivalence.test.ts

@@ -126,7 +126,8 @@ interface NormExperiment {
 type NormWarning =
   | { kind: "partial-coverage"; experimentId: string; covered: number; total: number }
   | { kind: "stale-snapshot"; experimentId: string; startedAt: string; latestStartedAt: string }
-  | { kind: "unfinished-snapshot"; experimentId: string; startedAt: string };
+  | { kind: "unfinished-snapshot"; experimentId: string; startedAt: string }
+  | { kind: "unreadable-snapshot"; reason: string };
 interface NormSelection {
   warnings: NormWarning[];
   experiments: NormExperiment[];
@@ -141,6 +142,9 @@ function normalizeWarning(w: ScopeWarning): NormWarning {
     case "unfinished-snapshot":
       // dir 是宿主机绝对路径,归一化掉;身份靠 experimentId + startedAt。
       return { kind: w.kind, experimentId: w.experimentId, startedAt: w.startedAt };
+    case "unreadable-snapshot":
+      // dir 是宿主机绝对路径,归一化掉;这个 kind 本就非实验作用域,没有 experimentId 可比。
+      return { kind: w.kind, reason: w.reason };
   }
 }
 
@@ -325,7 +329,7 @@ describe("selectCurrentResults · 现刻水位结构化身份", () => {
     expect(algebra.warnings).toEqual([]);
   });
 
-  it("场景8 --experiment 分段前缀过滤:只留匹配段,不误配同前缀实验", async () => {
+  it("场景8 --exp 分段前缀过滤:只留匹配段,不误配同前缀实验", async () => {
     const root = await makeRoot();
     await writeSnapshot(root, "2026-07-01T08-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-01T08:00:00.000Z" }, [res("q1", "passed")]);
     await writeSnapshot(root, "2026-07-01T09-00-00-000Z", { experimentId: "compare/codex", agent: "codex", startedAt: "2026-07-01T09:00:00.000Z" }, [res("q1", "passed")]);

package/src/results/open.ts

@@ -150,7 +150,7 @@ export async function openResults(dir: string): Promise<Results> {
   try {
     targetStat = await stat(target);
   } catch {
-    return makeResults([], []);
+    return makeResults([], [], target);
   }
 
   if (targetStat.isFile()) {
@@ -165,17 +165,18 @@ export async function openResults(dir: string): Promise<Results> {
   // 建 locator 索引:必须在全部快照扫完、Experiment 归组完成之后,返回 Results 之前——
   // 撞车(LocatorCollisionError)在这里抛,不静默吞、不拖到消费方第一次 resolveLocator() 才发现。
   const locatorIndex = buildAttemptLocatorIndex(experiments);
-  const results = makeResults(experiments, state.skipped);
+  const results = makeResults(experiments, state.skipped, target);
   locatorIndexByResults.set(results, locatorIndex);
   return results;
 }
 
-function makeResults(experiments: Experiment[], skipped: SkippedDir[]): Results {
+function makeResults(experiments: Experiment[], skipped: SkippedDir[], root: string): Results {
   const results: Results = {
+    root,
     experiments,
     skipped,
     latest(opts?: { experiments?: string | string[] }): Scope {
-      return selectLatest(experiments, opts);
+      return selectLatest(results, opts);
     },
     current(opts?: { experiments?: string | string[] }): Scope {
       return selectCurrentResults(results, { experiment: opts?.experiments });

package/src/results/results.test.ts

@@ -375,13 +375,89 @@ describe("results.latest() · Selection", () => {
 
     const filtered = latest.filter((s) => s.experimentId !== "mid/b");
     expect(filtered.snapshots.map((s) => s.experimentId)).toEqual(["mid/a"]);
-    expect(filtered.warnings.map((w) => w.experimentId)).toEqual(["mid/a"]);
+    expect(filtered.warnings.map((w) => ("experimentId" in w ? w.experimentId : undefined))).toEqual(["mid/a"]);
     // 原 Selection 不被改动。
     expect(latest.snapshots).toHaveLength(2);
     expect(latest.warnings).toHaveLength(2);
   });
 });
 
+// ───────────────────────── unreadable-snapshot 警告 ─────────────────────────
+
+describe("results.latest() / results.current() · unreadable-snapshot", () => {
+  it("malformed 快照产生 warning 且其余快照照常计入;无关 JSON 不产生 warning", async () => {
+    const root = await makeRoot();
+    const okDir = await writeSnapshot(root, "ok-exp", "2026-07-04T08-00-00-000Z-oooo", meta({ experimentId: "ok", agent: "bub", startedAt: "2026-07-04T08:00:00.000Z", completedAt: "2026-07-04T08:10:00.000Z" }));
+    await writeResultFile(okDir, "q1/a1", record({ id: "q1", attempt: 1 }));
+
+    const badDir = join(root, "bad-exp", "2026-07-02T08-00-00-000Z-zzzz");
+    await mkdir(badDir, { recursive: true });
+    await writeFile(join(badDir, "snapshot.json"), "not json {", "utf-8");
+
+    const alienDir = join(root, "alien-exp", "2026-07-06T08-00-00-000Z-alien");
+    await mkdir(alienDir, { recursive: true });
+    await writeFile(join(alienDir, "summary.json"), JSON.stringify({ hello: 1 }), "utf-8");
+
+    const results = await openResults(root);
+    const latest = results.latest();
+    // 其余快照照常计入,不被坏落盘拖垮。
+    expect(latest.snapshots.map((s) => s.experimentId)).toEqual(["ok"]);
+
+    const unreadable = latest.warnings.filter((w) => w.kind === "unreadable-snapshot");
+    expect(unreadable).toHaveLength(1); // 无关 JSON(alien)不产生 warning
+    expect(unreadable[0]).toMatchObject({ kind: "unreadable-snapshot", dir: badDir, reason: "malformed" });
+    expect(unreadable[0].message).toContain(badDir);
+    expect(unreadable[0].message).toMatch(/inspect .*snapshot\.json/);
+    expect((unreadable[0] as { command?: string }).command).toBeUndefined();
+
+    // results.current() 同一份事实(show / view 报告槽走的是它)。
+    const current = results.current();
+    expect(current.warnings.filter((w) => w.kind === "unreadable-snapshot")).toHaveLength(1);
+  });
+
+  it("incompatible(schemaVersion 不兼容,niceeval producer)的 warning 带版本化 command", async () => {
+    const root = await makeRoot();
+    const oldDir = join(root, "old-exp", "2026-06-01T08-00-00-000Z");
+    await mkdir(oldDir, { recursive: true });
+    await writeFile(
+      join(oldDir, "snapshot.json"),
+      JSON.stringify({
+        format: RESULTS_FORMAT,
+        schemaVersion: RESULTS_SCHEMA_VERSION - 1,
+        producer: { name: "niceeval", version: "0.4.6" },
+        experimentId: "old",
+        agent: "bub",
+        startedAt: "2026-06-01T08:00:00.000Z",
+      }),
+      "utf-8",
+    );
+
+    const latest = (await openResults(root)).latest();
+    const warn = latest.warnings.find((w) => w.kind === "unreadable-snapshot")!;
+    expect(warn).toMatchObject({ kind: "unreadable-snapshot", dir: oldDir, reason: "incompatible-version" });
+    expect((warn as { command?: string }).command).toBe(`npx niceeval@0.4.6 show --results ${root}`);
+    expect(warn.message).toContain("npx niceeval@0.4.6 show --results");
+  });
+
+  it("非实验作用域:Selection.filter 收窄后 unreadable-snapshot warning 仍在", async () => {
+    const root = await makeRoot();
+    const aDir = await writeSnapshot(root, "mid_a", "s1", meta({ experimentId: "mid/a", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
+    await writeResultFile(aDir, "q1/a1", record({ id: "q1", attempt: 1 }));
+
+    const badDir = join(root, "bad-exp", "2026-07-02T08-00-00-000Z-zzzz");
+    await mkdir(badDir, { recursive: true });
+    await writeFile(join(badDir, "snapshot.json"), "not json {", "utf-8");
+
+    const latest = (await openResults(root)).latest();
+    expect(latest.warnings.filter((w) => w.kind === "unreadable-snapshot")).toHaveLength(1);
+
+    // filter 只删快照,不删非实验作用域的警告 —— 即便过滤条件与该 warning 无关的实验都不复存在。
+    const filtered = latest.filter((s) => s.experimentId === "mid/a");
+    expect(filtered.snapshots).toHaveLength(1);
+    expect(filtered.warnings.filter((w) => w.kind === "unreadable-snapshot")).toHaveLength(1);
+  });
+});
+
 // ───────────────────────── 身份键去重 ─────────────────────────
 
 function fakeSnapshot(over: { experimentId: string; startedAt: string; dir: string }): Snapshot {
@@ -974,6 +1050,7 @@ describe("AttemptLocator · 落盘 / 读取 / 携带 / 撞车", () => {
     snapshot.attempts = [attempt];
     snapshot.evals = [{ id: "q1", attempts: [attempt] }];
     const handMadeResults: Results = {
+      root: "/tmp/e",
       experiments: [{ id: "e", snapshots: [snapshot], latest: snapshot, evalIds: ["q1"] }],
       skipped: [],
       // filter() 本测试不调用,用不到,给个占位实现即可满足 Scope 接口。

package/src/results/select.ts

@@ -12,17 +12,23 @@ import type {
   Results,
   Scope,
   ScopeWarning,
+  SkippedDir,
   Snapshot,
 } from "./types.ts";
 import type { ExperimentRunInfo, JsonValue } from "../types.ts";
 import { evalPrefixPredicate } from "../shared/aggregate.ts";
 
-/** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
+/**
+ * Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。
+ * 收整个 `Results` 而不是裸 `Experiment[]`,是为了同时取 `skipped` / `root` 生成
+ * `unreadable-snapshot` 警告(非实验作用域,不受 `opts.experiments` 过滤 —— 那些落盘
+ * 本来就没能解析出 experimentId,没有前缀可过滤)。
+ */
 export function selectLatest(
-  experiments: Experiment[],
+  results: Pick<Results, "experiments" | "skipped" | "root">,
   opts?: { experiments?: string | string[] },
 ): Scope {
-  const selected = filterExperiments(experiments, opts?.experiments);
+  const selected = filterExperiments(results.experiments, opts?.experiments);
   const snapshots = selected.map((exp) => exp.latest);
   const warnings: ScopeWarning[] = [];
 
@@ -69,12 +75,13 @@ export function selectLatest(
       });
     }
   }
+  warnings.push(...unreadableSnapshotWarnings(results.skipped, results.root));
   return makeScope("latest-snapshots", snapshots, warnings);
 }
 
 /** selectCurrentResults 的范围输入:experiment id 前缀与 eval id 前缀,都可缺省。 */
 export interface ResultScope {
-  /** experiment id 前缀(--experiment),分段匹配语义同 filterExperiments。 */
+  /** experiment id 前缀(--exp),分段匹配语义同 filterExperiments。 */
   experiment?: string | string[];
   /** eval id 前缀(位置参数),收窄 Scope 覆盖的 eval;覆盖警告分母同步收窄到范围内。 */
   patterns?: string[];
@@ -235,9 +242,63 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
     }
   }
 
+  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: readonly SkippedDir[], root: string): ScopeWarning[] {
+  return skipped.map((s): ScopeWarning => {
+    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 不在幸存快照中的丢弃,
@@ -307,7 +368,7 @@ export function isNewerSnapshot(a: Snapshot, b: Snapshot): boolean {
   return a.dir.localeCompare(b.dir) > 0;
 }
 
-/** experiment id 分段前缀过滤(--experiment / latest({ experiments }) 同一语义);包内使用,不进公共 barrel。 */
+/** experiment id 分段前缀过滤(--exp / latest({ experiments }) 同一语义);包内使用,不进公共 barrel。 */
 export function filterExperiments(experiments: Experiment[], filter?: string | string[]): Experiment[] {
   if (filter === undefined) return experiments;
   // 允许 "compare/" 这种带尾斜杠的写法,与 "compare" 等价;分段匹配不误配 "compare2"。
@@ -315,15 +376,22 @@ export function filterExperiments(experiments: Experiment[], filter?: string | s
   return experiments.filter((exp) => prefixes.some((p) => exp.id === p || exp.id.startsWith(p + "/")));
 }
 
-/** stale 警告的人话时距:选粒度最大的单位,四舍五入。 */
-function humanizeGap(fromIso: string, toIso: string): string {
+/**
+ * stale 警告的人话时距:选粒度最大的单位,四舍五入。结构化形态是单源——message 的英文时距
+ * 与 ScopeWarnings 徽标的本地化时距都从这里出,阈值不写两份。
+ */
+export function gapParts(fromIso: string, toIso: string): { n: number; unit: "second" | "minute" | "hour" | "day" } {
   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"}`;
+  if (seconds < 90) return { n: seconds, unit: "second" };
   const minutes = Math.round(seconds / 60);
-  if (minutes < 90) return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  if (minutes < 90) 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"}`;
+  if (hours < 36) return { n: hours, unit: "hour" };
+  return { n: Math.round(hours / 24), unit: "day" };
+}
+
+function humanizeGap(fromIso: string, toIso: string): string {
+  const { n, unit } = gapParts(fromIso, toIso);
+  return `${n} ${unit}${n === 1 ? "" : "s"}`;
 }

package/src/results/types.ts

@@ -160,6 +160,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[];
@@ -237,6 +243,27 @@ 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,宁可不去重也不误删。 */

package/src/runner/attempt.ts

@@ -6,7 +6,7 @@
 import { resolve as resolvePath } from "node:path";
 import { readFile as readSourceFile } from "node:fs/promises";
 import { Effect, Cause, Duration } from "effect";
-import { createSandbox, resolveSandbox, sandboxRunInfo } from "../sandbox/resolve.ts";
+import { createSandbox, resolveSandbox } from "../sandbox/resolve.ts";
 import { stopSandbox, unregisterSandbox } from "../sandbox/registry.ts";
 import { KEEPABLE_PROVIDERS, nativeEnterCommand, suspendSandbox } from "../sandbox/keep.ts";
 import { keptEntryId, updateKeptEntry, writeKeptEntry } from "../sandbox/keep-registry.ts";
@@ -51,6 +51,7 @@ import type {
 import { reportAttemptLifecycle, reportDiagnostic, reportKept } from "./feedback/sink.ts";
 import { encodeAttemptKey, runWho } from "./types.ts";
 import { commandDisplay, commandNode, createTimingRecorder, type TimingRecorder } from "./timing.ts";
+import { sandboxForEval, sandboxProjection } from "./sandbox-selection.ts";
 import type {
   AgentRun,
   Attempt,
@@ -81,7 +82,7 @@ export function runAttemptEffect(
     id: evalDef.id,
     description: evalDef.description,
     experimentId: run.experimentId,
-    experiment: experimentRunInfo(run),
+    experiment: experimentRunInfo(run, config.sandbox),
     agent: run.agent.name,
     model: run.model,
     verdict: "errored",
@@ -178,9 +179,9 @@ export function runAttemptEffect(
 
   return Effect.scoped(
     Effect.gen(function* () {
-      // run.sandbox ?? config.sandbox 是同一个 SandboxSpec 对象,既用来起沙箱 provider,
-      // 也是 sandbox.setup / sandbox.teardown 钩子(SandboxSpec.setup()/.teardown() 链式挂的)的来源。
-      const sandboxSpec = run.sandbox ?? config.sandbox;
+      // 规划期按当前 eval 解析出的同一个 SandboxSpec，既用来起 provider，也作为
+      // sandbox.setup / sandbox.teardown 钩子(SandboxSpec.setup()/.teardown() 链式挂的)来源。
+      const sandboxSpec = a.sandboxSpec ?? sandboxForEval(run, evalDef, config.sandbox);
       // defineSandbox 自定义 provider 不参与留存(事后命令不执行用户项目代码,新进程无法安全
       // 找回用户对象上的 stopDetached);组合使用在创建沙箱前报清晰错误。
       if (
@@ -809,7 +810,7 @@ async function runAttemptBody(
       id: evalDef.id,
       description: evalDef.description,
       experimentId: run.experimentId,
-      experiment: experimentRunInfo(run),
+      experiment: experimentRunInfo(run, config.sandbox),
       agent: run.agent.name,
       model: run.model,
       verdict,
@@ -832,7 +833,7 @@ async function runAttemptBody(
       ...(usesSandbox
         ? {
             sandbox: {
-              provider: resolveSandbox(run.sandbox ?? config.sandbox).provider,
+              provider: resolveSandbox(a.sandboxSpec ?? sandboxForEval(run, evalDef, config.sandbox)).provider,
               sandboxId: sandbox.sandboxId,
             },
           }
@@ -1016,7 +1017,7 @@ async function collectSources(
 
 /** 解析后运行配置的穷尽投影(ExperimentRunInfo,见 docs/feature/results/architecture.md):
  *  agent/model 只在快照顶层,这里不复制;sandbox 只经 provider 的公开参数投影落盘。 */
-function experimentRunInfo(run: AgentRun): EvalResult["experiment"] {
+function experimentRunInfo(run: AgentRun, configSandbox?: Config["sandbox"]): EvalResult["experiment"] {
   return {
     ...(run.description !== undefined ? { description: run.description } : {}),
     ...(run.reasoningEffort !== undefined ? { reasoningEffort: run.reasoningEffort } : {}),
@@ -1028,7 +1029,7 @@ function experimentRunInfo(run: AgentRun): EvalResult["experiment"] {
     ...(run.maxConcurrency !== undefined ? { maxConcurrency: run.maxConcurrency } : {}),
     selectedEvalIds: run.selectedEvalIds ?? [],
     ...(run.evalFilterFingerprint !== undefined ? { evalFilterFingerprint: run.evalFilterFingerprint } : {}),
-    ...(run.sandbox !== undefined ? { sandbox: sandboxRunInfo(run.sandbox) } : {}),
+    ...sandboxProjection(run, configSandbox),
   };
 }
 

package/src/runner/discover.test.ts

@@ -6,7 +6,7 @@ import { describe, expect, it, afterEach } from "vitest";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { discoverEvals } from "./discover.ts";
+import { discoverEvals, makeFilter } from "./discover.ts";
 import { captureEvalSource } from "./eval-source.ts";
 
 const roots: string[] = [];
@@ -20,6 +20,14 @@ afterEach(async () => {
 });
 
 describe("discoverEvals · 源码捕获", () => {
+  // bug: memory/exp-eval-prefix-segment-drift.md
+  it("eval 位置参数按裸字面前缀命中 sibling，不要求路径段边界", () => {
+    const filter = makeFilter(["memory/terminal-swe-bench"]);
+    expect(filter("memory/terminal-swe-bench-astropy-1")).toBe(true);
+    expect(filter("memory/terminal-swe-bench-astropy-2")).toBe(true);
+    expect(filter("memory/other")).toBe(false);
+  });
+
   it("单个默认导出:source 与 captureEvalSource() 直接调出来的一致(路径/内容/哈希)", async () => {
     const root = await makeRoot();
     await mkdir(join(root, "evals"), { recursive: true });

package/src/runner/discover.ts

@@ -6,6 +6,7 @@ import { dirname, join, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { pad4 } from "../util.ts";
 import { captureEvalSource } from "./eval-source.ts";
+import { evalPrefixPredicate } from "../shared/aggregate.ts";
 import type { DiscoveredEval, DiscoveredExperiment, EvalDef, ExperimentDef } from "../types.ts";
 
 const SKIP_DIRS = new Set(["node_modules", ".git", ".niceeval", "dist", ".next"]);
@@ -108,8 +109,7 @@ export async function discoverExperiments(root: string): Promise<DiscoveredExper
   return out;
 }
 
-/** id 前缀过滤:精确匹配或目录前缀(weather 命中 weather 与 weather/*)。 */
+/** eval id 的裸字面前缀过滤；exp / show / view 共用 shared helper，避免路径段语义漂移。 */
 export function makeFilter(patterns: string[]): (id: string) => boolean {
-  if (patterns.length === 0) return () => true;
-  return (id) => patterns.some((p) => id === p || id.startsWith(p + "/"));
+  return evalPrefixPredicate(patterns.length > 0 ? patterns : undefined);
 }

package/src/runner/fingerprint.ts

@@ -3,9 +3,10 @@
 
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
-import { sandboxLabel } from "../sandbox/resolve.ts";
-import type { DiscoveredEval, EvalResult } from "../types.ts";
+import { sandboxRunInfo } from "../sandbox/resolve.ts";
+import type { DiscoveredEval, EvalResult, SandboxOption } from "../types.ts";
 import type { AgentRun } from "./types.ts";
+import { prepareRunSandboxes, sandboxForEval } from "./sandbox-selection.ts";
 
 export function cacheKey(run: AgentRun, evalId: string): string {
   return `${run.experimentId ?? ""}|${evalId}`;
@@ -19,6 +20,7 @@ export async function computeFingerprint(
   evalDef: DiscoveredEval,
   run: AgentRun,
   sourceCache?: Map<string, Promise<string>>,
+  configSandbox?: SandboxOption,
 ): Promise<string> {
   let sourcePromise = sourceCache?.get(evalDef.sourcePath);
   if (!sourcePromise) {
@@ -31,6 +33,7 @@ export async function computeFingerprint(
     eval: {
       id: evalDef.id,
       tags: evalDef.tags ?? [],
+      environment: evalDef.environment,
       metadata: evalDef.metadata ?? {},
       timeoutMs: evalDef.timeoutMs,
     },
@@ -39,7 +42,7 @@ export async function computeFingerprint(
       agent: run.agent.name,
       model: run.model,
       flags: run.flags,
-      sandbox: run.sandbox === undefined ? undefined : sandboxLabel(run.sandbox),
+      sandbox: sandboxRunInfo(sandboxForEval(run, evalDef, configSandbox)),
       timeoutMs: run.timeoutMs,
       strict: run.strict,
     },
@@ -66,14 +69,16 @@ export async function planCarry(
   evals: DiscoveredEval[],
   agentRuns: AgentRun[],
   priorResults: EvalResult[] | undefined,
+  configSandbox?: SandboxOption,
 ): Promise<CarryPlan> {
+  prepareRunSandboxes(evals, agentRuns, configSandbox);
   const sourceCache = new Map<string, Promise<string>>();
   const plannedFingerprints = new Map<string, string>();
   const jobs: Promise<void>[] = [];
   for (const run of agentRuns) {
     for (const evalDef of evals.filter((e) => run.evalFilter(e.id))) {
       jobs.push(
-        computeFingerprint(evalDef, run, sourceCache).then((fp) => {
+        computeFingerprint(evalDef, run, sourceCache, configSandbox).then((fp) => {
           plannedFingerprints.set(cacheKey(run, evalDef.id), fp);
         }),
       );