niceeval 0.6.1 → 0.6.2

package/src/runner/feedback/reducer.ts

@@ -0,0 +1,260 @@
+// 纯 reducer:RunFeedbackEvent → RunFeedbackState。计数、active slot、cost 累计、
+// failure/diagnostic 去重全部只在这里计算 —— 三种 profile 的 renderer(后续阶段实现)只读
+// RunFeedbackState,不各自维护第二份推导,也不解析 message 里的人类文案(结构化字段都在
+// DiagnosticNotice.data / FailureNotice 的具名字段上,见 ../types.ts 的类型注释)。
+//
+// `total = reused + running + queued + completed` 在处理每一个事件之后都成立 —— 见
+// reducer.test.ts 的表驱动用例,每一步都断言这个不变量,不只在流程末尾断言一次。
+//
+// reducer 本身不读 Date.now()、不碰 process.stdout/stderr、不知道 profile 是 human/agent/ci ——
+// 纯函数 (state, event) => state,方便脱离真实 runner/terminal 单测。
+
+import type { DiagnosticNotice, FailureNotice, RunFeedbackEvent, RunFeedbackState } from "../types.ts";
+import { encodeAttemptKey } from "../types.ts";
+
+/** reducer 的起始状态:一个尚未收到任何事件的 run。 */
+export function createInitialRunFeedbackState(): RunFeedbackState {
+  return {
+    total: 0,
+    reused: 0,
+    running: 0,
+    queued: 0,
+    completed: 0,
+    earlyExitSkipped: 0,
+    elapsedMs: 0,
+    active: new Map(),
+    failures: [],
+    freshFailureCount: 0,
+    diagnostics: [],
+    kept: [],
+  };
+}
+
+export function reduceRunFeedback(state: RunFeedbackState, event: RunFeedbackEvent): RunFeedbackState {
+  switch (event.type) {
+    case "plan": {
+      const total = event.plan.shape.totalRuns;
+      const reused = event.plan.reused;
+      // plan 是一次 run 的起点:重置 active/failures/diagnostics,即便 reducer 被复用于
+      // 多次 run 也不会把上一次的残留状态带进新 run(正常用法下 plan 本来就应是第一个事件)。
+      return {
+        ...state,
+        total,
+        reused,
+        // 全部非携入 attempt 在此刻就已知会被派发,先计入 queued;后续 attempt:start
+        // 逐个把它们移进 running,不必等每条 attempt:queued 事件才累加(见类型注释)。
+        queued: Math.max(0, total - reused),
+        running: 0,
+        completed: 0,
+        active: new Map(),
+        failures: (event.plan.reusedFailures ?? []).map((failure) => ({ ...failure, at: event.at })),
+        freshFailureCount: 0,
+        diagnostics: [],
+      };
+    }
+
+    case "tick":
+      return { ...state, elapsedMs: event.elapsedMs };
+
+    case "attempt:queued":
+      // 计数已经在 "plan" 时一次性算好(见上),这个事件目前只是为后续阶段预留「单条 attempt
+      // 进入排队」的挂点(如展示排队位置),对 RunFeedbackState 不产生任何变化。
+      return state;
+
+    case "attempt:start": {
+      const key = encodeAttemptKey(event.identity);
+      const active = new Map(state.active);
+      active.set(key, {
+        identity: event.identity,
+        who: event.who,
+        phase: event.phase,
+        phaseStartedAt: event.at,
+      });
+      return {
+        ...state,
+        queued: state.queued - 1,
+        running: state.running + 1,
+        active,
+      };
+    }
+
+    case "attempt:phase": {
+      const key = encodeAttemptKey(event.identity);
+      const existing = state.active.get(key);
+      if (!existing) return state; // 防御:识别不到的 attempt 静默忽略,不让 renderer 崩
+      const active = new Map(state.active);
+      // 进入新 phase 清空旧 detail —— 次要文本是绑定到具体 phase 的(如 running 阶段的
+      // "tool: shell"),不该原样带进下一个 phase 显示。
+      active.set(key, { ...existing, phase: event.phase, phaseStartedAt: event.at, detail: undefined });
+      return { ...state, active };
+    }
+
+    case "attempt:progress": {
+      const key = encodeAttemptKey(event.identity);
+      const existing = state.active.get(key);
+      if (!existing) return state;
+      const active = new Map(state.active);
+      active.set(key, { ...existing, detail: event.detail });
+      return { ...state, active };
+    }
+
+    case "attempt:complete": {
+      const key = encodeAttemptKey(event.identity);
+      const active = new Map(state.active);
+      active.delete(key);
+      const estimatedCostUSD =
+        event.estimatedCostUSD === undefined
+          ? state.estimatedCostUSD
+          : (state.estimatedCostUSD ?? 0) + event.estimatedCostUSD;
+      const newTokenCount =
+        event.tokenCount === undefined
+          ? state.newTokenCount
+          : (state.newTokenCount ?? 0) + event.tokenCount;
+      return {
+        ...state,
+        running: state.running - 1,
+        completed: state.completed + 1,
+        active,
+        newTokenCount,
+        estimatedCostUSD,
+      };
+    }
+
+    case "attempt:early-exit":
+      // 首过即停下已知 verdict 的省略次数:折进 completed(结论已经确定,不再需要派发),
+      // 不产生 failures/diagnostics —— 这不是一次失败或异常,只是省下的重复验证
+      // (真正「未完整覆盖」的信号来自 budget-exhausted / fail-fast diagnostic,不是这里)。
+      return {
+        ...state,
+        queued: state.queued - 1,
+        completed: state.completed + 1,
+        earlyExitSkipped: state.earlyExitSkipped + 1,
+      };
+
+    case "failure": {
+      const isFresh = !state.failures.some((failure) => failure.locator === event.locator);
+      return {
+        ...state,
+        failures: upsertFailure(state.failures, {
+          at: event.at,
+          locator: event.locator,
+          identity: event.identity,
+          who: event.who,
+          verdict: event.verdict,
+          reason: event.reason,
+          ...(event.assertion !== undefined ? { assertion: event.assertion } : {}),
+          ...(event.phase !== undefined ? { phase: event.phase } : {}),
+        }),
+        freshFailureCount: state.freshFailureCount + (isFresh ? 1 : 0),
+      };
+    }
+
+    case "diagnostic":
+      return {
+        ...state,
+        diagnostics: upsertDiagnostic(state.diagnostics, {
+          at: event.at,
+          key: event.key,
+          severity: event.severity,
+          message: event.message,
+          identity: event.identity,
+          data: event.data,
+        }),
+      };
+
+    case "budget-exhausted":
+      // 约定:emitter 对每一个因 budget 到顶而不派发的 attempt 各发一次这个事件(与
+      // attempt:early-exit 同构),所以每次触发在这里折进 completed 一次 —— 不去信任
+      // event.unstarted 的绝对值来算「这次要挪多少」(那需要 reducer 额外记住上一次的值,
+      // 破坏纯 (state, event) => state 的最小状态原则)。event.unstarted / event.spent 仍然
+      // 整体写进 diagnostic 的 data,供 agent/ci 直接读取当次快照值;真正的去重计数由
+      // upsertDiagnostic 的 count 字段给出,天然等于「目前为止因 budget 未派发的次数」。
+      return {
+        ...state,
+        queued: state.queued - 1,
+        completed: state.completed + 1,
+        diagnostics: upsertDiagnostic(state.diagnostics, {
+          at: event.at,
+          key: `budget-exhausted:${event.experimentId}`,
+          severity: "warning",
+          message: `budget exhausted for ${event.experimentId}`,
+          data: { experimentId: event.experimentId, spent: event.spent, unstarted: event.unstarted },
+        }),
+      };
+
+    case "kept":
+      // 留存授予的永久通知:run 摘要后各 profile 追加输出(见 docs/feature/sandbox/cli.md)。
+      return {
+        ...state,
+        kept: [
+          ...state.kept,
+          {
+            at: event.at,
+            locator: event.locator,
+            identity: event.identity,
+            who: event.who,
+            verdict: event.verdict,
+            provider: event.provider,
+            sandboxId: event.sandboxId,
+            ...(event.enter !== undefined ? { enter: event.enter } : {}),
+          },
+        ],
+      };
+
+    case "interrupted":
+      return {
+        ...state,
+        diagnostics: upsertDiagnostic(state.diagnostics, {
+          at: event.at,
+          key: "interrupted",
+          severity: "warning",
+          message: "run interrupted",
+        }),
+      };
+
+    case "reporter-error":
+      return {
+        ...state,
+        diagnostics: upsertDiagnostic(state.diagnostics, {
+          at: event.at,
+          key: `reporter-error:${event.reporter}`,
+          severity: event.required ? "error" : "warning",
+          message: `reporter "${event.reporter}" failed: ${event.message}`,
+          data: { reporter: event.reporter, required: event.required },
+        }),
+      };
+
+    case "summary":
+    case "saved":
+      // 终局通知:发出时 counts/active 已经由前面的 attempt 事件更新到位,状态本身不再变化——
+      // 这两个事件的 payload(summary/completion/paths)由 coordinator 直接使用,不经 reducer
+      // 折叠进 RunFeedbackState(RunFeedbackState 是「当前进行中」的 dashboard 状态,不是终局报告)。
+      return state;
+
+    default: {
+      // 穷尽性检查:新增 RunFeedbackEvent 变体时,这里会在编译期报错提醒补上对应分支。
+      const exhaustive: never = event;
+      return exhaustive;
+    }
+  }
+}
+
+function upsertFailure(failures: readonly FailureNotice[], notice: FailureNotice): readonly FailureNotice[] {
+  // 同一 locator 理论上不该出现两次;真出现时按最新一次覆盖(幂等),而不是重复追加同一条失败。
+  const idx = failures.findIndex((f) => f.locator === notice.locator);
+  if (idx === -1) return [...failures, notice];
+  const next = failures.slice();
+  next[idx] = notice;
+  return next;
+}
+
+function upsertDiagnostic(
+  diagnostics: readonly DiagnosticNotice[],
+  input: Omit<DiagnosticNotice, "count">,
+): readonly DiagnosticNotice[] {
+  const idx = diagnostics.findIndex((d) => d.key === input.key);
+  if (idx === -1) return [...diagnostics, { ...input, count: 1 }];
+  const next = diagnostics.slice();
+  next[idx] = { ...input, count: next[idx].count + 1 };
+  return next;
+}

