niceeval 0.12.1-canary.25 → 0.12.1

package/src/runner/experiment-cleanup-registry.ts

@@ -0,0 +1,39 @@
+// 实验级 teardown 的宿主机侧登记表 + 强清兜底,与 sandbox/registry.ts 同一模式。
+//
+// 正常路径(per-attempt 计数归零 / run 收尾扫尾)在 runner 的 fiber 里执行 teardown;强清退出
+// (二次 Ctrl+C / 看门狗 / main() 崩溃路径)时 fiber 可能来不及走到那一步,cli 需要一个独立于
+// Effect 的入口把「还没 settle 的实验级 teardown」收口,否则隧道/容器这类宿主机资源随
+// process.exit 变成孤儿(契约见 docs/cli.md「中断:三级响应」)。
+//
+// 登记的闭包由 runner 构造,执行体是 memoized 的一次性 promise(见 run.ts 的
+// runExperimentTeardown):正常路径、drain、崩溃路径谁先到都启动同一个 promise,后到者等到
+// 同一个结果——不双跑、也不空转。条目在 settle 后由闭包自己注销,所以 drain 的完整语义就是
+// 「启动全部未启动 + 等待全部未 settle」;在飞中的 teardown 对 drain 同样可等待,这正是
+// 强清「事件驱动收口」的数据基础。
+
+const pending = new Map<string, () => Promise<void>>();
+
+/** 登记一个实验的 teardown 入口(实验生命周期触发时点调用;setup 尚未完成也已可达)。 */
+export function registerExperimentTeardown(experimentId: string, run: () => Promise<void>): void {
+  pending.set(experimentId, run);
+}
+
+/** teardown settle 后注销;不存在时是 no-op。 */
+export function unregisterExperimentTeardown(experimentId: string): void {
+  pending.delete(experimentId);
+}
+
+export function pendingExperimentTeardownCount(): number {
+  return pending.size;
+}
+
+/**
+ * 强清兜底:启动所有还登记着的实验级 teardown 并等待它们 settle(各执行体自己有界、自己兜错,
+ * 绝不抛;已在飞的返回同一个 memoized promise,等待而非重跑)。返回本次等待的条目数。
+ * 与 stopAllSandboxes 同语义:重复调用安全,表空时是 no-op。
+ */
+export async function drainExperimentTeardowns(): Promise<number> {
+  const entries = [...pending.values()];
+  await Promise.allSettled(entries.map((run) => run()));
+  return entries.length;
+}

package/src/runner/experiment-labels.test.ts

