niceeval 0.5.4 → 0.6.1

package/src/runner/reporters/quiet.ts

@@ -0,0 +1,49 @@
+// Quiet 报告器:--quiet 下的最小结果流。进度流照旧(attempt 无 onProgress 时直写 stderr),
+// 这里只补「坏结果」:verdict 为 errored / failed 的结果各写一行 stderr,passed / skipped
+// 静默 —— 保证 --quiet 下起沙箱失败这类执行错不会全程无声、只能事后读 summary.json。
+// 结果流仍走统一的 Reporter 管线,不在 attempt 里散写。
+
+import type { EvalResult, Reporter } from "../../types.ts";
+import { t } from "../../i18n/index.ts";
+import { runWho } from "../types.ts";
+import { verdictSymbol } from "./shared.ts";
+
+/** error / 断言 detail 的截断上限;比 Console 的 400 更紧,--quiet 只要能定位问题。 */
+const DETAIL_MAX = 200;
+
+/** 纯函数:一条结果 → 该写 stderr 的行;passed / skipped 返回 undefined(静默)。 */
+export function quietLine(result: EvalResult): string | undefined {
+  if (result.verdict !== "errored" && result.verdict !== "failed") return undefined;
+  // [who] 与 attempt 进度行同源(runWho),两条流才能对上同一个运行配置。
+  const who = runWho({ agentName: result.agent, model: result.model, experimentId: result.experimentId });
+  const verdict = result.verdict === "errored" ? t("report.errored") : t("report.failed");
+  const detail =
+    result.error !== undefined
+      ? `${t("report.error")}: ${truncate(result.error, DETAIL_MAX)}`
+      : firstFailedAssertion(result);
+  return `  ${verdictSymbol(result.verdict)} ${result.id} ${verdict}  [${who}]${detail ? `  ${detail}` : ""}\n`;
+}
+
+function firstFailedAssertion(result: EvalResult): string | undefined {
+  const a = result.assertions.find((x) => !x.passed);
+  if (!a) return undefined;
+  const sev = a.severity === "gate" ? t("report.gate") : t("report.soft");
+  const thr =
+    a.threshold !== undefined
+      ? t("report.assertionThreshold", { score: a.score.toFixed(2), threshold: a.threshold })
+      : "";
+  return `${sev}: ${a.name}${thr}${a.detail ? ` — ${truncate(a.detail, DETAIL_MAX)}` : ""}`;
+}
+
+function truncate(s: string, n: number): string {
+  return s.length > n ? s.slice(0, n) + "…" : s;
+}
+
+export function Quiet(): Reporter {
+  return {
+    onEvalComplete(result: EvalResult) {
+      const line = quietLine(result);
+      if (line !== undefined) process.stderr.write(line);
+    },
+  };
+}

package/src/runner/reporters/shared.ts

@@ -1,18 +1,18 @@
 // reporter 共用的展示常量。符号表只此一份 —— console/live/table 各抄一份时,
 // 改一个符号要同步三处且不报错。
 
-import type { ResultOutcome } from "../../types.ts";
+import type { Verdict } from "../../types.ts";
 