package/src/runner/feedback/renderer.ts

@@ -0,0 +1,82 @@
+// FeedbackRenderer:human / agent / ci 三种 profile(见 docs/feature/experiments/cli.md)各实现
+// 一份的插件契约。FeedbackCoordinator(coordinator.ts)是这份契约唯一的调用方 —— renderer 不
+// 知道、也不需要知道事件从哪来、该不该去重、什么时候该 tick,这些全部由 coordinator 保证好
+// 了才调用这里;renderer 只管「拿到一个已经确定要展示的 typed 事件 / 已经更新好的状态,
+// 该画成什么样」。
+//
+// 后续阶段(D=human、E=agent、F=ci)各写一个模块实现这个接口,不需要再回来改这个文件。
+
+import type {
+  AttemptLifecycleEvent,
+  DurableFeedbackEvent,
+  FeedbackTickEvent,
+  RunFeedbackState,
+} from "../types.ts";
+
+/**
+ * 方法命名对应 docs 里「coordinator 负责:撤下动态区域 → 永久写一行 → 在下方重建」的三步:
+ * clearDynamic → appendDurable → redrawDynamic。coordinator 保证三步按序、原子执行(内部单
+ * 队列串行处理一个事件的三步,不会被下一个事件插入打断);agent/ci 没有「动态区域」概念,
+ * 两个 clear/redraw 钩子留空不实现即可 —— coordinator 探测到未实现就跳过,不会因为可选方法
+ * 缺失而报错。
+ */
+export interface FeedbackRenderer {
+  /**
+   * 一条永久事件落地(见 `DurableFeedbackEvent`):human 打一行、agent 按 envelope 追加、ci 按
+   * stdout 事件追加。三种 profile 都必须实现 —— 这是最基本的职责,即便某个 profile 选择对
+   * 某个 `event.type` 不输出任何可见内容(如 agent 收到 "saved" 但把路径信息留到最终 handoff
+   * 才汇总展示),也要显式接住、不抛错。
+   *
+   * 同一个逻辑事件(如两次 `key` 相同的 "diagnostic")可能被调用多次 —— coordinator 只保证
+   * `RunFeedbackState.diagnostics` 里的去重计数正确,不代为决定「该不该重复打印」;renderer
+   * 自己决定重复出现时是刷新一行还是静默吸收计数(human dashboard 通常选后者,见 cli.md
+   * 「同一 dedupeKey 并发出现时只留一条并显示次数」—— 在只能追加、不能回改 scrollback 的
+   * 终端模型下,这意味着首次之后的调用大多是no-op,只靠 state 里的 count 保证信息不丢)。
+   */
+  appendDurable(event: DurableFeedbackEvent, state: RunFeedbackState): void | Promise<void>;
+
+  /**
+   * 即将落地一条永久事件 / 一条 activity 之前,若当前画着动态区域(human dashboard)先撤下。
+   * 返回后 coordinator 紧接着调用 appendDurable(或 activity),再(若仍处于「运行中」阶段)
+   * 调用 redrawDynamic —— 三者被 coordinator 视为一个原子操作,renderer 不需要自己处理并发/
+   * 交错。agent/ci 不实现即可。**必须幂等**:当前没有画任何动态内容时调用也必须安全(coordinator
+   * 在 stopDynamic() 收尾时会无条件再调用一次)。
+   */
+  clearDynamic?(): void | Promise<void>;
+
+  /** appendDurable(或 activity)之后,若动态区域还应该存在,在这里重建(human dashboard 专用)。
+   *  run 收尾阶段(coordinator.stopDynamic() 之后)不会再调用这个钩子 —— 见 coordinator.ts
+   *  的「结束后不允许再重建动态区域」。 */
+  redrawDynamic?(state: RunFeedbackState): void | Promise<void>;
+
+  /**
+   * 不进入 `RunFeedbackState`、不去重的瞬时活动文本(如 docker 镜像拉取进度、vercel session
+   * rotate 成功通知)—— A2 阶段(scoped `ScopedFeedback.progress`)落地前的过渡出口,详见
+   * `sink.ts` 的 `reportActivity`。coordinator 仍按 clearDynamic → activity → redrawDynamic
+   * 的顺序调用;不实现就等价于「provisioning retry/backoff 不逐次输出」——agent/ci 的目标行为
+   * (见 cli.md 信息分级表)天然由「不实现这个可选方法」满足,不需要 renderer 自己判断 profile。
+   */
+  activity?(text: string, state: RunFeedbackState): void | Promise<void>;
+
+  /**
+   * 运行级时钟 tick(见 `FeedbackTickEvent`):human 用它判断要不要重画 dashboard(自行做
+   * 4fps/1Hz 节流 —— coordinator 只保证「这是一次重画机会」,不承诺 tick 间隔恰好等于某个
+   * profile 需要的帧率);agent/ci 用它判断距上一次永久事件是否已超过空闲阈值(30s / 60s,
+   * coordinator 不知道这两个数字,那是各 renderer 自己维护的常量),超过则自行追加一条
+   * heartbeat(通过自己的输出通道,不是再回调 coordinator——heartbeat 不是需要去重/计入
+   * RunFeedbackState 的永久事件)。
+   */
+  onTick?(event: FeedbackTickEvent, state: RunFeedbackState): void | Promise<void>;
+
+  /** attempt 生命周期事件(见 `AttemptLifecycleEvent`):human 用它驱动 active slot 的内容;
+   *  agent/ci 通常不需要实现 —— 它们不逐条展示 active 状态(见 cli.md 的信息分级表)。 */
+  onLifecycle?(event: AttemptLifecycleEvent, state: RunFeedbackState): void | Promise<void>;
+
+  /**
+   * coordinator 关闭时的最后一次机会 —— 在 `finish()` 内部,已经完成 stopDynamic() 且已经把
+   * "summary"/"saved" 两个永久事件送进 appendDurable 之后才调用。之后保证不会再收到任何调用。
+   * 适合释放 renderer 自己持有的资源(如未 unref 的句柄);不适合再写任何输出 —— 该写的已经
+   * 通过 appendDurable 写完。
+   */
+  close?(): void | Promise<void>;
+}

