niceeval 0.10.3-canary.7 → 0.11.0

package/src/context/send-retry.test.ts

@@ -9,6 +9,7 @@ import {
   type SendRetryDeps,
   type TurnLens,
 } from "./send-retry.ts";
+import { failureClassOf, type FailureClass } from "../shared/failure-class.ts";
 import type { Turn } from "../types.ts";
 
 // 直调执行体,不用真实 setTimeout 睡眠——sleep 注入即返回(受控时钟),random 注入固定值,
@@ -265,6 +266,91 @@ describe("sendWithTurnRetry · adapter 分类器接入", () => {
   });
 });
 
+describe("sendWithTurnRetry · 终局失败携带分类浮出(止损闸的进料)", () => {
+  const tunnelDown = { retryable: false, scope: "experiment", reason: "tunnel_down" } as const;
+
+  it("thrown 形态:终局失败的分类标在浮出的错误上,经 failureClassOf 读得到", async () => {
+    const original = new Error("connect ECONNREFUSED tunnel.example:443");
+    const promise = sendWithTurnRetry(
+      async () => {
+        throw original;
+      },
+      identityLens,
+      baseDeps({ experimentClassifier: () => tunnelDown }),
+    );
+    await expect(promise).rejects.toBe(original); // 浮出的仍是原始错误对象,不被包装替换
+    expect(failureClassOf(original)).toEqual(tunnelDown);
+  });
+
+  it("turn-failed 形态:分类经 onFinalFailure 回执转交调用方(Turn 上不留字段)", async () => {
+    const seen: { cls: FailureClass; turn?: Turn }[] = [];
+    const result = await sendWithTurnRetry(
+      async () => failedTurn("connect ECONNREFUSED tunnel.example:443"),
+      identityLens,
+      baseDeps({
+        experimentClassifier: () => tunnelDown,
+        onFinalFailure: (cls, failure) => {
+          seen.push({ cls, turn: failure.type === "turn-failed" ? failure.turn : undefined });
+        },
+      }),
+    );
+    expect(seen).toEqual([{ cls: tunnelDown, turn: result }]);
+    expect(failureClassOf(result)).toBeUndefined();
+  });
+
+  it("被重试吸收的失败不外泄:重试后成功时没有任何终局分类回执", async () => {
+    const seen: FailureClass[] = [];
+    let calls = 0;
+    const result = await sendWithTurnRetry(
+      async () => {
+        calls++;
+        return calls === 1 ? failedTurn("too many requests, retry later") : completedTurn();
+      },
+      identityLens,
+      baseDeps({
+        experimentClassifier: () => ({ retryable: true, reason: "tunnel_flaky", scope: "experiment" }),
+        onFinalFailure: (cls) => seen.push(cls),
+      }),
+    );
+    expect(result.status).toBe("completed");
+    expect(seen).toEqual([]);
+  });
+
+  it("重试耗尽时 scope 随失败携带浮出,回执报的是带耗尽摘要的那个 Turn", async () => {
+    const seen: { cls: FailureClass; turn?: Turn }[] = [];
+    const result = await sendWithTurnRetry(
+      async () => failedTurn("too many requests, retry later"),
+      identityLens,
+      baseDeps({
+        experimentClassifier: () => ({ retryable: true, reason: "tunnel_flaky", scope: "experiment" }),
+        onFinalFailure: (cls, failure) => {
+          seen.push({ cls, turn: failure.type === "turn-failed" ? failure.turn : undefined });
+        },
+      }),
+    );
+    expect(seen).toHaveLength(1);
+    expect(seen[0].cls).toEqual({ retryable: true, reason: "tunnel_flaky", scope: "experiment" });
+    expect(seen[0].turn).toBe(result);
+    expect((result.events[0] as { message: string }).message).toContain("tunnel_flaky");
+  });
+
+  it("实验分类器排在 adapter 之前:两者同时认领时携带的是实验的 scope", async () => {
+    const original = new Error("connect ECONNREFUSED tunnel.example:443");
+    const promise = sendWithTurnRetry(
+      async () => {
+        throw original;
+      },
+      identityLens,
+      baseDeps({
+        experimentClassifier: () => tunnelDown,
+        classifier: () => ({ retryable: true, reason: "network" }),
+      }),
+    );
+    await expect(promise).rejects.toBe(original);
+    expect(failureClassOf(original)).toEqual(tunnelDown);
+  });
+});
+
 describe("sendWithTurnRetry · 中断", () => {
   it("退避睡眠期间 signal abort:干净打断,不等满整段延迟,槽位仍被收回", async () => {
     const ac = new AbortController();

package/src/context/send-retry.ts

@@ -6,7 +6,8 @@
 
 import type { Turn } from "../types.ts";
 import { t } from "../i18n/index.ts";
-import { resolveTurnErrorClass, type TurnErrorClass, type TurnErrorClassifier, type TurnFailure } from "./turn-errors.ts";
+import { attachFailureClass, type AttemptFailureClassifier, type FailureClass } from "../shared/failure-class.ts";
+import { resolveTurnFailureClass, type TurnErrorClassifier, type TurnFailure } from "./turn-errors.ts";
 
 /** 单次 send 调用封顶的尝试次数(首次 + 至多 3 次重试)。 */
 export const SEND_MAX_ATTEMPTS = 4;
@@ -47,6 +48,14 @@ export interface TurnLens<T> {
 export interface SendRetryDeps {
   /** adapter 声明的分类器(可选),undefined 回落保守兜底。 */
   classifier?: TurnErrorClassifier;
+  /** 实验声明的分类器(`ExperimentDef.classifyFailure`,可选),排在 adapter 之前询问。 */
+  experimentClassifier?: AttemptFailureClassifier;
+  /**
+   * 终局失败(不重试 / 重试耗尽)的分类回执:被重试吸收的失败不回调——只有真正浮出的失败
+   * 携带分类,止损闸消费的空间轴由此抵达 attempt 封口。`turn-failed` 形态的失败没有错误对象
+   * 可标记(错误在 `expectOk()` 才铸造),经这条回执转交调用方。
+   */
+  onFinalFailure?: (cls: FailureClass, failure: TurnFailure) => void;
   /** attempt 级预算,持续扣减(调用方在 attempt 生命周期内只创建一份并跨多次 send 复用)。 */
   budget: AttemptRetryBudget;
   /** 省略时不释放槽位(测试 / 无并发闸场景)。 */
@@ -93,7 +102,7 @@ function appendToLastErrorEvent(turn: Turn, suffix: string): Turn | undefined {
 
 /**
  * turn 级重试执行体:反复调 `callOnce()`(每次都是原样重发同一个 `TurnInput`),对失败结果
- * 走三道分类链(见 turn-errors.ts 的 `resolveTurnErrorClass`),可重试则退避后重试,否则把
+ * 走分类链(见 turn-errors.ts 的 `resolveTurnFailureClass`),可重试则退避后重试,否则把
  * 失败原样(或带耗尽摘要)浮出。
  */
 export async function sendWithTurnRetry<T>(
@@ -116,10 +125,15 @@ export async function sendWithTurnRetry<T>(
       failure = { type: "thrown", error: e };
     }
 
-    const cls = resolveTurnErrorClass(failure, deps.classifier);
-    if (!cls.retryable) return finalize(failure, result, lens);
-    if (sendAttempt >= SEND_MAX_ATTEMPTS) return finalize(failure, result, lens, { layer: "send", cls });
-    if (deps.budget.remaining <= 0) return finalize(failure, result, lens, { layer: "attempt", cls });
+    const cls = resolveTurnFailureClass(failure, {
+      experiment: deps.experimentClassifier,
+      adapter: deps.classifier,
+    });
+    // 终局失败才携带分类浮出:被吸收的失败尝试不留痕(见 architecture.md「重试执行体」),
+    // 它的 scope 永远到不了止损闸。
+    if (!cls.retryable) return finalize(failure, result, lens, deps, cls);
+    if (sendAttempt >= SEND_MAX_ATTEMPTS) return finalize(failure, result, lens, deps, cls, { layer: "send", cls });
+    if (deps.budget.remaining <= 0) return finalize(failure, result, lens, deps, cls, { layer: "attempt", cls });
 
     deps.budget.remaining -= 1;
     const delayMs = BASE_DELAY_MS * 2 ** (sendAttempt - 1) * random();
@@ -143,15 +157,22 @@ export async function sendWithTurnRetry<T>(
   }
 }
 
-/** 循环收口:未耗尽的非重试失败原样浮出;耗尽时按耗尽层追加摘要文本。 */
+/**
+ * 循环收口:未耗尽的非重试失败原样浮出;耗尽时按耗尽层追加摘要文本。两条路径都先把终局分类
+ * 挂到浮出的失败上(`thrown` 形态标在错误对象上,沿 cause 链可读;两种形态都经 `onFinalFailure`
+ * 回执),抛出点自己声明过分类的错误不被覆盖。
+ */
 function finalize<T>(
   failure: TurnFailure,
   result: T | undefined,
   lens: TurnLens<T>,
-  exhausted?: { layer: "send" | "attempt"; cls: Extract<TurnErrorClass, { retryable: true }> },
+  deps: SendRetryDeps,
+  cls: FailureClass,
+  exhausted?: { layer: "send" | "attempt"; cls: Extract<FailureClass, { retryable: true }> },
 ): T {
   if (!exhausted) {
-    if (failure.type === "thrown") throw failure.error;
+    deps.onFinalFailure?.(cls, failure);
+    if (failure.type === "thrown") throw attachFailureClass(failure.error, cls);
     return result as T;
   }
   const suffix =
@@ -160,11 +181,15 @@ function finalize<T>(
       : t("session.turnRetryBudgetExhausted", { maxRetries: ATTEMPT_MAX_RETRIES, reason: exhausted.cls.reason });
 
   if (failure.type === "thrown") {
+    deps.onFinalFailure?.(cls, failure);
     const e = failure.error;
-    // adapter 抛出的 Error 仍可能被上层保留、复用或记录；不要原地篡改它。
-    if (e instanceof Error) throw new Error(e.message + suffix, { cause: e });
-    throw e;
+    // adapter 抛出的 Error 仍可能被上层保留、复用或记录；不要原地篡改它(分类标记挂在外层)。
+    if (e instanceof Error) throw attachFailureClass(new Error(e.message + suffix, { cause: e }), cls);
+    throw attachFailureClass(e, cls);
   }
+  // 追加摘要产出的是一个新的 Turn 对象;回执必须报浮出的那个,分类才登记在调用方拿到的 Turn 上。
   const withSuffix = appendToLastErrorEvent(failure.turn, suffix);
+  const finalTurn = withSuffix ?? failure.turn;
+  deps.onFinalFailure?.(cls, { type: "turn-failed", turn: finalTurn });
   return withSuffix ? lens.set(result as T, withSuffix) : (result as T);
 }

package/src/context/session.ts

@@ -12,6 +12,8 @@ import {
   type AttemptRetryBudget,
   type ConcurrencySlot,
 } from "./send-retry.ts";
+import type { AttemptFailureClassifier, FailureClass } from "../shared/failure-class.ts";
+import type { TurnFailure } from "./turn-errors.ts";
 import { recordFact } from "../shared/facts.ts";
 
 /**
@@ -144,6 +146,11 @@ export interface SessionDeps {
    * architecture.md「退避与槽位」)。省略时退避不释放槽位(测试 / 无并发闸场景)。
    */
   concurrencySlot?: ConcurrencySlot;
+  /**
+   * 实验声明的失败分类器(`ExperimentDef.classifyFailure`):turn 链上排在 adapter 分类器
+   * 之前询问(决议序见 docs/feature/error-classification/architecture.md「分类链」)。
+   */
+  experimentClassifier?: AttemptFailureClassifier;
   /** 仅供确定性单测注入:turn 重试执行体的随机数与睡眠(生产路径省略,走真实退避)。 */
   retryRandom?: () => number;
   retrySleep?: (ms: number, signal: AbortSignal) => Promise<void>;
@@ -194,6 +201,17 @@ export class SessionManager {
     return downgradeCoverage(this.agentCoverage, turn.coverage);
   }
 
+  /**
+   * 终局失败 Turn 的分类:失败 Turn 本身不是错误(作者不调 `expectOk()` 就不算失败),分类
+   * 因此不能挂在 Turn 上,只在 `expectOk()` 铸造 `TurnFailed` 时随错误浮出——这里按 Turn 身份
+   * 登记,`makeTurnHandle` 取用。被重试吸收的失败 Turn 从不外泄,也就不会被登记。
+   */
+  resolveTurnFailureClass(turn: Turn): FailureClass | undefined {
+    return this.turnFailureClasses.get(turn);
+  }
+
+  private readonly turnFailureClasses = new WeakMap<Turn, FailureClass>();
+
   async send(
     session: RunSession,
     text: string,
@@ -271,6 +289,12 @@ export class SessionManager {
     // 因此能被 Effect interruption 干净打断,不新增超时语义。
     const retryDeps = {
       classifier: this.deps.agent.classifyTurnError,
+      experimentClassifier: this.deps.experimentClassifier,
+      // 终局失败的分类落账:thrown 形态由执行体标在错误对象上,turn-failed 形态在这里按 Turn
+      // 身份登记,`expectOk()` 铸造 TurnFailed 时取出随错误浮出(止损闸的消费点在 attempt 封口)。
+      onFinalFailure: (cls: FailureClass, failure: TurnFailure) => {
+        if (failure.type === "turn-failed") this.turnFailureClasses.set(failure.turn, cls);
+      },
       budget: this.retryBudget,
       slot: this.deps.concurrencySlot,
       reportRetry: (message: string) => ctx.progress({ message }),

package/src/context/turn-errors.test.ts

@@ -1,13 +1,18 @@
 // cases: docs/engineering/testing/unit/eval.md
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
   classifyTurnError,
   hasAgentEvidence,
-  resolveTurnErrorClass,
+  resolveTurnFailureClass,
   turnErrorText,
-  type TurnErrorClass,
   type TurnFailure,
 } from "./turn-errors.ts";
+import {
+  EvalFatalError,
+  ExperimentFatalError,
+  type AttemptFailureInfo,
+  type FailureClass,
+} from "../shared/failure-class.ts";
 import type { StreamEvent, Turn } from "../types.ts";
 
 function turnFailed(events: StreamEvent[]): TurnFailure {
@@ -87,30 +92,43 @@ describe("classifyTurnError(保守兜底) · thrown 形态", () => {
   });
 });
 
-describe("resolveTurnErrorClass · 三道分类链", () => {
+describe("resolveTurnFailureClass · 五道分类链", () => {
   it("adapter 分类器返回结果时优先生效,自定义 reason 原样透出(不被塞进内建词表)", () => {
     const failure = turnFailed([errorEvent("ACME_QUEUE_FULL: too many concurrent runs")]);
-    const result = resolveTurnErrorClass(failure, () => ({ retryable: true, reason: "acme_queue_full" }));
+    const result = resolveTurnFailureClass(failure, { adapter: () => ({ retryable: true, reason: "acme_queue_full" }) });
     expect(result).toEqual({ retryable: true, reason: "acme_queue_full" });
   });
 
   it("adapter 分类器返回 undefined 时回落保守兜底", () => {
     const failure = turnFailed([errorEvent("too many requests, back off")]);
-    const result = resolveTurnErrorClass(failure, () => undefined);
+    const result = resolveTurnFailureClass(failure, { adapter: () => undefined });
     expect(result).toEqual({ retryable: true, reason: "rate_limit" });
   });
 
-  it("adapter 分类器抛错按不可重试处理并被吞掉——不回落兜底,即使兜底本会判可重试", () => {
+  it("adapter 分类器抛错按 undefined 回落:错误被吞掉,链继续走到兜底", () => {
     const failure = turnFailed([errorEvent("too many requests, back off")]);
-    const result = resolveTurnErrorClass(failure, () => {
-      throw new Error("classifier bug");
+    const result = resolveTurnFailureClass(failure, {
+      adapter: () => {
+        throw new Error("classifier bug");
+      },
+    });
+    expect(result).toEqual({ retryable: true, reason: "rate_limit" });
+  });
+
+  it("实验分类器抛错同样按 undefined 回落,后续通道照常认领(不掩盖原始失败)", () => {
+    const failure = turnFailed([errorEvent("ACME_QUEUE_FULL")]);
+    const result = resolveTurnFailureClass(failure, {
+      experiment: () => {
+        throw new Error("classifier bug");
+      },
+      adapter: () => ({ retryable: true, reason: "acme_queue_full" }),
     });
-    expect(result).toEqual({ retryable: false });
+    expect(result).toEqual({ retryable: true, reason: "acme_queue_full" });
   });
 
   it("没有 adapter 分类器时直接走保守兜底", () => {
     const failure = turnFailed([errorEvent("too many requests, back off")]);
-    expect(resolveTurnErrorClass(failure)).toEqual({ retryable: true, reason: "rate_limit" });
+    expect(resolveTurnFailureClass(failure)).toEqual({ retryable: true, reason: "rate_limit" });
   });
 
   describe("受理证据门:失败 Turn 带 agent 产出事件时强制降级为不可重试", () => {
@@ -119,9 +137,9 @@ describe("resolveTurnErrorClass · 三道分类链", () => {
       ["thinking", { type: "thinking", text: "let me think" } satisfies StreamEvent],
       ["action.called", { type: "action.called", name: "bash", callId: "c1", input: {} } satisfies StreamEvent],
       ["action.result", { type: "action.result", callId: "c1", output: "", status: "completed" } satisfies StreamEvent],
-    ])("%s 事件出现时,文本再像限流也不重试", (_label, evidenceEvent) => {
+    ])("%s 事件出现时,文本再像限流也不重试(reason 原样留着给人读)", (_label, evidenceEvent) => {
       const failure = turnFailed([evidenceEvent, errorEvent("Concurrency limit exceeded, please retry later")]);
-      expect(resolveTurnErrorClass(failure)).toEqual({ retryable: false });
+      expect(resolveTurnFailureClass(failure)).toEqual({ retryable: false, reason: "rate_limit" });
     });
 
     it("adapter 分类器判可重试同样被否决(执行体的否决权压过分类器)", () => {
@@ -129,13 +147,24 @@ describe("resolveTurnErrorClass · 三道分类链", () => {
         { type: "action.called", name: "bash", callId: "c1", input: {} },
         errorEvent("ACME_QUEUE_FULL"),
       ]);
-      const result = resolveTurnErrorClass(failure, () => ({ retryable: true, reason: "acme_queue_full" }));
-      expect(result).toEqual({ retryable: false });
+      const result = resolveTurnFailureClass(failure, { adapter: () => ({ retryable: true, reason: "acme_queue_full" }) });
+      expect(result).toEqual({ retryable: false, reason: "acme_queue_full" });
+    });
+
+    it("只裁时间轴:分类器给的 scope 原样保留,证据门不触碰空间轴", () => {
+      const failure = turnFailed([
+        { type: "action.called", name: "bash", callId: "c1", input: {} },
+        errorEvent("tunnel flaky, retry later"),
+      ]);
+      const result = resolveTurnFailureClass(failure, {
+        experiment: () => ({ retryable: true, reason: "tunnel_flaky", scope: "experiment" }),
+      });
+      expect(result).toEqual({ retryable: false, reason: "tunnel_flaky", scope: "experiment" });
     });
 
     it("thrown 形态没有 Turn 可查,不受证据门影响", () => {
       const failure: TurnFailure = { type: "thrown", error: new Error("too many requests") };
-      expect(resolveTurnErrorClass(failure)).toEqual({ retryable: true, reason: "rate_limit" });
+      expect(resolveTurnFailureClass(failure)).toEqual({ retryable: true, reason: "rate_limit" });
     });
 
     it("不可重试分类结果不受证据门触碰(门只降级可重试的判断)", () => {
@@ -143,12 +172,90 @@ describe("resolveTurnErrorClass · 三道分类链", () => {
         { type: "action.called", name: "bash", callId: "c1", input: {} },
         errorEvent("stream reset mid-response"),
       ]);
-      const result: TurnErrorClass = resolveTurnErrorClass(failure);
+      const result: FailureClass = resolveTurnFailureClass(failure);
       expect(result).toEqual({ retryable: false });
     });
   });
 });
 
+describe("resolveTurnFailureClass · 决议序(先非 undefined 定案)", () => {
+  // 区分力场景:同一条失败两个通道都认领——adapter 只能给时间轴(连接错误的通用形状),
+  // 只有实验作者认得这个 host 是全实验共享的隧道。实验分类器排在 adapter 之前,
+  // scope 才赢得下来(裁决见 memory/failure-chain-experiment-before-adapter.md)。
+  const tunnelFailure = turnFailed([errorEvent("connect ECONNREFUSED nowledge.trycloudflare.com:443")]);
+  const experimentClassifier = () => ({ retryable: false, scope: "experiment", reason: "tunnel_down" }) as const;
+  const adapterClassifier = () => ({ retryable: true, reason: "network" }) as const;
+
+  it("实验分类器与 adapter 同时认领时,实验的 scope 声明胜出", () => {
+    const result = resolveTurnFailureClass(tunnelFailure, {
+      experiment: experimentClassifier,
+      adapter: adapterClassifier,
+    });
+    expect(result).toEqual({ retryable: false, scope: "experiment", reason: "tunnel_down" });
+  });
+
+  it("实验分类器认领后不再询问 adapter", () => {
+    const adapter = vi.fn(adapterClassifier);
+    resolveTurnFailureClass(tunnelFailure, { experiment: experimentClassifier, adapter });
+    expect(adapter).not.toHaveBeenCalled();
+  });
+
+  it("实验分类器不认(返回 undefined)时才轮到 adapter,adapter 的时间轴答案生效", () => {
+    const result = resolveTurnFailureClass(tunnelFailure, {
+      experiment: () => undefined,
+      adapter: adapterClassifier,
+    });
+    expect(result).toEqual({ retryable: true, reason: "network" });
+  });
+
+  it("实验分类器读到的 text 与报错文案同源,phase 是 agent.run,cause 是那个失败 Turn", () => {
+    const turn: Turn = { status: "failed", events: [errorEvent("connect ECONNREFUSED nowledge.trycloudflare.com:443")] };
+    const seen: AttemptFailureInfo[] = [];
+    resolveTurnFailureClass(
+      { type: "turn-failed", turn },
+      {
+        experiment: (failure) => {
+          seen.push(failure);
+          return undefined;
+        },
+      },
+    );
+    expect(seen).toHaveLength(1);
+    expect(seen[0].phase).toBe("agent.run");
+    expect(seen[0].text).toBe(turnErrorText(turn));
+    expect(seen[0].cause).toBe(turn);
+  });
+
+  it("thrown 形态下实验分类器读到抛出的错误本身,text 是错误链串接", () => {
+    const error = new Error("send failed", { cause: new Error("connect ECONNREFUSED tunnel.example:443") });
+    const seen: { text: string; cause: unknown }[] = [];
+    resolveTurnFailureClass({ type: "thrown", error }, {
+      experiment: (failure) => {
+        seen.push(failure);
+        return undefined;
+      },
+    });
+    expect(seen[0].cause).toBe(error);
+    expect(seen[0].text).toBe("send failed · connect ECONNREFUSED tunnel.example:443");
+  });
+
+  it("抛出点携带的分类优先级最高:糖衣类命中即定,任何分类器都不被询问", () => {
+    const experiment = vi.fn(experimentClassifier);
+    const adapter = vi.fn(adapterClassifier);
+    const failure: TurnFailure = { type: "thrown", error: new ExperimentFatalError("tunnel probe failed") };
+    const result = resolveTurnFailureClass(failure, { experiment, adapter });
+    expect(result).toEqual({ retryable: false, scope: "experiment" });
+    expect(experiment).not.toHaveBeenCalled();
+    expect(adapter).not.toHaveBeenCalled();
+  });
+
+  it("糖衣类被上层包装再抛(cause 链)也照样命中,声明不丢失", () => {
+    const wrapped = new Error("adapter wrapped", { cause: new EvalFatalError("fixture missing") });
+    const result = resolveTurnFailureClass({ type: "thrown", error: wrapped });
+    expect(result).toEqual({ retryable: false, scope: "eval" });
+  });
+});
+
 describe("hasAgentEvidence", () => {
   it("空事件流(无 error 事件也无产出事件)判 false", () => {
     expect(hasAgentEvidence({ status: "failed", events: [] })).toBe(false);

package/src/context/turn-errors.ts

@@ -1,20 +1,18 @@
-// turn 级瞬时错误分类:把一次 send 失败(抛出 / 返回 failed Turn)按重试安全性归类。
-// 判据全文见 docs/feature/error-classification/README.md「分类」;这里只落三道分类链里
-// 「保守兜底」与「受理证据门」两道的实现,adapter 分类器本身不在这个文件(它是 Agent 的可选字段,
-// 挂载在 src/agents/types.ts)。执行体的重试时序在 send-retry.ts,不在这里——本模块只回答
-// 「这次失败能不能安全重发」,不碰次数/退避/槽位。
+// turn 失败分类链:把一次 send 失败(抛出 / 返回 failed Turn)归成一份 `FailureClass`。
+// 判据全文见 docs/feature/error-classification/README.md「分类」;两轴词表、糖衣类与守卫在
+// src/shared/failure-class.ts(全仓单源),这里只落 turn 这条链——五道里的「保守兜底」与
+// 「受理证据门」两道的实现在本文件,抛出点声明走守卫、实验分类器挂在 ExperimentDef、adapter
+// 分类器挂在 Agent(src/agents/types.ts),本文件只按序询问它们。执行体的重试时序在
+// send-retry.ts:本模块只回答「这次失败能不能安全重发、波及多远」,不碰次数/退避/槽位。
 
 import type { Turn } from "../types.ts";
-
-/**
- * 一次 send 失败的分类结果:`retryable` 是执行体唯一消费的决策轴;`reason` 是开放词表的
- * 细分诊断,只进 activity 与耗尽摘要,不参与策略。内建兜底产出 reason `"rate_limit"` /
- * `"network"`;adapter 分类器可自造词。`retryable: true` 时 `reason` 必填——可重试的失败
- * 一定会出现在 activity 行与可能的耗尽摘要里,那里需要一个给人读的词。
- */
-export type TurnErrorClass =
-  | { readonly retryable: true; readonly reason: string }
-  | { readonly retryable: false; readonly reason?: string };
+import {
+  callClassifier,
+  errorChainText,
+  failureClassOf,
+  type AttemptFailureClassifier,
+  type FailureClass,
+} from "../shared/failure-class.ts";
 
 /** 一次 send 失败的两种浮出形态:`send()` 抛出异常,或返回 `status: "failed"` 的 Turn。 */
 export type TurnFailure =
@@ -22,10 +20,10 @@ export type TurnFailure =
   | { readonly type: "turn-failed"; readonly turn: Turn };
 
 /**
- * adapter 可选分类器:返回 `undefined` 表示「不认识,交给保守兜底」。分类器必须快、纯、
- * 不抛错——执行体按「抛错等价于不可重试」处理,自身错误被吞掉,不会掩盖原始失败。
+ * adapter 可选分类器:返回 `undefined` 表示「不认识,交给后续链路」。分类器必须快、纯、
+ * 不抛错——抛错按 `undefined` 回落处理,自身错误被吞掉,不会掩盖原始失败。
  */
-export type TurnErrorClassifier = (failure: TurnFailure) => TurnErrorClass | undefined;
+export type TurnErrorClassifier = (failure: TurnFailure) => FailureClass | undefined;
 
 /**
  * 失败 Turn 的错误摘要:取 `events` 里最后一个 `type: "error"` 事件的 message。
@@ -41,23 +39,14 @@ export function turnErrorText(turn: Turn): string | undefined {
   return undefined;
 }
 
-/** `thrown` 形态的错误文本:沿错误链(含 `cause`)取 message,串接成一段供分类器与摘要读的文本。 */
-function thrownErrorText(error: unknown): string {
-  const parts: string[] = [];
-  let current: unknown = error;
-  for (let depth = 0; depth < 5 && current != null; depth++) {
-    const message = current instanceof Error ? current.message : String(current);
-    if (message) parts.push(message);
-    current = current instanceof Error ? (current as { cause?: unknown }).cause : undefined;
-  }
-  return parts.join(" · ");
-}
-
 /** 两种 `TurnFailure` 形态统一取「给人读也给分类器看」的那段文本。 */
 export function turnFailureText(failure: TurnFailure): string {
-  return failure.type === "thrown" ? thrownErrorText(failure.error) : (turnErrorText(failure.turn) ?? "");
+  return failure.type === "thrown" ? errorChainText(failure.error) : (turnErrorText(failure.turn) ?? "");
 }
 
+/** turn 失败在生命周期词表里的归属:adapter send 期间打开的那一段。 */
+const TURN_FAILURE_PHASE = "agent.run" as const;
+
 // 限流关键字 / 明示 retry later → rate_limit;正则形状对齐 sandbox IO 分类器
 // (src/sandbox/errors.ts 的 classifySandboxIoError),各自实现、不共享模块。
 const RATE_LIMIT_PATTERN = /too many requests|rate.?limit|\b429\b|retry later|concurrency limit/i;
@@ -68,10 +57,11 @@ const NETWORK_CODE_PATTERN = /^(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ENETUNREACH|EHO
 const NETWORK_MESSAGE_PATTERN = /getaddrinfo|connection refused|certificate|tls handshake|connect etimedout|connection timeout/i;
 
 /**
- * 保守兜底分类器:三道分类链里的第二道。对失败文本做正则匹配,认不出的一律 `{ retryable: false }`
- * ——宁可判死一个 attempt,不产出不可信的 verdict(判据见 README「分类」)。
+ * 保守兜底分类器:turn 链里的第四道。对失败文本做正则匹配,认不出的一律 `{ retryable: false }`
+ * ——宁可判死一个 attempt,不产出不可信的 verdict(判据见 README「分类」)。兜底永不给出超出
+ * `"attempt"` 的 scope:框架无法从文案证明兄弟必死,扩 scope 只属于携带作者知识的通道。
  */
-export function classifyTurnError(failure: TurnFailure): TurnErrorClass {
+export function classifyTurnError(failure: TurnFailure): FailureClass {
   const text = turnFailureText(failure);
   if (RATE_LIMIT_PATTERN.test(text)) return { retryable: true, reason: "rate_limit" };
   const code = errorCode(failure);
@@ -98,25 +88,45 @@ export function hasAgentEvidence(turn: Turn): boolean {
   return turn.events.some((e) => AGENT_EVIDENCE_TYPES.has(e.type));
 }
 
+/** turn 链上两个可选声明通道;都省略时链退化成「抛出点 → 兜底 → 证据门」。 */
+export interface TurnClassifiers {
+  /** 实验作者的 `ExperimentDef.classifyFailure`,按自家坐标识别共享基建死因。 */
+  experiment?: AttemptFailureClassifier;
+  /** adapter 作者的 `Agent.classifyTurnError`,识别自家协议的错误形状。 */
+  adapter?: TurnErrorClassifier;
+}
+
 /**
- * 三道分类链的完整决议:adapter 分类器(可选,抛错按不可重试处理并吞掉)→ 保守兜底 →
- * 受理证据门(否决权,失败 Turn 带 agent 产出事件时强制降级)。执行体只需要调这一个函数,
- * 不必自己拼三道链的顺序。
+ * turn 失败分类链的完整决议(五道,先给出非 `undefined` 结果的一道定分类):
+ *
+ * 1. 抛出点携带的分类(`failureClassOf`,含 cause 链穿透)——作者知识优先级最高;
+ * 2. 实验分类器——按自家坐标(host、路径)过滤,特异性高于协议通用形状,排在 adapter 之前
+ *    保证「两者同时认领时 scope 赢」(裁决见 memory/failure-chain-experiment-before-adapter.md);
+ * 3. adapter 分类器;
+ * 4. 保守兜底正则;
+ * 5. 受理证据门(执行体的否决权,只裁时间轴):失败 Turn 里已有 agent 产出事件时 `retryable`
+ *    强制降为 `false`,`reason` 与 `scope` 原样保留——门裁的是重发安全性,不是波及范围。
+ *
+ * 分类器抛错按 `undefined` 回落(继续问后续通道),分类是旁路,不得用新错误掩盖原始失败。
  */
-export function resolveTurnErrorClass(failure: TurnFailure, adapterClassifier?: TurnErrorClassifier): TurnErrorClass {
-  let cls: TurnErrorClass | undefined;
-  if (adapterClassifier) {
-    try {
-      cls = adapterClassifier(failure);
-    } catch {
-      // 分类器抛错按不可重试处理:分类是旁路,不得用新错误掩盖原始失败,也不回落到兜底
-      // (自造分类器都判断不了的形状,交给通用正则复判没有意义)。
-      return { retryable: false };
-    }
-  }
-  const resolved = cls ?? classifyTurnError(failure);
+export function resolveTurnFailureClass(failure: TurnFailure, classifiers: TurnClassifiers = {}): FailureClass {
+  const declared = failure.type === "thrown" ? failureClassOf(failure.error) : undefined;
+  const resolved = declared ?? classifyByChain(failure, classifiers);
   if (resolved.retryable && failure.type === "turn-failed" && hasAgentEvidence(failure.turn)) {
-    return { retryable: false };
+    return { ...resolved, retryable: false };
   }
   return resolved;
 }
+
+function classifyByChain(failure: TurnFailure, classifiers: TurnClassifiers): FailureClass {
+  if (classifiers.experiment) {
+    const info = {
+      phase: TURN_FAILURE_PHASE,
+      text: turnFailureText(failure),
+      cause: failure.type === "thrown" ? failure.error : failure.turn,
+    };
+    const cls = callClassifier(classifiers.experiment, info);
+    if (cls) return cls;
+  }
+  return callClassifier(classifiers.adapter, failure) ?? classifyTurnError(failure);
+}

package/src/define.ts

@@ -114,6 +114,11 @@ export function defineExperiment(def: ExperimentDef): ExperimentDef {
   if (def.setup !== undefined && typeof def.setup !== "function") {
     throw new Error(t("define.experimentSetupNotFunction"));
   }
+  // classifyFailure 是失败分类链上的实验通道(见 runner/types.ts 的 ExperimentDef.classifyFailure):
+  // 传成非函数在解析时就报,不等到某条 attempt 撞死才发现这一路声明白写。
+  if (def.classifyFailure !== undefined && typeof def.classifyFailure !== "function") {
+    throw new Error(t("define.experimentClassifyFailureNotFunction"));
+  }
   // flags 必须可 JSON 序列化(进结果快照的 ExperimentRunInfo.flags):解析时即校验,
   // 非 JSON 值(函数 / undefined / 循环引用 / bigint)直接报错,不等到落盘才炸。
   if (def.flags !== undefined) {