@@ -0,0 +1,100 @@
+// cases: docs/engineering/testing/unit/experiments-runner.md
+// 登记行:ExperimentDef.labels 值域 string | number(解析时校验),原样投影进快照
+// ExperimentRunInfo.labels;不透传 ctx / t,不参与可比性配置。
+
+import { Effect } from "effect";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { defineDirectAgent, defineEval, defineExperiment } from "../define.ts";
+import { experimentRunInfo } from "./attempt.ts";
+import { comparabilityConfigOf, deepEqualJson } from "../sample/index.ts";
+import type { Run } from "../record/types.ts";
+import type { AgentRun } from "./types.ts";
+import { discoverEval } from "./types.ts";
+import { prepareRunSandboxes } from "./sandbox-selection.ts";
+import { completeEvidenceCoverage } from "../assertions/coverage.ts";
+
+const fakeAgent = defineDirectAgent({
+  name: "fake",
+  evidenceCoverage: completeEvidenceCoverage,
+  async send() {
+    return { events: [], status: "completed" };
+  },
+});
+
+const evalDef = discoverEval(defineEval({ test() {} }), {
+  id: "e",
+  baseDir: "/project/evals/e",
+  sourcePath: fileURLToPath(import.meta.url),
+  loaderDataPaths: [],
+  criteriaPaths: [],
+  privatePaths: [],
+  source: { path: "src/runner/experiment-labels.test.ts", content: "", sha256: "0".repeat(64) },
+});
+
+function runWith(labels?: globalThis.Record<string, string | number>): AgentRun {
+  return {
+    agent: fakeAgent,
+    flags: {},
+    attempts: 1,
+    earlyExit: true,
+    selectedEvalIds: ["e"],
+    experimentId: "exp",
+    experimentBaseDir: "/project/experiments",
+    experimentSourcePath: "/project/experiments/exp.ts",
+    ...(labels !== undefined ? { labels } : {}),
+  };
+}
+
+async function runInfo(run: AgentRun) {
+  const [pair] = await Effect.runPromise(prepareRunSandboxes([evalDef], [run]));
+  if (pair === undefined) throw new Error("expected one prepared run pair");
+  return experimentRunInfo(run, pair.plan, { [evalDef.id]: pair.identity });
+}
+
+describe("ExperimentDef.labels", () => {
+  it("值域 string | number:合法值通过,布尔 / 对象在解析时报错", () => {
+    expect(() =>
+      defineExperiment({ agent: fakeAgent, labels: { line: "codex", contextK: 32 } }),
+    ).not.toThrow();
+    expect(() =>
+      defineExperiment({ agent: fakeAgent, labels: { on: true as unknown as string } }),
+    ).toThrow(/labels\.on/);
+    expect(() =>
+      defineExperiment({ agent: fakeAgent, labels: { nested: { a: 1 } as unknown as string } }),
+    ).toThrow(/labels\.nested/);
+    expect(() =>
+      defineExperiment({ agent: fakeAgent, labels: { nan: Number.NaN } }),
+    ).toThrow(/labels\.nan/);
+  });
+
+  it("原样投影进 ExperimentRunInfo.labels;未声明时字段缺省", async () => {
+    const labels = { line: "codex", memory: "mempal" };
+    expect((await runInfo(runWith(labels)))?.labels).toEqual(labels);
+    expect((await runInfo(runWith()))?.labels).toBeUndefined();
+    // 空对象不落盘(与 flags 同一态度:不写空壳字段)
+    expect((await runInfo(runWith({})))?.labels).toBeUndefined();
+  });
+
+  it("不参与可比性配置:仅 labels 不同的两快照仍互相可比", () => {
+    const snapshotWith = (labels?: globalThis.Record<string, string | number>): Run =>
+      ({
+        experimentId: "mem/codex",
+        agent: "codex",
+        model: "gpt-5.4",
+        experiment: {
+          attempts: 1,
+          earlyExit: true,
+          selectedEvalIds: [],
+          flags: { web: true },
+          ...(labels !== undefined ? { labels } : {}),
+        },
+      }) as unknown as Run;
+    const a = comparabilityConfigOf(snapshotWith({ line: "codex" }));
+    const b = comparabilityConfigOf(snapshotWith({ line: "renamed", memory: "mempal" }));
+    const c = comparabilityConfigOf(snapshotWith());
+    expect(deepEqualJson(a, b)).toBe(true);
+    expect(deepEqualJson(a, c)).toBe(true);
+  });
+});

package/src/runner/feedback/coordinator.test.ts

