niceeval 0.11.1 → 0.11.3

package/src/runner/attempt.ts

@@ -204,7 +204,7 @@ export function runAttemptEffect(
   // 非零 Sandbox 命令证据的累加器(与 diagnostics/facts 同一种「共享容器」模式):
   // withCommandTiming 在 CommandResult 交还调用方之前把每条非零退出命令 push 进来,
   // runAttemptBody 的 finally 与本函数的超时/中断兜底分支都读同一个数组引用
-  // (见 docs/feature/results/architecture.md「commandsjson」「证据在 CommandResult 返回
+  // (见 docs/feature/record/architecture.md「commandsjson」「证据在 CommandResult 返回
   // 调用方之前写入内存」)。
   const commands: FailedCommandEvidence[] = [];
   const recordDiagnostic = (input: DiagnosticInput) => {
@@ -1068,7 +1068,7 @@ async function runAttemptBody(
     const durationMs = Date.now() - t0;
     const o11y = buildO11ySummary(events);
     // 实测成本(网关带回)优先,缺则按 model + 用量查价格表估算(见 o11y/cost.ts)。
-    // 权威唯一在 result.json 的 estimatedCostUSD;o11y.json 只留行为计数(见 docs/feature/results/architecture.md「o11y.json」)。
+    // 权威唯一在 result.json 的 estimatedCostUSD;o11y.json 只留行为计数(见 docs/feature/record/architecture.md「o11y.json」)。
     const cost = usage.costUSD ?? estimateCost(run.model, usage, config.pricing);
 
     // 收 test 引用到的 eval 源码(按 send / 断言的 loc 去重),供 view 渲染代码视图。
@@ -1090,7 +1090,7 @@ async function runAttemptBody(
       scoring: evalDef.scoring ?? "pass",
       // 只在计分制 eval 上落 scoreEntries(t.score 直接给分记录);通过制 eval 的 t 上没有
       // t.score,collector.scoreEntries 恒为空数组,省略即等价于空数组
-      // (见 docs/feature/results/architecture.md「result.json」)。
+      // (见 docs/feature/record/architecture.md「result.json」)。
       ...(evalDef.scoring === "points" ? { scoreEntries: state.collector.scoreEntries } : {}),
       usage,
       estimatedCostUSD: cost,
@@ -1129,7 +1129,7 @@ async function runAttemptBody(
     return value;
   } finally {
     // 收尾段一律在 finally 跑(主链成败都执行),不改判定,各自兜错(diagnostic)、各自计时
-    // (不计入 durationMs 口径,见 docs/feature/results/architecture.md)。执行序与 LifecyclePhase
+    // (不计入 durationMs 口径,见 docs/feature/record/architecture.md)。执行序与 LifecyclePhase
     // 闭集声明一致:eval.teardown → agent.teardown → sandbox.teardown;各段可独立标 failed。
     // 沙箱 stop / 接收器 close 不在这里 —— 由 runAttemptEffect 的 Scope 在本函数返回后回收,
     // 并经 finalizer 计成 sandbox.stop。触发规则统一是「同层 setup 时点走到过」(setup / test
@@ -1216,7 +1216,7 @@ function teardownDiagnostic(phase: LifecyclePhase, e: unknown): DiagnosticRecord
  * (有界脱敏摘要 + exitCode;env 值与 stdout/stderr 不进入时间树)。Proxy 只拦这两个方法,
  * provider 内部 `this.runCommand(...)` 转调不经过它——不形成重复节点。非零退出的命令额外
  * 把完整 `CommandResult` 登记进 `commands` 累加器,登记发生在把结果交还调用方**之前**
- * (docs/feature/results/architecture.md「commandsjson」);登记不改变 `runCommand` 的
+ * (docs/feature/record/architecture.md「commandsjson」);登记不改变 `runCommand` 的
  * 返回/抛错语义,调用方可以处理非零退出并继续,证据仍保留。只记录成功拿到 `CommandResult`
  * 且 `exitCode !== 0` 的情形——`fn()` 本身抛错(如传输失败)不产出 `CommandResult`,不在这
  * 条证据线里,那类失败只落进时间树的 `failed` 标记。
@@ -1309,7 +1309,7 @@ async function collectSources(
   return out;
 }
 
-/** 解析后运行配置的穷尽投影(ExperimentRunInfo,见 docs/feature/results/architecture.md):
+/** 解析后运行配置的穷尽投影(ExperimentRunInfo,见 docs/feature/record/architecture.md):
  *  agent/model 只在快照顶层,这里不复制;sandbox 只经 provider 的公开参数投影落盘。 */
 export function experimentRunInfo(run: AgentRun, configSandbox?: Config["sandbox"]): EvalResult["experiment"] {
   return {

package/src/runner/eval-source.test.ts

@@ -1,5 +1,5 @@
 // cases: docs/engineering/testing/unit/experiments-runner.md
-// captureEvalSource 的单测(定稿见 docs/feature/results/architecture.md「sources.json」)。
+// captureEvalSource 的单测(定稿见 docs/feature/record/architecture.md「sources.json」)。
 // 覆盖:哈希确定性、path 相对 root 计算、CRLF/BOM 归一化行为、与 results/source-hash.ts
 // 算法保持一致(两处哈希必须逐字节相同,见 eval-source.ts 顶部注释)。
 

package/src/runner/eval-source.ts

@@ -1,5 +1,5 @@
 // Eval 源码捕获:discovery 时读一次 eval 定义文件、归一化、算 SHA-256(定稿见
-// docs/concepts.md「标注 Eval 源码」、docs/feature/results/architecture.md「sources.json」)。
+// docs/concepts.md「标注 Eval 源码」、docs/feature/record/architecture.md「sources.json」)。
 //
 // 目标形态是"发现时捕获,同一快照内相同内容只存一份"——本函数只做捕获这一步(读 + 归一化 +
 // 哈希),不碰去重存储、不写 result.json、不改 discoverEvals()。它的产物形状是为了让后续

package/src/runner/reporters/artifacts.ts

@@ -2,7 +2,7 @@
 //
 // 本文件是 niceeval/results 写入面(createResultsWriter)的薄壳:订阅 reporter 事件按
 // experimentId 路由转手调 writer,自己不持有任何布局知识(实验目录、快照目录、attempt
-// 路径清洗、大字段拆分、瘦身、版本元数据全在库内)。落盘格式见 docs/feature/results/architecture.md:
+// 路径清洗、大字段拆分、瘦身、版本元数据全在库内)。落盘格式见 docs/feature/record/architecture.md:
 // 每个 experiment 一个实验目录,目录下按时间戳开快照,快照内每 eval-attempt 一个文件夹,
 // 重数据分文件,snapshot.json 只留快照元数据,view 展开某条 trace 时再按需 fetch 它的 trace.json。
 

package/src/runner/run.ts

@@ -159,7 +159,7 @@ export async function runEvals(opts: RunOptions): Promise<InvocationSummary> {
   for (const run of opts.agentRuns) {
     // selectedEvalIds 已由 CLI 在构造 AgentRun 时对候选 eval 各求值一次算好(见
     // eval-selection.ts 的 resolveExperimentEvals());这里只按 resolved id 取 eval,
-    // 不重新调用用户谓词(见 docs/feature/results/architecture.md「selectedEvalIds」)。
+    // 不重新调用用户谓词(见 docs/feature/record/architecture.md「selectedEvalIds」)。
     const evals = selectedEvalsForRun(opts.evals, run);
     for (let i = 0; i < run.runs; i++) {
       for (const evalDef of evals) {
@@ -470,7 +470,7 @@ export async function runEvals(opts: RunOptions): Promise<InvocationSummary> {
   const experimentCompletedAt = new Map<string, string>();
   // experiment 作用域 ctx.fact() 的累加器(与 experimentDiagnostics 同一种「按 experimentId 分桶」
   // 模式):同一实验内后写覆盖先写,与 completedAt 同批在快照封口补写进 SnapshotMeta.facts
-  // (见 docs/feature/results/architecture.md#facts运行事实)。没有 experimentId 的裸 run 没有
+  // (见 docs/feature/record/architecture.md#facts运行事实)。没有 experimentId 的裸 run 没有
   // Snapshot 可挂,调用直接丢弃(与 recordExperimentDiagnostic 同一条纪律)。
   const experimentFacts = new Map<string, Record<string, FactValue>>();
   const recordExperimentFact = (experimentId: string | undefined, key: string, value: FactValue): void => {

package/src/runner/timing.ts

@@ -1,5 +1,5 @@
 // attempt 级阶段计时:LifecyclePhase 主链/收尾段的耗时 + 阶段内时间树(hook / turn / command)。
-// 契约见 docs/feature/results/architecture.md「result.json」的 PhaseTiming / TimingNode:
+// 契约见 docs/feature/record/architecture.md「result.json」的 PhaseTiming / TimingNode:
 // 数组顺序即执行顺序;没执行的阶段不写 0 值条目;收尾段不计入 durationMs 口径但照常计时;
 // 结果封口发生在 Effect Scope release 完成之后(sandbox.stop 也向这个 recorder 写入)。
 

package/src/runner/types.ts

@@ -23,7 +23,7 @@ import type { AttemptLocator } from "../results/locator.ts";
 /**
  * 解析后运行配置的**穷尽可序列化投影**——记录这次运行实际生效的值,不是原始 `ExperimentDef`
  * (函数与 hooks 无法忠实落盘,存「原样」只能存谎)。`model` 与 `agent` 只在快照顶层存在,
- * 这里不复制(见 docs/feature/results/architecture.md「snapshot.json」)。
+ * 这里不复制(见 docs/feature/record/architecture.md「snapshot.json」)。
  */
 export interface ExperimentRunInfo {
   description?: string;
@@ -53,7 +53,7 @@ export interface SandboxRunInfo {
 }
 
 /**
- * 一次 attempt 的生命周期词表——**全仓唯一一套**(见 docs/feature/results/architecture.md
+ * 一次 attempt 的生命周期词表——**全仓唯一一套**(见 docs/feature/record/architecture.md
  * 「result.json」)。计时(`phases[].name`)、错误归因(`error.phase`)、诊断归属
  * (`diagnostics[].phase`)、live 展示与 agent/ci envelope 的 `phase=` 都使用这同一个闭集,
  * 不存在第二套词表。phase 是 runner 对真实 lifecycle 的单方面投影,不是 adapter / sandbox
@@ -84,7 +84,7 @@ export type LifecyclePhase =
   | "sandbox.suspend" // 留存提交后 provider 把现场转入休眠(docker stop / e2b pause)
   | "sandbox.stop"; // provider 销毁沙箱;与 sandbox.suspend 同一 attempt 互斥
 
-/** TimingNode 的种类(见 docs/feature/results/architecture.md「result.json」)。 */
+/** TimingNode 的种类(见 docs/feature/record/architecture.md「result.json」)。 */
 export type TimingNodeKind = "hook" | "turn" | "command" | "provider" | "operation";
 
 /**
@@ -120,7 +120,7 @@ export interface TimingNode {
   };
 }
 
-/** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/results/architecture.md)。 */
+/** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/record/architecture.md)。 */
 export interface PhaseTiming {
   name: LifecyclePhase;
   /** 阶段耗时;失败阶段计到抛错或超时中断时。 */
@@ -132,7 +132,7 @@ export interface PhaseTiming {
 }
 
 /**
- * `commands.json` 的一条落盘记录(见 docs/feature/results/architecture.md「commandsjson」):
+ * `commands.json` 的一条落盘记录(见 docs/feature/record/architecture.md「commandsjson」):
  * 公开 `Sandbox.runCommand()` / `runShell()` 的最外层调用返回非零 `exitCode` 时,Runner 在
  * `CommandResult` 交还调用方**之前**登记的完整证据——Eval 后续即使只把 `.slice(-N)` 拼进
  * 异常消息,这份证据仍然完整。只记非零退出;成功命令的输出不进第二份 artifact,provider 内部
@@ -156,7 +156,7 @@ export interface FailedCommandEvidence {
 export type CommandsArtifact = FailedCommandEvidence[];
 
 /**
- * 使 attempt 无法正常完成的唯一致命执行错误(见 docs/feature/results/architecture.md 的
+ * 使 attempt 无法正常完成的唯一致命执行错误(见 docs/feature/record/architecture.md 的
  * `AttemptError`)。`message` 是人可读的一层原因(不拼整份 SDK response);完整 stack 单放
  * `stack`,`niceeval show @locator` 首页展开、终端即时反馈不整段打印。榜单只显示 `message`。
  */
@@ -174,7 +174,7 @@ export interface AttemptError {
 }
 
 /**
- * 不一定改变 verdict、但运行后仍需回顾的有界诊断(见 docs/feature/results/architecture.md 的
+ * 不一定改变 verdict、但运行后仍需回顾的有界诊断(见 docs/feature/record/architecture.md 的
  * `DiagnosticRecord`)。`level` 表达消息严重度,不是 verdict 的别名 —— passed / failed / errored
  * 任一 verdict 都可以带 cleanup / teardown 诊断。与运行级的 `DiagnosticNotice` 不同,这条挂在单个
  * attempt 结果上、随 `result.json` 落盘。
@@ -217,7 +217,7 @@ export interface EvalResult {
   /**
    * 题型:`defineEval` → `"pass"`,`defineScoreEval` → `"points"`,定义期事实,与
    * `EvalDescriptor.scoring` 同源。省略等价于 `"pass"`——兼容此字段引入前写入的落盘与未声明它的
-   * 第三方 harness(见 docs/feature/results/architecture.md「result.json」)。
+   * 第三方 harness(见 docs/feature/record/architecture.md「result.json」)。
    */
   scoring?: EvalScoring;
   /**
@@ -234,10 +234,10 @@ export interface EvalResult {
   /**
    * sandbox hook / agent setup·send·teardown 经 `ctx.fact()` 上报的运行事实(同 attempt 内
    * 后写覆盖先写)。中性环境观测,不参与 verdict / 评分 / 指纹。见
-   * docs/feature/results/architecture.md#facts运行事实。
+   * docs/feature/record/architecture.md#facts运行事实。
    */
   facts?: Record<string, string | number | boolean>;
-  /** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/results/architecture.md)。 */
+  /** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/record/architecture.md)。 */
   phases?: PhaseTiming[];
   skipReason?: string;
   events?: StreamEvent[];
@@ -268,7 +268,7 @@ export interface EvalResult {
   artifactBase?: string;
   /**
    * writer 实际写出的按需 artifact 词干列表(词表与全部横切属性单源在
-   * docs/feature/results/architecture.md「证据 registry」,如 ["commands", "events", "sources"])。
+   * docs/feature/record/architecture.md「证据 registry」,如 ["commands", "events", "sources"])。
    * 省略等价于空列表;携带条目原样携带。读取面的懒加载语义(缺失返回 null)独立成立,
    * 本字段只服务「不 stat 磁盘就知道有什么」的消费方。
    */
@@ -278,7 +278,7 @@ export interface EvalResult {
 /** `snapshot.json` 的格式标记;把 niceeval 报告和其它工具的同名文件区分开。 */
 export const RESULTS_FORMAT = "niceeval.results";
 /**
- * 结果格式版本,只在破坏兼容读取时递增;读取器只认相同版本。见 docs/feature/results/architecture.md。
+ * 结果格式版本,只在破坏兼容读取时递增;读取器只认相同版本。见 docs/feature/record/architecture.md。
  * `5`(见 memory 的 attempt-locator-and-source-dedup 条目)= result.json 新增 `locator` 字段;
  * `sources.json` 从逐 attempt 内联全量内容改为「attempt 级引用 + 快照级 `sources/<sha256>.json`
  * 去重仓库」,`AttemptHandle.sources()` 的公开返回形状不变(仍是 `SourceArtifact[] | null`)。
@@ -297,7 +297,7 @@ export const RESULTS_FORMAT = "niceeval.results";
  */
 export const RESULTS_SCHEMA_VERSION = 9;
 
-/** 一次 Invocation 的纯运行时内存聚合(reporter 契约用);落盘格式契约在 niceeval/results 的 SnapshotMeta / AttemptRecord,见 docs/feature/results/architecture.md。不携带顶层 `agent`/`model`——一次 Invocation 可能横跨多个 `(agent, model, flags)` 配置,塞一个顶层单值只能代表其中一份配置;需要时从 `results` 里逐条 `EvalResult.agent`/`.model` 去重派生。 */
+/** 一次 Invocation 的纯运行时内存聚合(reporter 契约用);落盘格式契约在 niceeval/results 的 SnapshotMeta / AttemptRecord,见 docs/feature/record/architecture.md。不携带顶层 `agent`/`model`——一次 Invocation 可能横跨多个 `(agent, model, flags)` 配置,塞一个顶层单值只能代表其中一份配置;需要时从 `results` 里逐条 `EvalResult.agent`/`.model` 去重派生。 */
 export interface InvocationSummary {
   /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
   name?: LocalizedText;
@@ -498,7 +498,7 @@ export interface ExperimentHookContext extends ScopedFeedback {
    * 第三条反馈通道:上报整场实验的环境观测,与 `completedAt` 同批在快照封口补写进
    * `SnapshotMeta.facts`。key 匹配 `[a-z0-9._-]{1,64}`,value 是标量;同 key 后写覆盖先写,
    * 非法 key 或非标量 value 抛错。不影响判定,不参与 verdict / 评分 / 指纹。形状与归属语义见
-   * docs/feature/results/architecture.md#facts运行事实。`niceeval exp --teardown` 的独立收尾
+   * docs/feature/record/architecture.md#facts运行事实。`niceeval exp --teardown` 的独立收尾
    * 路径不派发 attempt、不落任何 Snapshot,没有 `SnapshotMeta.facts` 可写——该路径下这个方法仍然
    * 校验入参(非法 key / 非标量 value 照样抛错),校验通过后丢弃写入(no-op:诚实优于
    * 静默——非法调用照样报错、不被这条路径悄悄吞掉,但也不假装有地方落盘),见 cli.ts 的

package/src/sandbox/docker-agent-image.ts

@@ -0,0 +1,36 @@
+import {
+  type CodingAgentBaseline,
+  agentBaselineVersionTag,
+} from "../agents/coding-cli-versions.ts";
+
+/** 每个 Agent 的 NiceEval 公共 Docker Hub repository（不含 tag）。 */
+export const NICEEVAL_DOCKER_IMAGE_NAME: Record<CodingAgentBaseline, string> = {
+  "claude-code": "niceeval/claude-code",
+  codex: "niceeval/codex",
+  bub: "niceeval/bub",
+  opencode: "niceeval/opencode",
+  hermes: "niceeval/hermes",
+  openclaw: "niceeval/openclaw",
+};
+
+/**
+ * Fully pinned reference to a NiceEval official coding-agent Docker image.
+ *
+ * tag 就是[基线版本号](../agents/coding-cli-versions.ts)`<Agent 版本>-r<配方修订>`：
+ * 镜像的配方与版本常量在同一个 commit 里，Docker 侧的发布由配方变更触发的 CI 完成，
+ * 因此引用直接由版本常量派生，不另存一份易漂移的镜像 tag。
+ */
+export function niceevalDockerImage(agent: CodingAgentBaseline): string {
+  return `${NICEEVAL_DOCKER_IMAGE_NAME[agent]}:${agentBaselineVersionTag(agent)}`;
+}
+
+/**
+ * NiceEval 官方公共 Docker 镜像：每个值是完整、版本钉死的引用，直接交给 `dockerSandbox({ image })`，
+ * 或写进项目 Dockerfile 的 `FROM` 继续叠加依赖。
+ */
+export const NICEEVAL_CLAUDE_CODE_DOCKER_IMAGE = niceevalDockerImage("claude-code");
+export const NICEEVAL_CODEX_DOCKER_IMAGE = niceevalDockerImage("codex");
+export const NICEEVAL_BUB_DOCKER_IMAGE = niceevalDockerImage("bub");
+export const NICEEVAL_OPENCODE_DOCKER_IMAGE = niceevalDockerImage("opencode");
+export const NICEEVAL_HERMES_DOCKER_IMAGE = niceevalDockerImage("hermes");
+export const NICEEVAL_OPENCLAW_DOCKER_IMAGE = niceevalDockerImage("openclaw");

package/src/sandbox/e2b-agent-template.test.ts

@@ -4,14 +4,12 @@ import { describe, expect, it } from "vitest";
 import {
   BUB_INSTALL_MARKER,
   DEFAULT_BUB_OTEL_PLUGIN,
-  DEFAULT_BUB_OVERRIDE,
+  DEFAULT_BUB_REQUIREMENT,
 } from "../agents/bub-install-spec.ts";
 import {
   E2B_NODE_TOOL_PREFIX,
   E2B_OFFICIAL_AGENT_TEMPLATES,
-  NICEEVAL_BUB_E2B_TEMPLATE,
-  NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE,
-  NICEEVAL_CODEX_E2B_TEMPLATE,
+  NICEEVAL_E2B_TEMPLATE_NAME,
   e2bCodingAgentTemplate,
   verifyE2BNodeToolContract,
 } from "./e2b-agent-template.ts";
@@ -26,22 +24,7 @@ async function runSteps(template: Parameters<typeof Template.toJSON>[0]) {
     .map((step) => ({ command: step.args[0]!, user: step.args[1] }));
 }
 
-const publicTemplates = {
-  "claude-code": NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE,
-  codex: NICEEVAL_CODEX_E2B_TEMPLATE,
-  bub: NICEEVAL_BUB_E2B_TEMPLATE,
-} as const;
-
 describe("e2bCodingAgentTemplate", () => {
-  it("exports complete public refs pinned to one verified release", () => {
-    const releases = Object.values(publicTemplates).map((template) => template.split(":").at(-1));
-
-    expect(new Set(releases).size).toBe(1);
-    for (const template of Object.values(publicTemplates)) {
-      expect(template).toMatch(/^correctroads-default-team\/.+:v\d+\.\d+\.\d+$/);
-    }
-  });
-
   it.each([
     ["claude-code", "claude"],
     ["codex", "codex"],
@@ -49,7 +32,7 @@ describe("e2bCodingAgentTemplate", () => {
     const json = JSON.parse(await Template.toJSON(e2bCodingAgentTemplate(agent)));
     expect(json.fromTemplate).toBe(base);
     expect(E2B_OFFICIAL_AGENT_TEMPLATES[agent]).toBe(base);
-    expect(publicTemplates[agent]).toContain(`/niceeval-${agent}`);
+    expect(NICEEVAL_E2B_TEMPLATE_NAME[agent]).toContain(`/niceeval-${agent}`);
     expect(JSON.stringify(json)).toContain(
       agent === "claude-code" ? "claude.ai/install.sh" : "npm install -g",
     );
@@ -97,7 +80,9 @@ describe("e2bCodingAgentTemplate", () => {
       bubPythonPackages: ["bub-plugin-memory==1.3.0"],
     }));
     // pin 的单源在 bub-install-spec.ts;这里只证明 spec → 模板 recipe 的传播,不复刻 pin 值。
-    expect(json).toContain(DEFAULT_BUB_OVERRIDE.split("@").at(-1)!);
+    // requirement 必须经 override 文件落进 recipe:少了它,构建会拉 Bub 主干而不是钉死的版本。
+    expect(json).toContain(DEFAULT_BUB_REQUIREMENT);
+    expect(json).toContain("--overrides");
     expect(json).toContain(DEFAULT_BUB_OTEL_PLUGIN.split("@").at(-1)!.split("#")[0]!);
     expect(json).toContain(BUB_INSTALL_MARKER.split("/").at(-1)!);
     expect(json).toContain("bub-plugin-memory==1.3.0");

package/src/sandbox/e2b-agent-template.ts

@@ -2,15 +2,22 @@ import { Template, type TemplateBuilder } from "e2b";
 import {
   BUB_INSTALL_MARKER,
   DEFAULT_BUB_OTEL_PLUGIN,
-  DEFAULT_BUB_OVERRIDE,
+  DEFAULT_BUB_REQUIREMENT,
   bubInstallHash,
   normalizeBubPackages,
 } from "../agents/bub-install-spec.ts";
 import {
   DEFAULT_CLAUDE_CODE_CLI_VERSION,
   DEFAULT_CODEX_CLI_VERSION,
+  agentBaselineVersionTag,
 } from "../agents/coding-cli-versions.ts";
 
+/**
+ * 已发布（或即将发布进台账）的 E2B 公共基线 Agent。
+ *
+ * 是 `CodingAgentBaseline` 的子集：OpenCode / Hermes / OpenClaw 只有 Docker 公共镜像，
+ * E2B 模板尚未进 `sandbox/e2b/published.json`，不能提前导出指向空制品的常量。
+ */
 export type E2BCodingAgent = "claude-code" | "codex" | "bub";
 
 export interface E2BCodingAgentTemplateOptions {
@@ -24,25 +31,49 @@ export const E2B_OFFICIAL_AGENT_TEMPLATES = {
   codex: "codex",
 } as const;
 
+/** NiceEval 公共 E2B baseline 所在的 Team namespace;跨 Team 引用必须带它。 */
+export const NICEEVAL_E2B_TEAM = "correctroads-default-team";
+
+/** 每个 Agent 的公共 E2B template 名字（不含 tag）。 */
+export const NICEEVAL_E2B_TEMPLATE_NAME: Record<E2BCodingAgent, string> = {
+  "claude-code": `${NICEEVAL_E2B_TEAM}/niceeval-claude-code`,
+  codex: `${NICEEVAL_E2B_TEAM}/niceeval-codex`,
+  bub: `${NICEEVAL_E2B_TEAM}/niceeval-bub`,
+};
+
 /**
- * NiceEval 当前已发布并完成启动校验的公共 E2B template release。
+ * 各 Agent 当前已发布并完成启动校验的公共 template tag。
  *
- * 这是公共模板 registry 的版本，不从源码 checkout 中可能滞后的 package.json 推导。
- * 发布一组新的 Claude Code / Codex / Bub template 并验证后，由 NiceEval 在这里统一 bump；
- * 下游不应再复制这条 release 知识。
+ * E2B 的发布是维护者手动动作（需要 `e2b auth login`），所以这里记的是**已发布事实**，
+ * 不是源码配方派生值：构建脚本按 `agentBaselineVersionTag()` 打 tag，发布并真机验证后，
+ * 同一批改动更新这张表与 `sandbox/e2b/published.json`。两者与源码版本常量的一致性由
+ * `e2b-agent-template.test.ts` 守护——版本常量走在发布前面时测试红，常量不会先指向不存在的制品。
  */
-const NICEEVAL_E2B_TEMPLATE_RELEASE = "v0.6.1";
+const PUBLISHED_E2B_BASELINE_TAG: Record<E2BCodingAgent, string> = {
+  "claude-code": "v0.6.1",
+  codex: "v0.6.1",
+  bub: "v0.6.1",
+};
 
 /**
- * NiceEval 官方公共 E2B baseline：每个值已经是完整、release-pinned、跨 Team template ref。
+ * NiceEval 官方公共 E2B baseline：每个值已经是完整、版本钉死、跨 Team 的 template ref。
  * 直接交给 `e2bSandbox({ template })`，或交给 E2B `Template().fromTemplate(...)` 继续派生。
  */
 export const NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE =
-  `correctroads-default-team/niceeval-claude-code:${NICEEVAL_E2B_TEMPLATE_RELEASE}`;
+  `${NICEEVAL_E2B_TEMPLATE_NAME["claude-code"]}:${PUBLISHED_E2B_BASELINE_TAG["claude-code"]}`;
 export const NICEEVAL_CODEX_E2B_TEMPLATE =
-  `correctroads-default-team/niceeval-codex:${NICEEVAL_E2B_TEMPLATE_RELEASE}`;
+  `${NICEEVAL_E2B_TEMPLATE_NAME.codex}:${PUBLISHED_E2B_BASELINE_TAG.codex}`;
 export const NICEEVAL_BUB_E2B_TEMPLATE =
-  `correctroads-default-team/niceeval-bub:${NICEEVAL_E2B_TEMPLATE_RELEASE}`;
+  `${NICEEVAL_E2B_TEMPLATE_NAME.bub}:${PUBLISHED_E2B_BASELINE_TAG.bub}`;
+
+/**
+ * Build tag for the next official E2B baseline of this agent: `<agent version>-r<recipe revision>`.
+ *
+ * 构建脚本用它打 tag,而不是用 niceeval 自己的 release——制品的版本位是它装的那个 Agent 的版本。
+ */
+export function e2bBaselineBuildTag(agent: E2BCodingAgent): string {
+  return agentBaselineVersionTag(agent);
+}
 
 function shellQuote(value: string): string {
   return `'${value.replaceAll("'", `'"'"'`)}'`;
@@ -136,7 +167,9 @@ export function e2bCodingAgentTemplate(
     .runCmd("curl -LsSf https://astral.sh/uv/install.sh | sh", { user: E2B_RUN_USER })
     .runCmd(
       [
-        `printf '%s\\n' ${shellQuote(DEFAULT_BUB_OVERRIDE)} > ${overrideFile}`,
+        // override 把 `bub` 钉成一个 PyPI 版本:OTel 插件所在 workspace 把 bub 声明成 git
+        // 依赖,不覆盖的话构建会拉到 Bub 主干,模板里装的版本随构建时间漂移。
+        `printf '%s\\n' ${shellQuote(DEFAULT_BUB_REQUIREMENT)} > ${overrideFile}`,
         `$HOME/.local/bin/uv tool install --python 3.12 --prerelease allow bub --overrides ${overrideFile} --with ${shellQuote(DEFAULT_BUB_OTEL_PLUGIN)}${withPackages}`,
         `mkdir -p $(dirname ${marker}) && printf '%s' ${shellQuote(installHash)} > ${marker}`,
       ],

package/src/sandbox/index.ts

@@ -4,6 +4,14 @@
 
 export { dockerSandbox, vercelSandbox, e2bSandbox, localSandbox, defineSandbox } from "../define.ts";
 export { createCheckpoint, restoreCheckpoint } from "./checkpoint.ts";
+export {
+  NICEEVAL_BUB_DOCKER_IMAGE,
+  NICEEVAL_CLAUDE_CODE_DOCKER_IMAGE,
+  NICEEVAL_CODEX_DOCKER_IMAGE,
+  NICEEVAL_HERMES_DOCKER_IMAGE,
+  NICEEVAL_OPENCLAW_DOCKER_IMAGE,
+  NICEEVAL_OPENCODE_DOCKER_IMAGE,
+} from "./docker-agent-image.ts";
 
 export type {
   Sandbox,

package/src/sandbox/official-baselines.test.ts

@@ -0,0 +1,175 @@
+// cases: docs/engineering/testing/unit/sandbox.md
+import { readFile } from "node:fs/promises";
+import { describe, expect, it } from "vitest";
+import {
+  AGENT_BASELINE_RECIPE_REVISION,
+  AGENT_BASELINE_VERSION,
+  DEFAULT_BUB_VERSION,
+  DEFAULT_CLAUDE_CODE_CLI_VERSION,
+  DEFAULT_CODEX_CLI_VERSION,
+  DEFAULT_HERMES_CLI_VERSION,
+  DEFAULT_OPENCLAW_CLI_VERSION,
+  DEFAULT_OPENCODE_CLI_VERSION,
+  type CodingAgentBaseline,
+  agentBaselineVersionTag,
+} from "../agents/coding-cli-versions.ts";
+import {
+  BUB_INSTALL_MARKER,
+  DEFAULT_BUB_OTEL_PLUGIN,
+  DEFAULT_BUB_REQUIREMENT,
+  bubInstallHash,
+  bubRequirement,
+} from "../agents/bub-install-spec.ts";
+import {
+  type E2BCodingAgent,
+  NICEEVAL_BUB_E2B_TEMPLATE,
+  NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE,
+  NICEEVAL_CODEX_E2B_TEMPLATE,
+  NICEEVAL_E2B_TEMPLATE_NAME,
+  e2bBaselineBuildTag,
+} from "./e2b-agent-template.ts";
+import {
+  NICEEVAL_BUB_DOCKER_IMAGE,
+  NICEEVAL_CLAUDE_CODE_DOCKER_IMAGE,
+  NICEEVAL_CODEX_DOCKER_IMAGE,
+  NICEEVAL_DOCKER_IMAGE_NAME,
+  NICEEVAL_HERMES_DOCKER_IMAGE,
+  NICEEVAL_OPENCLAW_DOCKER_IMAGE,
+  NICEEVAL_OPENCODE_DOCKER_IMAGE,
+} from "./docker-agent-image.ts";
+
+const DOCKER_AGENTS = [
+  "claude-code",
+  "codex",
+  "bub",
+  "opencode",
+  "hermes",
+  "openclaw",
+] as const satisfies readonly CodingAgentBaseline[];
+
+const E2B_AGENTS = ["claude-code", "codex", "bub"] as const satisfies readonly E2BCodingAgent[];
+
+const e2bTemplates: Record<E2BCodingAgent, string> = {
+  "claude-code": NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE,
+  codex: NICEEVAL_CODEX_E2B_TEMPLATE,
+  bub: NICEEVAL_BUB_E2B_TEMPLATE,
+};
+
+const dockerImages: Record<CodingAgentBaseline, string> = {
+  "claude-code": NICEEVAL_CLAUDE_CODE_DOCKER_IMAGE,
+  codex: NICEEVAL_CODEX_DOCKER_IMAGE,
+  bub: NICEEVAL_BUB_DOCKER_IMAGE,
+  opencode: NICEEVAL_OPENCODE_DOCKER_IMAGE,
+  hermes: NICEEVAL_HERMES_DOCKER_IMAGE,
+  openclaw: NICEEVAL_OPENCLAW_DOCKER_IMAGE,
+};
+
+interface PublishedTemplate {
+  name: string;
+  versionTag: string;
+  agentVersion: string;
+  installMarker?: string;
+  templateId: string;
+  buildId: string;
+  /** 源码配方已前进到这个 tag、制品尚未发布时填;值必须就是配方派生出的 tag。 */
+  supersededBy?: string;
+}
+
+const ledger = JSON.parse(
+  await readFile(new URL("../../sandbox/e2b/published.json", import.meta.url), "utf8"),
+) as { templates: Record<E2BCodingAgent, PublishedTemplate> };
+
+const dockerfile = await readFile(
+  new URL("../../sandbox/docker/Dockerfile", import.meta.url),
+  "utf8",
+);
+
+describe("official coding-agent baselines", () => {
+  it.each(DOCKER_AGENTS)("versions the %s Docker baseline by the agent it ships, not by niceeval", (agent) => {
+    // 版本位是被装的那个 Agent 的版本;-r 位是 NiceEval 配方自己的修订号。
+    expect(agentBaselineVersionTag(agent)).toBe(
+      `${AGENT_BASELINE_VERSION[agent]}-r${AGENT_BASELINE_RECIPE_REVISION[agent]}`,
+    );
+    expect(dockerImages[agent]).toBe(
+      `${NICEEVAL_DOCKER_IMAGE_NAME[agent]}:${agentBaselineVersionTag(agent)}`,
+    );
+    // 接受 semver(`0.144.1-r2`)与 OpenClaw calver(`2026.7.1-2-r1`)。
+    expect(agentBaselineVersionTag(agent)).toMatch(/^\d+(\.\d+)+(?:-\d+)?-r\d+$/);
+  });
+
+  it.each(E2B_AGENTS)("keeps the %s E2B build tag on the same recipe version as Docker", (agent) => {
+    // 同一个 Agent 的两份制品共用一个版本号:一个版本号 = 一套基线配方。
+    expect(e2bBaselineBuildTag(agent)).toBe(agentBaselineVersionTag(agent));
+  });
+
+  it("takes the version position from the same constants the runtime fallback installs", () => {
+    expect(AGENT_BASELINE_VERSION).toEqual({
+      "claude-code": DEFAULT_CLAUDE_CODE_CLI_VERSION,
+      codex: DEFAULT_CODEX_CLI_VERSION,
+      bub: DEFAULT_BUB_VERSION,
+      opencode: DEFAULT_OPENCODE_CLI_VERSION,
+      hermes: DEFAULT_HERMES_CLI_VERSION,
+      openclaw: DEFAULT_OPENCLAW_CLI_VERSION,
+    });
+  });
+
+  it.each(E2B_AGENTS)("points the exported %s E2B ref at a published template", (agent) => {
+    const published = ledger.templates[agent];
+
+    // 具名常量只能指向台账里真实存在的制品:发布是维护者手动动作,常量不能先跑到发布前面。
+    expect(published.name).toBe(NICEEVAL_E2B_TEMPLATE_NAME[agent]);
+    expect(e2bTemplates[agent]).toBe(`${published.name}:${published.versionTag}`);
+    // 台账记的是那份制品里 Agent 的版本。源码把版本位往前推却没发布,只有一条合法出路:
+    // 在台账里写下待发布的 tag(supersededBy)。默不作声地分叉不行——那正是「常量指着装了
+    // 旧 Agent 的制品」而全绿的形态。
+    if (published.supersededBy === undefined) {
+      expect(published.agentVersion).toBe(AGENT_BASELINE_VERSION[agent]);
+    } else {
+      expect(published.supersededBy).toBe(agentBaselineVersionTag(agent));
+    }
+  });
+
+  it("keeps the published Bub template's install fingerprint in sync with the recipe", () => {
+    const published = ledger.templates.bub;
+
+    // 换 pin 必然换指纹:预装环境的 marker 对不上时 Adapter 回退完整安装,所以旧制品仍可用,
+    // 但台账必须承认它已被取代。
+    if (published.supersededBy === undefined) {
+      expect(published.installMarker).toBe(bubInstallHash([]));
+    } else {
+      expect(published.installMarker).not.toBe(bubInstallHash([]));
+    }
+  });
+
+  it("keeps the Dockerfile's pinned versions in sync with the source constants", () => {
+    // Dockerfile 不能 import TypeScript,漂移只在真实构建时暴露,所以逐个比对。
+    expect(dockerfile).toContain(`ARG CODEX_VERSION=${DEFAULT_CODEX_CLI_VERSION}`);
+    expect(dockerfile).toContain(`ARG CLAUDE_CODE_VERSION=${DEFAULT_CLAUDE_CODE_CLI_VERSION}`);
+    expect(dockerfile).toContain(`ARG OPENCODE_VERSION=${DEFAULT_OPENCODE_CLI_VERSION}`);
+    expect(dockerfile).toContain(`ARG OPENCLAW_VERSION=${DEFAULT_OPENCLAW_CLI_VERSION}`);
+    expect(dockerfile).toContain(`ARG HERMES_VERSION=${DEFAULT_HERMES_CLI_VERSION}`);
+    expect(dockerfile).toContain(DEFAULT_BUB_OTEL_PLUGIN.replace(/^git\+/, ""));
+    expect(dockerfile).toContain(`'${bubInstallHash([])}' > $HOME/${BUB_INSTALL_MARKER}`);
+  });
+
+  it("puts both Bub pins into the install fingerprint", () => {
+    const baseline = bubInstallHash([]);
+
+    // 预装环境靠 marker 命中。版本或插件换了指纹却不变,就会在配方已变时继续命中旧环境,
+    // 装到上一代 Bub 而全程无声。
+    expect(bubInstallHash([], bubRequirement("0.3.9"))).not.toBe(baseline);
+    expect(bubInstallHash([], DEFAULT_BUB_REQUIREMENT, `${DEFAULT_BUB_OTEL_PLUGIN}x`)).not.toBe(baseline);
+    expect(bubRequirement("0.3.9")).toBe("bub==0.3.9");
+  });
+
+  it("keeps the Docker bub override file in sync with the pinned recipe", async () => {
+    const override = await readFile(
+      new URL("../../sandbox/docker/bub-override.txt", import.meta.url),
+      "utf8",
+    );
+
+    // 这份 override 不是遗留物:插件所在 workspace 把 bub 声明成 git 依赖,少了它构建会拉
+    // Bub 主干,镜像里的版本随构建时间漂移。
+    expect(override.trim()).toBe(DEFAULT_BUB_REQUIREMENT);
+  });
+});

package/src/sandbox/resolve.ts

@@ -76,7 +76,7 @@ export function sandboxRecommendedConcurrency(opt: SandboxOption | undefined): n
 /**
  * ExperimentRunInfo.sandbox 的投影:provider 名 + 公开参数(镜像/快照/模板/runtime)+ 配置指纹。
  * 参数只经这个投影落盘——token、凭据路径永不进来;defineSandbox 自定义 provider 未实现
- * `publicConfig()` 时只落 provider 名(见 docs/feature/results/architecture.md)。
+ * `publicConfig()` 时只落 provider 名(见 docs/feature/record/architecture.md)。
  */
 export function sandboxRunInfo(
   opt: SandboxOption | undefined,

package/src/sandbox/types.ts

@@ -79,7 +79,7 @@ export interface SandboxHookContext extends ScopedFeedback {
    * 第三条反馈通道:上报本次运行的中性环境观测,落进 `AttemptRecord.facts`。key 匹配
    * `[a-z0-9._-]{1,64}`,value 是标量;同 key 后写覆盖先写,非法 key 或非标量 value 抛错。
    * 不影响判定,不参与 verdict / 评分 / 指纹。形状与归属语义见
-   * docs/feature/results/architecture.md#facts运行事实。
+   * docs/feature/record/architecture.md#facts运行事实。
    */
   fact(key: string, value: string | number | boolean): void;
 }

package/src/scoring/diff.ts

@@ -1,5 +1,5 @@
 // agent 归因 diff 的派生视图:从落盘事实(DiffWindow[])派生文件级摘要与终态读取。
-// 派生物可随时重算、不落盘——符合「聚合在消费方」铁律(docs/feature/results/architecture.md「diff.json」)。
+// 派生物可随时重算、不落盘——符合「聚合在消费方」铁律(docs/feature/record/architecture.md「diff.json」)。
 
 import type { DiffArtifact, DiffData, DiffFileSummary, DiffWindow, WindowChange } from "./types.ts";