-export const OUTCOME_SYM: Record<ResultOutcome, string> = {
+export const VERDICT_SYM: Record<Verdict, string> = {
   passed: "✓",
   failed: "✗",
   errored: "!",
   skipped: "○",
 };
 
-export function outcomeSymbol(outcome: string): string {
-  return OUTCOME_SYM[outcome as ResultOutcome] ?? "?";
+export function verdictSymbol(verdict: string): string {
+  return VERDICT_SYM[verdict as Verdict] ?? "?";
 }
 
-/** live 表格里「还没抢到并发名额」的行:和转圈的 SPINNER、完成后的 OUTCOME_SYM 三态区分开。 */
+/** live 表格里「还没抢到并发名额」的行:和转圈的 SPINNER、完成后的 VERDICT_SYM 三态区分开。 */
 export const WAITING_SYM = "·";

package/src/runner/reporters/table.ts

@@ -1,11 +1,11 @@
 import type { EvalResult, RunSummary, Usage } from "../../types.ts";
 import { t } from "../../i18n/index.ts";
-import { outcomeSymbol } from "./shared.ts";
-import { foldEvalOutcome, evalLevelStats as sharedEvalLevelStats } from "../../shared/outcome.ts";
+import { verdictSymbol } from "./shared.ts";
+import { foldEvalVerdict, evalLevelStats as sharedEvalLevelStats } from "../../shared/verdict.ts";
 // 展示口径(耗时/成本/百分比)与聚合小工具(标签/求和/排序)与 view 共用一份实现;
 // console.ts 经这里 re-export formatDuration。
 import { formatCost, formatDuration, formatPercent } from "../../shared/format.ts";
-import { OUTCOME_ORDER, avg, displayExperimentName, fallbackExperimentLabel, sumMaybe, totalTokens } from "../../shared/aggregate.ts";
+import { VERDICT_ORDER, avg, displayExperimentName, fallbackExperimentLabel, sumMaybe, totalTokens } from "../../shared/aggregate.ts";
 
 export { formatCost, formatDuration } from "../../shared/format.ts";
 
@@ -29,7 +29,7 @@ interface ExperimentRow {
 
 interface EvalRow {
   id: string;
-  outcome: EvalResult["outcome"];
+  verdict: EvalResult["verdict"];
   reason: string;
   durationMs: number;
   tokens: number;
@@ -77,7 +77,7 @@ export function renderRunReport(summary: RunSummary): string {
         t("report.table.runs"),
       ],
       aggregateEvalRows(row.results).map((evalRow) => [
-        formatOutcome(evalRow.outcome),
+        formatVerdict(evalRow.verdict),
         evalRow.id,
         evalRow.reason,
         formatDuration(evalRow.durationMs),
@@ -114,14 +114,14 @@ export function formatTokens(n: number): string {
   return String(n);
 }
 
-export function formatOutcome(outcome: string): string {
-  const sym = outcomeSymbol(outcome);
-  switch (outcome) {
+export function formatVerdict(verdict: string): string {
+  const sym = verdictSymbol(verdict);
+  switch (verdict) {
     case "passed": return `${sym} ${t("report.passed")}`;
     case "failed": return `${sym} ${t("report.failed")}`;
     case "errored": return `${sym} ${t("report.errored")}`;
     case "skipped": return `${sym} ${t("report.skipped")}`;
-    default: return `${sym} ${outcome}`;
+    default: return `${sym} ${verdict}`;
   }
 }
 
@@ -162,26 +162,26 @@ function aggregateEvalRows(results: EvalResult[]): EvalRow[] {
   for (const result of results) byEval.set(result.id, [...(byEval.get(result.id) ?? []), result]);
   return [...byEval.entries()]
     .map(([id, evalResults]) => {
-      const outcome = foldEvalOutcome(evalResults);
+      const verdict = foldEvalVerdict(evalResults);
       const representative =
-        evalResults.find((r) => r.outcome === outcome) ??
-        evalResults.find((r) => r.outcome !== "passed") ??
+        evalResults.find((r) => r.verdict === verdict) ??
+        evalResults.find((r) => r.verdict !== "passed") ??
         evalResults[0]!;
       return {
         id,
-        outcome,
-        reason: outcome === "passed" ? t("report.passed") : reasonFor(representative),
+        verdict,
+        reason: verdict === "passed" ? t("report.passed") : reasonFor(representative),
         durationMs: avg(evalResults.map((r) => r.durationMs)),
         tokens: totalTokens(evalResults.map((r) => r.usage)),
         cost: sumMaybe(evalResults.map((r) => r.estimatedCostUSD)),
-        passedAttempts: evalResults.filter((r) => r.outcome === "passed").length,
+        passedAttempts: evalResults.filter((r) => r.verdict === "passed").length,
         attempts: evalResults.length,
       };
     })
-    .sort((a, b) => OUTCOME_ORDER[a.outcome] - OUTCOME_ORDER[b.outcome] || a.id.localeCompare(b.id));
+    .sort((a, b) => VERDICT_ORDER[a.verdict] - VERDICT_ORDER[b.verdict] || a.id.localeCompare(b.id));
 }
 
-// 折叠 / 计票口径与 view 同一份实现(src/shared/outcome.ts),CLI 表格和网页榜单永不打架。
+// 折叠 / 计票口径与 view 同一份实现(src/shared/verdict.ts),CLI 表格和网页榜单永不打架。
 function evalLevelStats(results: EvalResult[]) {
   return sharedEvalLevelStats(results, (r) => r.id);
 }

package/src/runner/run.ts

@@ -3,13 +3,14 @@
 // reporter 编排 / 汇总在 report.ts,Sandbox 适配器在 remote-sandbox.ts。
 
 import { readFile } from "node:fs/promises";
-import { Effect, Cause, Duration, Exit } from "effect";
+import { Effect, Cause, Exit } from "effect";
 import { probeJudge } from "../scoring/judge.ts";
 import { t } from "../i18n/index.ts";
-import { cacheKey, computeFingerprint } from "./fingerprint.ts";
+import { cacheKey, planCarry } from "./fingerprint.ts";
 import { OtelReceiverPool } from "../o11y/otlp/turn-otel.ts";
 import { runAttemptEffect } from "./attempt.ts";
 import { runReporter, emitReporterEvent, scopeReporter, summarize } from "./report.ts";
+import { writeStderrLine } from "../tty-line.ts";
 import type { Agent, EvalResult, JudgeConfig, Reporter, RunShape, RunSummary } from "../types.ts";
 import type { AgentRun, Attempt, RunOptions } from "./types.ts";
 
@@ -54,42 +55,14 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
     return p;
   };
 
-  const plannedFingerprints = new Map<string, string>();
-  {
-    const jobs: Promise<void>[] = [];
-    for (const run of opts.agentRuns) {
-      for (const evalDef of opts.evals.filter((e) => run.evalFilter(e.id))) {
-        jobs.push(
-          computeFingerprint(evalDef, run, sourceCache).then((fp) => {
-            plannedFingerprints.set(cacheKey(run, evalDef.id), fp);
-          }),
-        );
-      }
-    }
-    await Promise.all(jobs);
-  }
-
-  // 跨实验结果复用:只有上次 passed 且 fingerprint 匹配的 (experimentId, evalId) 组合直接携入。
-  // 失败/错误/跳过/fingerprint 不匹配都会重跑。--force 跳过此逻辑。
-  const priorRunKeys = new Set<string>();
-  const carriedResults: EvalResult[] = [];
-  if (opts.priorResults?.length) {
-    for (const r of opts.priorResults) {
-      if (!r.experimentId) continue;
-      const key = `${r.experimentId}|${r.id}`;
-      if (r.outcome === "passed" && r.fingerprint !== undefined && r.fingerprint === plannedFingerprints.get(key)) {
-        priorRunKeys.add(key);
-      }
-    }
-    for (const r of opts.priorResults) {
-      if (!r.experimentId || !priorRunKeys.has(`${r.experimentId}|${r.id}`)) continue;
-      // artifactsDir 是相对"本次 run 自己目录"的路径,新 summary 换了目录就会失效,必须清掉。
-      // artifactBase 不一样:它已经是 loadLatestResultsPerEval(经 withViewRefs)拼好的、
-      // 相对稳定的 .niceeval 根的路径,指向旧 run 的产物目录依然可解析,原样带过来
-      // ——不然 view 就再也找不到这条携带结果的源码/转录/trace 了。
-      carriedResults.push({ ...r, artifactsDir: undefined });
-    }
-  }
+  // 跨实验结果复用:上次 passed 或 failed 且 fingerprint 匹配的 (experimentId, evalId) 组合
+  // 直接携入 —— 两者都是"跑完了、判定确定"的终态,没有理由重花一次 agent/sandbox 成本去
+  // 复现同一个已知结果。errored 是框架/环境层面的不确定失败(超时、沙箱挂了、judge 探测失败
+  // 等),判定本身不可信,必须重跑。跳过/fingerprint 不匹配同样重跑。--force 跳过此逻辑
+  // (cli.ts 在 --force 时不传 priorResults,也不算 carryPlan)。
+  // carryPlan 优先用调用方(cli.ts,为了 live 表格)已经算好的那份,不重算一遍。
+  const { plannedFingerprints, priorRunKeys, carriedResults } =
+    opts.carryPlan ?? (await planCarry(opts.evals, opts.agentRuns, opts.priorResults));
 
   // 展开 attempts
   // 外层按「round」(run index)迭代,内层按 eval 迭代:同一 key 的第 i+1 次 attempt 排在
@@ -207,17 +180,16 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
   // 真的没过)才代表 agent 行为的样本,值得跑满 runs 去测通过率。earlyExit 开时两者都提前收尾。
   const erroredKeys = new Set<string>();
 
-  // budget 护栏带「在飞预扣」:实测成本只有 attempt 完成后才知道,若只检查已完成花费,
-  // maxConcurrency 个 attempt 会在任何成本回写前全部起飞,实际花费能冲到 budget 的十几倍。
-  // 口径:还没有任何【带成本】的完成样本时,同一 budgetKey 只放一个 attempt 在飞(探单次成本);
-  // 有样本后,用平均实测成本给每个在飞 attempt 预扣,预计总额到顶就等,已花到顶就停。
-  // costSamples 只数报了成本的 attempt —— 不报成本的完成(agent 无用量、模型不在价格表、
-  // 早期 errored)不能算 0 元样本,否则均值被拉成 0,护栏彻底失效。连续多次完成都拿不到
-  // 成本时,说明这个 agent 的 budget 根本不可执行:警告一次然后放行,而不是永远串行装样子。
+  // budget 护栏:只按「已完成 attempt 的实测花费」判断,不做预测性节流。之前的实现会按
+  // 「平均成本 × 在飞数」预扣,快到顶就让还没起飞的 attempt 排队等——这在探测阶段(还没有任何
+  // 成本样本时)等价于把同一 budgetKey 的并发摁到一个很小的数,且完全没有文档承诺过这个副作用
+  // (`docs-site/zh/guides/write-experiment.mdx` 对 `budget` 的描述只有一句「这一格配置的预算
+  // 上限」)。新语义:已完成 attempt 的花费加总一旦到顶,就不再放新 attempt 起飞(已经在飞的
+  // 照常跑完,不会被中途打断);到顶之前不做任何预测性限流,并发完全由 globalSem / runSem 决定。
+  // 代价是「已花 + 在飞未结算」的总花费可能短暂超出 budget——这是有意识的取舍:budget 是防止
+  // 无限烧钱的安全网,不是精确计费闸,不应该反过来限制吞吐。
   interface BudgetState {
     spent: number;
-    inflight: number;
-    costSamples: number;
     completedNoCost: number;
     unenforceableWarned: boolean;
   }
@@ -225,7 +197,7 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
   const budgetState = (key: string): BudgetState => {
     let s = budgetStates.get(key);
     if (!s) {
-      s = { spent: 0, inflight: 0, costSamples: 0, completedNoCost: 0, unenforceableWarned: false };
+      s = { spent: 0, completedNoCost: 0, unenforceableWarned: false };
       budgetStates.set(key, s);
     }
     return s;
@@ -236,7 +208,7 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
   // 并发 worker 交错写 → 用一个 permit=1 的信号量串起来(替代原先手搓的 reportQueue 链)。
   const reportMutex = Effect.runSync(Effect.makeSemaphore(1));
   // 沙箱启动单独限流:与 agent 并发(maxConcurrency)解耦,防高并发下 daemon/API 过载。
-  // 未显式指定时跟 maxConcurrency 走——各 backend 的推荐值已在 cli 层写进 maxConcurrency 默认值。
+  // 未显式指定时跟 maxConcurrency 走——各 provider 的推荐值已在 cli 层写进 maxConcurrency 默认值。
   const sandboxSem = Effect.runSync(Effect.makeSemaphore(opts.maxConcurrency));
 
   // 两级并发闸:全局(opts.maxConcurrency)+ 实验级(AgentRun.maxConcurrency,可选)。
@@ -286,10 +258,15 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
     Effect.forEach(
       attempts,
       (a) => {
-        const body = Effect.gen(function* () {
-            // 早停:同 key 已通过,或已 errored(重跑只会重复同一个框架错误)且开了 earlyExit
-            // → 跳过未启动的 attempt。检查必须在拿到 permit 之后(fiber 是 unbounded 一次性
-            // 全建的,建时结果还没出来);跳过路径短暂占一个 permit,可忽略。
+        const budgetKey = a.run.experimentId ?? a.run.agent.name;
+
+        // preflight:「要不要开始跑」的许可判断(首过即停 + budget 上限检查),不持有
+        // globalSem——两类判断都是即时返回,不该占着全局并发槽位做无谓等待。runSem(实验自己的
+        // maxConcurrency)例外:它是实验私有资源,preflight 占着不影响别的实验,且和 mempal
+        // 那类「必须串行」的语义一致,所以仍然把 preflight 包在 runSem 里面(见下方)。
+        const preflight = Effect.gen(function* () {
+            // 首过即停:同 key 已通过,或已 errored(重跑只会重复同一个框架错误)且开了 earlyExit
+            // → 跳过未启动的 attempt。
             if (a.run.earlyExit && (passedKeys.has(a.key) || erroredKeys.has(a.key))) {
               yield* reportMutex.withPermits(1)(
                 Effect.promise(() =>
@@ -300,49 +277,32 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
                   }),
                 ),
               );
-              return;
+              return false;
             }
 
             const budget = a.run.budget;
-            const budgetKey = a.run.experimentId ?? a.run.agent.name;
             if (budget !== undefined) {
-              // 预扣循环:预计花费(已花 + 在飞×均值)到顶就等在飞的结算,已花到顶就整段停。
-              // 注意等待的 fiber 仍占一个并发位(简单可靠;混跑「带 budget + 不带 budget」
-              // 的多实验时会牺牲些吞吐 —— budget 本就是拿速度换花费上限的模式)。
-              for (;;) {
-                const s = budgetState(budgetKey);
-                if (s.spent >= budget) {
-                  if (!budgetReported.has(budgetKey)) {
-                    budgetReported.add(budgetKey);
-                    yield* reportMutex.withPermits(1)(
-                      Effect.promise(() =>
-                        emitReporterEvent(reporters, { type: "run:budgetExceeded", budget, spent: s.spent }),
-                      ),
-                    );
-                  }
-                  return;
-                }
-                if (s.costSamples === 0 && s.completedNoCost >= 3 && !s.unenforceableWarned) {
-                  // 连续几次完成都拿不到成本:budget 对这个 agent 不可执行,说清楚再放行。
-                  s.unenforceableWarned = true;
-                  process.stderr.write(t("runner.budgetUnenforceable", { budgetKey }));
-                }
-                if (s.costSamples === 0 && s.unenforceableWarned) {
-                  s.inflight += 1;
-                  break;
-                }
-                const avg = s.costSamples > 0 ? s.spent / s.costSamples : undefined;
-                const projected =
-                  avg === undefined ? (s.inflight > 0 ? Number.POSITIVE_INFINITY : 0) : s.spent + s.inflight * avg;
-                if (projected < budget) {
-                  s.inflight += 1;
-                  break;
+              // 只看已完成 attempt 的实测花费(见上方 BudgetState 注释),到顶就跳过新 attempt,
+              // 没到顶就立即放行——不等待、不做预测性节流。
+              const s = budgetState(budgetKey);
+              if (s.spent >= budget) {
+                if (!budgetReported.has(budgetKey)) {
+                  budgetReported.add(budgetKey);
+                  yield* reportMutex.withPermits(1)(
+                    Effect.promise(() =>
+                      emitReporterEvent(reporters, { type: "run:budgetExceeded", budget, spent: s.spent }),
+                    ),
+                  );
                 }
-                yield* Effect.sleep(Duration.millis(200));
+                return false;
               }
             }
+            return true;
+          });
 
-            // 合并全局信号与本 eval 的早停信号:任一 abort → 本 attempt 的信号 abort。
+        // body:preflight 放行之后才跑,只有这一段真正占用全局并发槽位(globalSem)。
+        const body = Effect.gen(function* () {
+            // 合并全局信号与本 eval 的首过即停信号:任一 abort → 本 attempt 的信号 abort。
             const evalAc = evalAbortControllers.get(a.key);
             const attemptSignal =
               evalAc && opts.signal
@@ -361,34 +321,29 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
                 }),
               ),
             );
-            const result = yield* runAttemptEffect(a, opts, sandboxSem, attemptSignal).pipe(
-              Effect.ensuring(
-                Effect.sync(() => {
-                  if (a.run.budget !== undefined) {
-                    const s = budgetState(budgetKey);
-                    s.inflight = Math.max(0, s.inflight - 1);
-                  }
-                }),
-              ),
-            );
+            const result = yield* runAttemptEffect(a, opts, sandboxSem, attemptSignal);
             if (a.run.budget !== undefined) {
               const s = budgetState(budgetKey);
               if (result.estimatedCostUSD !== undefined) {
                 s.spent += result.estimatedCostUSD;
-                s.costSamples += 1;
               } else {
                 s.completedNoCost += 1;
+                if (s.spent === 0 && s.completedNoCost >= 3 && !s.unenforceableWarned) {
+                  // 连续几次完成都拿不到成本:budget 对这个 agent 不可执行,说清楚一次。
+                  s.unenforceableWarned = true;
+                  writeStderrLine(t("runner.budgetUnenforceable", { budgetKey }));
+                }
               }
             }
 
-            if (result.outcome === "passed") {
+            if (result.verdict === "passed") {
               passedKeys.add(a.key);
               evalAc?.abort(); // 让同 key 并发 attempt 尽早退出
             } else if (a.run.earlyExit && (passedKeys.has(a.key) || erroredKeys.has(a.key))) {
               // 并发情况:同 key 另一个 attempt 已通过/已 errored 后本 attempt 才完成
               // (被 abort 后产出 errored),不计入结果。
               return;
-            } else if (result.outcome === "errored") {
+            } else if (result.verdict === "errored") {
               erroredKeys.add(a.key);
               evalAc?.abort(); // 框架层面的错误会确定性重复,让同 key 剩余 attempt 尽早退出
             }
@@ -413,7 +368,11 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
               Effect.promise(() => emitReporterEvent(reporters, { type: "eval:complete", result })),
             );
           });
-        const gated = globalSem.withPermits(1)(body);
+        const gated = Effect.gen(function* () {
+          const proceed = yield* preflight;
+          if (!proceed) return;
+          yield* globalSem.withPermits(1)(body);
+        });
         const runSem = runSems.get(a.run);
         return runSem ? runSem.withPermits(1)(gated) : gated;
       },

package/src/runner/types.ts

@@ -3,10 +3,11 @@
 
 import type { Cleanup, LocalizedText, SourceArtifact } from "../shared/types.ts";
 import type { O11ySummary, StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
-import type { Agent } from "../agents/types.ts";
+import type { Agent, AgentSetupManifest } from "../agents/types.ts";
 import type { Sandbox, SandboxOption } from "../sandbox/types.ts";
-import type { AssertionResult, DiffData, JudgeConfig, ResultOutcome } from "../scoring/types.ts";
+import type { AssertionResult, DiffData, JudgeConfig, Verdict } from "../scoring/types.ts";
 import type { TestContext } from "../context/types.ts";
+import type { CapturedEvalSource } from "./eval-source.ts";
 
 // ───────────────────────── 结果 / 报告 ─────────────────────────
 
@@ -27,11 +28,19 @@ export interface EvalResult {
   experiment?: ExperimentRunInfo;
   agent: string;
   model?: string;
-  outcome: ResultOutcome;
+  verdict: Verdict;
   fingerprint?: string;
   attempt: number;
   /** 本 attempt 开始的墙钟时刻(ISO);view 按 eval 粒度展示「何时跑的」。 */
   startedAt?: string;
+  /**
+   * 不透明的 Attempt 定位符(`@` 前缀短确定性编码,见 `src/results/locator.ts` 的 AttemptLocator),
+   * 由 {experimentId, 快照 startedAt, evalId, attempt} 身份元组派生。非携带条目由 writer 在落盘时
+   * 算出;携带条目(`--resume` 合入)原样复制上一轮的值,从不重算——原快照的 startedAt 已经不在
+   * 当前快照里,重算会算出不同的字符串,详见 writer.ts 对携带分支的说明。省略时读取面按当前
+   * 已知身份兜底算出(第三方 harness 未实现 locator 时的降级,不保证跨 --resume 稳定)。
+   */
+  locator?: string;
   durationMs: number;
   assertions: AssertionResult[];
   usage?: Usage;
@@ -44,33 +53,29 @@ export interface EvalResult {
   o11y?: O11ySummary;
   /** agent 经 OpenTelemetry 导出的运行追踪(有 tracing 能力且收到 span 时)。 */
   trace?: TraceSpan[];
+  /** 本 attempt 的 agent setup 实际装了什么(Skill / native plugin / MCP / Python plugin);不参与评分。 */
+  agentSetup?: AgentSetupManifest;
   diff?: DiffData;
   rawTranscript?: string;
-  // ── 拆分工件的引用(Artifacts 报告器写 summary.json 时填;view 按需懒加载)──
-  /** 本 attempt 工件目录(相对 run 根),下有 events/trace/o11y/diff.json。 */
-  artifactsDir?: string;
-  /** 工件目录(相对结果根,供前端 fetch 与懒加载回退);view 的 loader 注入,--resume 携带条目落盘时保留。 */
+  /** 携带条目(--resume 合入)专用:artifact 目录(相对结果根目录),指向原快照里的落盘。 */
   artifactBase?: string;
-  /** 工件目录的绝对路径;历史字段,当前读取面不再注入。 */
-  artifactAbsBase?: string;
   hasTrace?: boolean;
   hasEvents?: boolean;
   hasSources?: boolean;
 }
 
-/** `summary.json` 的格式标记;把 niceeval 报告和其它工具的同名文件区分开。 */
+/** `snapshot.json` 的格式标记;把 niceeval 报告和其它工具的同名文件区分开。 */
 export const RESULTS_FORMAT = "niceeval.results";
-/** 结果格式版本,只在破坏兼容读取时递增;读取器只认相同版本,缺失按 1。见 docs/results-format.md。 */
-export const RESULTS_SCHEMA_VERSION = 3;
+/**
+ * 结果格式版本,只在破坏兼容读取时递增;读取器只认相同版本。见 docs/feature/results/architecture.md。
+ * `5`(见 memory 的 attempt-locator-and-source-dedup 条目)= result.json 新增 `locator` 字段;
+ * `sources.json` 从逐 attempt 内联全量内容改为「attempt 级引用 + 快照级 `sources/<sha256>.json`
+ * 去重仓库」,`AttemptHandle.sources()` 的公开返回形状不变(仍是 `SourceArtifact[] | null`)。
+ */
+export const RESULTS_SCHEMA_VERSION = 5;
 
+/** 一次运行的纯运行时内存聚合(reporter 契约用);落盘格式契约在 niceeval/results 的 SnapshotMeta / AttemptRecord,见 docs/feature/results/architecture.md。 */
 export interface RunSummary {
-  /** 恒为 "niceeval.results";和 schemaVersion、producer 一起构成持久化契约,永不移动或改名。 */
-  format?: typeof RESULTS_FORMAT;
-  /** 结果格式版本;与读取器不同即视为不兼容,提示用 producer.version 对应的 niceeval 查看。 */
-  schemaVersion?: number;
-  /** 写这份报告的工具:niceeval 自己,或经 niceeval/results 写入面转换的第三方 harness。
-   *  name === "niceeval" 时 version 用于拼 `npx niceeval@<version> view` 提示;其它 name 如实报出。 */
-  producer?: { name: string; version?: string; commit?: string };
   /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
   name?: LocalizedText;
   agent: string;
@@ -87,12 +92,6 @@ export interface RunSummary {
   usage?: Usage;
   estimatedCostUSD?: number;
   results: EvalResult[];
-  outputDir?: string;
-  /** 快照级元数据,按 experiment 键(缺 experimentId 时为 "<agent>/<model>" 合成键)存放:
-   *  startedAt 只在与顶层 startedAt 不同(一个 run 装多份不同时刻的快照)时需要;
-   *  knownEvalIds 是写入时刻该实验已知的 eval 并集(copySnapshots 自动补记,writer.snapshot 可声明)。
-   *  可选新增字段,不递增 schemaVersion(docs/results-format.md 版本规则)。 */
-  snapshots?: Record<string, { startedAt?: string; knownEvalIds?: string[] }>;
 }
 
 /** onRunStart 的运行规模:去重后 eval 数 × 配置(agent×model×flags)数 → 总运行(attempt)数。 */
@@ -144,7 +143,7 @@ export interface EvalDef {
   /**
    * eval 级预置:拿到沙箱(已上传 workspace + git 基线 + 装好依赖前)。
    * 默认命令以非 root 跑(agent 的自然环境);装系统依赖时给 `runCommand` 传 `{ root: true }`
-   * (如 `runCommand("apt-get", ["install", …], { root: true })`),跨后端语义一致。
+   * (如 `runCommand("apt-get", ["install", …], { root: true })`),跨 provider 语义一致。
    */
   setup?: (sandbox: Sandbox) => Promise<void | Cleanup> | void | Cleanup;
   /** eval 主体:拿到 TestContext,驱动对话 / 沙箱操作并就地断言。 */
@@ -158,6 +157,11 @@ export interface DiscoveredEval extends EvalDef {
   baseDir: string;
   /** 定义文件绝对路径,用于内容指纹缓存。 */
   sourcePath: string;
+  /**
+   * discovery 时捕获的规范化源码(归一化文本 + 项目相对路径 + SHA-256),见 `eval-source.ts`。
+   * 同一文件里多个 eval(数组默认导出)共享同一份引用——哈希与内容天然相同,不重复读盘。
+   */
+  source: CapturedEvalSource;
 }
 
 export interface ExperimentDef {
@@ -196,7 +200,7 @@ export interface ExperimentDef {
    * 本实验自己的并发上限:调度器只对这个实验的 attempt 限流,同批其它实验不受影响,
    * 仍按全局并发(CLI / env / config / 沙箱默认)跑。用于串行化有共享状态的实验
    * (如跨 eval 累积记忆:`maxConcurrency: 1` 保证 attempt 按 eval 顺序一个个跑),
-   * 或给撞后端限额的实验单独降速。
+   * 或给撞 provider 限额的实验单独降速。
    */
   maxConcurrency?: number;
 }
@@ -212,7 +216,7 @@ export interface Config {
    * 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
    */
   name?: LocalizedText;
-  /** 项目级默认沙箱后端(docker / vercel / e2b / custom);experiment / CLI flag 可覆盖。 */
+  /** 项目级默认沙箱 provider(docker / vercel / e2b / custom);experiment 可覆盖。 */
   sandbox?: SandboxOption;
   /** 上传进沙箱的工作区根目录,省略则用项目根;eval 的 sandbox 视图从这里起步。 */
   workspace?: string;
@@ -262,9 +266,9 @@ export interface PriceOverride {
  * 能区分同 agent 同 model 的实验变体,如 xxx 与 xxx--agents-md;与汇总表口径一致);
  * 无 experiment 时退回 agent/model。live display 以它作行聚合 key,两处必须同源。
  */
-export function runWho(run: Pick<AgentRun, "agent" | "model" | "experimentId">): string {
+export function runWho(run: { agentName: string; model?: string; experimentId?: string }): string {
   if (run.experimentId) return run.experimentId.split("/").pop()!;
-  return run.model ? `${run.agent.name}/${run.model}` : run.agent.name;
+  return run.model ? `${run.agentName}/${run.model}` : run.agentName;
 }
 
 /** 一个 (agent, model, flags) 的运行配置 —— 由 CLI / 实验展开。 */
@@ -295,8 +299,15 @@ export interface RunOptions {
   signal?: AbortSignal;
   /** TTY live display 的进度回调;设置后 attempt 的 log 消息路由到它而不是 stderr。 */
   onProgress?: (evalId: string, who: string, msg: string) => void;
-  /** 上次运行的结果。outcome === "passed" 的 (experimentId, evalId) 组合跳过重跑,结果直接合入本次汇总。 */
+  /** 上次运行的结果。verdict 为 passed/failed 的 (experimentId, evalId) 组合跳过重跑,结果直接合入本次汇总。 */
   priorResults?: EvalResult[];
+  /**
+   * 预算好的携入计划(见 fingerprint.ts 的 planCarry)。cli.ts 为了让 live 表格提前知道
+   * 哪些行会被携入,必须在构建 liveRows 之前算一次;传进来后 runEvals 直接复用,不重算
+   * 一遍(否则两处各自算一次,不仅重复 I/O,还留下"两边判断可能不一致"的隐患)。
+   * 省略时 runEvals 自己算(测试直调等场景)。
+   */
+  carryPlan?: import("./fingerprint.ts").CarryPlan;
   /**
    * 非沙箱 tracing agent 的 run 级共享 OTLP 接收池(runEvals 创建并回收;
    * 每个 agent 一个 receiver,attempt 之间共享 —— 被测应用是长驻进程,端点不能随 attempt 换)。
@@ -309,7 +320,7 @@ export interface Attempt {
   evalDef: DiscoveredEval;
   run: AgentRun;
   attempt: number;
-  /** agent+model+evalId,用于早停。 */
+  /** agent+model+evalId,用于首过即停。 */
   key: string;
   fingerprint: string;
 }

package/src/sandbox/checkpoint.ts

@@ -8,7 +8,7 @@
 //   restore: uploadFile → /tmp/__fe_rs_<uuid>.tar.gz  →  tar xzf -C /
 //
 // tar / binary file I/O 在所有 Linux sandbox(Docker、Vercel、e2b、Modal…)里都支持,
-// 这段代码对任意 backend 的 Sandbox 实现无改动即可使用。
+// 这段代码对任意 provider 的 Sandbox 实现无改动即可使用。
 
 import { randomUUID } from "node:crypto";
 import type { Sandbox } from "../types.ts";

package/src/sandbox/docker.ts

@@ -1,4 +1,4 @@
-// Docker 沙箱后端:用 dockerode 把容器当隔离工作区跑 eval。
+// Docker 沙箱 provider:用 dockerode 把容器当隔离工作区跑 eval。
 // 改编自 agent-eval 的 docker-sandbox.ts,签名对齐 ../types.ts 的 Sandbox 契约
 //(runShell/runCommand 的 opts 一律是选项对象,不再用位置参数)。
 
@@ -24,6 +24,17 @@ import { buildFindScript, shellQuote } from "./shell.ts";
 import { createExecDemuxer, extractFileFromTar, packFilesToTar, readableToBuffer } from "./docker-stream.ts";
 import { resolveSandboxPath } from "./paths.ts";
 import { t } from "../i18n/index.ts";
+import { beforeExternalTerminalWrite } from "../tty-line.ts";
+import type { SandboxProvisionErrorKind } from "./errors.ts";
+
+/**
+ * dockerode 对镜像拉取限流没有专门的错误类型;Docker Hub 429 体现在错误 message 里
+ * (如 "toomanyrequests: You have reached your pull rate limit")。
+ */
+export function classifyProvisionError(e: unknown): SandboxProvisionErrorKind {
+  const msg = e instanceof Error ? e.message : String(e);
+  return /toomanyrequests|rate limit exceeded|429/i.test(msg) ? "rate_limit" : "unknown";
+}
 
 // 行首哨兵:源码文件几乎不可能出现这一串,用来切分单次 shell 输出里的多份文件。
 const SOURCE_FILE_MARKER = "::FE-SRC-7b3f9c::";
@@ -167,8 +178,10 @@ export class DockerSandbox implements Sandbox {
       await image.inspect();
     } catch {
       // 镜像不存在,拉取。
+      beforeExternalTerminalWrite();
       console.log(t("docker.imagePullStart", { image: imageName }));
       await this.pullImage(imageName);
+      beforeExternalTerminalWrite();
       console.log(t("docker.imagePullDone", { image: imageName }));
     }
   }
@@ -240,7 +253,7 @@ export class DockerSandbox implements Sandbox {
     });
   }
 
-  /** 以 root 跑命令(后端内部用:容器初始化、属主收敛)。 */
+  /** 以 root 跑命令(provider 内部用:容器初始化、属主收敛)。 */
   private async runCommandAsRoot(
     cmd: string,
     args: string[] = [],