niceeval 0.6.0 → 0.6.2

package/src/show/show.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
 // niceeval show 终端宿主的测试(行为规范:docs-site/zh/guides/viewing-results.mdx;
 // 组合语义:docs/feature/reports/architecture.md「Selection 是计算入口」)。覆盖:
 // - 榜单合成口径:每 experiment × eval 取最新判定,局部重跑从更早快照补齐,头部标注合成自几个快照;
@@ -17,7 +18,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
 import { openResults } from "../results/index.ts";
-import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type Verdict } from "../types.ts";
+import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type TimingNode, type TraceSpan, type Verdict } from "../types.ts";
 import { selectCurrentResults } from "../results/select.ts";
 import { evalHistory } from "./compose.ts";
 import { runShow, type ShowFlags } from "./index.ts";
@@ -52,7 +53,7 @@ type AttemptFixture = Pick<EvalResult, "id" | "verdict"> &
   Partial<
     Pick<
       EvalResult,
-      "attempt" | "durationMs" | "assertions" | "estimatedCostUSD" | "usage" | "error" | "startedAt" | "artifactBase" | "hasEvents" | "hasTrace"
+      "attempt" | "durationMs" | "assertions" | "estimatedCostUSD" | "usage" | "error" | "diagnostics" | "startedAt" | "artifactBase" | "hasEvents" | "hasTrace" | "phases"
     >
   >;
 
@@ -135,7 +136,7 @@ async function seedComposedRoot(): Promise<string> {
           name: 'fileChanged("src/components/Button.tsx")',
           severity: "gate",
           score: 0,
-          passed: false,
+          outcome: "failed" as const,
           detail: "file was not modified",
         },
       ],
