niceeval 0.8.0 → 0.9.0

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 {
@@ -552,7 +628,7 @@ describe("createResultsWriter", () => {
     expect(await q2.agentSetup()).toBeNull();
 
     const dest = join(await makeRoot(), "published");
-    await copySnapshots(results.latest(), dest, { ...{ artifacts: ["agentSetup"] }, redact: false });
+    await copySnapshots(results.latest(), dest, { artifacts: ["agentSetup"] });
     const copied = join(dest, "skill-ab_claude-effect", basename(snap.dir), "q1", "a1", "agent-setup.json");
     expect(JSON.parse(await readFile(copied, "utf-8"))).toEqual(manifest);
   });
@@ -737,7 +813,7 @@ describe("copySnapshots", () => {
 
     const results = await openResults(root);
     const dest = join(await makeRoot(), "site/data/run");
-    const copied = await copySnapshots(results.latest(), dest, { ...{ artifacts: ["events"] }, redact: false });
+    const copied = await copySnapshots(results.latest(), dest, { artifacts: ["events"] });
 
     expect(copied.warnings).toHaveLength(0);
     expect(copied.dir).toBe(dest);
@@ -775,15 +851,15 @@ describe("copySnapshots", () => {
 
     const occupied = await makeRoot();
     await writeFile(join(occupied, "existing.txt"), "x", "utf-8");
-    await expect(copySnapshots(results.latest(), occupied, { redact: false })).rejects.toThrow(/not empty/);
+    await expect(copySnapshots(results.latest(), occupied)).rejects.toThrow(/not empty/);
 
-    await expect(copySnapshots(results.latest(), join(await makeRoot(), "out"), { ...{ artifacts: ["evnets" as never] }, redact: false })).rejects.toThrow(/Unknown artifact kind/);
+    await expect(copySnapshots(results.latest(), join(await makeRoot(), "out"), { artifacts: ["evnets" as never] })).rejects.toThrow(/Unknown artifact kind/);
 
-    await expect(copySnapshots([], join(await makeRoot(), "out"), { redact: false })).rejects.toThrow(/no snapshots/);
+    await expect(copySnapshots([], join(await makeRoot(), "out"))).rejects.toThrow(/no snapshots/);
 
     // 手工传入同一 experiment 的两个快照(未走 latest 去重):只带最新,记 warning。
     const dest2 = join(await makeRoot(), "run2");
-    const collided = await copySnapshots(results.experiments[0].snapshots, dest2, { redact: false });
+    const collided = await copySnapshots(results.experiments[0].snapshots, dest2);
     expect(collided.warnings).toHaveLength(1);
     expect(collided.warnings[0]).toMatch(/multiple snapshots selected/);
     const destDirs = await readdir(join(dest2, "e"));
@@ -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 接口。
@@ -1005,7 +1082,7 @@ describe("AttemptLocator · 落盘 / 读取 / 携带 / 撞车", () => {
     const locator1 = a1!.locator!;
 
     const dest = join(await makeRoot(), "published");
-    await copySnapshots(results.latest(), dest, { ...{ artifacts: [] }, redact: false });
+    await copySnapshots(results.latest(), dest, { artifacts: [] });
 
     const destResults = await openResults(dest);
     expect(resolveLocator(destResults, locator0).result.attempt).toBe(0);
@@ -1192,7 +1269,7 @@ describe("sources · 快照级去重仓库", () => {
 
     const results = await openResults(root);
     const dest = join(await makeRoot(), "published");
-    await copySnapshots(results.latest(), dest, { ...{ artifacts: ["sources"] }, redact: false });
+    await copySnapshots(results.latest(), dest, { artifacts: ["sources"] });
 
     const destSnapDir = join(dest, "e", basename(snap.dir));
     const destStoreFiles = await readdir(join(destSnapDir, "sources"));

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,6 +75,7 @@ export function selectLatest(
       });
     }
   }
+  warnings.push(...unreadableSnapshotWarnings(results.skipped, results.root));
   return makeScope("latest-snapshots", snapshots, warnings);
 }
 
@@ -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 不在幸存快照中的丢弃,
@@ -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

@@ -44,11 +44,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;
 }
@@ -130,8 +125,6 @@ export interface Snapshot {
   dir: string;
   /** 写入时刻该实验已知的 eval 并集(可选);copySnapshots 自动补记,writer.snapshot() 也可声明。 */
   knownEvalIds?: string[];
-  /** 发布拷贝的自描述标记(见 SnapshotMeta.publish);本地事实根没有此字段。 */
-  publish?: { redaction: "applied" | "none" };
 }
 
 /** 一个实验的全部历史:同一 experiment id 的历次快照归在一起。 */
@@ -167,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[];
@@ -244,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);
         }),
       );