package/src/runner/feedback/sink.ts

@@ -0,0 +1,203 @@
+// run 激活期间,底层模块(sandbox provider、budget 记账、reporter 兜底、中断处理……)不得
+// 直接写 stdout/stderr(见 docs/feature/experiments/cli.md「输出流和落盘节奏」与本文件对应的
+// PLAN 第 2 节「一个 run 内只有一个终端协调者」)。它们改调用这里的 reportXxx() 系列函数。
+//
+// - 有活跃 FeedbackCoordinator 时(coordinator.start() 之后、finish() 之前,见 cli.ts 的
+//   run:start 接线),转发给它 —— coordinator 负责去重、clear→append→redraw 排序、按 profile
+//   分派给 renderer。
+// - 没有活跃 coordinator 时(run:start 之前的 bootstrap 错误、finish() 之后、或不经过
+//   cli.ts 的直接库调用),透传回 `src/tty-line.ts` 的 bootstrap 出口。
+//
+// 活跃 coordinator 用一个栈而不是单个全局变量:允许嵌套/连续的 runEvals() 调用(如测试里
+// 同进程跑多个 run,或未来某种「run 之内再跑一个子 run」的场景)各自持有自己的活跃身份,
+// 不会互相覆盖对方的 sink。用显式栈(而不是旧 `tty-line.ts` 那套「广播给所有监听者」的
+// 订阅模式)是因为 reportXxx() 需要一个*唯一*目的地来做去重决策,不能让多个监听者都收到
+// 同一条消息。
+
+import { writeStderrLine } from "../../tty-line.ts";
+import { t } from "../../i18n/index.ts";
+import type { AttemptLifecycleEvent, AttemptRef, FailureDetail } from "../types.ts";
+import type { Verdict } from "../../scoring/types.ts";
+import type { JsonValue } from "../../shared/types.ts";
+import type { AttemptLocator } from "../../results/locator.ts";
+
+/** `sink.diagnostic()` 的输入 —— 与 `DurableFeedbackEvent` 的 "diagnostic" 变体字段一致,
+ *  只是省略 `type`/`at`(由 coordinator 补上)。 */
+export interface DiagnosticInput {
+  /** 稳定去重 key —— 同一种 warning/error 用同一个 key(见 cli.md「同一 dedupeKey 并发出现时
+   *  只留一条并显示次数」),不要把可变的实例细节(如具体 sandbox id)编进 key 本身,
+   *  那些细节放 `data`。 */
+  key: string;
+  severity: "warning" | "error";
+  /** 一句话人类可读摘要;renderer 的 appendDurable 直接展示,不需要再解析。 */
+  message: string;
+  identity?: AttemptRef;
+  data?: Readonly<Record<string, JsonValue>>;
+}
+
+/** `sink.failure()` 的输入 —— 与 `DurableFeedbackEvent` 的 "failure" 变体字段一致,只省略
+ *  `type`/`at`(由 coordinator 补上)。`locator` 只有在 attempt 挂靠 experiment 时才存在
+ *  (见 `results/locator.ts` 的 `encodeAttemptLocator`);调用方(run.ts)只在拿到 locator 之后
+ *  才应该调用这个函数——没有 locator 的裸 run 不产出这类永久失败通知。 */
+export type FailureInput = FailureDetail;
+
+/** `sink.budgetExhausted()` 的输入 —— 与 `DurableFeedbackEvent` 的 "budget-exhausted" 变体字段
+ *  一致,只省略 `type`/`at`。调用方(run.ts)对每一个因预算到顶而不派发的 attempt 各调一次
+ *  (与 `AttemptLifecycleEvent` 的 "attempt:early-exit" 同构);`unstarted` 是调用方自己维护的、
+ *  发出这条时的累计未派发数,不是 reducer 能推导的值(见 reducer.ts 对应事件的注释)。 */
+export interface BudgetExhaustedInput {
+  experimentId: string;
+  spent: number;
+  unstarted: number;
+}
+
+/** `sink.kept()` 的输入 —— 与 `DurableFeedbackEvent` 的 "kept" 变体字段一致,省略 type/at。 */
+export interface KeptInput {
+  locator: AttemptLocator;
+  identity: AttemptRef;
+  who: string;
+  verdict: Verdict;
+  provider: string;
+  sandboxId: string;
+  enter?: string;
+}
+
+/** `sink.ts` façade 函数实际转发到的最小接口 —— `FeedbackCoordinator`(coordinator.ts)实现它。
+ *  定义在这里(而不是从 coordinator.ts 导入)是为了让 sink.ts 不必在运行时依赖 coordinator.ts,
+ *  避免两个模块互相 import 造成的循环依赖 —— coordinator.ts 反过来 `import type` 这个接口。 */
+export interface FeedbackSink {
+  activity(text: string): void;
+  diagnostic(input: DiagnosticInput): void;
+  interrupted(): void;
+  reporterError(input: { reporter: string; required: boolean; message: string }): void;
+  /** 一次失败/errored attempt 的永久通知(见 `FailureInput`)。 */
+  failure(input: FailureInput): void;
+  /** 一个因预算到顶而未被派发的 attempt(见 `BudgetExhaustedInput`)。 */
+  budgetExhausted(input: BudgetExhaustedInput): void;
+  /** 一次留存授予(--keep-sandbox);见 `KeptInput` 与 docs/feature/sandbox/cli.md。 */
+  kept(input: KeptInput): void;
+  /** attempt 生命周期事件(queued/start/phase/progress/complete/early-exit),见
+   *  `AttemptLifecycleEvent`。只驱动 human dashboard 的 active slot,不落 RunSummary/结果文件,
+   *  所以没有活跃 coordinator 时(见 `reportAttemptLifecycle`)静默丢弃是安全的 —— 这类信息
+   *  本身就只服务「正在画着的 dashboard」,不是必须留痕的诊断。 */
+  lifecycle(event: AttemptLifecycleEvent): void;
+}
+
+const activeStack: FeedbackSink[] = [];
+
+/**
+ * coordinator 进入「活跃」阶段时调用一次(见 coordinator.ts 的 start()),把自己注册为当前
+ * reportXxx() 调用的目的地。返回的函数用于退出活跃状态(见 coordinator.ts 的 finish())——
+ * 调用一次即失效,重复调用是安全的 no-op。
+ */
+export function activateFeedbackSink(sink: FeedbackSink): () => void {
+  activeStack.push(sink);
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    const idx = activeStack.lastIndexOf(sink);
+    if (idx !== -1) activeStack.splice(idx, 1);
+  };
+}
+
+function current(): FeedbackSink | undefined {
+  return activeStack[activeStack.length - 1];
+}
+
+/** 仅供测试:断言没有遗留未退出的活跃 coordinator(避免一个测试忘记 finish() 污染下一个)。 */
+export function activeFeedbackSinkCount(): number {
+  return activeStack.length;
+}
+
+/** 不需要去重、不进入 RunFeedbackState 的瞬时活动文本(docker 镜像拉取进度、vercel session
+ *  rotate 成功通知……)。没有活跃 coordinator 时退回一行 stderr,与迁移前的裸写视觉效果一致。 */
+export function reportActivity(text: string): void {
+  const sink = current();
+  if (sink) {
+    sink.activity(text);
+    return;
+  }
+  writeStderrLine(text.endsWith("\n") ? text : `${text}\n`);
+}
+
+/** 需要去重、要出现在三种 profile 永久事件流里的一条 warning/error。 */
+export function reportDiagnostic(input: DiagnosticInput): void {
+  const sink = current();
+  if (sink) {
+    sink.diagnostic(input);
+    return;
+  }
+  writeStderrLine(input.message.endsWith("\n") ? input.message : `${input.message}\n`);
+}
+
+/** 一次失败/errored attempt 的永久通知(见 `FailureInput`)。与 `reportDiagnostic` 同级别的
+ *  「必须留痕」信号 —— 没有活跃 coordinator 时退回一行 stderr,不像 `reportAttemptLifecycle`
+ *  那样静默丢弃(定位一次真实失败不该因为没接 coordinator 就彻底没有出口)。 */
+export function reportFailure(input: FailureInput): void {
+  const sink = current();
+  if (sink) {
+    sink.failure(input);
+    return;
+  }
+  writeStderrLine(`${input.who} ${input.verdict}: ${input.reason}\n`);
+}
+
+/** 一个因预算到顶而未被派发的 attempt(见 `BudgetExhaustedInput`)。没有活跃 coordinator 时的
+ *  兜底文案与 coordinator.ts 的 `fallbackTextFor` 对 "budget-exhausted" 事件的格式化保持一致。 */
+/** 一次留存授予的永久通知(--keep-sandbox);没有活跃 coordinator 时退回一行 stderr。 */
+export function reportKept(input: KeptInput): void {
+  const sink = current();
+  if (sink) {
+    sink.kept(input);
+    return;
+  }
+  writeStderrLine(`kept sandbox ${input.sandboxId} (${input.provider}) — ${input.identity.evalId} #${input.identity.attempt} ${input.verdict}\n`);
+}
+
+export function reportBudgetExhausted(input: BudgetExhaustedInput): void {
+  const sink = current();
+  if (sink) {
+    sink.budgetExhausted(input);
+    return;
+  }
+  writeStderrLine(`budget exhausted for ${input.experimentId} (spent ${input.spent}, unstarted ${input.unstarted})\n`);
+}
+
+/** 用户中断(Ctrl+C)。没有活跃 coordinator 时的兜底文案与迁移前的 `runner.interrupted` 完全
+ *  相同 —— 调用方(run.ts)不再需要自己持有这段 i18n 文案。 */
+export function reportInterrupted(): void {
+  const sink = current();
+  if (sink) {
+    sink.interrupted();
+    return;
+  }
+  writeStderrLine(t("runner.interrupted"));
+}
+
+/**
+ * runner 自己驱动的 attempt 生命周期投影(见 docs/feature/experiments/cli.md「Attempt 阶段」)——
+ * `src/runner/attempt.ts`(phase/progress)与 `src/runner/run.ts`(start/complete/early-exit)是
+ * 目前仅有的两个调用方。没有活跃 coordinator 时(今天:CLI 还没接入 --output)静默 no-op ——
+ * 与其它 reportXxx() 不同,这里不退回 `writeStderrLine` 兜底:这类事件只服务尚不存在的
+ * dashboard,不是需要留痕的诊断,现有可观察行为(直到 CLI 接入真正的 coordinator 之前)因此
+ * 完全不变。
+ */
+export function reportAttemptLifecycle(event: AttemptLifecycleEvent): void {
+  current()?.lifecycle(event);
+}
+
+/** 一个 reporter 的某次回调抛错(见 `runner/report.ts` 的 `runReporter`)。`reporter`/`required`
+ *  来自调用方注册这个 reporter 时的 `ReporterRegistration`(见其字段注释)——默认 artifacts、
+ *  显式 `--json`/`--junit` 传 `required: true`,用户 `config.reporters`/`EvalDef.reporters`
+ *  传 `required: false`。coordinator 把它折进 `RunFeedbackState.diagnostics`(reducer 按
+ *  `reporter-error:<reporter>` 去重),调用方(`cli.ts` 的 `assembleRunCompletion`)据此把
+ *  `required` 为真的失败折进 `RunCompletion.reporterErrors`,让 completion/CI 退出码判红。 */
+export function reportReporterError(input: { reporter: string; required: boolean; message: string }): void {
+  const sink = current();
+  if (sink) {
+    sink.reporterError(input);
+    return;
+  }
+  writeStderrLine(t("runner.reporterDiagnostic", { stage: input.reporter, message: input.message }));
+}

