niceeval 0.9.1 → 0.10.2

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,28 @@ 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(提前退出省钱)。 */
+  /** 一次重复(runs > 1)里某次 attempt 通过后是否跳过剩余重复;省略默认 false(`runs` 跑满、测完整通过率),
+   *  显式打开用于「只想知道能不能过」的省钱场景。 */
   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 +452,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 +496,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 +511,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 +573,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 +709,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 +810,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 +865,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 +933,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 +972,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-reconcile.test.ts

@@ -0,0 +1,125 @@
+// 覆盖 reconcileProvision 对账逻辑,不打真实 e2b API——mock "e2b" 整个模块。
+// 背景:线上跑分撞见过 nextItems() 之后 `for...of` 抛 "X is not iterable" 的一次,
+// 没能稳定复现出确切成因;这里补的是"对账这条路径本身撞上瞬时错误该怎么办"这层契约,
+// 不是去复现那次具体的 SDK 行为。
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+class FakeNotFoundError extends Error {}
+class FakeRateLimitError extends Error {}
+class FakeCommandExitError extends Error {}
+
+const listMock = vi.fn();
+const killMock = vi.fn();
+
+vi.mock("e2b", () => ({
+  Sandbox: { list: (...args: unknown[]) => listMock(...args), kill: (...args: unknown[]) => killMock(...args) },
+  NotFoundError: FakeNotFoundError,
+  RateLimitError: FakeRateLimitError,
+  CommandExitError: FakeCommandExitError,
+}));
+
+function fakePaginator(pages: Array<() => Promise<unknown[]>>) {
+  let i = 0;
+  return {
+    get hasNext() {
+      return i < pages.length;
+    },
+    nextItems: async () => {
+      const page = pages[i];
+      i += 1;
+      return page();
+    },
+  };
+}
+
+describe("reconcileProvision", () => {
+  beforeEach(() => {
+    listMock.mockReset();
+    killMock.mockReset();
+  });
+
+  it("kills every sandbox found under the provision token, across pages", async () => {
+    const { reconcileProvision } = await import("./e2b.ts");
+    listMock.mockReturnValue(
+      fakePaginator([
+        async () => [{ sandboxId: "a" }],
+        async () => [{ sandboxId: "b" }],
+      ]),
+    );
+    killMock.mockResolvedValue(undefined);
+
+    await reconcileProvision("tok");
+
+    expect(killMock).toHaveBeenCalledTimes(2);
+    expect(killMock.mock.calls.map((c) => c[0])).toEqual(["a", "b"]);
+  });
+
+  it("treats a NotFound on kill as already-reconciled, not an error", async () => {
+    const { reconcileProvision } = await import("./e2b.ts");
+    listMock.mockReturnValue(fakePaginator([async () => [{ sandboxId: "gone" }]]));
+    killMock.mockRejectedValue(new FakeNotFoundError("gone"));
+
+    await expect(reconcileProvision("tok")).resolves.toBeUndefined();
+  });
+
+  it("retries nextItems() on a transient (ambiguous) error and still succeeds", async () => {
+    vi.useFakeTimers();
+    try {
+      const { reconcileProvision } = await import("./e2b.ts");
+      let calls = 0;
+      let done = false;
+      listMock.mockReturnValue({
+        get hasNext() {
+          return !done;
+        },
+        nextItems: vi.fn(async () => {
+          calls += 1;
+          if (calls === 1) throw new Error("fetch failed");
+          done = true;
+          return [];
+        }),
+      });
+
+      const promise = reconcileProvision("tok");
+      await vi.runAllTimersAsync();
+      await promise;
+      expect(calls).toBe(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("does not swallow a nextItems() result that isn't an array", async () => {
+    const { reconcileProvision } = await import("./e2b.ts");
+    listMock.mockReturnValue({ hasNext: true, nextItems: vi.fn().mockResolvedValue(undefined) });
+
+    await expect(reconcileProvision("tok")).rejects.toThrow(/not an array|SandboxInfo/);
+  });
+
+  it("gives up after repeated transient nextItems() failures instead of retrying forever", async () => {
+    vi.useFakeTimers();
+    try {
+      const { reconcileProvision } = await import("./e2b.ts");
+      const err = new Error("fetch failed");
+      listMock.mockReturnValue({
+        hasNext: true,
+        nextItems: vi.fn().mockRejectedValue(err),
+      });
+
+      const assertion = expect(reconcileProvision("tok")).rejects.toBe(err);
+      await vi.runAllTimersAsync();
+      await assertion;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("propagates a non-retryable kill error immediately", async () => {
+    const { reconcileProvision } = await import("./e2b.ts");
+    listMock.mockReturnValue(fakePaginator([async () => [{ sandboxId: "a" }]]));
+    const err = new Error("permission denied");
+    killMock.mockRejectedValue(err);
+
+    await expect(reconcileProvision("tok")).rejects.toBe(err);
+  });
+});

package/src/sandbox/e2b.ts

@@ -14,7 +14,11 @@ import type {
   SourceFiles,
   ReadSourceFilesOptions,
 } from "../types.ts";
-import { classifyProvisionErrorFallback, type SandboxProvisionErrorKind } from "./errors.ts";
+import {
+  classifyProvisionErrorFallback,
+  isRetryableProvisionError,
+  type SandboxProvisionErrorKind,
+} from "./errors.ts";
 import { classifySandboxIoError } from "./errors.ts";
 import { readSourceFilesByList } from "./source-files.ts";
 import { collectLocalFiles } from "./local-files.ts";
@@ -30,6 +34,13 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 600_000;
 const SESSION_TIMEOUT_MS = 1_800_000;
 
 /** e2b 的限流错误是 SDK 原生的 RateLimitError(HTTP 429 映射而来);见 resolve.ts 的 withProvisionRetry。 */
+// 对账本身只有一次机会:retry.ts 的 withProvisionRetry 对账失败就直接放弃重试、抛回原始
+// create() 错误(见那边的注释)。对账走的这次 list 请求跟刚失败的 create() 往往挨得很近,
+// 大概率处在同一段网络抖动里——不给它自己的重试,一次瞬时失败就会把本可能自愈的 attempt
+// 判死。这里给 nextItems() 单独包一层短重试,只吃与 create() 侧同一套分类下的瞬时错误。
+const RECONCILE_LIST_MAX_ATTEMPTS = 3;
+const RECONCILE_LIST_RETRY_DELAY_MS = 500;
+
 /**
  * Provisioning 重试前的对账:按 metadata 里的 provision token 检索远端实例,查到即 kill。
  * 检索或销毁失败必须抛出——对账是重试的硬前置,静默放行等于盲重试,会复制计费实例
@@ -38,19 +49,43 @@ 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");
+  // 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 fetchNextItemsWithRetry(paginator);
+    for (const info of sandboxes) {
+      try {
+        await E2BSdkSandbox.kill(info.sandboxId, { apiKey });
+      } catch (e) {
+        if (!(e instanceof NotFoundError)) throw e;
+      }
+    }
+  }
+}
+
+/**
+ * `nextItems()` 按类型契约总是 resolve 成数组(SDK 内部对空响应也兜了 `?? []`),但对账这条
+ * 路径线上真实撞见过它 resolve 成非数组的一次——没能复现出确切成因,不排它,原样让下面的
+ * `for...of` 抛出,但换一句能定位的诊断,而不是留一条裸的 "X is not iterable"。
+ */
+async function fetchNextItemsWithRetry(
+  paginator: ReturnType<typeof E2BSdkSandbox.list>,
+): Promise<Awaited<ReturnType<typeof paginator.nextItems>>> {
+  for (let attempt = 0; ; attempt += 1) {
     try {
-      await kill(info.sandboxId, { apiKey });
+      const items = await paginator.nextItems();
+      if (!Array.isArray(items)) {
+        throw new Error(
+          `e2b Sandbox.list() 分页器 nextItems() 返回了非数组(${typeof items}),不是 SDK 类型契约里的 SandboxInfo[]`,
+        );
+      }
+      return items;
     } catch (e) {
-      if (!(e instanceof NotFoundError)) throw e;
+      const kind = classifyProvisionErrorFallback(e);
+      if (attempt >= RECONCILE_LIST_MAX_ATTEMPTS - 1 || !isRetryableProvisionError(kind)) throw e;
+      await new Promise((resolve) => setTimeout(resolve, RECONCILE_LIST_RETRY_DELAY_MS * 2 ** attempt));
     }
   }
 }