package/src/runner/ledger.test.ts

@@ -1,4 +1,4 @@
-// cases: docs/engineering/unit-tests/experiments-runner/cases.md
+// cases: docs/engineering/unit-tests/sandbox/cases.md
 // 变更分类账的集成测试:用宿主 shell 扮演沙箱(真实 git),验证
 // - .git 不在 workdir 内(agent 看不到分类账;eval 自己 git init 不冲突)
 // - eval 归因(send 前写入)不进 agent diff;send 窗口内写入逐窗口归因
@@ -153,6 +153,10 @@ describe("createChangeLedger", () => {
     await mkdir(join(workdir, "node_modules"), { recursive: true });
     await writeFile(join(workdir, "node_modules", "dep.js"), "excluded\n");
     await writeFile(join(workdir, "node_modules", "keep.js"), "included back\n");
+    await mkdir(join(workdir, "packages/app/node_modules/dep"), { recursive: true });
+    await writeFile(join(workdir, "packages/app/node_modules/dep/index.js"), "nested dependency\n");
+    await mkdir(join(workdir, "packages/app/__pycache__"), { recursive: true });
+    await writeFile(join(workdir, "packages/app/__pycache__/mod.pyc"), "nested cache\n");
     await mkdir(join(workdir, "secret"), { recursive: true });
     await writeFile(join(workdir, "secret", "token.txt"), "excluded via ignore\n");
     // Python 工具链目录不依赖项目 .gitignore:任意 *venv*/ 名字都由 runner 私有清单排除。
@@ -167,10 +171,35 @@ describe("createChangeLedger", () => {
     expect(paths).toContain("output.txt");
     expect(paths).toContain("node_modules/keep.js");
     expect(paths).not.toContain("node_modules/dep.js");
+    expect(paths).not.toContain("packages/app/node_modules/dep/index.js");
+    expect(paths).not.toContain("packages/app/__pycache__/mod.pyc");
     expect(paths).not.toContain("secret/token.txt");
     expect(paths.some((path) => path.includes("venv"))).toBe(false);
   });
 
+  // bug: memory/ledger-gitignore-pathspec-and-gitlinks.md
+  it("未排除的 nested repo 明确失败；整目录 ignore 后允许作为无关环境存在", async () => {
+    const first = await makeDirs();
+    const checkout = join(first.workdir, "checkout");
+    await mkdir(checkout, { recursive: true });
+    await execAsync("git init -q && git config user.email t@t && git config user.name t", { cwd: checkout });
+    await writeFile(join(checkout, "app.py"), "print('hello')\n");
+    await execAsync("git add app.py && git commit -qm baseline", { cwd: checkout });
+
+    await expect(createChangeLedger(hostSandbox(first.workdir, first.ledgerDir))).rejects.toThrow(
+      /nested Git repository checkout.*sandbox\.workdir root.*diff.*ignore/,
+    );
+
+    const second = await makeDirs();
+    const ignoredCheckout = join(second.workdir, "checkout");
+    await mkdir(ignoredCheckout, { recursive: true });
+    await execAsync("git init -q && git config user.email t@t && git config user.name t", { cwd: ignoredCheckout });
+    await writeFile(join(ignoredCheckout, "app.py"), "print('ignored')\n");
+    await execAsync("git add app.py && git commit -qm baseline", { cwd: ignoredCheckout });
+
+    await expect(createChangeLedger(hostSandbox(second.workdir, second.ledgerDir), { ignore: ["checkout/"] })).resolves.toBeDefined();
+  });
+
   it("整相导出只用一条 shell 命令 + 一次文件下载,不随文件数与窗口数增长", async () => {
     const { workdir, ledgerDir } = await makeDirs();
     const counters = { shells: [] as string[], downloads: [] as string[] };

package/src/runner/ledger.ts

@@ -123,6 +123,23 @@ function shellQuote(s: string): string {
   return `'${s.replaceAll("'", `'\\''`)}'`;
 }
 
+/**
+ * 把仓库根语义的 gitignore 风格规则编译成 ledger pathspec。
+ * 无斜杠的名字匹配任意深度；有斜杠的规则相对 workdir 根；目录本身与后代一起处理。
+ */
+function gitignorePathspecs(pattern: string, exclude: boolean): string[] {
+  let normalized = pattern;
+  while (normalized.startsWith("./")) normalized = normalized.slice(2);
+  if (normalized.startsWith("/")) normalized = normalized.slice(1);
+  normalized = normalized.replace(/\/+$/, "");
+  if (!normalized) return [];
+
+  const glob = normalized.includes("/") ? normalized : `**/${normalized}`;
+  const globs = exclude && !glob.endsWith("/**") ? [glob, `${glob}/**`] : [glob];
+  const magic = exclude ? ":(glob,exclude)" : ":(glob)";
+  return [...new Set(globs)].map((value) => `${magic}${value}`);
+}
+
 /** 打分类账锚点(workspace.baseline 阶段,环境层钩子之后):git init + 冻结排除清单 + 首笔 commit。 */
 export async function createChangeLedger(sandbox: Sandbox, opts?: LedgerOptions): Promise<ChangeLedger> {
   const excludes = [...DEFAULT_EXCLUDES, ...(opts?.ignore ?? [])];
@@ -131,11 +148,15 @@ export async function createChangeLedger(sandbox: Sandbox, opts?: LedgerOptions)
 
   // add -A -f:绕过项目自己的 .gitignore(项目 ignore 的文件照常记录);排除靠 pathspec
   // (runner 私有清单,agent / fixture 写 .gitignore 影响不了它);include 用第二次 add 打洞加回。
-  const excludeSpecs = excludes.map((e) => shellQuote(`:(exclude)${e}`)).join(" ");
+  const excludeSpecs = excludes.flatMap((pattern) => gitignorePathspecs(pattern, true)).map(shellQuote).join(" ");
   // include 打洞:路径此刻可能还不存在(如 agent 之后才写),unmatched pathspec 不算错。
+  const includeSpecs = includes.flatMap((pattern) => gitignorePathspecs(pattern, false)).map(shellQuote).join(" ");
   const includeAdd =
-    includes.length > 0 ? ` && { git add -A -f -- ${includes.map(shellQuote).join(" ")} 2>/dev/null || true; }` : "";
-  const addAll = `git add -A -f -- . ${excludeSpecs}${includeAdd}`;
+    includeSpecs.length > 0 ? ` && { git -c advice.addEmbeddedRepo=false add -A -f -- ${includeSpecs} 2>/dev/null || true; }` : "";
+  const rejectGitlinks =
+    " && nested=$(git ls-files --stage | awk '$1 == \"160000\" { sub(/^[^\\t]*\\t/, \"\"); print; exit }')" +
+    ' && if [ -n "$nested" ]; then printf \'%s\\n\' "niceeval ledger cannot track nested Git repository $nested as file-level evidence; move the checkout to sandbox.workdir root, or add the whole path to defineEval({ diff: { ignore: [...] } }) when it is intentionally out of scope" >&2; exit 2; fi';
+  const addAll = `git -c advice.addEmbeddedRepo=false add -A -f -- . ${excludeSpecs}${includeAdd}${rejectGitlinks}`;
 
   const anchor = await sandbox.runShell(`git init -q "${LEDGER_GIT_DIR}" && ${addAll} && git commit -q --allow-empty -m "anchor"`, {
     env,
@@ -170,7 +191,8 @@ async function exportAgentWindows(sandbox: Sandbox, env: Record<string, string>)
 
 function ensureCommandSucceeded(result: { exitCode: number; stderr: string }, operation: string): void {
   if (result.exitCode === 0) return;
-  const detail = result.stderr.trim().split("\n")[0];
+  // git 可能先输出 advisory warning，再输出 niceeval 的可操作诊断；最后一行最接近失败根因。
+  const detail = result.stderr.trim().split("\n").at(-1);
   throw new Error(`${operation} failed (exit ${result.exitCode})${detail ? `: ${detail}` : ""}`);
 }