package/src/runner/feedback/testing.ts

@@ -0,0 +1,106 @@
+// 测试专用:确定性假 FeedbackIO。coordinator.test.ts 与后续阶段(D/E/F renderer 测试)共用,
+// 好让「同一种 fake IO 的搭建方式」只维护一份 —— 不在每个测试文件里各自 monkey-patch
+// `process.stdout`/`process.stderr`/`Date.now`/`setInterval`。
+//
+// 只在测试导入(`from "./testing.ts"`),不进 index.ts 的生产条形码出口。
+
+import type { FeedbackClock, FeedbackIO, FeedbackStream, FeedbackTimerHandle } from "./io.ts";
+
+export interface FakeFeedbackStream extends FeedbackStream {
+  /** 按写入顺序累积的完整历史,供断言「写了几次、写了什么」。 */
+  readonly writes: readonly string[];
+  isTTY: boolean;
+  columns: number;
+  rows: number;
+}
+
+function createFakeStream(overrides: Partial<Pick<FakeFeedbackStream, "isTTY" | "columns" | "rows">> = {}): FakeFeedbackStream {
+  const writes: string[] = [];
+  return {
+    isTTY: overrides.isTTY ?? false,
+    columns: overrides.columns ?? 100,
+    rows: overrides.rows ?? 30,
+    writes,
+    write(text) {
+      writes.push(text);
+    },
+  };
+}
+
+export interface FakeFeedbackIO {
+  readonly io: FeedbackIO;
+  readonly stdout: FakeFeedbackStream;
+  readonly stderr: FakeFeedbackStream;
+  /** 手动推进时钟 ms 毫秒;推进途中到期的 setInterval 回调按到期顺序依次同步触发
+   *  (每次到期都重新入队下一次到期,不会因为一次 advance 跨越多个周期而漏触发)。 */
+  advance(ms: number): void;
+  /** 当前仍在运行(未被 clearInterval)的定时器数量,断言 stopDynamic()/finish() 之后
+   *  没有遗留定时器时用。 */
+  activeTimerCount(): number;
+}
+
+interface FakeTimer {
+  id: number;
+  fn: () => void;
+  intervalMs: number;
+  nextFireAt: number;
+  cleared: boolean;
+}
+
+/** 创建一份完全确定性的假 IO;env 默认空对象(profile.ts 的 CI 检测据此判定「非 CI」)。 */
+export function createFakeFeedbackIO(
+  opts: {
+    stdout?: Partial<Pick<FakeFeedbackStream, "isTTY" | "columns" | "rows">>;
+    stderr?: Partial<Pick<FakeFeedbackStream, "isTTY" | "columns" | "rows">>;
+    env?: Readonly<Record<string, string | undefined>>;
+    startAt?: number;
+  } = {},
+): FakeFeedbackIO {
+  const stdout = createFakeStream(opts.stdout);
+  const stderr = createFakeStream(opts.stderr);
+  let now = opts.startAt ?? 0;
+  let nextId = 1;
+  const timers = new Map<number, FakeTimer>();
+
+  const clock: FeedbackClock = {
+    now: () => now,
+    setInterval: (fn, ms) => {
+      const id = nextId++;
+      timers.set(id, { id, fn, intervalMs: ms, nextFireAt: now + ms, cleared: false });
+      return { id } as unknown as FeedbackTimerHandle;
+    },
+    clearInterval: (handle) => {
+      const id = (handle as unknown as { id: number }).id;
+      const timer = timers.get(id);
+      if (timer) timer.cleared = true;
+      timers.delete(id);
+    },
+  };
+
+  const io: FeedbackIO = { stdout, stderr, env: opts.env ?? {}, clock };
+
+  function advance(ms: number): void {
+    const target = now + ms;
+    // 按到期时间逐个触发,支持一次 advance 跨越同一个定时器的多个周期,也支持多个不同
+    // 定时器交错到期 —— 每次只处理「当前最早到期」的那一个,触发后立即重新计算下一次到期。
+    for (;;) {
+      let earliest: FakeTimer | undefined;
+      for (const timer of timers.values()) {
+        if (timer.cleared) continue;
+        if (timer.nextFireAt > target) continue;
+        if (!earliest || timer.nextFireAt < earliest.nextFireAt) earliest = timer;
+      }
+      if (!earliest) break;
+      now = earliest.nextFireAt;
+      earliest.nextFireAt += earliest.intervalMs;
+      earliest.fn();
+    }
+    now = target;
+  }
+
+  function activeTimerCount(): number {
+    return [...timers.values()].filter((t) => !t.cleared).length;
+  }
+
+  return { io, stdout, stderr, advance, activeTimerCount };
+}