niceeval 0.10.3-canary.6 → 0.11.0

package/src/shared/failure-class.ts

@@ -0,0 +1,175 @@
+// 执行失败分类的词表、抛出点糖衣类与结构守卫——全仓唯一一份两轴词表,turn 失败、生命周期
+// 阶段失败与 sandbox provisioning 失败说同一种语言(判据见
+// docs/feature/error-classification/README.md「分类」)。
+//
+// 本模块刻意零依赖(只 import type):公开面活在 Promise 世界,糖衣类不继承任何 effect 类型,
+// 生成的 .d.ts 零 effect 依赖(见 architecture.md「Effect 边界」)。turn 链的实现在
+// src/context/turn-errors.ts,provisioning 的内部分类在 src/sandbox/,两边各自实现、只共享
+// 这份词表。
+
+import type { LifecyclePhase } from "../runner/types.ts";
+
+/** 空间轴取值:失败死因的波及范围。 */
+export type FailureScope = "attempt" | "eval" | "experiment";
+
+/**
+ * 一次执行失败的分类:`retryable`(时间轴)与 `scope`(空间轴)是仅有的两条决策轴;
+ * `reason` 是开放词表的细分诊断,只进 activity 与诊断文案,不参与策略。内建兜底产出
+ * reason `"rate_limit"` / `"network"`;声明方可自造词。`scope` 缺省 `"attempt"`。
+ *
+ * `retryable: true` 时 `reason` 必填:可重试的失败一定出现在 activity 行与可能的耗尽摘要里,
+ * 那里需要一个给人读的词;不可重试的失败常常说不清是什么(这正是它不可重试的原因)。
+ */
+export type FailureClass =
+  | { readonly retryable: true; readonly reason: string; readonly scope?: FailureScope }
+  | { readonly retryable: false; readonly reason?: string; readonly scope?: FailureScope };
+
+/**
+ * 实验级分类器的输入:本实验任意 per-attempt 阶段的一次终局失败。
+ */
+export interface AttemptFailureInfo {
+  /** 失败发生在哪个生命周期阶段;turn 失败恒为 `"agent.run"`。 */
+  readonly phase: LifecyclePhase;
+  /** 与报错文案同源的失败文本:thrown 取错误链(含 cause 链)message 串接,turn 失败取 `turnErrorText`。 */
+  readonly text: string;
+  /** 原始失败对象:thrown 形态是抛出的错误,turn 失败形态是那个失败 Turn。 */
+  readonly cause: unknown;
+}
+
+/**
+ * 实验可选分类器,挂载在 `ExperimentDef.classifyFailure`:识别自家共享基建的死因
+ * (对自家隧道 host 的拒连一类)。返回 `undefined` 表示「不认识,交给后续链路」。
+ * 分类器必须快、纯、不抛错——抛错按 `undefined` 回落并被吞掉,不掩盖原始失败。
+ */
+export type AttemptFailureClassifier = (failure: AttemptFailureInfo) => FailureClass | undefined;
+
+/** 携带分类的错误对象的判别字段值;识别只看这个数据字段,不看类身份。 */
+const FAILURE_CLASS_TAG = "NiceevalClassifiedError";
+
+/**
+ * 从任意 per-attempt 阶段抛出:全实验剩余 attempt 同因必死,停止派发。
+ * 携带 `{ retryable: false, scope: "experiment" }`,message 原样走完反馈流与
+ * `dispatch-halted` 诊断——把它写成「现象 + 下一步」的修复提示。
+ */
+export class ExperimentFatalError extends Error {
+  readonly _tag = FAILURE_CLASS_TAG;
+  readonly class: FailureClass = { retryable: false, scope: "experiment" };
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "ExperimentFatalError";
+  }
+}
+
+/**
+ * 从任意 per-attempt 阶段抛出:本 eval 剩余 attempt 同因必死,停止派发。
+ * 携带 `{ retryable: false, scope: "eval" }`;message 同样是走完全程的修复提示。
+ */
+export class EvalFatalError extends Error {
+  readonly _tag = FAILURE_CLASS_TAG;
+  readonly class: FailureClass = { retryable: false, scope: "eval" };
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "EvalFatalError";
+  }
+}
+
+/**
+ * 结构守卫:识别任何携带分类的错误对象(`_tag` + `class` 两个数据字段),沿 `cause` 链逐层
+ * 查找、取**最外层**命中——糖衣类被上层库包装再抛时声明不丢失。识别不依赖 `instanceof`:
+ * 依赖树里出现第二份 niceeval 实例(link、版本重复)时类身份静默失效,数据不会。
+ */
+export function failureClassOf(error: unknown): FailureClass | undefined {
+  let current: unknown = error;
+  for (let depth = 0; depth < CAUSE_CHAIN_DEPTH && current != null; depth++) {
+    if (typeof current === "object") {
+      const candidate = current as { _tag?: unknown; class?: unknown };
+      if (candidate._tag === FAILURE_CLASS_TAG && isFailureClass(candidate.class)) return candidate.class;
+    }
+    current = causeOf(current);
+  }
+  return undefined;
+}
+
+/** cause 链与错误文本串接共用的深度上限:防御自引用 / 病态深链,不做环检测。 */
+const CAUSE_CHAIN_DEPTH = 5;
+
+function causeOf(value: unknown): unknown {
+  return typeof value === "object" && value !== null ? (value as { cause?: unknown }).cause : undefined;
+}
+
+function isFailureClass(value: unknown): value is FailureClass {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as { retryable?: unknown; reason?: unknown; scope?: unknown };
+  if (typeof v.retryable !== "boolean") return false;
+  if (v.retryable && typeof v.reason !== "string") return false;
+  if (v.reason !== undefined && typeof v.reason !== "string") return false;
+  if (v.scope !== undefined && v.scope !== "attempt" && v.scope !== "eval" && v.scope !== "experiment") return false;
+  return true;
+}
+
+/**
+ * @internal 把框架决议出的分类挂到即将浮出的失败对象上,供 attempt 封口经 `failureClassOf`
+ * 读取(止损闸的消费点)。两个字段都不可枚举——不进 JSON、不进 console 输出,只是路由标记;
+ * 已携带分类的对象不覆盖(抛出点声明优先),不可写对象静默跳过(分类是旁路,不制造新失败)。
+ */
+export function attachFailureClass<T>(target: T, cls: FailureClass): T {
+  if (typeof target !== "object" || target === null) return target;
+  if (failureClassOf(target) !== undefined) return target;
+  try {
+    Object.defineProperty(target, "_tag", { value: FAILURE_CLASS_TAG, enumerable: false, configurable: true });
+    Object.defineProperty(target, "class", { value: cls, enumerable: false, configurable: true });
+  } catch {
+    // 冻结 / 密封的错误对象:标记不上就算了,分类退化成 attempt 档,不掩盖原始失败。
+  }
+  return target;
+}
+
+/**
+ * @internal 错误链(含 `cause` 链)的 message 串接:给人读的报错文案与给分类器看的失败文本
+ * 用这同一段,不出现「报错说 A、分类看 B」。
+ */
+export function errorChainText(error: unknown): string {
+  const parts: string[] = [];
+  let current: unknown = error;
+  for (let depth = 0; depth < CAUSE_CHAIN_DEPTH && current != null; depth++) {
+    const message = current instanceof Error ? current.message : String(current);
+    if (message) parts.push(message);
+    current = current instanceof Error ? causeOf(current) : undefined;
+  }
+  return parts.join(" · ");
+}
+
+/**
+ * @internal 调分类器的统一纪律:抛错按 `undefined` 回落(自身错误被吞掉,不得用新错误掩盖
+ * 原始失败),返回值原样透出。turn 链与生命周期链共用这一处,两条链的纪律不会跑偏。
+ */
+export function callClassifier<T>(classifier: ((failure: T) => FailureClass | undefined) | undefined, failure: T) {
+  if (!classifier) return undefined;
+  try {
+    return classifier(failure);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @internal 生命周期阶段失败的分类链(三道):抛出点携带的分类 → 实验分类器 → 缺省
+ * `{ retryable: false }`。这些位置(sandbox 钩子、`EvalDef.setup`、`test(t)` 体内、
+ * per-attempt teardown)没有重试执行体,链上不挂产时间轴的兜底正则——时间轴即使给出也无人
+ * 消费(见 architecture.md「分类链」)。
+ */
+export function resolveAttemptFailureClass(
+  info: AttemptFailureInfo,
+  experimentClassifier?: AttemptFailureClassifier,
+): FailureClass {
+  const declared = failureClassOf(info.cause);
+  if (declared) return declared;
+  return callClassifier(experimentClassifier, info) ?? { retryable: false };
+}
+
+/** @internal 从一个抛出的错误构造实验分类器的输入(文本与报错文案同源)。 */
+export function attemptFailureInfo(phase: LifecyclePhase, error: unknown): AttemptFailureInfo {
+  return { phase, text: errorChainText(error), cause: error };
+}

package/src/show/index.ts

@@ -391,11 +391,10 @@ const MISSING_MARK = "—";
 const USAGE_COLUMNS = ["locator", "eval", "result", "turns", "tools", "uncached in", "cache read", "out", "requests", "cost"];
 const USAGE_ALIGN: readonly ColumnAlign[] = ["left", "left", "left", "right", "right", "right", "right", "right", "right", "right"];
 
-/** uncached in 列的取值:与 `usage:` 行同一条回退口径(见 docs/feature/reports/library/
- *  attempt-detail.md#usagetable-组装口径单源)——优先派生的 uncachedInputTokens,两个输入
- *  缺一个就回退显示原始 inputTokens,不猜 0。 */
+/** uncached in 列的取值:桶恒互斥,inputTokens 本身就是未缓存输入(见 docs/feature/reports/
+ *  library/attempt-detail.md#usagetable-组装口径单源)。 */
 function uncachedInOf(row: UsageTableData): number | undefined {
-  return row.uncachedInputTokens ?? row.usage?.inputTokens;
+  return row.usage?.inputTokens;
 }
 
 /**
@@ -554,7 +553,7 @@ async function renderUsageCompareSlice(
   const usageRows = await usageRowsOf(selection.attempts);
   const byConditionByEval = new Map<string, UsageTableData[]>();
   for (const row of usageRows) {
-    const key = `${row.experimentId}${row.evalId}`;
+    const key = `${row.experimentId}\u0000${row.evalId}`;
     const list = byConditionByEval.get(key);
     if (list) list.push(row);
     else byConditionByEval.set(key, [row]);
@@ -567,7 +566,7 @@ async function renderUsageCompareSlice(
     const cellsText = conditions.flatMap((condition) => {
       const deltaCell = row.cells[condition];
       if (!deltaCell) return USAGE_MATRIX_METRIC_COLUMNS.map(() => MISSING_MARK);
-      const usageCell = usageMatrixCellOf(byConditionByEval.get(`${condition}${row.key}`) ?? []);
+      const usageCell = usageMatrixCellOf(byConditionByEval.get(`${condition}\u0000${row.key}`) ?? []);
       return usageMatrixCellText(usageCell, deltaCell.historical);
     });
     return [row.key, ...cellsText];

package/src/show/render.test.ts

@@ -4,11 +4,12 @@
 // 完整多行 message 归 attempt 详情块展开。
 // bug: memory/diagnose-tail-inline-defeats-one-line-elision.md
 //
-// 「execution 的预算、句柄与 grep」(docs/engineering/testing/unit/reports.md):卡片预览预算按
-// UTF-8 字节在字符边界截断;Agent 卡的 t<N>.c<M> 从事件序确定性派生,失败 Sandbox 命令卡的
-// cmd<N> 按 timing node 时序派生;--expand 命中还原完整落盘值、句柄超界的完整报错;--grep 的
-// 匹配面覆盖角色文本、工具名、input、result 与失败命令 display/stdout/stderr;命中计数与
-// 0 命中的明确输出。
+// 「execution 的预算、句柄与 grep」(docs/engineering/testing/unit/reports.md):卡片预览预算按段
+// 独立截断——每段最多显示前 3 行(骨架行不计入),每段另有 1 KiB 字节兜底(按字符边界回退);
+// 卡尾聚合全卡各段被折的行数与字符数,没有整行被折时行数退化省略;Agent 卡的 t<N>.c<M> 从事件序
+// 确定性派生,失败 Sandbox 命令卡的 cmd<N> 按 timing node 时序派生;--expand 命中还原完整落盘值、
+// 句柄超界的完整报错;--grep 的匹配面覆盖角色文本、工具名、input、result 与失败命令
+// display/stdout/stderr;命中计数与 0 命中的明确输出。
 
 import { describe, expect, it } from "vitest";
 import { executionText, verdictReasonLine } from "./render.ts";
@@ -164,9 +165,88 @@ describe("--execution:轮内卡片句柄 t<N>.c<M> 从事件序确定性派生",
   });
 });
 
-describe("--execution:卡片预览预算按 UTF-8 字节在字符边界截断", () => {
-  function bigBodyEvidence(): AttemptEvidence {
-    const bigText = "x".repeat(8190) + "🙂".repeat(3); // 8190 ascii(1B) + 3 emoji(4B) = 8202B > 8192B 预算
+describe("--execution:单段卡按 3 行截断,骨架行不计入,尾巴 `(+N lines · M chars · …)`", () => {
+  function fiveLineEvidence(): AttemptEvidence {
+    // 5 行,前 3 行("alpha"/"bravo"/"charlie")在预算内,后 2 行("delta"/"echo")被整行折掉。
+    const events: StreamEvent[] = [
+      { type: "message", role: "user", text: "start" },
+      { type: "thinking", text: "alpha\nbravo\ncharlie\ndelta\necho" },
+    ];
+    return evidenceOf({ execution: buildExecutionTree(events, []), result: resultOf({ phases: twoTurnPhases() }) });
+  }
+
+  it("只显示前 3 行(保留原始换行),第 4/5 行整行折掉,尾巴报被折行数与字符数", () => {
+    const evidence = fiveLineEvidence();
+    const { text } = executionText(evidence, OPTS);
+    expect(text).toContain("alpha\n    bravo\n    charlie");
+    expect(text).not.toContain("delta");
+    expect(text).not.toContain("echo");
+    // "\ndelta\necho" 相对 "alpha\nbravo\ncharlie" 前缀被折掉的字符(含分隔行首的 \n)。
+    expect(text).toContain(`(+2 lines · 11 chars · niceeval show ${LOCATOR} --execution --expand t1.c2)`);
+  });
+
+  it("--expand 还原完整未截断内容,不带尾巴", () => {
+    const evidence = fiveLineEvidence();
+    const { text } = executionText(evidence, OPTS, { expand: "t1.c2" });
+    // --expand 走 renderExpand,不经 renderFull 的额外一层 turn 缩进,只剩 renderCardLines 自身
+    // 的基础缩进(2 空格),比预览路径(4 空格)少一层。
+    expect(text).toContain("alpha\n  bravo\n  charlie\n  delta\n  echo");
+    expect(text).not.toContain("niceeval show");
+  });
+});
+
+describe("--execution:TOOL 卡 input/result 各自独立按 3 行截断,尾巴聚合两段", () => {
+  function toolCardEvidence(): AttemptEvidence {
+    const events: StreamEvent[] = [
+      { type: "message", role: "user", text: "start" },
+      { type: "action.called", callId: "call-1", name: "shell", input: { command: "cmd1\ncmd2\ncmd3\ncmd4" } },
+      {
+        type: "action.result",
+        callId: "call-1",
+        output: { output: "out1\nout2\nout3\nout4\nout5", exit_code: 0 },
+        status: "completed",
+      },
+    ];
+    return evidenceOf({ execution: buildExecutionTree(events, []), result: resultOf({ phases: twoTurnPhases() }) });
+  }
+
+  it("input(4 行折 1 行)与 result(5 行折 2 行)各自独立截断,骨架行`input`/`result · <status>`原样全显", () => {
+    const evidence = toolCardEvidence();
+    const { text } = executionText(evidence, OPTS);
+    expect(text).toContain("input");
+    expect(text).toContain("result · completed · exit 0");
+    expect(text).toContain("cmd1");
+    expect(text).toContain("cmd2");
+    expect(text).toContain("cmd3");
+    expect(text).not.toContain("cmd4");
+    expect(text).toContain("out1");
+    expect(text).toContain("out2");
+    expect(text).toContain("out3");
+    expect(text).not.toContain("out4");
+    expect(text).not.toContain("out5");
+  });
+
+  it("卡尾只有一条,聚合两段各自被折的行数(1+2=3)与字符数(5+10=15)", () => {
+    const evidence = toolCardEvidence();
+    const { text } = executionText(evidence, OPTS);
+    expect(text).toContain(`(+3 lines · 15 chars · niceeval show ${LOCATOR} --execution --expand t1.c2)`);
+    // 每卡只出现一次尾巴,不是 input/result 各带一条。
+    expect(text.match(/niceeval show .* --expand/g)?.length).toBe(1);
+  });
+
+  it("--expand 还原两段完整内容,不截断", () => {
+    const evidence = toolCardEvidence();
+    const { text } = executionText(evidence, OPTS, { expand: "t1.c2" });
+    expect(text).toContain("cmd4");
+    expect(text).toContain("out5");
+    expect(text).not.toContain("niceeval show");
+  });
+});
+
+describe("--execution:1 KiB 字节兜底(按字符边界回退,不切分代理对),没有整行被折时 N 退化省略", () => {
+  function bigSingleLineEvidence(): AttemptEvidence {
+    // 单行(不触发 3 行上限)但 1022 ascii(1B) + 3 emoji(4B) = 1034B > 1024B 段预算。
+    const bigText = "x".repeat(1022) + "🙂".repeat(3);
     const events: StreamEvent[] = [
       { type: "message", role: "user", text: "start" },
       { type: "thinking", text: bigText },
@@ -174,28 +254,49 @@ describe("--execution:卡片预览预算按 UTF-8 字节在字符边界截断",
     return evidenceOf({ execution: buildExecutionTree(events, []), result: resultOf({ phases: twoTurnPhases() }) });
   }
 
-  it("超预算截到恰好塞满 8192 字节的 codepoint 边界,不切分代理对/多字节字符", () => {
-    const evidence = bigBodyEvidence();
+  it("超预算截到恰好塞满 1024 字节的 codepoint 边界,没有整行被折,尾巴退化为 `(+M chars · …)`(没有 `lines` 段)", () => {
+    const evidence = bigSingleLineEvidence();
     const { text } = executionText(evidence, OPTS);
-    // 8190 个 ascii "x" 用尽预算内的 8190 字节,下一枚 emoji(4B)放不进剩余 2 字节,整枚被折掉。
+    // 1022 个 ascii "x" 用尽预算内的 1022 字节,下一枚 emoji(4B)放不进剩余 2 字节,整枚被折掉。
     // 用最长连续 x 串而不是全文 x 计数——尾巴里的 "--execution"/"--expand" 与 header 的 "exp/a"
     // 本身也含 'x' 字母,全文计数会被这些无关 'x' 污染。
     const longestXRun = Math.max(0, ...[...text.matchAll(/x+/g)].map((m) => m[0].length));
-    expect(longestXRun).toBe(8190);
+    expect(longestXRun).toBe(1022);
     expect(text).not.toContain("🙂");
     expect(text).toContain(`(+3 chars · niceeval show ${LOCATOR} --execution --expand t1.c2)`);
+    expect(text).not.toContain("lines ·");
   });
 
   it("--expand 还原完整未截断内容(原始换行,不再截断)", () => {
-    const evidence = bigBodyEvidence();
+    const evidence = bigSingleLineEvidence();
     const { text } = executionText(evidence, OPTS, { expand: "t1.c2" });
     expect(text).toContain("🙂🙂🙂");
     expect(text).not.toContain("niceeval show");
     const longestXRun = Math.max(0, ...[...text.matchAll(/x+/g)].map((m) => m[0].length));
-    expect(longestXRun).toBe(8190);
+    expect(longestXRun).toBe(1022);
+  });
+
+  it("被字节兜底截到一半的行,如果全卡还有整行被折,计入被折行数(不退化)", () => {
+    // 4 行:前 2 行短,第 3 行(2000 个 'x')把候选(3 行)的字节数撑到 1024 以上触发字节兜底,
+    // 第 4 行("hiddenLine")完全在 3 行上限之外被整行折掉——两种折法同一张卡都发生。
+    const events: StreamEvent[] = [
+      { type: "message", role: "user", text: "start" },
+      { type: "thinking", text: `short1\nshort2\n${"x".repeat(2000)}\nhiddenLine` },
+    ];
+    const evidence = evidenceOf({ execution: buildExecutionTree(events, []), result: resultOf({ phases: twoTurnPhases() }) });
+    const { text } = executionText(evidence, OPTS);
+    expect(text).toContain("short1");
+    expect(text).toContain("short2");
+    expect(text).not.toContain("hiddenLine");
+    const longestXRun = Math.max(0, ...[...text.matchAll(/x+/g)].map((m) => m[0].length));
+    expect(longestXRun).toBe(1010); // 1024 字节预算 - "short1\nshort2\n"(14 字节) = 1010 个 x
+    // N = 1(hiddenLine 整行被折) + 1(第 3 行被字节兜底截到一半,全卡有整行被折时计入) = 2。
+    expect(text).toContain(`(+2 lines · 1001 chars · niceeval show ${LOCATOR} --execution --expand t1.c2)`);
   });
+});
 
-  it("落盘已截断的值(marker 是写入时刻烘进正文的字面文本)在预览与 --expand 中都原样透传", () => {
+describe("--execution:落盘已截断的值原样透传", () => {
+  it("marker 是写入时刻烘进正文的字面文本,在预览与 --expand 中都原样透传(短文本,预算内不截断)", () => {
     const diskTruncated = "partial output before cut\n[niceeval] truncated 51467156 → 262144 bytes";
     const events: StreamEvent[] = [
       { type: "message", role: "user", text: "start" },

package/src/show/render.ts

@@ -393,14 +393,16 @@ function relSeconds(ms: number, originMs: number): string {
 }
 
 /** 卡片正文的有界预览预算(docs/feature/reports/show/execution.md「卡片预览预算与 --expand」):
- *  8 KiB,按 UTF-8 字节计,超限时按字符边界(codepoint,不切分代理对)回退截断。 */
-const CARD_BODY_BUDGET_BYTES = 8 * 1024;
+ *  主尺度是行——每个内容段最多显示前 3 行(保留原始换行);每段另有 1 KiB(UTF-8 字节)兜底,
+ *  防单行超长的 JSON blob 击穿行预算。 */
+const CARD_SEGMENT_MAX_LINES = 3;
+const CARD_SEGMENT_BUDGET_BYTES = 1024;
 
 /**
  * 按 UTF-8 字节预算截断,永不切断一个 codepoint。快速路径:总字节数不超预算时不做任何逐字符
  * 扫描。慢速路径只在确实超限时才逐 codepoint 累加字节数,找到恰好塞满预算的前缀。
  */
-function truncateCardBody(text: string, maxBytes: number): { shown: string; foldedChars: number } {
+function truncateByteBudget(text: string, maxBytes: number): { shown: string; foldedChars: number } {
   if (Buffer.byteLength(text, "utf8") <= maxBytes) return { shown: text, foldedChars: 0 };
   const chars = Array.from(text);
   let bytes = 0;
@@ -413,6 +415,55 @@ function truncateCardBody(text: string, maxBytes: number): { shown: string; fold
   return { shown: chars.slice(0, i).join(""), foldedChars: chars.length - i };
 }
 
+/** 一段内容截断后的状态:`shown` 是保留的前缀,`linesFullyHidden` 是被 3 行上限整行折掉的行数
+ *  (不含被字节兜底截到一半的那一行),`partialCut` 标记这段是否被字节兜底从中间截断过,
+ *  `foldedChars` 是这段被折掉的字符总数(= 原文 codepoint 数 − `shown` 的 codepoint 数)。 */
+interface SegmentTruncation {
+  shown: string;
+  linesFullyHidden: number;
+  partialCut: boolean;
+  foldedChars: number;
+}
+
+/**
+ * 单段的行 + 字节双重预算截断(docs/feature/reports/show/execution.md「卡片预览预算与
+ * --expand」):先按 3 行裁剪(保留原始换行),再对裁剪结果套 1 KiB 字节兜底(按字符边界回退,
+ * 不切分代理对),防单行超长的 JSON blob 击穿行预算。两次裁剪都只从末尾裁,`shown` 因此恒是
+ * 原文的一个前缀,折字符数可以直接用两侧 codepoint 数之差倒推。
+ */
+function truncateSegment(text: string): SegmentTruncation {
+  const lines = text.split("\n");
+  const shownLineCount = Math.min(CARD_SEGMENT_MAX_LINES, lines.length);
+  const candidate = lines.slice(0, shownLineCount).join("\n");
+  const { shown, foldedChars: byteFoldedChars } = truncateByteBudget(candidate, CARD_SEGMENT_BUDGET_BYTES);
+  const totalChars = Array.from(text).length;
+  const shownChars = Array.from(shown).length;
+  return {
+    shown,
+    linesFullyHidden: lines.length - shownLineCount,
+    partialCut: byteFoldedChars > 0,
+    foldedChars: totalChars - shownChars,
+  };
+}
+
+/**
+ * 卡尾截断提示的聚合(docs/feature/reports/show/execution.md「卡片预览预算与 --expand」):
+ * N 是全卡各段被整行折掉的行数之和,再加上「同一张卡里确实有整行被折」时,每个被字节兜底截到
+ * 一半的段各计 1 行——这条规则只在 N 本来就 > 0 时生效;如果全卡没有任何一段整行被折、只是
+ * 某段字节兜底切了字符(单段本身没超 3 行,但这一两行太长),N 退化为 0,尾巴退化成
+ * `(+M chars · …)`,不虚报一行「被折」。返回 undefined 表示这张卡没有任何段被截断,调用方不
+ * 应追加尾巴。
+ */
+function foldCardTail(bits: readonly SegmentTruncation[], locator: string, handle: string): string | undefined {
+  const totalFoldedChars = bits.reduce((sum, b) => sum + b.foldedChars, 0);
+  if (totalFoldedChars === 0) return undefined;
+  const totalHiddenLines = bits.reduce((sum, b) => sum + b.linesFullyHidden, 0);
+  const partialCutCount = bits.reduce((sum, b) => sum + (b.partialCut ? 1 : 0), 0);
+  const n = totalHiddenLines > 0 ? totalHiddenLines + partialCutCount : 0;
+  const head = n > 0 ? `+${n} line${n === 1 ? "" : "s"} · ${totalFoldedChars} chars` : `+${totalFoldedChars} chars`;
+  return `(${head} · niceeval show ${locator} --execution --expand ${handle})`;
+}
+
 /** 逐行加前缀,保留原始换行(不做 wrapDisplay 折行——「保留原始换行」是这个区块 text 面的契约)。
  *  空行不补前缀,避免制造纯空白的尾随行。 */
 function indentLines(text: string, indent: string): string {
@@ -522,38 +573,49 @@ function nodeMeta(node: ExecutionNode, originMs: number): string {
   return `${relSeconds(span.startMs, originMs)} · ${formatDurationMs(span.endMs - span.startMs)}`;
 }
 
+/** 卡片正文的一个内容段(docs/feature/reports/show/execution.md「卡片预览预算与 --expand」):
+ *  预览预算(3 行 + 1 KiB 兜底)按段独立截断,不是对整卡正文一次性截断。 */
+interface CardSegment {
+  /** 段的骨架行(如 `input` / `result · completed`);不计入预算、不截断。undefined 表示这段
+   *  没有骨架行——单段卡的正文,或失败命令卡的命令行本身。 */
+  label?: string;
+  /** 这段的完整(未截断)原始内容,保留原始换行;预算截断与 --expand 的完整输出都基于它。 */
+  text: string;
+}
+
 interface CardParts {
   /** 卡片标题行(不缩进,含 kind 标签与相对时间/耗时 meta)。 */
   header: string;
-  /** 卡片正文的完整(未截断)原始内容,保留原始换行;预算截断与 --expand 的完整输出都基于它。 */
-  body: string;
+  /** 卡片正文按结构划分的段落;角色文本/thinking 这类单段卡只有 1 段,TOOL 卡 input/result
+   *  各一段,失败命令卡命令行/stdout/stderr 各一段。 */
+  segments: CardSegment[];
   /** --grep 的匹配面:角色文本、工具名、input、result(docs/feature/reports/show/execution.md
    *  「范围化:跨 attempt 扫描与 --grep」);未经截断,grep 命中不受预览预算影响。 */
   matchText: string;
-  /** 截断尾巴 `(+N chars · …)` 相对卡片正文的额外缩进——多段结构(如 TOOL 的 input/result)
-   *  的正文本身已经带一层内嵌缩进,尾巴要落在同一层,不是贴着卡片左边。 */
+  /** 截断尾巴相对卡片正文的额外缩进——多段结构(如 TOOL 的 input/result)的正文本身已经带
+   *  一层内嵌缩进,尾巴要落在同一层,不是贴着卡片左边。 */
   tailIndent: string;
 }
 
-/** 一个 Agent 事件节点 → 卡片的标题/正文/匹配面。`node.kind` 已排除 telemetry(见调用方的
+/** 一个 Agent 事件节点 → 卡片的标题/段落/匹配面。`node.kind` 已排除 telemetry(见调用方的
  *  agentNodes 过滤),telemetry 分支仅为联合类型穷尽性存在,不会被触达。 */
 function agentCardParts(node: ExecutionNode, originMs: number): CardParts {
   const meta = nodeMeta(node, originMs);
   const withMeta = (title: string) => (meta ? `${title}  ${meta}` : title);
   switch (node.kind) {
     case "message":
-      return { header: withMeta(node.role.toUpperCase()), body: node.text, matchText: node.text, tailIndent: "" };
+      return { header: withMeta(node.role.toUpperCase()), segments: [{ text: node.text }], matchText: node.text, tailIndent: "" };
     case "thinking":
-      return { header: withMeta("THINKING"), body: node.text, matchText: node.text, tailIndent: "" };
+      return { header: withMeta("THINKING"), segments: [{ text: node.text }], matchText: node.text, tailIndent: "" };
     case "context.injected":
       return {
         header: withMeta(node.source ? `CONTEXT INJECTED · ${node.source}` : "CONTEXT INJECTED"),
-        body: node.text,
+        segments: [{ text: node.text }],
         matchText: node.text,
         tailIndent: "",
       };
     case "skill.loaded":
-      return { header: withMeta(`SKILL · ${node.skill}`), body: "loaded", matchText: node.skill, tailIndent: "" };
+      return { header: withMeta(`SKILL · ${node.skill}`), segments: [{ text: "loaded" }], matchText: node.skill, tailIndent: "" };
     case "action": {
       const input = recordOf(node.input);
       const output = recordOf(node.output);
@@ -564,36 +626,43 @@ function agentCardParts(node: ExecutionNode, originMs: number): CardParts {
           ? jsonText(node.output)
           : "(no result)";
       const exit = typeof output?.exit_code === "number" ? ` · exit ${output.exit_code}` : "";
-      const body = ["input", indentLines(inputText, "  "), `result · ${node.status}${exit}`, indentLines(outputText, "  ")].join("\n");
-      return { header: withMeta(`TOOL · ${node.name}`), body, matchText: `${node.name} ${inputText} ${outputText}`, tailIndent: "  " };
+      return {
+        header: withMeta(`TOOL · ${node.name}`),
+        segments: [
+          { label: "input", text: inputText },
+          { label: `result · ${node.status}${exit}`, text: outputText },
+        ],
+        matchText: `${node.name} ${inputText} ${outputText}`,
+        tailIndent: "  ",
+      };
     }
     case "subagent": {
       const resultText = node.output === undefined ? node.status : `result · ${node.status}: ${jsonText(node.output)}`;
-      return { header: withMeta(`SUBAGENT · ${node.name}`), body: resultText, matchText: `${node.name} ${resultText}`, tailIndent: "" };
+      return { header: withMeta(`SUBAGENT · ${node.name}`), segments: [{ text: resultText }], matchText: `${node.name} ${resultText}`, tailIndent: "" };
     }
     case "input.requested": {
       const text = node.request.prompt ?? node.request.display ?? "(input requested)";
       const matchText = [text, node.request.action, node.request.input !== undefined ? jsonText(node.request.input) : undefined]
         .filter((s): s is string => s !== undefined)
         .join(" ");
-      return { header: withMeta("INPUT REQUESTED"), body: text, matchText, tailIndent: "" };
+      return { header: withMeta("INPUT REQUESTED"), segments: [{ text }], matchText, tailIndent: "" };
     }
     case "compaction":
-      return { header: withMeta("COMPACTION"), body: node.reason ?? "context compacted", matchText: node.reason ?? "", tailIndent: "" };
+      return { header: withMeta("COMPACTION"), segments: [{ text: node.reason ?? "context compacted" }], matchText: node.reason ?? "", tailIndent: "" };
     case "error":
-      return { header: withMeta("ERROR"), body: node.message, matchText: node.message, tailIndent: "" };
+      return { header: withMeta("ERROR"), segments: [{ text: node.message }], matchText: node.message, tailIndent: "" };
     case "telemetry":
-      return { header: "TELEMETRY", body: "", matchText: "", tailIndent: "" };
+      return { header: "TELEMETRY", segments: [], matchText: "", tailIndent: "" };
   }
 }
 
 function commandCardParts(command: FailedCommandEvidence): CardParts {
-  const sections = [command.display];
-  if (command.stdout) sections.push("stdout", indentLines(command.stdout, "  "));
-  if (command.stderr) sections.push("stderr", indentLines(command.stderr, "  "));
+  const segments: CardSegment[] = [{ text: command.display }];
+  if (command.stdout) segments.push({ label: "stdout", text: command.stdout });
+  if (command.stderr) segments.push({ label: "stderr", text: command.stderr });
   return {
     header: "",
-    body: sections.join("\n"),
+    segments,
     matchText: `${command.display} ${command.stdout} ${command.stderr}`,
     tailIndent: "  ",
   };
@@ -629,19 +698,37 @@ function turnUsageText(turn: TimingNode | undefined): string | undefined {
   return parts.length > 0 ? parts.join(" · ") : undefined;
 }
 
-/** 一张卡片的完整渲染:`full` 时输出未截断的落盘内容(--expand);否则按 8 KiB 预算截断,
- *  截断尾巴带被折字符数与展开句柄。两种形态都只做逐行前缀(indentLines),不做 wrapDisplay 折行
- *  ——保留原始换行是这个区块 text 面的契约,不是遗漏。 */
+/**
+ * 一张卡片的完整渲染:`full` 时逐段输出未截断的落盘内容(--expand);否则每段独立按 3 行 + 1 KiB
+ * 预算截断(docs/feature/reports/show/execution.md「卡片预览预算与 --expand」),卡尾追加一条
+ * 聚合尾巴。带 `label` 的段(TOOL 的 input/result、失败命令的 stdout/stderr)先输出骨架行,
+ * 段正文本身再多缩进一层;没有 label 的段(单段卡的正文,命令行本身)正文与骨架行同一层。
+ * 两种形态都只做逐行前缀(indentLines),不做 wrapDisplay 折行——保留原始换行是这个区块 text
+ * 面的契约,不是遗漏。
+ */
 function renderCardLines(parts: CardParts, handle: string, locator: string, full: boolean): string[] {
-  if (full) {
-    const body = indentLines(parts.body, "  ");
-    return parts.header ? [parts.header, ...body.split("\n")] : body.split("\n");
+  const bodyLines: string[] = [];
+  const truncations: SegmentTruncation[] = [];
+  for (const seg of parts.segments) {
+    let content: string;
+    if (full) {
+      content = seg.text;
+    } else {
+      const t = truncateSegment(seg.text);
+      truncations.push(t);
+      content = t.shown;
+    }
+    if (seg.label) {
+      bodyLines.push(seg.label, ...indentLines(content, "  ").split("\n"));
+    } else {
+      bodyLines.push(...content.split("\n"));
+    }
+  }
+  if (!full) {
+    const tail = foldCardTail(truncations, locator, handle);
+    if (tail) bodyLines.push(`${parts.tailIndent}${tail}`);
   }
-  const { shown, foldedChars } = truncateCardBody(parts.body, CARD_BODY_BUDGET_BYTES);
-  const withTail = foldedChars > 0
-    ? `${shown}\n${parts.tailIndent}(+${foldedChars} chars · niceeval show ${locator} --execution --expand ${handle})`
-    : shown;
-  const body = indentLines(withTail, "  ");
+  const body = indentLines(bodyLines.join("\n"), "  ");
   return parts.header ? [parts.header, ...body.split("\n")] : body.split("\n");
 }
 
@@ -814,7 +901,9 @@ export interface ExecutionRenderOptions {
  * (`cmd<N>`,来自 `commands.json`,经 `evidence.commands` 读取;没有失败命令时这一段自然
  * 零输出,见 `failedCommandsOf`)。
  *
- * 卡片正文是 8 KiB(UTF-8 字节,按字符边界回退)的有界预览,截断尾巴带被折字符数与展开句柄；
+ * 卡片正文按段(单段卡的正文、TOOL 卡的 input/result、失败命令卡的命令行/stdout/stderr)分别是
+ * 3 行(保留原始换行)的有界预览,单段另有 1 KiB 字节兜底(按字符边界回退);截断尾巴带被折
+ * 行数与字符数、以及展开句柄(全卡没有整行被折、只是字节兜底切了字符时,行数退化为省略)。
  * `options.expand` 精确定位一张卡片输出完整落盘内容;`options.grep` 只输出匹配面(角色文本/
  * 工具名/input/result,命令卡另加 display/stdout/stderr)命中的卡片,返回值的 `matches` 是本
  * attempt 内的命中卡片数——「N matches in M attempts」与 0 命中的措辞归调用方组装。

package/src/types.ts

@@ -20,3 +20,12 @@ export * from "./agents/types.ts";
 export * from "./scoring/types.ts";
 export * from "./context/types.ts";
 export * from "./runner/types.ts";
+
+// 失败分类词表:两轴 FailureClass / FailureScope 与实验分类器的输入输出形状。糖衣类与守卫
+// 是运行时值,从包根(src/index.ts)直接导出,不进这个纯类型 facade。
+export type {
+  FailureClass,
+  FailureScope,
+  AttemptFailureInfo,
+  AttemptFailureClassifier,
+} from "./shared/failure-class.ts";