niceeval 0.6.0 → 0.6.2

package/dist/runner/types.d.ts

@@ -1,18 +1,119 @@
-import type { Cleanup, LocalizedText, SourceArtifact } from "../shared/types.ts";
+import type { Cleanup, JsonValue, LocalizedText, 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, SandboxOption } from "../sandbox/types.ts";
-import type { AssertionResult, DiffData, JudgeConfig, Verdict } from "../scoring/types.ts";
+import type { Sandbox, SandboxHookContext, SandboxOption } from "../sandbox/types.ts";
+import type { AssertionResult, DiffArtifact, JudgeConfig, PrimaryAssertionSummary, Verdict } from "../scoring/types.ts";
 import type { TestContext } from "../context/types.ts";
 import type { CapturedEvalSource } from "./eval-source.ts";
+import type { AttemptLocator } from "../results/locator.ts";
+/**
+ * 解析后运行配置的**穷尽可序列化投影**——记录这次运行实际生效的值,不是原始 `ExperimentDef`
+ * (函数与 hooks 无法忠实落盘,存「原样」只能存谎)。`model` 与 `agent` 只在快照顶层存在,
+ * 这里不复制(见 docs/feature/results/architecture.md「snapshot.json」)。
+ */
 export interface ExperimentRunInfo {
-    id?: string;
-    flags?: Record<string, unknown>;
-    runs?: number;
-    earlyExit?: boolean;
-    sandbox?: string;
+    description?: string;
+    reasoningEffort?: string;
+    flags?: Record<string, JsonValue>;
+    runs: number;
+    earlyExit: boolean;
     timeoutMs?: number;
     budget?: number;
+    maxConcurrency?: number;
+    /** 本次运行解析后实际选中的 eval id 全集——evals 过滤器(含函数形式)的求值结果,不存过滤器本身。 */
+    selectedEvalIds: string[];
+    /** evals 过滤器的指纹(数组内容 / 函数体哈希),供「配置没变」判断;与 selectedEvalIds 一起取代原过滤器。 */
+    evalFilterFingerprint?: string;
+    /** provider 名、provider 的公开参数投影与配置 fingerprint;参数只经投影落盘,token/凭据永不进来。 */
+    sandbox?: {
+        provider: string;
+        params?: Record<string, JsonValue>;
+        fingerprint?: string;
+    };
+}
+/**
+ * 一次 attempt 的生命周期词表——**全仓唯一一套**(见 docs/feature/results/architecture.md
+ * 「result.json」)。计时(`phases[].name`)、错误归因(`error.phase`)、诊断归属
+ * (`diagnostics[].phase`)、live 展示与 agent/ci envelope 的 `phase=` 都使用这同一个闭集,
+ * 不存在第二套词表。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";
+/** TimingNode 的种类(见 docs/feature/results/architecture.md「result.json」)。 */
+export type TimingNodeKind = "hook" | "turn" | "command" | "provider" | "operation";
+/**
+ * Runner 直接观察到的阶段内时间树节点;只供单 attempt 诊断,不做跨实验聚合。
+ * `startOffsetMs` 相对 attempt 单调时钟起点——并发 sibling 可据此还原重叠,
+ * 不能只靠数组顺序相加。
+ */
+export interface TimingNode {
+    /** attempt 内唯一,供 children 与展示层稳定引用;不作为跨 attempt 身份。 */
+    id: string;
+    kind: TimingNodeKind;
+    /** 人读标签;hook 匿名时用 setup#<i>/teardown#<i>,turn 用 s<session>/t<turn>。 */
+    label: string;
+    /** 相对 attempt 单调时钟起点的偏移。 */
+    startOffsetMs: number;
+    durationMs: number;
+    failed?: true;
+    children?: TimingNode[];
+    /** kind=turn 时存在;把 runner 的 send 墙钟包络与 trace.json 中同一轮的 spans 显式关联。 */
+    sessionIndex?: number;
+    turnIndex?: number;
+    turnId?: string;
+    traceId?: string;
+    traceAttribution?: "traceparent" | "window" | "none";
+    /** kind=command 时的有界脱敏摘要;环境变量值与 stdout/stderr 不进入时间树。 */
+    command?: {
+        display: string;
+        exitCode?: number;
+    };
+}
+/** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/results/architecture.md)。 */
+export interface PhaseTiming {
+    name: LifecyclePhase;
+    /** 阶段耗时;失败阶段计到抛错或超时中断时。 */
+    durationMs: number;
+    /** 该阶段抛错或被超时中断。主链至多一条,其后无主链条目;收尾阶段各自独立标记,不改判定。 */
+    failed?: true;
+    /** Runner 直接观察到的阶段内时间树;只供单 attempt 诊断,不做跨实验聚合。 */
+    children?: TimingNode[];
+}
+/**
+ * 使 attempt 无法正常完成的唯一致命执行错误(见 docs/feature/results/architecture.md 的
+ * `AttemptError`)。`message` 是人可读的一层原因(不拼整份 SDK response);完整 stack 单放
+ * `stack`,`niceeval show @locator` 首页展开、终端即时反馈不整段打印。榜单只显示 `message`。
+ */
+export interface AttemptError {
+    /** 稳定、可供 CI/Agent 分支处理的机器码;未知异常使用 `"unexpected-error"`。 */
+    code: string;
+    /** 人可读的一层原因,不拼接整份 SDK response。 */
+    message: string;
+    /** runner 在错误发生时已经打开的生命周期阶段。 */
+    phase: LifecyclePhase;
+    /** 原异常有 stack 时保留,供 show 展开;终端即时反馈不整段打印。 */
+    stack?: string;
+    /** 下层 SDK/OS 错误的有限摘要。 */
+    cause?: {
+        name?: string;
+        code?: string;
+        message: string;
+    };
+}
+/**
+ * 不一定改变 verdict、但运行后仍需回顾的有界诊断(见 docs/feature/results/architecture.md 的
+ * `DiagnosticRecord`)。`level` 表达消息严重度,不是 verdict 的别名 —— passed / failed / errored
+ * 任一 verdict 都可以带 cleanup / teardown 诊断。与运行级的 `DiagnosticNotice` 不同,这条挂在单个
+ * attempt 结果上、随 `result.json` 落盘。
+ */
+export interface DiagnosticRecord {
+    code: string;
+    level: "warning" | "error";
+    message: string;
+    phase: LifecyclePhase;
+    data?: Readonly<Record<string, JsonValue>>;
+    /** 相同 dedupeKey 折叠后的出现次数;省略等于 1。 */
+    count?: number;
 }
 export interface EvalResult {
     id: string;
@@ -38,7 +139,12 @@ export interface EvalResult {
     assertions: AssertionResult[];
     usage?: Usage;
     estimatedCostUSD?: number;
-    error?: string;
+    /** 使 attempt 进入 `errored` 的唯一致命执行错误(结构化);榜单显示 `error.message` 一层原因。 */
+    error?: AttemptError;
+    /** 本 attempt 的诊断(与 verdict 独立);teardown / cleanup 失败等挂在这里,不改判定。 */
+    diagnostics?: readonly DiagnosticRecord[];
+    /** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/results/architecture.md)。 */
+    phases?: PhaseTiming[];
     skipReason?: string;
     events?: StreamEvent[];
     /** test 引用到的 eval 源码(按 loc 收集),供 view 渲染 github-diff 式代码视图。 */
@@ -48,7 +154,23 @@ export interface EvalResult {
     trace?: TraceSpan[];
     /** 本 attempt 的 agent setup 实际装了什么(Skill / native plugin / MCP / Python plugin);不参与评分。 */
     agentSetup?: AgentSetupManifest;
-    diff?: DiffData;
+    /**
+     * attempt 级聚合的证据覆盖(各 turn 的最差值,unknown/unavailable < partial < complete),
+     * 报告据此展示证据覆盖徽标(见 docs/feature/adapters/architecture/evidence.md)。
+     */
+    coverage?: import("../scoring/coverage.ts").ResolvedCoverage;
+    /**
+     * 沙箱型 attempt 的执行环境标识:provider 名与实例 id,用于关联 provider 侧日志与留存现场;
+     * remote 型 agent 无此字段。`kept` 表示运行收尾时按 --keep-sandbox 留存了沙箱;之后的存活
+     * 状态归 `niceeval sandbox list` 回答,本记录一次写成、不回写。
+     */
+    sandbox?: {
+        provider: string;
+        sandboxId: string;
+        kept?: true;
+    };
+    /** agent 归因增量:逐 send 窗口的 delta 序列(落盘为 diff.json;文件级视图由读取面派生)。 */
+    diff?: DiffArtifact;
     rawTranscript?: string;
     /** 携带条目(--resume 合入)专用:artifact 目录(相对结果根目录),指向原快照里的落盘。 */
     artifactBase?: string;
@@ -63,8 +185,16 @@ export declare const RESULTS_FORMAT = "niceeval.results";
  * `5`(见 memory 的 attempt-locator-and-source-dedup 条目)= result.json 新增 `locator` 字段;
  * `sources.json` 从逐 attempt 内联全量内容改为「attempt 级引用 + 快照级 `sources/<sha256>.json`
  * 去重仓库」,`AttemptHandle.sources()` 的公开返回形状不变(仍是 `SourceArtifact[] | null`)。
+ * `6` = `error` 从自由字符串改为结构化 `AttemptError`,并新增有界 `diagnostics`。
+ * `8` = 断言记录改 outcome 判别联合(groupPath/optional/expected/received/unavailable+reason);
+ * 生命周期词表统一为 LifecyclePhase,`error.operation`/`diagnostics[].operation` 更名 `phase`;
+ * 新增 `phases`(阶段计时)、`coverage`(证据覆盖聚合)、`sandbox`(执行环境标识)字段;
+ * `ExperimentRunInfo` 改为解析后运行配置的穷尽投影(sandbox 从字符串改结构化投影对象);
+ * `diff.json` 落逐窗口 delta 序列(DiffWindow[]);events/trace 的字符串值统一 256 KiB 截断
+ * (结构化 `truncated` 标记);snapshot.json 新增发布拷贝的 `publish` 标记。
+ * 旧版快照按格式规则整份判为不兼容并在扫描时列为占位条目,不迁移不降级。
  */
-export declare const RESULTS_SCHEMA_VERSION = 5;
+export declare const RESULTS_SCHEMA_VERSION = 8;
 /** 一次运行的纯运行时内存聚合(reporter 契约用);落盘格式契约在 niceeval/results 的 SnapshotMeta / AttemptRecord,见 docs/feature/results/architecture.md。 */
 export interface RunSummary {
     /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
@@ -95,6 +225,17 @@ export interface RunShape {
     /** 本次运行实际生效的全局并发数(flag/env/config/sandbox 默认值解析后的结果);
      *  实验级 maxConcurrency 只在该实验内部限流,不改这个全局值。 */
     maxConcurrency: number;
+    /**
+     * 本次 invocation 的快照身份锚点(ISO 时间戳),在调度任何 attempt 前确定。fresh
+     * `EvalResult.locator` 编码进去的 `snapshotStartedAt`(见 `results/locator.ts` 的
+     * `AttemptIdentity`)与 Artifacts writer 写进 `snapshot.json` 的 `startedAt` 共用
+     * 同一个值 —— 不同 experiment 在同一次 invocation 内共享它也不会碰撞(locator 身份
+     * 还含 experimentId)。`runEvals()` 恒在 `onRunStart` 触发前把它填进这里,这是它
+     * 从 run.ts 传给 Artifacts 等 reporter 的唯一途径;省略只出现在测试/第三方手写
+     * `RunShape` 的直调场景。见 docs/feature/experiments/cli.md「Locator 必须在
+     * result 发布前确定」。
+     */
+    snapshotStartedAt?: string;
 }
 export interface Reporter {
     onEvent?(event: ReporterEvent): void | Promise<void>;
@@ -104,6 +245,29 @@ export interface Reporter {
     onEvalComplete?(result: EvalResult): void | Promise<void>;
     onRunComplete?(summary: RunSummary): void | Promise<void>;
 }
+/**
+ * 内部 reporter 注册项:CLI/runner 给每个 `Reporter` 实例附上「叫什么名字」「失败是否致命」
+ * 两条元数据,不改变用户实现 `Reporter` 的公共形状——`Reporter` 接口本身不变,用户只需要实现
+ * 上面那四个回调,从不需要知道 `ReporterRegistration` 的存在。`name` 是
+ * `reportReporterError()` / `DiagnosticNotice.key` 里 `reporter-error:<name>` 的稳定标识:
+ * 同一个 reporter 反复失败折叠成一条诊断、`count` 递增,不同 reporter 各自一条,由这个字段的
+ * 取值决定,不是「在哪个回调阶段失败」(onRunStart/onEvalComplete/…)决定——后者只作为
+ * 诊断消息里的次要上下文,不参与去重身份。
+ *
+ * `required` 语义(见 docs/feature/experiments/cli.md「运行完成状态不只看 verdict 计数」):
+ * - 默认 Artifacts reporter、CLI 显式 `--json` / `--junit`:`required: true`——它们的产物是
+ *   agent/CI 读取权威结果的唯一入口,写失败必须让 `RunCompletion` 判红、CI 退出码非零。
+ * - 用户 `Config.reporters` / `EvalDef.reporters`:`required: false`——失败只折成一条
+ *   diagnostic,不影响 completion,也不阻断其它 reporter 收尾或后续 attempt。
+ *
+ * `target` 是可选的落盘路径(如 `--json`/`--junit` 指定的文件),纯展示 / 排障用途,不参与判定。
+ */
+export interface ReporterRegistration {
+    reporter: Reporter;
+    name: string;
+    required: boolean;
+    target?: string;
+}
 export type ReporterEvent = {
     type: "run:start";
     evals: {
@@ -153,12 +317,24 @@ export interface EvalDef {
     timeoutMs?: number;
     /** 任意附加元数据,原样透传进 EvalResult,不参与调度或打分;供自定义 reporter 消费。 */
     metadata?: Record<string, unknown>;
+    /**
+     * 调整 agent diff 的归因排除清单(仅沙箱型;见 docs/feature/eval/README.md):两个数组都是
+     * gitignore 风格 glob(workdir 相对)。默认排除 .git/node_modules/构建产物/包管理器缓存;
+     * `ignore` 在默认清单上追加排除;`include` 优先级最高,把匹配路径显式加回。
+     * 合成规则固定为「默认 ∪ ignore,再被 include 打洞」,清单在分类账锚点时冻结。
+     */
+    diff?: {
+        include?: string[];
+        ignore?: string[];
+    };
     /**
      * eval 级预置:拿到沙箱(已上传 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`。
      */
-    setup?: (sandbox: Sandbox) => Promise<void | Cleanup> | void | Cleanup;
+    setup?: (sandbox: Sandbox, ctx: SandboxHookContext) => Promise<void | Cleanup> | void | Cleanup;
     /** eval 主体:拿到 TestContext,驱动对话 / 沙箱操作并就地断言。 */
     test(t: TestContext): Promise<void> | void;
 }
@@ -189,8 +365,10 @@ export interface ExperimentDef {
     model?: string;
     /** 模型推理努力程度(如 "low"/"medium"/"high",取值由具体模型/adapter 决定);省略=用 agent 原生默认。经 ctx.reasoningEffort 透给 adapter 与 eval。 */
     reasoningEffort?: string;
-    /** 实验条件(A/B 里的 feature flag),由实验文件声明;经 ctx.flags 透传给 adapter、t.flags 暴露给 eval。 */
-    flags?: Record<string, unknown>;
+    /** 实验条件(A/B 里的 feature flag),由实验文件声明;必须是可 JSON 序列化的值
+     *  (defineExperiment 解析时校验,非 JSON 直接报错),经 ctx.flags 透传给 adapter、
+     *  t.flags 暴露给 eval,并原样进入结果快照的 ExperimentRunInfo.flags。 */
+    flags?: Record<string, JsonValue>;
     /** 同一 eval 重复跑几次(结果各计一条 attempt);省略/CLI `--runs` 覆盖时默认 1。 */
     runs?: number;
     /** 一次重复(runs > 1)里某次 attempt 失败后是否跳过剩余重复;省略默认 true(提前退出省钱)。 */
@@ -202,9 +380,8 @@ export interface ExperimentDef {
     /** 覆盖项目级 Config.sandbox,只对这个实验生效。 */
     sandbox?: SandboxOption;
     /**
-     * 本实验的花费上限(USD)。调度器按「已花 + 在飞预估」的护栏口径逼近上限时限流,
-     * 累计花费到顶后跳过这个实验剩下未起飞的 attempt 并上报一次 `run:budgetExceeded`
-     * (已在飞的 attempt 仍会跑完)。
+     * 本实验的花费上限(USD)。调度器按「已完成 attempt 的实测花费」累计,到顶后跳过这个实验
+     * 剩下未起飞的 attempt 并上报一次 `run:budgetExceeded`(已在飞的 attempt 仍会跑完)。
      */
     budget?: number;
     /**
@@ -272,7 +449,16 @@ export interface PriceOverride {
 /**
  * 进度行 / 日志里标识一个 run 配置的短名。有 experiment 时用其 basename(唯一,
  * 能区分同 agent 同 model 的实验变体,如 xxx 与 xxx--agents-md;与汇总表口径一致);
- * 无 experiment 时退回 agent/model。live display 以它作行聚合 key,两处必须同源。
+ * 无 experiment 时退回 agent/model。现有 live display 以它(拼 evalId)作行聚合 key,
+ * 两处必须同源(改这里的格式要同步核对 live.ts 的 key 计算,见 memory 的
+ * live-who-key-mismatch-freezes-rows —— 上一次格式改动漏改 live.ts 自己手写的两处曾冻结整表)。
+ *
+ * 这是展示 label,不是 identity —— 两个不同的 (evalId, attempt) 可能巧合算出同一个 who
+ * (同 experiment 同 eval 的第 2 次重试与另一条 eval 的第 1 次重试,展示上都叫同一个 basename)。
+ * 反馈系统新的事件/状态(见上面 `AttemptRef` / `AttemptKey` / `encodeAttemptKey`)一律用
+ * `{experimentId, evalId, attempt}` 做 identity/Map key,`who` 只作为 `ActiveAttempt.who`
+ * 之类的展示字段附着,不参与去重或查找 —— 把展示 label 错当成 identity key 曾经是 live 表格
+ * 两个真实 bug 的根因(另见 memory 的 live-rows-fold-experiment-variants)。
  */
 export declare function runWho(run: {
     agentName: string;
@@ -284,7 +470,7 @@ export interface AgentRun {
     agent: Agent;
     model?: string;
     reasoningEffort?: string;
-    flags: Record<string, unknown>;
+    flags: Record<string, JsonValue>;
     runs: number;
     earlyExit: boolean;
     sandbox?: SandboxOption;
@@ -292,6 +478,12 @@ export interface AgentRun {
     budget?: number;
     evalFilter: (id: string) => boolean;
     experimentId?: string;
+    /** 实验的一句话描述(ExperimentDef.description),进结果快照的 ExperimentRunInfo。 */
+    description?: string;
+    /** evals 过滤器的指纹(数组内容 / 函数体哈希),进 ExperimentRunInfo.evalFilterFingerprint。 */
+    evalFilterFingerprint?: string;
+    /** 本次运行解析后实际选中的 eval id 全集;runEvals 在调度前按 evalFilter 求值填入。 */
+    selectedEvalIds?: string[];
     strict?: boolean;
     /** 本配置自己的并发上限(来自 ExperimentDef.maxConcurrency):调度器为它单建信号量,
      *  attempt 先过这道闸再占全局并发位;省略则只受全局并发约束。 */
@@ -301,11 +493,24 @@ export interface RunOptions {
     config: Config;
     evals: DiscoveredEval[];
     agentRuns: AgentRun[];
-    reporters: Reporter[];
+    /**
+     * `--keep-sandbox` 的留存档位:failed 留 failed/errored(含硬超时的 errored),all 全部留;
+     * 省略 = 全部销毁(留存永远是显式选择)。留存决策在 verdict 定稿的收尾点按档位提交,
+     * 见 docs/feature/sandbox/architecture.md「留存(keep)与注册表」。
+     */
+    keepSandbox?: "failed" | "all";
+    /** 结果根目录(.niceeval;留存注册表 `.niceeval/sandboxes/` 挂在它下面)。省略 = cwd/.niceeval。 */
+    niceevalRoot?: string;
+    /**
+     * 已注册的 reporter,携带 name/required 元数据(见 `ReporterRegistration`)。这是内部编排
+     * 通道——调用方(今天只有 `cli.ts`)按来源(默认 artifacts / 显式 --json·--junit / 用户
+     * `Config.reporters`)把裸 `Reporter` 各自包一层元数据后传进来;eval 级 `EvalDef.reporters`
+     * 不经过这里,由 `runEvals()` 自己按 `scopeReporter()` 包装、统一记作 `required: false`
+     *(见 run.ts 的 scopedSets 处理)。
+     */
+    reporters: ReporterRegistration[];
     maxConcurrency: number;
     signal?: AbortSignal;
-    /** TTY live display 的进度回调;设置后 attempt 的 log 消息路由到它而不是 stderr。 */
-    onProgress?: (evalId: string, who: string, msg: string) => void;
     /** 上次运行的结果。verdict 为 passed/failed 的 (experimentId, evalId) 组合跳过重跑,结果直接合入本次汇总。 */
     priorResults?: EvalResult[];
     /**
@@ -329,4 +534,290 @@ export interface Attempt {
     /** agent+model+evalId,用于首过即停。 */
     key: string;
     fingerprint: string;
+    /**
+     * 构造 fresh attempt plan 时即算好的 Attempt 定位符(不是完成后写回):由 invocation 的
+     * snapshotStartedAt 与 attempt 身份派生,贯穿执行、留存登记与落盘——登记项、run 收尾反馈与
+     * result.json 从第一次写入起就用同一个值。裸 run(无 experimentId)不产出。
+     */
+    locator?: AttemptLocator;
+}
+/** 三种最终反馈 profile。`--output auto` 只是 CLI flag 的输入值,解析后必然落在这三者之一。 */
+export type OutputProfile = "human" | "agent" | "ci";
+/**
+ * 反馈系统里一次 attempt 的稳定身份:reducer 用它做 active map 的 key、事件的关联字段。
+ * 只含调度身份三元组 —— 不含 agent/model/展示 label(那是 `who`,来自 `runWho()`,
+ * 见该函数注释:展示 label 不能当 identity key 用,folding 两个不同 config 到同一个 key
+ * 曾经就是 live 表格两个真实 bug 的根因),也不含 `AttemptLocator` 需要的
+ * `snapshotStartedAt`(那是落盘身份,由 `results/locator.ts` 的 `AttemptIdentity` 独立管理;
+ * 完成/failure 事件在 locator 确定后直接携带派生好的 `AttemptLocator` 字符串,反馈层
+ * 不重新推导身份 —— 两个同名概念的 identity 类型故意不同名,以免和落盘身份互相看错)。
+ */
+export interface AttemptRef {
+    /** 未挂靠 experiment 时为 undefined(直接指定 agent/model 跑,不经过 experiment);不用空字符串占位。 */
+    experimentId?: string;
+    evalId: string;
+    /** 0-indexed,与 `EvalResult.attempt` / `AttemptLocator` 的 attempt 同一口径。 */
+    attempt: number;
 }
+/** `AttemptRef` 的确定性字符串编码,只作 `RunFeedbackState.active` 的 Map key 使用 ——
+ *  不是展示文本(那是 `who`),也不是 `AttemptLocator`(那需要额外的 `snapshotStartedAt`)。 */
+export type AttemptKey = string & {
+    readonly __brand: "AttemptKey";
+};
+/** 由 `AttemptRef` 派生 `AttemptKey`;同一身份永远编码出同一个 key。 */
+export declare function encodeAttemptKey(ref: AttemptRef): AttemptKey;
+/**
+ * dashboard 当前可见的一个 active slot。`phase` 是正式状态,`detail` 只是该 phase 下的次要文本
+ *(如 `running` 阶段的 `tool: shell` / `turn 2`)—— 两者是两个字段,不把 adapter 的 raw progress
+ * string 直接当状态用;phase 变化时 `detail` 清空(旧阶段的次要文本不该残留到新阶段)。
+ */
+export interface ActiveAttempt {
+    identity: AttemptRef;
+    /** 展示 label,等价 `runWho()` 的结果;渲染要用,但绝不作为 identity/key。 */
+    who: string;
+    phase: LifecyclePhase;
+    /** 进入当前 phase 的墙钟时间(epoch ms),用于渲染阶段耗时;每次 phase 变化都会更新。 */
+    phaseStartedAt: number;
+    detail?: string;
+}
+/**
+ * 一次失败/错误的永久通知:human 撤下 dashboard 后追加一行、agent/ci 立即追加一行,都读它。
+ * 字段全部结构化(locator / identity / verdict / phase 都是具名字段),profile renderer 不需要
+ * 解析 `reason` 之外的任何文本就能拼出机器可读的输出。
+ */
+export interface FailureDetail {
+    locator: AttemptLocator;
+    identity: AttemptRef;
+    who: string;
+    verdict: "failed" | "errored";
+    /** 一层可行动摘要(gate 断言名、error 消息……),不是完整 stack/transcript;详情走 `niceeval show`。 */
+    reason: string;
+    /** failed / assertion-unavailable 时的结构化主断言摘要；机器 renderer 直接读字段。 */
+    assertion?: PrimaryAssertionSummary;
+    /** 仅 errored 使用：结构化执行错误发生时所在的阶段。failed 是断言 outcome，不带 phase。 */
+    phase?: LifecyclePhase;
+}
+/** 带发生时间的失败通知；复用失败以 FailureDetail 静态进入 plan，不伪装成刚发生的事件。 */
+export interface FailureNotice extends FailureDetail {
+    at: number;
+}
+/**
+ * 去重后的诊断通知(warning/error):相同 `key` 的诊断只保留一条,`count` 累加受影响次数
+ *(见 docs/feature/experiments/cli.md「什么动态更新,什么逐条追加」的去重规则)。
+ * `data` 携带结构化字段(如 budget 的 experimentId/spent/unstarted),agent/ci 直接读取,
+ * 不解析 `message`(`message` 只是 human 展示用的一句话)。
+ */
+export interface DiagnosticNotice {
+    at: number;
+    key: string;
+    severity: "warning" | "error";
+    message: string;
+    /** 相同 key 累计出现的次数,由 reducer 去重时递增。 */
+    count: number;
+    identity?: AttemptRef;
+    data?: Readonly<Record<string, JsonValue>>;
+}
+/** 运行完整性结论,独立于 verdict 计数。CI 退出码不能只看 failed/errored ——
+ *  budget 未覆盖全部计划、用户中断、required reporter 失败都必须让 completion 非「complete」。 */
+export type CompletionStatus = "complete" | "incomplete" | "interrupted";
+/** 一个 reporter 收尾失败的记录;`required` 区分它是否让 completion 判红(见 ReporterRegistration)。 */
+export interface ReporterError {
+    reporter: string;
+    required: boolean;
+    message: string;
+}
+export interface RunCompletion {
+    status: CompletionStatus;
+    /** budget 耗尽导致未派发的 attempt 数;不含首过即停省略的次数(见 `earlyExitUnstarted`)。 */
+    unstarted: number;
+    /** 首过即停在已知 verdict 下主动省略的计划次数 —— 这是「省下的重复验证」,不是「未完整覆盖」。 */
+    earlyExitUnstarted: number;
+    reporterErrors: readonly ReporterError[];
+}
+/**
+ * 事件 → 状态的纯 reducer 产出(见 `src/runner/feedback/reducer.ts`)。所有计数、active map、
+ * cost 累计、failure/diagnostic 去重都只在 reducer 里算一次;三种 profile 的 renderer 只读取
+ * 这份状态,不各自维护第二份推导。
+ *
+ * `total = reused + running + queued + completed` 在处理完每一个事件之后都成立,是 reducer 的
+ * 不变量(见 reducer.test.ts 的表驱动用例,每一步都断言,不只在流程末尾断言一次)。
+ */
+export interface RunFeedbackState {
+    total: number;
+    reused: number;
+    running: number;
+    queued: number;
+    completed: number;
+    /** attempt:early-exit 事件的累计次数(首过即停省略 + fail-fast 未派发;后者由 fail-fast
+     *  diagnostic 的 count 单独区分,见 cli.ts 的 assembleRunCompletion)。 */
+    earlyExitSkipped: number;
+    elapsedMs: number;
+    /** 仅本次实际派发 attempt 的 token；carry 结果的历史 usage 不进入这里。 */
+    newTokenCount?: number;
+    estimatedCostUSD?: number;
+    active: ReadonlyMap<AttemptKey, ActiveAttempt>;
+    failures: readonly FailureNotice[];
+    /** 本次实际派发后产生的去重失败数；复用失败不消耗 profile 的流式输出上限。 */
+    freshFailureCount: number;
+    diagnostics: readonly DiagnosticNotice[];
+    /** 留存授予的沙箱(--keep-sandbox);run 摘要后各 profile 追加输出。 */
+    kept: readonly KeptNotice[];
+}
+/** 一条留存授予的永久通知(见 docs/feature/sandbox/cli.md「run 收尾输出」)。 */
+export interface KeptNotice {
+    at: number;
+    locator: AttemptLocator;
+    identity: AttemptRef;
+    who: string;
+    verdict: Verdict;
+    provider: string;
+    sandboxId: string;
+    enter?: string;
+}
+/** 一次 run 的初始计划。复用只暴露数量；失败明细仅用于静态初始化终局清单。 */
+export interface RunFeedbackPlan {
+    shape: RunShape;
+    /** 携入(carry)结果数,直接计入 `RunFeedbackState.reused`,不需要重新调度。 */
+    reused: number;
+    /** 复用结果中的失败；plan 时静态注入，不产生“刚发生”的失败事件。 */
+    reusedFailures?: readonly FailureDetail[];
+}
+/**
+ * 只影响 dashboard 当前帧、reducer 不为它保留历史的事件:新值使旧值失去意义,所以覆盖而不是
+ * 追加(见 docs/feature/experiments/cli.md「什么动态更新,什么逐条追加」的判断标准)。
+ * `attempt:early-exit` 同样折进这一组 —— 它不打印永久行,只把已知 verdict 的省略次数收进
+ * `completed`(见 reducer 实现)。
+ */
+export type AttemptLifecycleEvent = {
+    type: "attempt:queued";
+    at: number;
+    identity: AttemptRef;
+    who: string;
+} | {
+    type: "attempt:start";
+    at: number;
+    identity: AttemptRef;
+    who: string;
+    phase: LifecyclePhase;
+} | {
+    type: "attempt:phase";
+    at: number;
+    identity: AttemptRef;
+    phase: LifecyclePhase;
+} | {
+    type: "attempt:progress";
+    at: number;
+    identity: AttemptRef;
+    detail: string;
+} | {
+    type: "attempt:complete";
+    at: number;
+    identity: AttemptRef;
+    who: string;
+    verdict: Verdict;
+    /** 本次 attempt 的输入 + 输出 token；缺失表示 provider 未报告。 */
+    tokenCount?: number;
+    estimatedCostUSD?: number;
+} | {
+    type: "attempt:early-exit";
+    at: number;
+    identity: AttemptRef;
+    who: string;
+};
+/**
+ * 运行级时钟 tick:唯一允许更新 `RunFeedbackState.elapsedMs` 的事件,由 coordinator 的定时器产出
+ *(见 plan 的可注入 `FeedbackIO` clock)。reducer 保持纯函数,不自己读 `Date.now()`,elapsedMs
+ * 因此只能通过事件携带的值前进 —— 这也让 reducer 测试可以喂任意 elapsed 值,不必真的等待。
+ */
+export interface FeedbackTickEvent {
+    type: "tick";
+    at: number;
+    elapsedMs: number;
+}
+/**
+ * 永久事件:human 撤下 dashboard 后追加一行、agent 按 envelope 追加、ci 按 stdout 事件追加,
+ * 一旦发生就不会被后续状态覆盖掉(与上面按当前帧覆盖的 `AttemptLifecycleEvent` 相对)。
+ * 字段全部结构化,profile renderer 不解析 `message` 之外的任何文本、不解析 i18n 字符串。
+ */
+export type DurableFeedbackEvent = {
+    type: "plan";
+    at: number;
+    plan: RunFeedbackPlan;
+} | {
+    type: "failure";
+    at: number;
+    locator: AttemptLocator;
+    identity: AttemptRef;
+    who: string;
+    verdict: "failed" | "errored";
+    reason: string;
+    assertion?: PrimaryAssertionSummary;
+    phase?: LifecyclePhase;
+} | {
+    type: "diagnostic";
+    at: number;
+    key: string;
+    severity: "warning" | "error";
+    message: string;
+    identity?: AttemptRef;
+    data?: Readonly<Record<string, JsonValue>>;
+}
+/**
+ * emitter 对每一个因 budget 到顶而不派发的 attempt 各发一次(与 `attempt:early-exit` 同构,
+ * 见 reducer 实现);`unstarted` 是 emitter 自己记的、发出这条时的累计未派发数,写进
+ * `DiagnosticNotice.data` 供 agent/ci 直接读取,不是 reducer 用来计算「这次要挪多少」的输入
+ *(reducer 只按事件触发次数折算,保持纯函数不需要额外记住上一次的值)。
+ */
+ | {
+    type: "budget-exhausted";
+    at: number;
+    experimentId: string;
+    spent: number;
+    unstarted: number;
+}
+/** 一次留存授予(--keep-sandbox):run 摘要后三种 profile 都追加输出(见 docs/feature/sandbox/cli.md)。 */
+ | {
+    type: "kept";
+    at: number;
+    locator: AttemptLocator;
+    identity: AttemptRef;
+    who: string;
+    verdict: Verdict;
+    provider: string;
+    sandboxId: string;
+    enter?: string;
+} | {
+    type: "interrupted";
+    at: number;
+} | {
+    type: "reporter-error";
+    at: number;
+    reporter: string;
+    required: boolean;
+    message: string;
+} | {
+    type: "summary";
+    at: number;
+    summary: RunSummary;
+    completion: RunCompletion;
+} | {
+    type: "saved";
+    at: number;
+    /** 本次 invocation 实际落盘的快照结果路径。不含 `--json`/`--junit` 聚合文件——那两个由
+     *  `json`/`junit` 两个独立字段单独携带,而不是塞进这个数组后靠猜文件后缀去反推「哪一个
+     *  是聚合报告、哪些是快照目录」;CI 的 result 收尾需要把 `json=`/`junit=`/`snapshots=`
+     *  打成三条独立的行(见 docs/feature/experiments/cli.md「CI 怎么用」的字面例子),
+     *  结构化字段让它不需要解析路径字符串就能做到。 */
+    paths: readonly string[];
+    /** 实际写出的 `--json` 聚合报告路径。未传 `--json`,或写入失败(见 required reporter
+     *  语义),都省略这个字段——省略表示「不打印这一行」,不是打印一个空路径。 */
+    json?: string;
+    /** 实际写出的 `--junit` 聚合报告路径,语义同 `json`。 */
+    junit?: string;
+};
+/**
+ * runner → feedback coordinator 的内部事件通道,与公共 `Reporter` / `ReporterEvent` 分开:
+ * profile renderer 只消费这里的具名字段,不解析 `ReporterEvent` 里的 i18n 文案或表格列宽
+ *(见 docs/feature/experiments/cli.md「输出流和落盘节奏」)。
+ */
+export type RunFeedbackEvent = AttemptLifecycleEvent | FeedbackTickEvent | DurableFeedbackEvent;