@@ -0,0 +1,367 @@
+// cases: docs/engineering/testing/unit/experiments-runner.md
+// coordinator.ts 的行为测试:全部使用 testing.ts 的假 FeedbackIO,不 monkey-patch 全局
+// process/Date/setInterval —— coordinator 的关闭路径(onRendererError 的兜底)刻意走真实
+// `src/tty-line.ts`(允许保留裸写的「feedback sink 自己」),这里只验证队列在 renderer 抛错
+// 后仍然继续正常处理后续事件,不对那条兜底裸写本身断言,避免整份测试沾上 monkey-patch 依赖。
+//
+// coordinator 内部投递用真实 Promise 微任务队列(SerialQueue),不挂在注入的 fake clock 上 ——
+// 断言前必须 flush() 一次(等一个真实宏任务,保证所有链式微任务都已跑完)。sink.ts 的活跃
+// coordinator 是模块级栈:每个调用 start() 的测试都必须以 finish() 收尾,否则会把自己遗留在
+// 栈里污染后续测试对 reportDiagnostic()/reportActivity() 路由目标的断言 —— afterEach 用
+// activeFeedbackSinkCount() 兜底校验,忘记清理会在下一个测试之前就报错定位到具体哪个测试。
+
+import { afterEach, describe, expect, it } from "vitest";
+import { createFeedbackCoordinator } from "./coordinator.ts";
+import { createFakeFeedbackIO } from "./testing.ts";
+import { activeFeedbackSinkCount, reportActivity, reportDiagnostic } from "./sink.ts";
+import type { FeedbackRenderer } from "./renderer.ts";
+import type {
+  AttemptLifecycleEvent,
+  DurableFeedbackEvent,
+  FeedbackTickEvent,
+  InvocationCompletion,
+  InvocationSummary,
+  RunFeedbackPlan,
+} from "../types.ts";
+
+/** 等一个真实宏任务:保证 SerialQueue 目前为止链上的全部微任务(不管链多深)都已经跑完。 */
+function flush(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+function plan(overrides: Partial<RunFeedbackPlan["shape"]> = {}): RunFeedbackPlan {
+  return {
+    shape: { evals: 1, configs: 1, totalAttempts: 1, maxConcurrency: 1, ...overrides },
+    reused: 0,
+    reusedFailures: [],
+  };
+}
+
+function summary(): InvocationSummary {
+  return {
+    startedAt: "2026-07-13T00:00:00.000Z",
+    completedAt: "2026-07-13T00:00:01.000Z",
+    passed: 1,
+    failed: 0,
+    skipped: 0,
+    errored: 0,
+    durationMs: 1000,
+    results: [],
+  };
+}
+
+function completion(): InvocationCompletion {
+  return { status: "complete", unstarted: 0, earlyExitUnstarted: 0, reporterErrors: [] };
+}
+
+/** 记录每次调用(按发生顺序拼成一条 tag),供断言 clear→append→redraw 的原子顺序。
+ *  可选 throwOn 让某个 durable 事件的 appendDurable 抛错,用来验证队列的容错性。 */
+function recordingRenderer(opts: { throwOn?: (event: DurableFeedbackEvent) => boolean } = {}) {
+  const calls: string[] = [];
+  const renderer: FeedbackRenderer = {
+    clearDynamic() {
+      calls.push("clear");
+    },
+    appendDurable(event: DurableFeedbackEvent) {
+      if (opts.throwOn?.(event)) throw new Error(`boom:${event.type}`);
+      calls.push(`durable:${event.type}`);
+    },
+    redrawDynamic() {
+      calls.push("redraw");
+    },
+    activity(text: string) {
+      calls.push(`activity:${text}`);
+    },
+    onTick(event: FeedbackTickEvent) {
+      calls.push(`tick:${event.elapsedMs}`);
+    },
+    onLifecycle(event: AttemptLifecycleEvent) {
+      calls.push(`lifecycle:${event.type}`);
+    },
+    close() {
+      calls.push("close");
+    },
+  };
+  return { calls, renderer };
+}
+
+afterEach(() => {
+  // 每个 start() 过的 coordinator 都应该在测试内 finish() 掉;这里兜底校验没有测试忘记清理
+  // 而把自己遗留在 sink.ts 的活跃栈里(会静默污染下一个测试对 reportXxx() 路由目标的断言)。
+  expect(activeFeedbackSinkCount()).toBe(0);
+});
+
+describe("createFeedbackCoordinator: durable 事件的 clear→append→redraw 顺序", () => {
+  it("start() 立即以 clear→append(plan)→redraw 的顺序调用 renderer,并更新 state", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "human", renderer, io });
+    coordinator.start(plan({ totalAttempts: 5 }));
+    await flush();
+    expect(calls).toEqual(["clear", "durable:plan", "redraw"]);
+    expect(coordinator.state).toMatchObject({ total: 5, queued: 5 });
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+
+  it("diagnostic() 按 emit() 的原子顺序处理,即便 renderer 方法是异步的也不交错", async () => {
+    const { io } = createFakeFeedbackIO();
+    const calls: string[] = [];
+    const renderer: FeedbackRenderer = {
+      async clearDynamic() {
+        await Promise.resolve();
+        calls.push("clear");
+      },
+      async appendDurable(event) {
+        await Promise.resolve();
+        calls.push(`durable:${event.type}`);
+      },
+      async redrawDynamic() {
+        await Promise.resolve();
+        calls.push("redraw");
+      },
+    };
+    const coordinator = createFeedbackCoordinator({ profile: "human", renderer, io });
+    coordinator.start(plan());
+    coordinator.diagnostic({ key: "a", severity: "warning", message: "first" });
+    coordinator.diagnostic({ key: "b", severity: "warning", message: "second" });
+    await coordinator.stopDynamic();
+    expect(calls).toEqual([
+      "clear",
+      "durable:plan",
+      "redraw",
+      "clear",
+      "durable:diagnostic",
+      "redraw",
+      "clear",
+      "durable:diagnostic",
+      "redraw",
+      "clear", // stopDynamic() 收尾的无条件再清一次
+    ]);
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+
+  it("同一 key 的 diagnostic 去重进 state,但仍逐次转发给 renderer(是否折叠展示由 renderer 决定)", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "json", renderer, io });
+    coordinator.start(plan());
+    coordinator.diagnostic({ key: "memory-warmup-degraded", severity: "warning", message: "cold index (1)" });
+    coordinator.diagnostic({ key: "memory-warmup-degraded", severity: "warning", message: "cold index (2)" });
+    coordinator.diagnostic({ key: "memory-warmup-degraded", severity: "warning", message: "cold index (3)" });
+    await flush();
+    expect(coordinator.state.diagnostics).toHaveLength(1);
+    expect(coordinator.state.diagnostics[0]).toMatchObject({ key: "memory-warmup-degraded", count: 3 });
+    expect(calls.filter((c) => c === "durable:diagnostic")).toHaveLength(3);
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+
+  it("activity() 不进入 state.diagnostics/failures,但同样走 clear→activity→redraw", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "human", renderer, io });
+    coordinator.start(plan());
+    coordinator.activity("pulling docker image node:24-slim...");
+    await flush();
+    expect(coordinator.state.diagnostics).toEqual([]);
+    expect(coordinator.state.failures).toEqual([]);
+    expect(calls.slice(-3)).toEqual(["clear", "activity:pulling docker image node:24-slim...", "redraw"]);
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+
+  it("renderer 在某个 durable 事件上抛错不会中断队列,后续事件照常按完整顺序处理", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer({ throwOn: (e) => e.type === "diagnostic" });
+    const coordinator = createFeedbackCoordinator({ profile: "human", renderer, io });
+    coordinator.start(plan());
+    coordinator.diagnostic({ key: "boom", severity: "warning", message: "x" });
+    coordinator.interrupted();
+    await coordinator.stopDynamic();
+    // plan 正常;diagnostic 那次 clear 之后抛错(所以没有 "durable:diagnostic"、没有紧跟的
+    // "redraw"),但下一个事件(interrupted)仍然拿到完整的 clear→append→redraw。
+    expect(calls).toEqual([
+      "clear",
+      "durable:plan",
+      "redraw",
+      "clear",
+      "clear",
+      "durable:interrupted",
+      "redraw",
+      "clear",
+    ]);
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+});
+
+// cases: docs/engineering/testing/unit/experiments-runner.md
+// 分区「live 面板的键盘接管与自愈重绘」:`forceRedraw()` 是 input-guard.ts 收到回车/SIGWINCH
+// 时的唯一入口,契约见 docs/feature/experiments/cli.md「键盘输入与画面自愈」。
+describe("createFeedbackCoordinator: forceRedraw()(键盘/终端自愈重绘)", () => {
+  it("经内部串行队列执行 clear→redraw,与正常 durable 事件的三步共用同一条队列(不交错)", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "human", renderer, io });
+    coordinator.start(plan());
+    coordinator.forceRedraw();
+    await flush();
+    expect(calls).toEqual(["clear", "durable:plan", "redraw", "clear", "redraw"]);
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+
+  it("即便状态自上一帧起没有变化,也真的调用 clear→redraw——不会被 renderer 自己的「同帧不写」判断吞掉", async () => {
+    // 区分力:forceRedraw() 与普通 durable 事件的关键差别正是"状态没变也要重画"。这里用
+    // recordingRenderer 断言 coordinator 侧确实每次都转发了 clear/redraw 调用;renderer 自己
+    // 是否真的重写字节(如 human.ts 靠 clearDynamic 清空 lastFrameText 绕过判断)由 human.test.ts
+    // 覆盖,这里只证明 coordinator 不会因为"看起来没有新状态"就跳过转发。
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "human", renderer, io });
+    coordinator.start(plan());
+    await flush();
+    calls.length = 0;
+    coordinator.forceRedraw();
+    coordinator.forceRedraw();
+    await flush();
+    expect(calls).toEqual(["clear", "redraw", "clear", "redraw"]);
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+
+  it("dynamicStopped/finished 阶段调用是安全的 no-op(结束路径的迟到按键不再触发重绘)", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "human", renderer, io });
+    coordinator.start(plan());
+    await coordinator.stopDynamic();
+    calls.length = 0;
+    coordinator.forceRedraw();
+    await flush();
+    expect(calls).toEqual([]);
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+    calls.length = 0;
+    coordinator.forceRedraw();
+    await flush();
+    expect(calls).toEqual([]);
+  });
+});
+
+describe("createFeedbackCoordinator: tick 与 heartbeat 节奏", () => {
+  it("tick 定时器按注入的 clock 周期性触发,elapsedMs 相对 start() 时刻计算", async () => {
+    const fake = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "json", renderer, io: fake.io, tickIntervalMs: 100 });
+    coordinator.start(plan());
+    fake.advance(350);
+    await flush();
+    const ticks = calls.filter((c) => c.startsWith("tick:"));
+    expect(ticks).toEqual(["tick:100", "tick:200", "tick:300"]);
+    expect(coordinator.state.elapsedMs).toBe(300);
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+
+  it("stopDynamic() 之后不再有 tick 触发(定时器已清)", async () => {
+    const fake = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "json", renderer, io: fake.io, tickIntervalMs: 100 });
+    coordinator.start(plan());
+    fake.advance(150);
+    await coordinator.stopDynamic();
+    expect(fake.activeTimerCount()).toBe(0);
+    const ticksBefore = calls.filter((c) => c.startsWith("tick:")).length;
+    fake.advance(1000); // 就算时钟继续走,也不会再触发(定时器已被 clearInterval)
+    const ticksAfter = calls.filter((c) => c.startsWith("tick:")).length;
+    expect(ticksAfter).toBe(ticksBefore);
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+});
+
+describe("createFeedbackCoordinator: 关闭顺序", () => {
+  it("stopDynamic() 之后,diagnostic()/activity() 仍会 append,但不再 clear/redraw", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "human", renderer, io });
+    coordinator.start(plan());
+    await coordinator.stopDynamic();
+    calls.length = 0; // 只看 stopDynamic 之后的行为(此时已经排空过一次队列,重置是安全的)
+    coordinator.diagnostic({ key: "late", severity: "warning", message: "reporter 收尾期间的诊断" });
+    coordinator.activity("late activity");
+    await flush();
+    expect(calls).toEqual(["durable:diagnostic", "activity:late activity"]);
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+
+  it("finish() 追加 summary/saved、调用 renderer.close(),之后不再接受任何输出", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "json", renderer, io });
+    coordinator.start(plan());
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [".niceeval/ci/2026"] });
+    expect(calls).toContain("durable:summary");
+    expect(calls).toContain("durable:saved");
+    expect(calls[calls.length - 1]).toBe("close");
+
+    const before = calls.length;
+    coordinator.diagnostic({ key: "after-finish", severity: "warning", message: "should be dropped" });
+    coordinator.activity("also dropped");
+    await flush();
+    expect(calls.length).toBe(before); // finish() 之后完全不再调用 renderer
+  });
+
+  it("finish() 内部会先跑 stopDynamic(顺序:停 tick → 清 dashboard → summary/saved → close)", async () => {
+    const fake = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "human", renderer, io: fake.io, tickIntervalMs: 50 });
+    coordinator.start(plan());
+    await flush(); // 让 plan 的 clear→append→redraw 先跑完,再清空追踪数组只看收尾阶段
+    calls.length = 0;
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+    // 第一个 "clear" 来自 stopDynamic() 收尾清空;finish() 时 phase 已经是 dynamicStopped,
+    // summary/saved 因此只 append、不再 clear/redraw。
+    expect(calls).toEqual(["clear", "durable:summary", "durable:saved", "close"]);
+    expect(fake.activeTimerCount()).toBe(0);
+  });
+
+  it("start() 重复调用抛错;stopDynamic()/diagnostic() 在 start() 之前调用抛错", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "human", renderer, io });
+    expect(() => coordinator.diagnostic({ key: "x", severity: "warning", message: "x" })).toThrow();
+    await expect(coordinator.stopDynamic()).rejects.toThrow();
+    coordinator.start(plan());
+    expect(() => coordinator.start(plan())).toThrow();
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+  });
+});
+
+describe("sink.ts 集成:reportDiagnostic()/reportActivity() 只在 coordinator 活跃期间转发给它", () => {
+  it("start() 之前调用落回 bootstrap,不触碰这个 coordinator 的 renderer", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "json", renderer, io });
+    reportDiagnostic({ key: "before-start", severity: "warning", message: "x" });
+    reportActivity("before-start activity");
+    expect(calls).toEqual([]);
+    // 清理:即便这个 coordinator 从未真正 start(),afterEach 只校验活跃栈计数,不要求
+    // 每个测试局部变量都必须走完整生命周期 —— 这里不 start() 就不需要 finish()。
+    void coordinator;
+  });
+
+  it("start() 之后,sink.ts 的便捷函数转发给活跃 coordinator;finish() 之后落回 bootstrap", async () => {
+    const { io } = createFakeFeedbackIO();
+    const { calls, renderer } = recordingRenderer();
+    const coordinator = createFeedbackCoordinator({ profile: "json", renderer, io });
+    coordinator.start(plan());
+    expect(activeFeedbackSinkCount()).toBe(1);
+    await flush();
+    calls.length = 0;
+    reportDiagnostic({ key: "via-sink", severity: "warning", message: "routed" });
+    reportActivity("also routed");
+    await flush();
+    expect(calls).toEqual(["clear", "durable:diagnostic", "redraw", "clear", "activity:also routed", "redraw"]);
+
+    await coordinator.finish({ summary: summary(), completion: completion(), paths: [] });
+    expect(activeFeedbackSinkCount()).toBe(0); // finish() 摘掉自己,不遗留在活跃栈里
+
+    calls.length = 0;
+    reportDiagnostic({ key: "after-finish", severity: "warning", message: "not routed" });
+    expect(calls).toEqual([]); // 落回 bootstrap,不再触碰这个已经 finish 的 coordinator
+  });
+});