niceeval 0.10.3-canary.6 → 0.11.0

package/src/cli.ts

@@ -7,8 +7,8 @@
 import { spawn } from "node:child_process";
 import { hostname } from "node:os";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join, relative, resolve as resolvePath } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve as resolvePath } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs as nodeParseArgs } from "node:util";
 import { discoverEvals, discoverExperiments } from "./runner/discover.ts";
@@ -19,6 +19,8 @@ import { fingerprintEvalsFilter, resolveExperimentEvals, selectedEvalsForRun, sp
 import { failureDetailFromResult } from "./runner/feedback/failure.ts";
 import { stopAllSandboxes, liveSandboxCount } from "./sandbox/registry.ts";
 import { drainExperimentTeardowns } from "./runner/experiment-cleanup-registry.ts";
+import { drainHeldCaseLocks, isCaseLockStale, readCaseLock } from "./runner/lock.ts";
+import { drainHeldGateLeases } from "./runner/gate-lease.ts";
 import { CLEANUP_TIMEOUT_MS, withCleanupTimeout } from "./runner/cleanup-timeout.ts";
 import type { ExperimentHookContext } from "./runner/types.ts";
 import { evalLevelStats } from "./shared/verdict.ts";
@@ -175,7 +177,7 @@ const FLAG_OPTIONS = {
   // 数字 `--attempt`,选哪个 attempt 由 locator 精确指名,不是「先选 eval 再挑第几次」。
   /** `show` 命令专用:该 attempt 运行时保存的 Eval 源码,gate/soft 断言标回源码行(证据切面)。 */
   source: { type: "boolean" },
-  /** `show` 命令专用:该 attempt 的标准执行事件流(消息、thinking、Skill load、工具调用/结果);有 OTel 时同一节点补时间(证据切面)。 */
+  /** `show` 命令专用:该 attempt 的标准执行事件流(消息、thinking、Skill load、工具调用/结果);有 OTel 时同一节点补时间(证据切面)。每个内容段最多预览前 3 行,截断尾巴自带 `--expand` 展开句柄。 */
   execution: { type: "boolean" },
   /** `show` 命令专用:整个 Attempt 的统一时间树;裸 `--timing` 给有界诊断投影,`--timing=full` 逐节点展开全部 runner/已关联 OTel 节点。 */
   timing: { type: "boolean" },
@@ -453,6 +455,29 @@ function resolveAgentDocPath(cwd: string): string {
   return agentsPath;
 }
 
+// init 提示用:从 cwd 向上找最近的 package.json,判断宿主是否 ESM 形态。装载本身不挑形态
+// (bin 注册了 tsx 的 ESM+CJS 双 hook,exports 全出口带 require 条件,见 docs/cli.md
+// 「装载用户 .ts」),但 CJS 编译面下 config / eval 文件用不了顶层 await,ESM 仍是推荐形态;
+// 找不到 package.json 或解析失败按非 ESM 处理(tsx/Node 的缺省语义就是 CJS)。只提示,
+// 不改用户的 package.json。
+function hostPrefersEsm(cwd: string): boolean {
+  let dir = resolvePath(cwd);
+  while (true) {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { type?: unknown };
+        return pkg.type === "module";
+      } catch {
+        return false;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+
 async function initProject(cwd: string): Promise<void> {
   await mkdir(join(cwd, "evals"), { recursive: true });
   const configPath = join(cwd, "niceeval.config.ts");
@@ -522,19 +547,32 @@ async function openBrowser(url: string): Promise<boolean> {
 function assembleInvocationCompletion(state: RunFeedbackState): InvocationCompletion {
   let unstarted = 0;
   let failFastSkipped = 0;
+  let haltedSkipped = 0;
   let interrupted = false;
   const reporterErrors: ReporterError[] = [];
   for (const d of state.diagnostics) {
-    if (d.key === "interrupted") {
+    // 归类按**稳定词法** `code`,不按 `key`:`key` 里编着折叠身份(experimentId / evalId /
+    // reporter 名),拿它做前缀匹配会在「把身份从 key 里摘出去」时静默失配——记账悄悄归零,
+    // 没有任何测试或类型会报警。`code` 省略时回落到 key 的首段:缺省 key 恒是
+    // `${code}:${identity}`(见 sink.ts 的 DiagnosticInput),首段即 code。
+    const code = d.code ?? d.key.split(":", 1)[0];
+    if (code === "interrupted") {
       interrupted = true;
-    } else if (d.key.startsWith("budget-exhausted:")) {
+    } else if (code === "budget-exhausted") {
       unstarted += d.count;
-    } else if (d.key.startsWith("fail-fast:")) {
+    } else if (code === "fail-fast") {
       // run 级 fail-fast 造成的未派发同样计入 unstarted(结论落 incomplete,见
       // docs/feature/experiments/architecture.md「Completion 与退出」)。
       unstarted += d.count;
       failFastSkipped += d.count;
-    } else if (d.key.startsWith("reporter-error:")) {
+    } else if (code === "dispatch-halted") {
+      // 止损闸停派发造成的未派发(见 docs/feature/error-classification/architecture.md
+      // 「记账」)。这条诊断的 count 是「同一死因被声明了几次」(重复声明折叠),不是未派发数——
+      // 未派发数由 emitter 累计后写在 data.unstarted 里(与 budget-exhausted 同一口径)。
+      const halted = typeof d.data?.unstarted === "number" ? d.data.unstarted : 0;
+      unstarted += halted;
+      haltedSkipped += halted;
+    } else if (code === "reporter-error") {
       // required 决定这条错误是否写进 InvocationCompletion.reporterErrors 并让 completion 非 complete
       // (见 docs/cli.md「required reporter」);best-effort reporter 的失败只保留为 diagnostic。
       if (d.data?.required !== true) continue;
@@ -548,9 +586,9 @@ function assembleInvocationCompletion(state: RunFeedbackState): InvocationComple
   // 中断造成的未派发(仍在 queued 的 attempt)同样计入 unstarted(见 docs/feature/experiments/
   // architecture.md「Completion 与退出」:budget 耗尽、fail-fast 或中断造成的未派发都不伪装成全绿)。
   if (interrupted) unstarted += state.queued;
-  // attempt:early-exit 计数含 fail-fast 的未派发(反馈层同一事件驱动计数守恒);
-  // 「省下的重复验证」= 总数减去 fail-fast 那部分。
-  const earlyExitUnstarted = Math.max(0, state.earlyExitSkipped - failFastSkipped);
+  // attempt:early-exit 计数含 fail-fast 与止损闸的未派发(反馈层同一事件驱动计数守恒);
+  // 「省下的重复验证」= 总数减去那两部分。
+  const earlyExitUnstarted = Math.max(0, state.earlyExitSkipped - failFastSkipped - haltedSkipped);
   const status: CompletionStatus = interrupted
     ? "interrupted"
     : unstarted > 0 || reporterErrors.length > 0
@@ -668,6 +706,7 @@ async function main(): Promise<void> {
   if (command === "init") {
     await initProject(cwd);
     process.stdout.write(t("cli.init.done"));
+    if (!hostPrefersEsm(cwd)) process.stdout.write(t("cli.init.esmHint"));
     process.exit(0);
   }
 
@@ -851,6 +890,9 @@ async function main(): Promise<void> {
         maxConcurrency: exp.maxConcurrency,
         setup: exp.setup,
         teardown: exp.teardown,
+        // 实验级失败分类器:随 AgentRun 进 attempt(turn 链与生命周期链共用同一份),
+        // 产出的 scope 由止损闸消费(见 docs/feature/error-classification/architecture.md)。
+        classifyFailure: exp.classifyFailure,
       });
     }
   } else {
@@ -902,21 +944,36 @@ async function main(): Promise<void> {
   // 人读 `--dry` 首行的携入摘要(见 docs/feature/experiments/cli.md 开头示例与「事件与计划
   // 文档的 TypeScript 形状」),口径必须与真正开跑时一致。
   const priorResults = flags.force ? undefined : await loadLatestResultsPerEval(join(cwd, ".niceeval"));
-  const carryPlan = priorResults?.length ? await planCarry(evals, agentRuns, priorResults, config.sandbox) : undefined;
+  const carryPlan = priorResults?.length
+    ? await planCarry(evals, agentRuns, priorResults, config.sandbox, config.timeoutMs)
+    : undefined;
 
   if (flags.dry) {
     // --dry 只按所选形态打印计划,不运行、不落盘——一次完成的读取,不是事件流
     // (见 docs/feature/experiments/cli.md「机器怎么读:--json」)。两种形态共用同一份摊平
     // 矩阵——(experimentId, evalId) 逐行,携带同一口径的 reused 预测——不是各自重算一遍。
     const dryRuns = Math.max(1, ...agentRuns.map((r) => r.runs));
-    const matrix: JsonPlanRow[] = [];
+    const rowInputs: { experimentId: string; evalId: string; reused: boolean }[] = [];
     for (let i = 0; i < agentRuns.length; i++) {
       const run = agentRuns[i]!;
       for (const e of matchedByRun[i]!) {
         const carriedCount = carryPlan?.carriedAttemptsByKey.get(cacheKey(run, e.id))?.size ?? 0;
-        matrix.push({ experimentId: run.experimentId ?? "", evalId: e.id, reused: carriedCount >= run.runs });
+        rowInputs.push({ experimentId: run.experimentId ?? "", evalId: e.id, reused: carriedCount >= run.runs });
       }
     }
+    // 只读锁目录,不取锁、不等待(见 docs/feature/experiments/architecture.md「并发
+    // Invocation:用例锁」);过期(无人续心跳)的锁不算"正被持锁运行",不标注。裸 run(没有
+    // experimentId)不参与锁,恒不标注。并行读——矩阵行数可能不小,不逐行串行等磁盘。
+    const niceevalRootForDry = resolvePath(cwd, ".niceeval");
+    const now = Date.now();
+    const lockedFlags = await Promise.all(
+      rowInputs.map(async (row) => {
+        if (!row.experimentId) return false;
+        const lock = await readCaseLock(niceevalRootForDry, row.experimentId, row.evalId).catch(() => undefined);
+        return lock !== undefined && !isCaseLockStale(lock, now);
+      }),
+    );
+    const matrix: JsonPlanRow[] = rowInputs.map((row, i) => ({ ...row, ...(lockedFlags[i] ? { locked: true } : {}) }));
     if (outputForm === "json") {
       process.stdout.write(
         renderJsonPlanDocument({
@@ -935,7 +992,7 @@ async function main(): Promise<void> {
           configs: agentRuns.length,
           runs: dryRuns,
           reused: carryPlan?.carriedResults.length ?? 0,
-          rows: matrix.map((row) => ({ experimentId: row.experimentId, evalId: row.evalId })),
+          rows: matrix.map((row) => ({ experimentId: row.experimentId, evalId: row.evalId, locked: row.locked })),
         }),
       );
     }
@@ -1001,6 +1058,8 @@ async function main(): Promise<void> {
       const settled = Promise.allSettled([
         ...(runInFlight ? [runInFlight] : []),
         drainExperimentTeardowns(),
+        drainHeldCaseLocks(),
+        drainHeldGateLeases(),
       ]);
       await Promise.race([
         settled.then(() => {}),
@@ -1077,9 +1136,12 @@ async function main(): Promise<void> {
   }
 
   // 正常返回(含被中断后走部分汇总)后再兜一刀:Scope finalizer 没停掉的残留沙箱、没被运行
-  // 路径消费的实验级 cleanup 在这里强清。跑顺利时两份登记表都已空,是 no-op。
+  // 路径消费的实验级 cleanup、没被 per-attempt Effect.ensuring 释放的用例锁与实验闸租约在这里
+  // 强清。跑顺利时四份登记表都已空,是 no-op。
   await stopAllSandboxes();
   await drainExperimentTeardowns();
+  await drainHeldCaseLocks();
+  await drainHeldGateLeases();
 
   // completion 要先算好,--junit 是否"这次真的写出"才有依据(见下)。
   const completion = assembleInvocationCompletion(coordinator.state);
@@ -1116,8 +1178,11 @@ async function main(): Promise<void> {
 
 main().catch(async (e) => {
   process.stderr.write(t("cli.error", { error: formatThrown(e) }));
-  // 真·崩溃路径也别留孤儿:强清还活着的沙箱(带超时)、排空实验级 cleanup 注册表,再退。
+  // 真·崩溃路径也别留孤儿:强清还活着的沙箱(带超时)、排空实验级 cleanup 注册表、用例锁与
+  // 实验闸租约,再退。
   await stopAllSandboxes();
   await drainExperimentTeardowns();
+  await drainHeldCaseLocks();
+  await drainHeldGateLeases();
   process.exit(2);
 });

package/src/context/context.test.ts

@@ -355,6 +355,40 @@ function baseScoringContext(state: ContextState) {
   };
 }
 
+describe("t.* 作用域断言聚合全部轮次(callId 跨轮复用)", () => {
+  // 回归:续轮场景下 adapter 常按轮各自编号(复用 c1)。第一轮读了 INDEX,第二轮才给答复;
+  // t.calledTool 聚合全部轮次,应命中第一轮的 read——旧折叠按 callId 覆盖会让它「只扫最后一轮」而 miss。
+  it("t.calledTool 命中发生在第一轮、callId 被第二轮复用的工具调用", async () => {
+    const agent = scriptedAgent([
+      {
+        status: "completed",
+        events: [
+          { type: "action.called", callId: "c1", name: "read", input: { path: "INDEX.md" } },
+          { type: "action.result", callId: "c1", output: "index contents", status: "completed" },
+          { type: "message", role: "assistant", text: "读完了 INDEX,继续" },
+        ],
+      },
+      {
+        status: "completed",
+        events: [
+          { type: "action.called", callId: "c1", name: "write", input: { path: "note.md" } },
+          { type: "action.result", callId: "c1", output: "ok", status: "completed" },
+          { type: "message", role: "assistant", text: "答复" },
+        ],
+      },
+    ]);
+    const { context, state } = makeContext(agent);
+    await context.send("第一轮"); // 读 INDEX
+    await context.send("第二轮"); // 续轮,复用 callId c1
+
+    context.calledTool("read", { input: { path: "INDEX.md" } });
+
+    const [result] = await state.collector.finalize(baseScoringContext(state));
+    expect(result.name).toBe("calledTool(read)");
+    expect(result.outcome).toBe("passed");
+  });
+});
+
 describe("TurnHandle scoped assertions (parked/loadedSkill/noFailedActions/maxTokens/maxCost)", () => {
   it("mirror t/session scope: turn.parked() reflects this turn's own waiting status", async () => {
     const agent = scriptedAgent([

package/src/context/context.ts

@@ -12,6 +12,7 @@ import * as Scoped from "../scoring/scoped.ts";
 import { buildJudge } from "../scoring/judge.ts";
 import { EvalSkipped, EvalRequirementFailed, TurnFailed } from "./control-flow.ts";
 import { turnErrorText } from "./turn-errors.ts";
+import { attachFailureClass, type FailureClass } from "../shared/failure-class.ts";
 import type { ConcurrencySlot } from "./send-retry.ts";
 import { deriveRunFacts } from "../o11y/derive.ts";
 import { diffIsEmpty, diffMatches, emptyDiffData } from "../scoring/diff.ts";
@@ -91,6 +92,8 @@ export interface ContextDeps {
   onTurn?: import("./session.ts").SessionDeps["onTurn"];
   /** turn 级重试退避期间释放/收回的全局并发槽位;透传给 SessionManager。 */
   concurrencySlot?: ConcurrencySlot;
+  /** 实验声明的失败分类器(`ExperimentDef.classifyFailure`);透传给 SessionManager。 */
+  experimentClassifier?: import("./session.ts").SessionDeps["experimentClassifier"];
   /** 仅供确定性单测注入:透传给 SessionManager 的 turn 重试随机数/睡眠(生产路径省略)。 */
   retryRandom?: import("./session.ts").SessionDeps["retryRandom"];
   retrySleep?: import("./session.ts").SessionDeps["retrySleep"];
@@ -131,6 +134,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     onTurn: deps.onTurn,
     ledgerHooks: deps.ledgerHooks,
     concurrencySlot: deps.concurrencySlot,
+    experimentClassifier: deps.experimentClassifier,
     retryRandom: deps.retryRandom,
     retrySleep: deps.retrySleep,
   });
@@ -332,11 +336,11 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
         const text = typeof input === "string" ? input : input.text;
         const files = typeof input === "string" ? undefined : input.files;
         const turn = await send(session, text, files);
-        return makeTurnHandle(turn, collector, deps, text, manager.resolveTurnCoverage(turn));
+        return makeTurnHandle(turn, collector, deps, text, manager.resolveTurnCoverage(turn), manager.resolveTurnFailureClass(turn));
       },
       sendFile: async (path, text) => {
         const turn = await send(session, text ?? "", [await readInputFile(path)]);
-        return makeTurnHandle(turn, collector, deps, text ?? "", manager.resolveTurnCoverage(turn));
+        return makeTurnHandle(turn, collector, deps, text ?? "", manager.resolveTurnCoverage(turn), manager.resolveTurnFailureClass(turn));
       },
       requireInputRequest: (filter) => requireInputRequest(session, filter),
       respond: async (...answers) => {
@@ -344,7 +348,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
         const built = buildRespondInput(session, answers);
         session.pendingInputRequests.length = 0;
         const turn = await send(session, built.text, undefined, built.responses);
-        return makeTurnHandle(turn, collector, deps, built.text, manager.resolveTurnCoverage(turn));
+        return makeTurnHandle(turn, collector, deps, built.text, manager.resolveTurnCoverage(turn), manager.resolveTurnFailureClass(turn));
       },
       respondAll: async (optionId) => {
         if (session.pendingInputRequests.length === 0) {
@@ -359,7 +363,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
         session.pendingInputRequests.length = 0;
         const input = requests.map(() => optionId).join("\n");
         const turn = await send(session, input, undefined, responses);
-        return makeTurnHandle(turn, collector, deps, input, manager.resolveTurnCoverage(turn));
+        return makeTurnHandle(turn, collector, deps, input, manager.resolveTurnCoverage(turn), manager.resolveTurnFailureClass(turn));
       },
       get reply() {
         return session.lastMessage;
@@ -565,6 +569,7 @@ function makeTurnHandle(
   deps: ContextDeps,
   input: string,
   coverage: ResolvedCoverage,
+  failureClass?: FailureClass,
 ): TurnHandle {
   const message = lastAssistantText(turn.events) ?? "";
   const facts = deriveRunFacts(turn.events);
@@ -598,7 +603,11 @@ function makeTurnHandle(
         // 与保守兜底分类器、turn 级重试摘要读的同一段文本(见 turn-errors.ts 的 turnErrorText)——
         // 不出现「报错说 A、分类看 B」。
         const message = turnErrorText(turn);
-        throw new TurnFailed(message !== undefined ? t("context.turnFailed", { message }) : undefined);
+        const error = new TurnFailed(message !== undefined ? t("context.turnFailed", { message }) : undefined);
+        // 终局失败的分类随错误浮出:attempt 封口据此落止损闸(见
+        // docs/feature/error-classification/architecture.md「止损执行体」)。没有分类
+        // (未经重试执行体的手工构造 Turn)时不标记,落缺省 attempt 档。
+        throw failureClass ? attachFailureClass(error, failureClass) : error;
       }
       return handle;
     },

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 }),