niceeval 0.9.0 → 0.10.0

package/dist/runner/types.d.ts

@@ -1,4 +1,4 @@
-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";
@@ -15,6 +15,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;
@@ -41,7 +43,7 @@ export interface SandboxRunInfo {
  * 不存在第二套词表。phase 是 runner 对真实 lifecycle 的单方面投影,不是 adapter / sandbox
  * provider / 用户 hook 能直接设置的公共字段。
  */
-export type LifecyclePhase = "sandbox.queue" | "sandbox.create" | "sandbox.setup" | "workspace.baseline" | "eval.setup" | "agent.setup" | "telemetry.configure" | "eval.run" | "agent.run" | "workspace.diff" | "scoring.evaluate" | "telemetry.collect" | "eval.teardown" | "agent.teardown" | "sandbox.teardown" | "sandbox.suspend" | "sandbox.stop";
+export type LifecyclePhase = "experiment.setup" | "experiment.teardown" | "sandbox.queue" | "sandbox.create" | "sandbox.setup" | "workspace.baseline" | "eval.setup" | "agent.setup" | "telemetry.configure" | "eval.run" | "agent.run" | "workspace.diff" | "scoring.evaluate" | "telemetry.collect" | "eval.teardown" | "agent.teardown" | "sandbox.teardown" | "sandbox.suspend" | "sandbox.stop";
 /** TimingNode 的种类(见 docs/feature/results/architecture.md「result.json」)。 */
 export type TimingNodeKind = "hook" | "turn" | "command" | "provider" | "operation";
 /**
@@ -312,18 +314,18 @@ 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 打洞」,清单在分类账锚点时冻结。
@@ -333,14 +335,23 @@ export interface EvalDef {
         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;
 }
 /** 内部:发现后带上 id 的 eval。 */
@@ -356,6 +367,20 @@ 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;
@@ -374,12 +399,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;
     /**
@@ -399,10 +439,40 @@ 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 {
     /**
@@ -410,11 +480,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[];
@@ -425,11 +495,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?: {
@@ -486,18 +556,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 {
     config: Config;
@@ -592,6 +673,23 @@ export interface ActiveAttempt {
     phaseStartedAt: number;
     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 不需要
@@ -668,6 +766,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;
@@ -736,6 +837,16 @@ export type AttemptLifecycleEvent = {
     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
@@ -798,6 +909,21 @@ export type DurableFeedbackEvent = {
     provider: string;
     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;
@@ -832,4 +958,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/dist/sandbox/docker.d.ts

@@ -91,6 +91,12 @@ export declare 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)。
      */
     uploadFile(destPath: string, content: Buffer): Promise<void>;
     /** 销毁容器:显式 stop + remove(创建时不带 AutoRemove,见 createContainer 的注释)。 */

package/dist/sandbox/types.d.ts

@@ -1,4 +1,4 @@
-import type { Cleanup, ScopedFeedback } from "../shared/types.ts";
+import type { ScopedFeedback } from "../shared/types.ts";
 export interface CommandResult {
     stdout: string;
     stderr: string;
@@ -65,15 +65,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 钩子,按追加顺序保存(内部读取,一般用不到)。 */
@@ -96,8 +97,9 @@ export interface SandboxHookContext extends ScopedFeedback {
     /** 本次 attempt 的中止信号。 */
     readonly signal: AbortSignal;
 }
-/** 沙箱级生命周期钩子(`.setup()` / `.teardown()` 链式挂载);`setup` 可返回 cleanup 闭包。 */
-export type SandboxHook = (sandbox: Sandbox, ctx: SandboxHookContext) => void | Cleanup | Promise<void | Cleanup>;
+/** 沙箱级生命周期钩子(`.setup()` / `.teardown()` 链式挂载);`setup` 不返回值——要把 `setup`
+ * 创建的句柄传给 `teardown`,以 `sandbox` 实例为键存取(见 {@link SandboxHooks})。 */
+export type SandboxHook = (sandbox: Sandbox, ctx: SandboxHookContext) => void | Promise<void>;
 /**
  * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/feature/sandbox/library.md)。
  * 必须用工厂函数构造(`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()`),
@@ -160,12 +162,12 @@ export type SandboxSpec = DockerSandboxSpec | VercelSandboxSpec | E2BSandboxSpec
 /** config / experiment 的 `sandbox` 字段:必须是工厂函数产出的 spec 数据结构;沙箱型 agent 不能省略。 */
 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 只声明意图。
@@ -180,7 +182,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 映射到自己的原生机制
@@ -191,7 +193,7 @@ export interface CommandOptions {
     root?: boolean;
 }
 export interface Sandbox {
-    /** 沙箱内项目/工作区根目录的绝对路径(agent 命令的默认 cwd,也是 git baseline 提交的位置)。各方法的相对路径都以此为基准解析,省略 `cwd`/`targetDir` 时也落到这里。 */
+    /** Sandbox 内项目/工作区根目录的绝对路径(agent 命令的默认 cwd,也是 git baseline 提交的位置)。各方法的相对路径都以此为基准解析,省略 `cwd`/`targetDir` 时也落到这里。 */
     readonly workdir: string;
     /**
      * 执行单个命令,`args` 作为独立 argv 传递、不经 shell 解释(无 `&&`、管道、通配符展开)。
@@ -203,31 +205,31 @@ 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;
@@ -237,12 +239,12 @@ 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/dist/scoring/display.d.ts

@@ -8,8 +8,13 @@ export declare function summaryText(value: string): string;
 export declare function primaryAssertionSummary(assertions: readonly AssertionResult[], verdict: Verdict): PrimaryAssertionSummary | undefined;
 /** 摘要的事实层；Human/Agent 用作第二行，表格可把它接在标题后。 */
 export declare function assertionSummaryDetail(summary: PrimaryAssertionSummary): string | undefined;
-/** Human/Agent 的至多两层文本。 */
-export declare function assertionSummaryLines(summary: PrimaryAssertionSummary): [string] | [string, string];
+/**
+ * Human/Agent 永久行的排版：标题独占一行；`matcher · expected`（含 score/threshold/reason）
+ * 独占下一行；`received` 能跟这行拼在一起仍在 DETAIL_LINE_MAX_CHARS 内就合并，放不下就单独
+ * 再起一行并硬截断。`+N more failures` 永远是独立尾行，不参与截断，也不拼进被截断的值——
+ * 截断处的 `…` 后面只会是值本身，不会被人误读成计数的一部分。
+ */
+export declare function assertionSummaryLines(summary: PrimaryAssertionSummary): string[];
 /** 比较列表的单元格投影；无 group 时不重复 `gate:` 前缀。 */
 export declare function compactAssertionSummary(summary: PrimaryAssertionSummary): string;
 /**

package/dist/scoring/display.js

@@ -5,6 +5,12 @@
  * 恰好是源码/工具输出时把多页内容灌进 scrollback；完整 AssertionResult 仍原样留给 show/view。
  */
 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) {
     const singleLine = value.replace(/\s+/g, " ").trim();
@@ -70,11 +76,43 @@ export function assertionSummaryDetail(summary) {
         parts.push(`+${summary.additionalFailures} more failures`);
     return parts.length > 0 ? parts.join(" · ") : undefined;
 }
-/** Human/Agent 的至多两层文本。 */
+/**
+ * Human/Agent 永久行的排版：标题独占一行；`matcher · expected`（含 score/threshold/reason）
+ * 独占下一行；`received` 能跟这行拼在一起仍在 DETAIL_LINE_MAX_CHARS 内就合并，放不下就单独
+ * 再起一行并硬截断。`+N more failures` 永远是独立尾行，不参与截断，也不拼进被截断的值——
+ * 截断处的 `…` 后面只会是值本身，不会被人误读成计数的一部分。
+ */
 export function assertionSummaryLines(summary) {
-    const head = `${summary.severity}: ${summary.assertion}`;
-    const detail = assertionSummaryDetail(summary);
-    return detail === undefined ? [head] : [head, detail];
+    const lines = [`${summary.severity}: ${summary.assertion}`];
+    const factParts = [];
+    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:` 前缀。 */
 export function compactAssertionSummary(summary) {

package/dist/scoring/types.d.ts

@@ -12,11 +12,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;
     /**

package/dist/shared/aggregate.d.ts

@@ -18,9 +18,23 @@ export declare function experimentGroupOf(experimentId: string): string | undefi
 /**
  * eval id 前缀过滤,同 CLI 位置参数语义(docs/feature/reports/show.md「打开与收窄」):
  * eval 位置参数是收窄过滤,按**裸前缀宽松匹配**——"algebra" 命中 "algebra"、"algebra/..."
- * 也命中 "algebra2",多命中正是它的用途(与 `--experiment` 的按路径段匹配有意不同)。
+ * 也命中 "algebra2",多命中正是它的用途(与 `--exp` 的按路径段匹配有意不同)。
  */
 export declare function evalPrefixPredicate(evals?: string | string[]): (id: string) => boolean;
+/**
+ * 实验选择器解析:`niceeval exp` 位置参数与 `--exp` 共用同一条规则(docs/feature/experiments/cli.md
+ * 「实验选择器怎样解析」)。按序:①精确 id 优先,即使它同时是同目录内其它文件名的前缀;
+ * ②目录段精确前缀(含更深层目录),选中该目录下全部实验;③以上都不命中且选择器形如
+ * `目录/文件名前缀` 时,目录段精确匹配后按文件名段前缀选中一族配置——目录段永远精确,不跨目录
+ * 误配,文件名段裸前缀,与 `evalPrefixPredicate` 同一条"共享前缀即家族"的逻辑。
+ */
+export declare function matchExperimentSelector(ids: readonly string[], selector: string): string[];
+/**
+ * 零命中时展示的可浏览路径清单(docs/feature/experiments/cli.md「零命中」):按 id 的顶层目录段
+ * 去重、排序,带尾斜杠;没有目录段的顶层 experiment id 原样列出(它本身就是一个可选择的目标,
+ * 不是一段路径)。这是运行选择的展示投影,不是报告分组。
+ */
+export declare function browsableExperimentPaths(ids: readonly string[]): string[];
 /** 无 experimentId 时的兜底标签。 */
 export declare function fallbackExperimentLabel(result: {
     experimentId?: string;

package/dist/shared/aggregate.js

@@ -38,7 +38,7 @@ export function experimentGroupOf(experimentId) {
 /**
  * eval id 前缀过滤,同 CLI 位置参数语义(docs/feature/reports/show.md「打开与收窄」):
  * eval 位置参数是收窄过滤,按**裸前缀宽松匹配**——"algebra" 命中 "algebra"、"algebra/..."
- * 也命中 "algebra2",多命中正是它的用途(与 `--experiment` 的按路径段匹配有意不同)。
+ * 也命中 "algebra2",多命中正是它的用途(与 `--exp` 的按路径段匹配有意不同)。
  */
 export function evalPrefixPredicate(evals) {
     if (evals === undefined)
@@ -46,6 +46,37 @@ export function evalPrefixPredicate(evals) {
     const prefixes = Array.isArray(evals) ? evals : [evals];
     return (id) => prefixes.some((prefix) => id.startsWith(prefix));
 }
+/**
+ * 实验选择器解析:`niceeval exp` 位置参数与 `--exp` 共用同一条规则(docs/feature/experiments/cli.md
+ * 「实验选择器怎样解析」)。按序:①精确 id 优先,即使它同时是同目录内其它文件名的前缀;
+ * ②目录段精确前缀(含更深层目录),选中该目录下全部实验;③以上都不命中且选择器形如
+ * `目录/文件名前缀` 时,目录段精确匹配后按文件名段前缀选中一族配置——目录段永远精确,不跨目录
+ * 误配,文件名段裸前缀,与 `evalPrefixPredicate` 同一条"共享前缀即家族"的逻辑。
+ */
+export function matchExperimentSelector(ids, selector) {
+    const exact = ids.find((id) => id === selector);
+    if (exact !== undefined)
+        return [exact];
+    const dirMatches = ids.filter((id) => id.startsWith(selector + "/"));
+    if (dirMatches.length > 0)
+        return dirMatches;
+    const lastSlash = selector.lastIndexOf("/");
+    if (lastSlash === -1)
+        return [];
+    const dir = selector.slice(0, lastSlash);
+    const namePrefix = selector.slice(lastSlash + 1);
+    if (namePrefix === "")
+        return [];
+    return ids.filter((id) => id.startsWith(dir + "/") && id.slice(dir.length + 1).startsWith(namePrefix));
+}
+/**
+ * 零命中时展示的可浏览路径清单(docs/feature/experiments/cli.md「零命中」):按 id 的顶层目录段
+ * 去重、排序,带尾斜杠;没有目录段的顶层 experiment id 原样列出(它本身就是一个可选择的目标,
+ * 不是一段路径)。这是运行选择的展示投影,不是报告分组。
+ */
+export function browsableExperimentPaths(ids) {
+    return [...new Set(ids.map((id) => (id.includes("/") ? `${id.split("/")[0]}/` : id)))].sort();
+}
 /** 无 experimentId 时的兜底标签。 */
 export function fallbackExperimentLabel(result) {
     if (result.experimentId)

package/dist/shared/types.d.ts

@@ -18,7 +18,12 @@ export interface SourceArtifact {
     path: string;
     content: string;
 }
-/** 通用清理闭包(setup 返回值 / teardown 的形状),异步同步皆可,统一在 finally 里执行。 */
+/**
+ * 内部收尾闭包类型:供运行器内部的清理注册表使用(如 `postSetup` 钩子内部累积待收尾动作),
+ * 不出现在任何公开的生命周期钩子签名里——`SandboxHook`/`AgentSetup`/`AgentTeardown` 等公开
+ * 钩子一律 `void | Promise<void>`,setup 不返回值,收尾靠成对的 teardown(见
+ * docs/runner.md「环境预置不进运行器,但按顺序调它」)。
+ */
 export type Cleanup = () => Promise<void> | void;
 /** `ScopedFeedback.progress` 的入参:此刻正在做什么(短命状态,可被后续更新覆盖)。 */
 export interface ProgressUpdate {