niceeval 0.9.0 → 0.10.0

package/src/runner/types.ts

@@ -1,7 +1,7 @@
 // runner 域类型:结果 / 汇总 / reporter 契约,eval / experiment / config 定义,
 // 以及调度器的编排类型(AgentRun / RunOptions / Attempt)。
 
-import type { Cleanup, JsonValue, LocalizedText, SourceArtifact } from "../shared/types.ts";
+import type { JsonValue, LocalizedText, ScopedFeedback, SourceArtifact } from "../shared/types.ts";
 import type { O11ySummary, StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
 import type { Agent, AgentSetupManifest } from "../agents/types.ts";
 import type { Sandbox, SandboxHookContext, SandboxOption } from "../sandbox/types.ts";
@@ -21,6 +21,8 @@ export interface ExperimentRunInfo {
   description?: string;
   reasoningEffort?: string;
   flags?: Record<string, JsonValue>;
+  /** 报告归类标注(ExperimentDef.labels 原样投影);不透传运行时,不参与可比性配置。 */
+  labels?: Record<string, string | number>;
   runs: number;
   earlyExit: boolean;
   timeoutMs?: number;
@@ -50,6 +52,10 @@ export interface SandboxRunInfo {
  * provider / 用户 hook 能直接设置的公共字段。
  */
 export type LifecyclePhase =
+  // 实验级(整场一次,宿主机侧):只用于错误/诊断归因,不属于任何单个 attempt,
+  // 永不出现在 phases[] 计时里(见 docs/feature/experiments/architecture.md「实验级生命周期」)
+  | "experiment.setup" // ExperimentDef.setup;setup 抛错时本实验所有 attempt 的 error.phase
+  | "experiment.teardown" // ExperimentDef.teardown;失败只产生运行级 diagnostic
   // 主链:从排队到 trace collect,覆盖到判定与主证据收集完成,按执行序
   | "sandbox.queue" // 等待并发信号量(调度等待,唯一不属于某个 owner 的成员)
   | "sandbox.create" // provider 起沙箱
@@ -64,7 +70,7 @@ export type LifecyclePhase =
   | "scoring.evaluate" // 断言 finalize + 判定,含 judge 调用
   | "telemetry.collect" // OTLP receiver settle / collect
   // 收尾段:无论主链成败都执行,不计入 durationMs 口径,按执行序
-  | "eval.teardown" // EvalDef.setup 返回的 cleanup 函数
+  | "eval.teardown" // EvalDef.teardown
   | "agent.teardown"
   | "sandbox.teardown" // SandboxSpec.teardown() 钩子链
   | "sandbox.suspend" // 留存提交后 provider 把现场转入休眠(docker stop / e2b pause)
@@ -320,32 +326,41 @@ export interface EvalDef {
   description?: string;
   /** 标签,供 CLI `--tag` 过滤和 view 分类;与 id 前缀过滤是两套独立的筛选维度。 */
   tags?: string[];
-  /** 这条 eval 需要的环境 profile id(provider-neutral,如 `"python-3.9-astropy-4.2"`);由 sandbox spec 的 `environments` 表翻译成该 provider 的预制产物。 */
+  /** 这条评估用例需要的环境 profile id(provider-neutral,如 `"python-3.9-astropy-4.2"`);由 sandbox spec 的 `environments` 表翻译成该 provider 的预制产物。 */
   environment?: string;
-  /** 覆盖项目级 Config.judge,只对这一个 eval 生效(如换个更贵的评审模型)。 */
+  /** 覆盖项目级 Config.judge,只对这一条评估用例生效(如换个更贵的评审模型)。 */
   judge?: JudgeConfig;
-  /** 覆盖 / 追加项目级 Config.reporters,只对这一个 eval 生效。 */
+  /** 覆盖 / 追加项目级 Config.reporters,只对这一条评估用例生效。 */
   reporters?: Reporter[];
-  /** 覆盖项目级 / CLI 的单次 attempt 超时(毫秒),只对这一个 eval 生效。 */
+  /** 覆盖项目级 / CLI 的单次 attempt 超时(毫秒),只对这一条评估用例生效。 */
   timeoutMs?: number;
   /** 任意附加元数据,原样透传进 EvalResult,不参与调度或打分;供自定义 reporter 消费。 */
   metadata?: Record<string, unknown>;
   /**
-   * 调整 agent diff 的归因排除清单(仅沙箱型;见 docs/feature/eval/README.md):两个数组都是
+   * 调整 agent diff 的归因排除清单(仅 Sandbox 型;见 docs/feature/eval/README.md):两个数组都是
    * gitignore 风格 glob(workdir 相对)。默认排除 .git/node_modules/构建产物/包管理器缓存;
    * `ignore` 在默认清单上追加排除;`include` 优先级最高,把匹配路径显式加回。
    * 合成规则固定为「默认 ∪ ignore,再被 include 打洞」,清单在分类账锚点时冻结。
    */
   diff?: { include?: string[]; ignore?: string[] };
   /**
-   * eval 级预置:拿到沙箱(已上传 workspace + git 基线 + 装好依赖前)。
+   * 评估用例级预置:拿到 Sandbox(已上传 workspace + git 基线 + 装好依赖前)。
    * 默认命令以非 root 跑(agent 的自然环境);装系统依赖时给 `runCommand` 传 `{ root: true }`
    * (如 `runCommand("apt-get", ["install", …], { root: true })`),跨 provider 语义一致。
    * 第二个参数是绑定到 `eval.setup` 的窄上下文(`ctx.progress` / `ctx.diagnostic`,
-   * 见 docs/feature/eval/README.md);可返回 cleanup 闭包,归因到 `eval.teardown`。
+   * 见 docs/feature/eval/README.md)。setup 不返回值;要把产物传给 teardown,
+   * 以 `sandbox` 实例作键存取(并发 attempt 共享同一模块,普通模块变量会互相覆写)。
    */
-  setup?: (sandbox: Sandbox, ctx: SandboxHookContext) => Promise<void | Cleanup> | void | Cleanup;
-  /** eval 主体:拿到 TestContext,驱动对话 / 沙箱操作并就地断言。 */
+  setup?: (sandbox: Sandbox, ctx: SandboxHookContext) => Promise<void> | void;
+  /**
+   * 评估用例级收尾:attempt 收尾链的第一段(`eval.teardown` → `agent.teardown` →
+   * `sandbox.teardown`),Sandbox 此刻还活着。当且仅当 `eval.setup` 时点走到过才执行——
+   * `setup` / `test` 抛错都不豁免,未声明 `setup` 不影响触发;抛错或超 30s 清理上限
+   * 只记 `teardown-failed` 诊断,不改判定。管 Sandbox 外的临时 Fixture(临时 repo / bucket),
+   * Sandbox 内的东西随销毁自动回收、不需要它。
+   */
+  teardown?: (sandbox: Sandbox, ctx: SandboxHookContext) => Promise<void> | void;
+  /** 评估用例主体:拿到 TestContext,驱动对话 / Sandbox 操作并就地断言。 */
   test(t: TestContext): Promise<void> | void;
 }
 
@@ -363,6 +378,21 @@ export interface DiscoveredEval extends EvalDef {
   source: CapturedEvalSource;
 }
 
+/**
+ * `ExperimentDef.setup` / `teardown` 拿到的窄上下文。`progress` 更新本实验运行级
+ * active 行的次要文本(短命状态,agent/ci profile 不逐条输出),`diagnostic` 进运行级永久
+ * 事件流(实验级钩子不属于任何单个 attempt,诊断不落 attempt 的 `result.json`;setup 抛错
+ * 以每条 attempt 的结构化 `error` 落盘,失败仍可回顾)。钩子的起止本身由 runner 直接发布为
+ * 运行级反馈,不依赖这里的 `progress`(见 docs/feature/experiments/cli.md「实验级钩子的显示」)。
+ */
+export interface ExperimentHookContext extends ScopedFeedback {
+  readonly experimentId: string;
+  /** 本实验解析后实际选中的 eval id 全集(evals 过滤器的求值结果)。 */
+  readonly selectedEvalIds: readonly string[];
+  /** 用户中断(Ctrl+C / kill)时 abort;长启动的 setup 应观察它提前退出。 */
+  readonly signal?: AbortSignal;
+}
+
 export interface ExperimentDef {
   /** 路径推导,定义里禁止手写(defineExperiment 会拒绝显式传入)。 */
   id?: string;
@@ -381,12 +411,27 @@ export interface ExperimentDef {
    *  (defineExperiment 解析时校验,非 JSON 直接报错),经 ctx.flags 透传给 adapter、
    *  t.flags 暴露给 eval,并原样进入结果快照的 ExperimentRunInfo.flags。 */
   flags?: Record<string, JsonValue>;
+  /**
+   * 报告归类标注:实验在各对比轴上的坐标(如 `{ line: "codex", memory: "mempal" }`)。
+   * 值域 string | number(解析时校验)。与 `flags` 的分界是「会不会改变 attempt 里发生的事」:
+   * labels 不透传 ctx / t(agent 和 eval 看不见)、不参与可比性配置(改它不作废已有结果),
+   * 只原样投影进快照的 `ExperimentRunInfo.labels` 供报告维度(`label()` / `numericLabel()`)
+   * 分组。`line` 键被默认报告识别:组内任一实验声明了它,散点按线归类并连线。
+   * 见 docs/feature/experiments/library.md「labels」。
+   */
+  labels?: Record<string, string | number>;
   /** 同一 eval 重复跑几次(结果各计一条 attempt);省略/CLI `--runs` 覆盖时默认 1。 */
   runs?: number;
   /** 一次重复(runs > 1)里某次 attempt 失败后是否跳过剩余重复;省略默认 true(提前退出省钱)。 */
   earlyExit?: boolean;
-  /** 这个实验覆盖哪些 eval:"*" 全部、字符串数组按 id 前缀、或自定义谓词;省略等价于 "*"。 */
-  evals?: "*" | string[] | ((id: string) => boolean);
+  /**
+   * 这个实验覆盖哪些 eval:`"*"` 全部、字符串数组按 id 前缀、或自定义谓词(逐条收到发现并扇出后的
+   * 只读 `EvalDescriptor`,不暴露路径 / 执行字段);省略等价于 `"*"`。谓词对本次 invocation 的
+   * 候选 eval 各求值一次,解析结果作为 `selectedEvalIds` 落进快照——不是运行时反复调用的过滤器
+   * (见 docs/feature/eval/library.md「EvalDescriptor」、docs/feature/experiments/library.md
+   * 「evals:遍历发现结果,自定义选择」)。
+   */
+  evals?: "*" | readonly string[] | ((e: EvalDescriptor) => boolean);
   /** 覆盖项目级 / CLI 的单次 attempt 超时(毫秒),只对这个实验生效。 */
   timeoutMs?: number;
   /**
@@ -406,11 +451,42 @@ export interface ExperimentDef {
    * 或给撞 provider 限额的实验单独降速。
    */
   maxConcurrency?: number;
+  /**
+   * 实验级生命周期钩子对的 setup 侧:整场至多一次、宿主机侧,管「每实验一份、所有 attempt
+   * 共享」的宿主机资源(隧道、mock server、license 租约)。本实验第一个通过派发许可的
+   * attempt 触发(memoized,并发 attempt 等同一个结果;全部结果被 carry 携入时不执行)。
+   * setup 不返回值;产物写模块级变量,`teardown` 与同文件 agent / sandbox 钩子从闭包读,
+   * runner 不做值的中介。setup 抛错 → 本实验所有 attempt 记 `errored`
+   * (code `"experiment-setup-failed"`、phase `"experiment.setup"`),同批其它实验不受影响。
+   * 函数体不进 fingerprint,改了钩子逻辑用 `--force` 强制重跑。
+   * 见 docs/feature/experiments/architecture.md「实验级生命周期」。
+   */
+  setup?: (ctx: ExperimentHookContext) => void | Promise<void>;
+  /**
+   * 实验级生命周期钩子对的 teardown 侧:本实验全部 attempt 收尾后执行(运行被中断也执行),
+   * 当且仅当 setup 时点走到过——setup 抛错不豁免(半初始化现场同样要扫尾,teardown 对可能
+   * 未赋值的闭包变量做防御),未声明 setup 不影响触发;一个 attempt 都不派发则跳过。
+   * 抛错或超 30s 清理上限只记运行级 diagnostic(`experiment-teardown-failed`),不改判定。
+   */
+  teardown?: (ctx: ExperimentHookContext) => void | Promise<void>;
 }
 
 export interface DiscoveredExperiment extends ExperimentDef {
   id: string;
-  group: string;
+}
+
+/**
+ * 用户谓词(`ExperimentDef.evals`)能看到的唯一形状——发现并扇出后的显式白名单投影,不透传
+ * `DiscoveredEval` 原对象(不暴露 `sourcePath` / `baseDir` / `test` / hooks 等内部路径与执行字段)。
+ * `tags` 缺省为冻结空数组;`metadata` 原样引用作者声明的对象(至少浅冻结),供 `tags.includes(...)` /
+ * `environment` / `metadata.<key>` 判断(见 docs/feature/eval/library.md「EvalDescriptor」)。
+ */
+export interface EvalDescriptor {
+  readonly id: string;
+  readonly description?: string;
+  readonly tags: readonly string[];
+  readonly environment?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
 }
 
 export interface Config {
@@ -419,11 +495,11 @@ export interface Config {
    * 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
    */
   name?: LocalizedText;
-  /** 项目级默认沙箱 provider(docker / vercel / e2b / custom);experiment 可覆盖。 */
+  /** 项目级默认 Sandbox provider(docker / vercel / e2b / custom);experiment 可覆盖。 */
   sandbox?: SandboxOption;
-  /** 上传进沙箱的工作区根目录,省略则用项目根;eval 的 sandbox 视图从这里起步。 */
+  /** 上传进 Sandbox 的工作区根目录,省略则用项目根;评估用例的 sandbox 视图从这里起步。 */
   workspace?: string;
-  /** 项目级默认 judge 配置(model / baseUrl / apiKeyEnv);EvalDef.judge 可按 eval 覆盖。 */
+  /** 项目级默认 judge 配置(model / baseUrl / apiKeyEnv);EvalDef.judge 可按评估用例覆盖。 */
   judge?: JudgeConfig;
   /** 项目级默认 reporter 列表(如落盘 / 上传结果);EvalDef.reporters 会与它合并。 */
   reporters?: Reporter[];
@@ -434,11 +510,11 @@ export interface Config {
   /**
    * OTLP 接收配置,niceeval 项目内唯一入口(不读 NICEEVAL_OTLP_* 环境变量)。
    * `port` 钉住接收端口(固定端口模式:长驻服务把 OTEL_EXPORTER_OTLP_ENDPOINT 一次性指到
-   * http://localhost:<port>/v1/traces,跑多少次 eval 都不用改)。省略 = 每次运行动态分配
+   * http://localhost:<port>/v1/traces,跑多少次评估用例都不用改)。省略 = 每次运行动态分配
    * 临时端口(经 ctx.telemetry 交给 adapter)。代价:固定端口下同机同时只能跑一个 niceeval 进程,
    * 且该端口被别的进程占用时会报错——换一个空闲端口写回这里即可。
    * `host` 是报给 adapter 的接收端 hostname(而非监听地址,监听地址恒为 0.0.0.0):默认
-   * "127.0.0.1";docker 沙箱型 tracing 需要 "host.docker.internal" 之类的场景,或配了隧道
+   * "127.0.0.1";docker Sandbox 型 tracing 需要 "host.docker.internal" 之类的场景,或配了隧道
    * 的远程接入,在这里覆盖。
    */
   telemetry?: { host?: string; port?: number };
@@ -496,18 +572,29 @@ export interface AgentRun {
   resolvedSandboxes?: Map<string, SandboxOption>;
   timeoutMs?: number;
   budget?: number;
-  evalFilter: (id: string) => boolean;
   experimentId?: string;
   /** 实验的一句话描述(ExperimentDef.description),进结果快照的 ExperimentRunInfo。 */
   description?: string;
+  /** 报告归类标注(ExperimentDef.labels),原样进 ExperimentRunInfo.labels;不透传 ctx / t。 */
+  labels?: Record<string, string | number>;
   /** evals 过滤器的指纹(数组内容 / 函数体哈希),进 ExperimentRunInfo.evalFilterFingerprint。 */
   evalFilterFingerprint?: string;
-  /** 本次运行解析后实际选中的 eval id 全集;runEvals 在调度前按 evalFilter 求值填入。 */
-  selectedEvalIds?: string[];
+  /**
+   * 本次 invocation 解析后实际选中的 eval id 全集——CLI 在构造 AgentRun 时对候选 eval 各求值
+   * 一次算好(见 `eval-selection.ts` 的 `resolveExperimentEvals()`),下游(dry-run、sandbox 查表、
+   * fingerprint/carry、attempt 展开、hook ctx、落盘)只消费这份已解析结果,不重新调用用户谓词。
+   * 保持顺序 = discovery 稳定顺序,去重。
+   */
+  selectedEvalIds: readonly string[];
   strict?: boolean;
   /** 本配置自己的并发上限(来自 ExperimentDef.maxConcurrency):调度器为它单建信号量,
    *  attempt 先过这道闸再占全局并发位;省略则只受全局并发约束。 */
   maxConcurrency?: number;
+  /** 实验级生命周期钩子对(来自 ExperimentDef.setup / .teardown):setup 整场至多一次,
+   *  调度器 memoize 执行;teardown 在全部 attempt 收尾后执行,当且仅当 setup 时点走到过
+   *  (语义见 ExperimentDef 对应字段)。 */
+  setup?: (ctx: ExperimentHookContext) => void | Promise<void>;
+  teardown?: (ctx: ExperimentHookContext) => void | Promise<void>;
 }
 
 export interface RunOptions {
@@ -621,6 +708,25 @@ export interface ActiveAttempt {
   detail?: string;
 }
 
+/** 实验级钩子只有 setup 与它返回的 teardown 两员,同一实验内两者永不并发
+ *  (teardown 在全部 attempt 收尾后才触发),所以运行级行按 experimentId 建 key 就够。 */
+export type ExperimentHookName = "setup" | "teardown";
+
+/**
+ * dashboard 当前可见的一个实验级钩子运行级行(见 docs/feature/experiments/cli.md
+ * 「实验级钩子的显示」)。与 `ActiveAttempt` 分开建模:钩子不属于任何单个 attempt、不占并发位,
+ * 也不参与 `total = reused + running + queued + completed` 的计数不变量——等待 setup 的
+ * attempt 保持 `queued`,这行就是「为什么它们还在排队」的解释。`detail` 来自实验级
+ * `ctx.progress`,后一条覆盖前一条。
+ */
+export interface ActiveExperimentHook {
+  experimentId: string;
+  hook: ExperimentHookName;
+  /** 钩子开始的墙钟时间(epoch ms),用于渲染运行级行的耗时。 */
+  startedAt: number;
+  detail?: string;
+}
+
 /**
  * 一次失败/错误的永久通知:human 撤下 dashboard 后追加一行、agent/ci 立即追加一行,都读它。
  * 字段全部结构化(locator / identity / verdict / phase 都是具名字段),profile renderer 不需要
@@ -703,6 +809,9 @@ export interface RunFeedbackState {
   newTokenCount?: number;
   estimatedCostUSD?: number;
   active: ReadonlyMap<AttemptKey, ActiveAttempt>;
+  /** 在飞的实验级钩子(experimentId → 运行级行状态),由 "experiment-hook" 事件增删、
+   *  "experiment:progress" 更新 detail(见 docs/feature/experiments/cli.md「实验级钩子的显示」)。 */
+  experimentHooks: ReadonlyMap<string, ActiveExperimentHook>;
   failures: readonly FailureNotice[];
   /** 本次实际派发后产生的去重失败数；复用失败不消耗 profile 的流式输出上限。 */
   freshFailureCount: number;
@@ -755,6 +864,17 @@ export type AttemptLifecycleEvent =
     }
   | { type: "attempt:early-exit"; at: number; identity: AttemptRef; who: string };
 
+/**
+ * 实验级 `ctx.progress` 的短命投影:只覆盖对应运行级行的 `detail`,不追加永久行——与
+ * `attempt:progress` 同一判断标准(新值使旧值失去意义)。对应的运行级行不存在时静默忽略。
+ */
+export interface ExperimentProgressEvent {
+  type: "experiment:progress";
+  at: number;
+  experimentId: string;
+  detail: string;
+}
+
 /**
  * 运行级时钟 tick:唯一允许更新 `RunFeedbackState.elapsedMs` 的事件,由 coordinator 的定时器产出
  *(见 plan 的可注入 `FeedbackIO` clock)。reducer 保持纯函数,不自己读 `Date.now()`,elapsedMs
@@ -812,6 +932,21 @@ export type DurableFeedbackEvent =
       sandboxId: string;
       enter?: string;
     }
+  /**
+   * 实验级钩子(`ExperimentDef.setup` / 它返回的 teardown)的起止,由 runner 在钩子真正
+   * 开始/结束时各发一次(见 docs/feature/experiments/cli.md「实验级钩子的显示」)。`failed`
+   * 只标记钩子自身的结局——setup 失败的每条 attempt 仍以 "failure" 事件逐条给出。human TTY
+   * 用它维护运行级 active 行(不写 scrollback),append-only profile 起止各追加一行。
+   */
+  | {
+      type: "experiment-hook";
+      at: number;
+      experimentId: string;
+      hook: ExperimentHookName;
+      status: "started" | "done" | "failed";
+      /** 只在 done / failed 上出现:钩子从开始到结束的耗时。 */
+      durationMs?: number;
+    }
   | { type: "interrupted"; at: number }
   | { type: "reporter-error"; at: number; reporter: string; required: boolean; message: string }
   | { type: "summary"; at: number; summary: RunSummary; completion: RunCompletion }
@@ -836,4 +971,4 @@ export type DurableFeedbackEvent =
  * profile renderer 只消费这里的具名字段,不解析 `ReporterEvent` 里的 i18n 文案或表格列宽
  *(见 docs/feature/experiments/cli.md「输出流和落盘节奏」)。
  */
-export type RunFeedbackEvent = AttemptLifecycleEvent | FeedbackTickEvent | DurableFeedbackEvent;
+export type RunFeedbackEvent = AttemptLifecycleEvent | ExperimentProgressEvent | FeedbackTickEvent | DurableFeedbackEvent;

package/src/sandbox/docker.ts

@@ -535,12 +535,19 @@ export class DockerSandbox implements Sandbox {
   /**
    * 向容器任意路径写文件(二进制)。
    * 打成单文件 tar → putArchive 到目标目录,与 uploadFiles 同一机制但目标路径自由。
+   *
+   * 修正属主:putArchive 以 root 解包,不 chown 的话文件在容器里保持 root 属主——非 root
+   * 沙箱用户不仅不能编辑它,后续对它做 `mv`/`rm` 这类改动它所在目录项的操作,只要目标目录带
+   * sticky bit(如 `/tmp`),也会因为「非属主不能改别人的目录项」被内核拒成
+   * `Operation not permitted`(与 uploadFiles() 对整个目标目录 chown 是同一个属主问题,
+   * 这里只需精确 chown 这一个文件;真机复现见 memory/docker-uploadfile-tmp-mv-eperm.md)。
    */
   async uploadFile(destPath: string, content: Buffer): Promise<void> {
     if (!this.container) throw new Error(t("docker.containerNotInitialized"));
     const absPath = resolveSandboxPath(this.workdir, destPath);
     const pack = packFilesToTar([{ name: basename(absPath), content }]);
     await (this.container as Docker.Container).putArchive(pack, { path: dirname(absPath) });
+    await this.chownToSandboxUser(absPath);
   }
 
   /** 销毁容器:显式 stop + remove(创建时不带 AutoRemove,见 createContainer 的注释)。 */

package/src/sandbox/e2b.ts

@@ -38,19 +38,18 @@ const SESSION_TIMEOUT_MS = 1_800_000;
  */
 export async function reconcileProvision(token: string): Promise<void> {
   const apiKey = process.env.E2B_API_KEY;
-  const list = (E2BSdkSandbox as unknown as {
-    list?: (opts?: Record<string, unknown>) => Promise<Array<{ sandboxId: string; metadata?: Record<string, string> }>>;
-  }).list;
-  if (typeof list !== "function") throw new Error("this e2b SDK version has no Sandbox.list; cannot reconcile provision token");
-  const sandboxes = await list({ apiKey });
-  for (const info of sandboxes) {
-    if (info.metadata?.["niceeval-provision-token"] !== token) continue;
-    const kill = (E2BSdkSandbox as unknown as { kill?: (id: string, opts?: Record<string, unknown>) => Promise<unknown> }).kill;
-    if (typeof kill !== "function") throw new Error("this e2b SDK version has no Sandbox.kill; cannot reconcile provision token");
-    try {
-      await kill(info.sandboxId, { apiKey });
-    } catch (e) {
-      if (!(e instanceof NotFoundError)) throw e;
+  // Sandbox.list() 是同步方法,返回分页器(SandboxPaginator),不是 Promise<数组>——用
+  // hasNext/nextItems() 翻页,不能直接 for...of。metadata 过滤走服务端 query,一次 token
+  // 命中的实例数极少,通常一页打完。
+  const paginator = E2BSdkSandbox.list({ apiKey, query: { metadata: { "niceeval-provision-token": token } } });
+  while (paginator.hasNext) {
+    const sandboxes = await paginator.nextItems();
+    for (const info of sandboxes) {
+      try {
+        await E2BSdkSandbox.kill(info.sandboxId, { apiKey });
+      } catch (e) {
+        if (!(e instanceof NotFoundError)) throw e;
+      }
     }
   }
 }

package/src/sandbox/types.ts

@@ -1,7 +1,7 @@
 // sandbox 域类型:Sandbox 接口、provider spec(可辨识联合)、命令与文件 IO 的形状。
 // 「在哪里跑、如何隔离」的全部契约在这里;provider 实现见本目录各文件,分发见 resolve.ts。
 
-import type { Cleanup, ScopedFeedback } from "../shared/types.ts";
+import type { ScopedFeedback } from "../shared/types.ts";
 
 export interface CommandResult {
   stdout: string;
@@ -76,15 +76,16 @@ export type SandboxRuntime = "node20" | "node24";
  * **执行顺序**:沙箱就绪 → `sandbox.setup` 钩子 → workspace 上传 / git 基线 / `eval.setup` →
  * `agent.setup` → `agent.tracing.configure` → 逐轮 `send`。`sandbox.setup` 特意排在 git
  * 基线之前——它的改动会被提交进基线,不会被误算进 agent 产出的 diff。收尾按 LIFO:
- * agent 级 cleanup / `agent.teardown` 先跑,`sandbox.teardown` 钩子最后跑(沙箱销毁前)。
+ * `agent.teardown` 先跑,`sandbox.teardown` 钩子最后跑(沙箱销毁前)。
  *
  * **多钩子**:`.setup(a).setup(b)` 按追加顺序依次执行(a 先 b 后);`.teardown(x).teardown(y)`
  * 按追加的**逆序**执行(y 先 x 后)。每次调用都返回一个新 spec(不改变原对象),可继续链式。
+ * `setup` 链中途抛错时后续 `setup` 不再执行,`teardown` 链仍完整走完。
  *
  * **失败语义**:`setup` 钩子抛错按执行错误计——与 `eval.setup` / `agent.setup` 抛错走同一条
- * 路径,不新增错误分类;但不阻断该 attempt 已进入的收尾(已跑过的 setup 返回的 cleanup、
- * `teardown` 钩子仍会在 finally 里跑)。`teardown` 钩子报错只作诊断(吞掉 / 记 log),不改变
- * 已产出的结果——与 `agent.teardown` 现状一致。
+ * 路径,不新增错误分类;但不阻断该 attempt 已进入的收尾(已挂载的 `teardown` 钩子仍会在
+ * finally 里跑)。`teardown` 钩子报错只作诊断(吞掉 / 记 log),不改变已产出的结果——与
+ * `agent.teardown` 现状一致。
  */
 export interface SandboxHooks<Self> {
   /** 已挂载的 setup 钩子,按追加顺序保存(内部读取,一般用不到)。 */
@@ -109,11 +110,12 @@ export interface SandboxHookContext extends ScopedFeedback {
   readonly signal: AbortSignal;
 }
 
-/** 沙箱级生命周期钩子(`.setup()` / `.teardown()` 链式挂载);`setup` 可返回 cleanup 闭包。 */
+/** 沙箱级生命周期钩子(`.setup()` / `.teardown()` 链式挂载);`setup` 不返回值——要把 `setup`
+ * 创建的句柄传给 `teardown`,以 `sandbox` 实例为键存取(见 {@link SandboxHooks})。 */
 export type SandboxHook = (
   sandbox: Sandbox,
   ctx: SandboxHookContext,
-) => void | Cleanup | Promise<void | Cleanup>;
+) => void | Promise<void>;
 
 /**
  * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/feature/sandbox/library.md)。
@@ -170,12 +172,12 @@ export type SandboxSpec = DockerSandboxSpec | VercelSandboxSpec | E2BSandboxSpec
 export type SandboxOption = SandboxSpec;
 
 export interface CommandOptions {
-  /** 追加/覆盖本命令的环境变量(与沙箱默认环境叠加,不清空默认值;各 provider 会保留自己固定的 `PATH` 等变量,不保证能被这里覆盖)。 */
+  /** 追加/覆盖本命令的环境变量(与 Sandbox 默认环境叠加,不清空默认值;各 provider 会保留自己固定的 `PATH` 等变量,不保证能被这里覆盖)。 */
   env?: Record<string, string>;
   /** 本命令的工作目录;省略时落到 `Sandbox.workdir`。相对路径按 workdir 解析,绝对路径原样使用。 */
   cwd?: string;
   /**
-   * 把本命令的输出也送进沙箱的「原生日志流」(于是 `docker logs` / Docker UI 的 Logs
+   * 把本命令的输出也送进 Sandbox 的「原生日志流」(于是 `docker logs` / Docker UI 的 Logs
    * 标签页能实时看到它)。给 agent 命令(codex exec / bub run / claude)开它,就能在容器
    * 日志里看到 agent 的【原始输出】。provider 各自实现(docker:tee 到 PID1 tail 的文件;
    * 不支持的 provider 忽略)—— 日志怎么浮现是 provider 的事,adapter 只声明意图。
@@ -190,7 +192,7 @@ export interface CommandOptions {
   /** `onStdout` 的 stderr 对应物；完整 stderr 仍保留在 `CommandResult`。 */
   onStderr?: (chunk: string) => void | Promise<void>;
   /**
-   * 以 root 跑本命令。默认 `false` —— 命令以沙箱的标准**非 root** 用户跑(agent 的自然环境)。
+   * 以 root 跑本命令。默认 `false` —— 命令以 Sandbox 的标准**非 root** 用户跑(agent 的自然环境)。
    * 给 setup 阶段装系统依赖用(`apt-get install …`、`pip install --break-system-packages …`)。
    *
    * 语义跨 provider 一致:"本命令以 root 跑,否则以标准非 root 用户跑"。各 provider 映射到自己的原生机制
@@ -202,7 +204,7 @@ export interface CommandOptions {
 }
 
 export interface Sandbox {
-  /** 沙箱内项目/工作区根目录的绝对路径(agent 命令的默认 cwd,也是 git baseline 提交的位置)。各方法的相对路径都以此为基准解析,省略 `cwd`/`targetDir` 时也落到这里。 */
+  /** Sandbox 内项目/工作区根目录的绝对路径(agent 命令的默认 cwd,也是 git baseline 提交的位置)。各方法的相对路径都以此为基准解析,省略 `cwd`/`targetDir` 时也落到这里。 */
   readonly workdir: string;
   /**
    * 执行单个命令,`args` 作为独立 argv 传递、不经 shell 解释(无 `&&`、管道、通配符展开)。
@@ -214,29 +216,29 @@ export interface Sandbox {
    * 需要拼多条命令或做条件判断时用它。
    */
   runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
-  /** 读取沙箱内文件的文本内容(UTF-8)。文件不存在时抛错,不返回空字符串——需要容错请自行 `.catch()`。 */
+  /** 读取 Sandbox 内文件的文本内容(UTF-8)。文件不存在时抛错,不返回空字符串——需要容错请自行 `.catch()`。 */
   readFile(path: string): Promise<string>;
-  /** 检查沙箱内路径是否存在。跨 provider 语义不完全一致:仅保证对普通文件可靠,对目录路径的行为不同 provider 不保证一致。 */
+  /** 检查 Sandbox 内路径是否存在。跨 provider 语义不完全一致:仅保证对普通文件可靠,对目录路径的行为不同 provider 不保证一致。 */
   fileExists(path: string): Promise<boolean>;
   /**
    * 一次 shell 往返读全部源码文件(按扩展名收、按目录/文件名忽略)。
-   * 取代每个 eval 目录里手写的 find + 逐文件 readFile。
+   * 取代每个评估用例目录里手写的 find + 逐文件 readFile。
    */
   readSourceFiles(opts?: ReadSourceFilesOptions): Promise<SourceFiles>;
   /** 写入若干文本文件(内容已在内存里的字符串);是 `uploadFiles` 的文本特化,省略 `targetDir` 落到 workdir。 */
   writeFiles(files: Record<string, string>, targetDir?: string): Promise<void>;
   /** 批量写入若干文件,内容可以是文本或二进制 Buffer;省略 `targetDir` 落到 workdir。 */
   uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void>;
-  /** 把本地磁盘上的一个目录整体上传进沙箱(递归读取本地文件后按 `uploadFiles` 写入);`opts.ignore` 是排除规则,省略 `targetDir` 落到 workdir。 */
+  /** 把本地磁盘上的一个目录整体上传进 Sandbox(递归读取本地文件后按 `uploadFiles` 写入);`opts.ignore` 是排除规则,省略 `targetDir` 落到 workdir。 */
   uploadDirectory(localDir: string, targetDir?: string, opts?: { ignore?: string[] }): Promise<void>;
-  /** 销毁沙箱占用的计算资源(容器/microVM)。调用后沙箱不可再用;是否可安全重复调用因 provider 而异,不要依赖这一点。 */
+  /** 销毁 Sandbox 占用的计算资源(容器/microVM)。调用后 Sandbox 不可再用;是否可安全重复调用因 provider 而异,不要依赖这一点。 */
   stop(): Promise<void>;
-  /** 本沙箱的稳定标识(各 provider 原生 ID,如 Docker 容器 ID 前缀);用于跨调用关联同一沙箱的会话状态,也用于日志展示。 */
+  /** 本 Sandbox 的稳定标识(各 provider 原生 ID,如 Docker 容器 ID 前缀);用于跨调用关联同一 Sandbox 的会话状态,也用于日志展示。 */
   readonly sandboxId: string;
   /**
    * 本地 OTLP 接收器的目标 host。
-   * - `string`:沙箱内可通过该 hostname 回连宿主 OTLP 端口(如 docker 的 `host.docker.internal`)。
-   * - `null`:沙箱运行在远程云端(如 e2b/vercel),无法访问宿主本地端口 → 跳过 tracing。
+   * - `string`:Sandbox 内可通过该 hostname 回连宿主 OTLP 端口(如 docker 的 `host.docker.internal`)。
+   * - `null`:Sandbox 运行在远程云端(如 e2b/vercel),无法访问宿主本地端口 → 跳过 tracing。
    *   可通过环境变量 `NICEEVAL_OTLP_HOST` 强制覆盖(如配置 tunnel 时)。
    */
   readonly otlpHost: string | null;
@@ -248,13 +250,13 @@ export interface Sandbox {
   appendLog?(line: string): Promise<void>;
 
   /**
-   * 从沙箱内任意路径读取文件,返回二进制 Buffer。
+   * 从 Sandbox 内任意路径读取文件,返回二进制 Buffer。
    * 对应各 provider:Docker getArchive / Vercel readFileToBuffer / e2b files.read(bytes) / …
    */
   downloadFile(path: string): Promise<Buffer>;
 
   /**
-   * 向沙箱内任意路径写入文件(二进制)。
+   * 向 Sandbox 内任意路径写入文件(二进制)。
    * 对应各 provider:Docker putArchive / Vercel fs.writeFile(Buffer) / e2b files.write / …
    */
   uploadFile(path: string, content: Buffer): Promise<void>;

package/src/scoring/display.test.ts

@@ -35,7 +35,8 @@ describe("primaryAssertionSummary", () => {
     });
     expect(assertionSummaryLines(summary!)).toEqual([
       "gate: Issue 15193: selected proposal matches the accepted proposal",
-      "equals(4) · expected 4 · received 3 · +1 more failures",
+      "equals(4) · expected 4 · received 3",
+      "+1 more failures",
     ]);
     expect(compactAssertionSummary(summary!)).toBe(
       "gate: Issue 15193: selected proposal matches the accepted proposal · equals(4) · expected 4 · received 3 · +1 more failures",
@@ -78,8 +79,33 @@ describe("primaryAssertionSummary", () => {
     expect(summary.received!.length).toBeLessThanOrEqual(240);
     expect(summary.received).toMatch(/…$/);
     const lines = assertionSummaryLines(summary);
-    expect(lines).toHaveLength(2);
     expect(lines.every((line) => !line.includes("\n"))).toBe(true);
+    // matcher · expected 放不下大值 received 时各自另起一行
+    expect(lines).toEqual([
+      "gate: includes(/updateTag/)",
+      expect.stringContaining("expected matches /updateTag/"),
+      expect.stringMatching(/^received: .*…$/),
+    ]);
+  });
+
+  it("received 大值单独截断一行时，+N more failures 仍是独立尾行、不与被截断的值粘连", () => {
+    const assertions: AssertionResult[] = [
+      {
+        name: "includes(/updateTag/)",
+        severity: "gate",
+        outcome: "failed",
+        score: 0,
+        expected: "matches /updateTag/",
+        received: `// app/actions/posts.ts\n'use server';\n${"const source = 1;\n".repeat(80)}`,
+      },
+      { name: "matches(schema)", severity: "gate", outcome: "failed", score: 0 },
+    ];
+
+    const summary = primaryAssertionSummary(assertions, "failed")!;
+    const lines = assertionSummaryLines(summary);
+    expect(lines.at(-1)).toBe("+1 more failures");
+    const receivedLine = lines.find((line) => line.startsWith("received:"))!;
+    expect(receivedLine).not.toContain("more failures");
   });
 });
 

package/src/scoring/display.ts

@@ -9,6 +9,13 @@ import type { AssertionResult, PrimaryAssertionSummary, Verdict } from "./types.
  */
 const SUMMARY_TEXT_MAX_CHARS = 240;
 
+/**
+ * Human/Agent 永久行的单行事实预算，与 SUMMARY_TEXT_MAX_CHARS（单值上限）分开计:一条
+ * `matcher · expected · received` 拼起来很容易超过一屏宽,这里给的是「一行」的上限，不依赖
+ * 终端 columns——agent profile 的 handoff 不是 TTY，不能按运行时宽度变化。
+ */
+const DETAIL_LINE_MAX_CHARS = 100;
+
 /** 摘要面的单值收口:折单行 + 240 字符上限。任何把断言事实放进「行」里的面共用这一条。 */
 export function summaryText(value: string): string {
   const singleLine = value.replace(/\s+/g, " ").trim();
@@ -80,11 +87,37 @@ export function assertionSummaryDetail(summary: PrimaryAssertionSummary): string
   return parts.length > 0 ? parts.join(" · ") : undefined;
 }
 
-/** Human/Agent 的至多两层文本。 */
-export function assertionSummaryLines(summary: PrimaryAssertionSummary): [string] | [string, string] {
-  const head = `${summary.severity}: ${summary.assertion}`;
-  const detail = assertionSummaryDetail(summary);
-  return detail === undefined ? [head] : [head, detail];
+/**
+ * Human/Agent 永久行的排版：标题独占一行；`matcher · expected`（含 score/threshold/reason）
+ * 独占下一行；`received` 能跟这行拼在一起仍在 DETAIL_LINE_MAX_CHARS 内就合并，放不下就单独
+ * 再起一行并硬截断。`+N more failures` 永远是独立尾行，不参与截断，也不拼进被截断的值——
+ * 截断处的 `…` 后面只会是值本身，不会被人误读成计数的一部分。
+ */
+export function assertionSummaryLines(summary: PrimaryAssertionSummary): string[] {
+  const lines: string[] = [`${summary.severity}: ${summary.assertion}`];
+
+  const factParts: string[] = [];
+  if (summary.matcher !== undefined) factParts.push(summary.matcher);
+  if (summary.expected !== undefined) factParts.push(`expected ${summary.expected}`);
+  if (summary.score !== undefined) factParts.push(`score ${summary.score}`);
+  if (summary.threshold !== undefined) factParts.push(`threshold ${summary.threshold}`);
+  if (summary.reason !== undefined) factParts.push(`reason ${summary.reason}`);
+  const facts = factParts.length > 0 ? factParts.join(" · ") : undefined;
+
+  if (summary.received !== undefined) {
+    const combined = facts !== undefined ? `${facts} · received ${summary.received}` : `received ${summary.received}`;
+    if (combined.length <= DETAIL_LINE_MAX_CHARS) {
+      lines.push(combined);
+    } else {
+      if (facts !== undefined) lines.push(facts);
+      lines.push(shrinkTo(`received: ${summary.received}`, DETAIL_LINE_MAX_CHARS));
+    }
+  } else if (facts !== undefined) {
+    lines.push(facts);
+  }
+
+  if (summary.additionalFailures > 0) lines.push(`+${summary.additionalFailures} more failures`);
+  return lines;
 }
 
 /** 比较列表的单元格投影；无 group 时不重复 `gate:` 前缀。 */

package/src/scoring/types.ts

@@ -22,11 +22,11 @@ export interface ValueAssertion {
   /** 期望条件的有界文本描述(如 `contains "Brooklyn"`),失败时进 AssertionResult.expected。 */
   readonly expected?: string;
   score(value: unknown): number | Promise<number>;
-  /** 转成硬门槛断言:未达阈值(省略 threshold 则按 score > 0 判定)整条 eval 判为 failed。返回新实例,不改原对象。 */
+  /** 转成硬门槛断言:未达阈值(省略 threshold 则按 score > 0 判定)整条评估用例判为 failed。返回新实例,不改原对象。 */
   gate(threshold?: number): ValueAssertion;
   /**
-   * 转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条 eval 的 verdict;
-   * `--strict` 运行下,软阈值失败也会把整条 eval 的 verdict 计为 failed。返回新实例,不改原对象。
+   * 转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条评估用例的 verdict;
+   * `--strict` 运行下,软阈值失败也会把整条评估用例的 verdict 计为 failed。返回新实例,不改原对象。
    */
   atLeast(threshold: number): ValueAssertion;
   /**