@@ -146,34 +147,31 @@ async function seedComposedRoot(): Promise<string> {
 
 // ───────────────────────── 榜单合成口径 ─────────────────────────
 
-describe("榜单:跨快照合成的现刻水位(show 专用 attempt 表)", () => {
-  it("局部重跑不撕榜单:另一题从更早快照补齐,单实验不出现比较空态", async () => {
+describe("默认报告:跨快照合成的现刻水位(ExperimentComparison text 面)", () => {
+  it("局部重跑不撕报告:另一题从更早快照补齐,缺成本时散点明确空态", async () => {
     const root = await seedComposedRoot();
     const { out, code } = await show(root, []);
     expect(code).toBe(0);
-    expect(out).not.toContain("No data to plot");
-    expect(out).not.toContain("At least 2 experiments");
+    expect(out).toContain("No data to plot Cost × End-to-end pass rate");
+    expect(out).toContain("1 point missing data");
+    expect(out).not.toContain("needed to compare");
     expect(out).not.toContain("COMPARISON");
-    expect(out).toContain("EXPERIMENT  compare/bub · bub");
-    expect(out).toContain("SUMMARY     1 passed · 1 failed · 0 errored · 0 skipped · 2 attempts");
-    expect(out).toMatch(/STATUS\s+EVAL\s+ATTEMPT\s+RESULT\s+DURATION\s+COST/);
-    expect(out).toMatch(/✗ failed\s+fixtures\/button\s+@1[0-9a-z]{7}\s+file was not modified/);
-    expect(out).toMatch(/✓ passed\s+weather\/brooklyn\s+@1[0-9a-z]{7}\s+—/);
-    expect(out).not.toMatch(/@1[0-9a-z]{7}[✓✗]/);
-    expect(out).not.toContain("[E,X,");
-    expect(out).toContain("DRILL DOWN  niceeval show @<attempt>");
+    expect(out).toMatch(/\bbub\s+default\s+bub\s+1s\s+50%/);
+    expect(out).toMatch(/1 passed[\s\S]*?\/ 1\s+failed/);
+    expect(out).toMatch(/✗ failed\s+fixtures\/button[\s\S]*└─ @1[0-9a-z]{7}[\s\S]*fileChanged/);
+    expect(out).toMatch(/✓ passed\s+weather\/brooklyn[\s\S]*└─ @1[0-9a-z]{7}/);
+    expect(out).not.toMatch(/\[[EXD⏱,]+\]/);
   });
 
-  it("裸 show 使用稳定表头,不受自定义报告 locale chrome 影响", async () => {
+  it("裸 show 的默认报告 chrome 跟随 locale", async () => {
     const root = await seedComposedRoot();
     process.env.NICEEVAL_LANG = "zh-CN";
     try {
       const { out, code } = await show(root, []);
       expect(code).toBe(0);
-      expect(out).toMatch(/STATUS\s+EVAL\s+ATTEMPT\s+RESULT\s+DURATION\s+COST/);
-      expect(out).toContain("1 passed · 1 failed");
-      expect(out).not.toContain("没有可绘制的数据");
-      expect(out).toContain("compare/bub");
+      expect(out).toContain("预估成本 × 端到端成功率 没有可绘制的数据");
+      expect(out).toContain("1 通过 / 1 失败");
+      expect(out).toMatch(/\bbub\s+默认\s+bub\s+1s\s+50%/);
     } finally {
       process.env.NICEEVAL_LANG = "en";
     }
@@ -183,13 +181,13 @@ describe("榜单:跨快照合成的现刻水位(show 专用 attempt 表)", () =>
     const root = await seedComposedRoot();
     const { out, code } = await show(root, [], {}, 60);
     expect(code).toBe(0);
-    expect(out).toContain("…");
+    expect(out).toContain("fixtures/button");
     for (const line of out.trimEnd().split("\n")) {
       expect(stringWidth(line), line).toBeLessThanOrEqual(60);
     }
   });
 
-  it("多个 experiment 先显示紧凑比较表,再逐 experiment 显示 attempt 表", async () => {
+  it("多个 experiment 显示散点图,再逐 experiment → Eval → Attempt", async () => {
     const root = await makeRoot();
     await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/a", agent: "codex", model: "mini", startedAt: "2026-07-08T10:00:00.000Z" }, [
       res("q1", "passed", { estimatedCostUSD: 0.1 }),
@@ -201,11 +199,13 @@ describe("榜单:跨快照合成的现刻水位(show 专用 attempt 表)", () =>
     ]);
     const { out, code } = await show(root, []);
     expect(code).toBe(0);
-    expect(out).toMatch(/COMPARISON\nEXPERIMENT\s+AGENT\s+MODEL\s+PASS\s+FAILED\s+ERROR\s+SKIP\s+DURATION\s+COST/);
-    expect(out).toContain("50% 1/2");
-    expect(out).toContain("100% 2/2");
-    expect(out.match(/^EXPERIMENT  compare\//gm)).toHaveLength(2);
-    expect(out).not.toContain("At least 2 experiments");
+    expect(out).toContain("better → upper right");
+    expect(out).toContain("A compare/a   B compare/b");
+    expect(out).toMatch(/\bb\s+large\s+claude\s+1s\s+100%/);
+    expect(out).toMatch(/\ba\s+mini\s+codex\s+1s\s+50%/);
+    expect(out).toMatch(/✓ passed\s+q1[\s\S]*└─ @1[0-9a-z]{7}/);
+    expect(out).toMatch(/✗ failed\s+q2[\s\S]*└─ @1[0-9a-z]{7}/);
+    expect(out).not.toContain("needed to compare");
   });
 
   it("合成 Selection:每 experiment × eval 取最新判定;compose 不产生残缺警告", async () => {
@@ -281,15 +281,15 @@ describe("单 eval 详情", () => {
               name: 'calledTool("get_weather")',
               severity: "gate",
               score: 0,
-              passed: false,
+              outcome: "failed" as const,
               detail: "tool was never called",
             },
-            { name: "succeeded()", severity: "gate", score: 1, passed: true },
+            { name: "succeeded()", severity: "gate", score: 1, outcome: "passed" as const },
             {
               name: 'judge("回答基于实时数据")',
               severity: "soft",
               score: 0.2,
-              passed: false,
+              outcome: "failed" as const,
               detail: "reply invents a temperature without any tool call",
             },
           ],
@@ -342,7 +342,7 @@ describe("--history 时间轴", () => {
         res("weather/brooklyn", "failed", {
           attempt: 1,
           estimatedCostUSD: 0.04,
-          assertions: [{ name: 'calledTool("get_weather")', severity: "gate", score: 0, passed: false }],
+          assertions: [{ name: 'calledTool("get_weather")', severity: "gate", score: 0, outcome: "failed" as const }],
         }),
       ],
     );
@@ -550,7 +550,7 @@ describe("--eval", () => {
       root,
       "2026-07-08T10-00-00-000Z",
       { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" },
-      [res("weather/brooklyn", "failed", { assertions: [{ name: "succeeded()", severity: "gate", score: 0, passed: false }] })],
+      [res("weather/brooklyn", "failed", { assertions: [{ name: "succeeded()", severity: "gate", score: 0, outcome: "failed" as const }] })],
     );
     const { out, code } = await show(root, ["weather/brooklyn"], { eval: true });
     expect(code).toBe(0);
@@ -570,11 +570,11 @@ describe("--eval", () => {
               name: 'calledTool("get_weather")',
               severity: "gate",
               score: 0,
-              passed: false,
+              outcome: "failed" as const,
               detail: "tool was never called",
               loc: { file: "evals/weather/brooklyn.eval.ts", line: 2 },
             },
-            { name: "unlocated()", severity: "soft", score: 0.5, passed: false, detail: "no loc on this one" },
+            { name: "unlocated()", severity: "soft", score: 0.5, outcome: "failed" as const, detail: "no loc on this one" },
           ],
         }),
       ],
@@ -600,7 +600,7 @@ describe("--eval", () => {
   it("源码行标注保留 group 与值断言的 expected/received", async () => {
     const root = await makeRoot();
     const dir = await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
-      res("manager", "failed", { assertions: [{ name: "equals(4)", severity: "gate", score: 0, passed: false, evidence: "1", group: "Issue 15193", loc: { file: "evals/manager.eval.ts", line: 1 } }] }),
+      res("manager", "failed", { assertions: [{ name: "equals(4)", severity: "gate", score: 0, outcome: "failed" as const, expected: "4", received: "1", groupPath: ["Issue 15193"], loc: { file: "evals/manager.eval.ts", line: 1 } }] }),
     ]);
     const attemptDir = join(dir, "manager/a0");
     const content = "t.check(actual, equals(expected));\n";
@@ -619,7 +619,7 @@ describe("show @<locator>", () => {
   it("默认页直接解释失败断言的 group、期望值、实际值和源码位置", async () => {
     const root = await makeRoot();
     await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
-      res("manager", "failed", { assertions: [{ name: "equals(4)", severity: "gate", score: 0, passed: false, evidence: "1", group: "Issue 15193", loc: { file: "evals/manager.eval.ts", line: 40, column: 11 } }] }),
+      res("manager", "failed", { assertions: [{ name: "equals(4)", severity: "gate", score: 0, outcome: "failed" as const, expected: "4", received: "1", groupPath: ["Issue 15193"], loc: { file: "evals/manager.eval.ts", line: 40, column: 11 } }] }),
     ]);
     const results = await openResults(root);
     const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
@@ -650,6 +650,41 @@ describe("show @<locator>", () => {
     expect(out).not.toContain("available:");
   });
 
+  it("errored attempt 首页展开结构化 error(phase/code/message/cause)与 diagnostics", async () => {
+    const root = await makeRoot();
+    await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/claude-e2b", startedAt: "2026-07-08T10:00:00.000Z" }, [
+      res("agent-029", "errored", {
+        error: {
+          code: "sandbox-rate-limit",
+          message: "E2B sandbox allocation failed after 5 attempts",
+          phase: "sandbox.create",
+          cause: { name: "RateLimitError", message: "too many concurrent sandboxes" },
+        },
+        diagnostics: [
+          { code: "teardown-failed", level: "warning", message: "container stop timed out", phase: "sandbox.teardown" },
+        ],
+      }),
+    ]);
+    const results = await openResults(root);
+    const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
+
+    const { out, code } = await show(root, [locator]);
+    expect(code).toBe(0);
+    expect(out).toContain(`${locator} · agent-029 · compare/claude-e2b · errored`);
+    // 结构化 error 块:phase 直接展示闭集点分名,code/message/cause 各一行(见 docs/feature/reports/show.md)
+    expect(out).toContain("error:");
+    expect(out).toContain("phase: sandbox.create");
+    expect(out).toContain("code: sandbox-rate-limit");
+    expect(out).toContain("message: E2B sandbox allocation failed after 5 attempts");
+    expect(out).toContain("cause: RateLimitError · too many concurrent sandboxes");
+    // attempt 级 diagnostics 块(与 verdict 独立)
+    expect(out).toContain("diagnostics:");
+    expect(out).toContain("warning · sandbox.teardown · teardown-failed");
+    expect(out).toContain("container stop timed out");
+    // errored 且无断言:不打印空的 assertions 汇总行
+    expect(out).not.toContain("assertions:");
+  });
+
   it("available 只逐行列出实际存在的证据命令,不打印能力字母或合并式 next", async () => {
     const root = await makeRoot();
     const dir = await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
@@ -689,6 +724,186 @@ describe("show @<locator>", () => {
     expect(out).not.toContain("available:");
   });
 
+  it("单独 --timing 进入完整时间树,不回落到 attempt 首页", async () => {
+    const root = await makeRoot();
+    await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
+      res("weather/brooklyn", "passed", {
+        durationMs: 50_000,
+        phases: [
+          { name: "eval.run", durationMs: 42_000 },
+          { name: "sandbox.stop", durationMs: 800 },
+        ],
+      }),
+    ]);
+    const results = await openResults(root);
+    const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
+
+    const { out, code } = await show(root, [locator], { timing: true });
+    expect(code).toBe(0);
+    expect(out).toContain("total 50.0s");
+    expect(out).toContain("eval.run              42.0s");
+    expect(out).toContain("teardown (not counted in total):");
+    expect(out).toContain("sandbox.stop          800ms");
+    expect(out).not.toContain("assertions:");
+    expect(out).not.toContain("available:");
+  });
+
+  it("--timing 在 80 个 detail node 内与 full 等价，81 个开始原位省略", async () => {
+    const root = await makeRoot();
+    const children: TimingNode[] = Array.from({ length: 81 }, (_, index) => ({
+      id: `command-${String(index).padStart(3, "0")}`,
+      kind: "command",
+      label: "tool",
+      startOffsetMs: index * 10,
+      durationMs: 81 - index,
+      command: { display: `tool --item=${index}` },
+    }));
+    await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
+      res("weather/brooklyn", "passed", {
+        durationMs: 50_000,
+        phases: [
+          { name: "sandbox.create", durationMs: 1_000 },
+          { name: "eval.run", durationMs: 42_000, children },
+          { name: "sandbox.stop", durationMs: 800 },
+        ],
+      }),
+    ]);
+    const results = await openResults(root);
+    const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
+
+    const bounded = await show(root, [locator], { timing: "summary" });
+    const full = await show(root, [locator], { timing: "full" });
+    expect(bounded.out).toContain("sandbox.create");
+    expect(bounded.out).toContain("eval.run");
+    expect(bounded.out).toContain("sandbox.stop");
+    expect(bounded.out).toMatch(/… 1 nodes omitted/);
+    expect(bounded.out).toContain(`niceeval show ${locator} --timing=full`);
+    expect(full.out).not.toContain("nodes omitted");
+    expect(full.out).toContain("tool --item=0");
+    expect(full.out).toContain("tool --item=80");
+
+    // 去掉第 81 个后，默认投影不再省略，detail 行与 full 完全一致。
+    children.pop();
+    const root80 = await makeRoot();
+    await writeSnapshot(root80, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
+      res("weather/brooklyn", "passed", {
+        durationMs: 50_000,
+        phases: [{ name: "eval.run", durationMs: 42_000, children }],
+      }),
+    ]);
+    const results80 = await openResults(root80);
+    const locator80 = results80.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
+    const bounded80 = await show(root80, [locator80], { timing: "summary" });
+    const full80 = await show(root80, [locator80], { timing: "full" });
+    expect(bounded80.out).toBe(full80.out);
+  });
+
+  it("默认投影保留失败路径/慢点/首尾，omission 报失败数且不虚构 children 合计", async () => {
+    const root = await makeRoot();
+    const children: TimingNode[] = Array.from({ length: 120 }, (_, index) => ({
+      id: `node-${String(index).padStart(3, "0")}`,
+      kind: "provider",
+      label: `provider-step-${index}`,
+      startOffsetMs: index * 100,
+      durationMs: index === 60 ? 99_000 : index + 1,
+      ...(index === 55 ? { failed: true as const } : {}),
+    }));
+    await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
+      res("weather/brooklyn", "errored", {
+        durationMs: 120_000,
+        error: { code: "provider-failed", message: "boom", phase: "sandbox.create" },
+        phases: [{ name: "sandbox.create", durationMs: 120_000, failed: true, children }],
+      }),
+    ]);
+    const results = await openResults(root);
+    const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
+    const { out } = await show(root, [locator], { timing: "summary" });
+
+    expect(out).toContain("provider-step-0");
+    expect(out).toContain("provider-step-55");
+    expect(out).toContain("provider-step-60");
+    expect(out).toContain("provider-step-119");
+    expect(out).not.toContain("combined");
+  });
+
+  it("operation 使用 producer label；full 按 parentSpanId 展开唯一关联 OTel 树", async () => {
+    const root = await makeRoot();
+    const dir = await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
+      res("weather/brooklyn", "passed", {
+        durationMs: 50_000,
+        hasTrace: true,
+        phases: [{
+          name: "workspace.diff",
+          durationMs: 5_000,
+          children: [{
+            id: "operation-1",
+            kind: "operation",
+            label: "export workspace diff · 1 window · 3,302 files",
+            startOffsetMs: 100,
+            durationMs: 4_000,
+            children: [{
+              id: "turn-1",
+              kind: "turn",
+              label: "s1/t1",
+              startOffsetMs: 200,
+              durationMs: 3_000,
+              traceId: "trace-1",
+            }],
+          }],
+        }],
+      }),
+    ]);
+    const trace: TraceSpan[] = [
+      { traceId: "trace-1", spanId: "child", parentSpanId: "root", name: "chat", kind: "model", startMs: 1_100, endMs: 2_000 },
+      { traceId: "trace-1", spanId: "root", name: "codex.exec", kind: "agent", startMs: 1_000, endMs: 3_000 },
+    ];
+    await writeFile(join(dir, "weather/brooklyn/a0/trace.json"), JSON.stringify(trace), "utf-8");
+    const results = await openResults(root);
+    const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
+    const { out } = await show(root, [locator], { timing: "full" });
+
+    expect(out).toContain("operation · export workspace diff · 1 window · 3,302 files");
+    expect(out).toMatch(/agent · codex\.exec[\s\S]*model · chat/);
+    expect(out).not.toContain("git show ×");
+  });
+
+  it("attempt 首页 timing 只列大头,但保留变慢的 telemetry 阶段", async () => {
+    const root = await makeRoot();
+    const dir = await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [
+      res("weather/brooklyn", "passed", {
+        durationMs: 100_000,
+        hasEvents: true,
+        phases: [
+          { name: "sandbox.queue", durationMs: 0 },
+          { name: "sandbox.create", durationMs: 3_000 },
+          { name: "workspace.baseline", durationMs: 310 },
+          { name: "telemetry.configure", durationMs: 358 },
+          { name: "eval.run", durationMs: 45_000 },
+          { name: "telemetry.collect", durationMs: 35_300 },
+          { name: "sandbox.stop", durationMs: 8_500 },
+        ],
+      }),
+    ]);
+    await writeFile(
+      join(dir, "weather/brooklyn/a0/events.json"),
+      JSON.stringify([{ type: "message", role: "assistant", text: "done" }]),
+      "utf-8",
+    );
+    const results = await openResults(root);
+    const locator = results.experiments[0]!.latest.evals[0]!.attempts[0]!.locator!;
+
+    const { out } = await show(root, [locator]);
+    const timingLine = out.split("\n").find((line) => line.startsWith("timing:"));
+    expect(out).toContain("1 AI message");
+    expect(timingLine).toContain("sandbox.queue 0ms");
+    expect(timingLine).toContain("sandbox.create 3.0s");
+    expect(timingLine).toContain("eval.run 45.0s");
+    expect(timingLine).toContain("telemetry.collect 35.3s");
+    expect(timingLine).toContain("teardown +8.5s");
+    expect(timingLine).not.toContain("workspace.baseline");
+    expect(timingLine).not.toContain("telemetry.configure");
+  });
+
   it("语法不对的 locator 报「not a valid attempt locator」,退出码 1,不崩", async () => {
     const root = await makeRoot();
     await writeSnapshot(root, "2026-07-08T10-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-08T10:00:00.000Z" }, [

package/src/tty-line.ts

@@ -1,32 +1,14 @@
-// 独立诊断行的统一终端出口。
+// 独立诊断行的 bootstrap 终端出口:只服务 run 启动前的 argv/config 错误,以及崩溃兜底/
+// 尚无活跃 coordinator 时的兜底(见 src/runner/feedback/sink.ts 的 no-active-coordinator 分支)。
 //
-// live 表格(src/runner/reporters/live.ts)重画靠 \x1B[{drawnLines}A 回跳到上一帧起点,
-// 这个回跳量的前提是"stderr/stdout 这块屏幕在两帧之间只有它自己在写"。sandbox teardown
-// 失败、budget 不可执行、reporter 抛错这类跟 attempt 进度无关的独立诊断行,如果在 live
-// 表格激活期间直接 process.stderr.write / console.log,就会插进两次 draw() 之间——下一帧
-// 按旧的 drawnLines 回跳,已经够不到表格真正的起点,清行重画变成往下多写一份,且这个偏移
-// 被记进新的 drawnLines,此后每帧都在错位的基础上继续错位,越滚越多(见
-// memory/live-raw-stderr-write-desyncs-redraw.md)。
-//
-// 所以任何不经过 Reporter.progress() / onEvalComplete() 的独立诊断行,写之前都要先广播
-// beforeExternalTerminalWrite(),live.ts 借此机会把已画内容清掉、drawnLines 归零,下一次
-// draw() 就会把这行诊断消息之下当成全新起点重画,不会累积。
-
-const listeners = new Set<() => void>();
-
-/** live.ts 用来订阅"即将有一行独立诊断消息落地"。返回取消订阅函数。 */
-export function onBeforeExternalTerminalWrite(fn: () => void): () => void {
-  listeners.add(fn);
-  return () => listeners.delete(fn);
-}
-
-/** 任何要绕开 Reporter 直接往终端打一行独立诊断消息的地方,写之前都先调用这个。 */
-export function beforeExternalTerminalWrite(): void {
-  for (const fn of listeners) fn();
-}
+// run 激活之后的全部反馈(dashboard、durable event、heartbeat)由
+// src/runner/feedback/coordinator.ts 统一排序;它通过 sink.ts 的模块级 coordinator 栈直接接管
+// reportXxx() 调用的目的地(显式路由,不是广播-订阅),所以这里不再需要"写之前先广播、订阅方
+// 自己清屏"的机制——那套机制是为已删除的 live.ts 的 ANSI 回跳重画设计的(见
+// memory/live-raw-stderr-write-desyncs-redraw.md),新 coordinator 的 clear → append → redraw
+// 顺序由 sink.ts 的显式路由保证,不依赖本文件。
 
 /** process.stderr.write 的替代:文本需自带换行(沿用现有 i18n 字符串的约定)。 */
 export function writeStderrLine(text: string): void {
-  beforeExternalTerminalWrite();
   process.stderr.write(text);
 }

package/src/util.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/scoring/cases.md
 import { describe, expect, it } from "vitest";
 import { brief, formatThrown, upsertManagedBlock } from "./util.ts";
 

package/src/util.ts

@@ -32,6 +32,47 @@ export function formatThrown(e: unknown): string {
   return String(e);
 }
 
+/**
+ * 截到第一个换行为止。`formatThrown()` 优先带完整 `.stack`(含本地绝对文件路径的多行调用栈)
+ * 给需要按 file:line 定位问题的落盘产物(`EvalResult.error`、`niceeval show`);但机器消费的
+ * 单行 envelope(`FailureNotice.reason`、reporter 失败诊断的 `message`……)只要「一层可行动摘要」
+ * ——`Error.stack` 的第一行恒为 `name: message`,不含栈帧,直接满足这个要求。完整栈仍然原样
+ * 留在调用方各自的落盘字段里,这个函数只负责第二次、更短的那份表达,不是唯一出口。
+ */
+export function firstLine(text: string): string {
+  const idx = text.indexOf("\n");
+  return idx === -1 ? text : text.slice(0, idx);
+}
+
+/**
+ * 把 catch 到的 e 拆成 `AttemptError` 的三段:`message`(一层原因,Error.message,不带 name 前缀、
+ * 不拼 stack)、`stack`(完整多行栈,供 `niceeval show` 展开)、`cause`(沿 `e.cause` 取一层结构化
+ * 摘要 `{ name?, code?, message }`)。Node 的 `Error.stack` 不展开 cause 链,所以 cause 只能从
+ * `e.cause` 单独取。非 Error 值只给 message。
+ */
+export function describeError(e: unknown): {
+  message: string;
+  stack?: string;
+  cause?: { name?: string; code?: string; message: string };
+} {
+  if (!(e instanceof Error)) return { message: String(e) };
+  const out: { message: string; stack?: string; cause?: { name?: string; code?: string; message: string } } = {
+    message: e.message || e.name,
+  };
+  if (e.stack) out.stack = e.stack;
+  const raw = (e as { cause?: unknown }).cause;
+  if (raw instanceof Error) {
+    const c: { name?: string; code?: string; message: string } = { message: raw.message || raw.name };
+    if (raw.name) c.name = raw.name;
+    const code = (raw as { code?: unknown }).code;
+    if (typeof code === "string") c.code = code;
+    out.cause = c;
+  } else if (typeof raw === "string" && raw.trim() !== "") {
+    out.cause = { message: raw };
+  }
+  return out;
+}
+
 /** 零填充到 4 位(数据集扇出的 id:sql/0000)。 */
 export function pad4(n: number): string {
   return String(n).padStart(4, "0");